🐈nanobot: hello world!
This commit is contained in:
Re-bin
287
README.md
287
README.md
@@ -1,2 +1,285 @@
|
||||
# nanobot
|
||||
"nanobot: Extremely Simple and Lightweight Clawdbot Implementation"
|
||||
<div align="center">
|
||||
<img src="nanobot_logo.png" alt="nanobot" width="500">
|
||||
<h1>nanobot: Your Lightweight Personal AI Assistant</h1>
|
||||
<p>
|
||||
<a href="https://pypi.org/project/nanobot-ai/"><img src="https://img.shields.io/pypi/v/nanobot-ai" alt="PyPI"></a>
|
||||
<img src="https://img.shields.io/badge/python-≥3.11-blue" alt="Python">
|
||||
<img src="https://img.shields.io/badge/license-MIT-green" alt="License">
|
||||
</p>
|
||||
</div>
|
||||
|
||||
🐈 **nanobot** is an **ultra-lightweight** personal AI assistant inspired by [Clawdbot](https://github.com/openclaw/openclaw)
|
||||
|
||||
⚡️ Delivers core agent functionality in just **~4,000** lines of code — **99% smaller** than Clawdbot's 430k+ lines.
|
||||
|
||||
## 📢 News
|
||||
|
||||
- **2025-02-01** 🎉 nanobot launched! Welcome to try 🐈 nanobot!
|
||||
|
||||
## Key Features of nanobot:
|
||||
|
||||
⚡️ **Ultra-Lightweight**: At just ~4,000 lines of code, nanobot is 99% smaller than comparable AI assistants while delivering full functionality.
|
||||
|
||||
🔬 **Research-Ready**: Clean, readable architecture makes it perfect for researchers and developers who need to understand, modify, or extend the codebase.
|
||||
|
||||
⚡️ **Lightning Fast**: Minimal footprint means faster startup, lower resource usage, and quicker iteration cycles.
|
||||
|
||||
## 🏗️ Architecture
|
||||
|
||||
<p align="center">
|
||||
<img src="nanobot_arch.png" alt="nanobot architecture" width="800">
|
||||
</p>
|
||||
|
||||
## ✨ Features
|
||||
|
||||
<table align="center">
|
||||
<tr align="center">
|
||||
<th><p align="center">🔍 Web Search</p></th>
|
||||
<th><p align="center">💻 Code & Files</p></th>
|
||||
<th><p align="center">📅 Scheduled Tasks</p></th>
|
||||
<th><p align="center">🧠 Memory</p></th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center"><p align="center"><img src="case/search.gif" width="180" height="400"></p></td>
|
||||
<td align="center"><p align="center"><img src="case/code.gif" width="180" height="400"></p></td>
|
||||
<td align="center"><p align="center"><img src="case/scedule.gif" width="180" height="400"></p></td>
|
||||
<td align="center"><p align="center"><img src="case/memory.gif" width="180" height="400"></p></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td align="center">Search real-time info</td>
|
||||
<td align="center">Read, write, execute</td>
|
||||
<td align="center">Cron jobs & reminders</td>
|
||||
<td align="center">Remember context</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## 📦 Install
|
||||
|
||||
**Install from PyPi**
|
||||
|
||||
```bash
|
||||
pip install nanobot-ai
|
||||
```
|
||||
|
||||
**Install from source** (recommended for development)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/HKUDS/nanobot.git
|
||||
cd nanobot
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
> [!TIP]
|
||||
> Set your API key in `~/.nanobot/config.json`. Get one at [OpenRouter](https://openrouter.ai/keys).
|
||||
|
||||
**1. Initialize**
|
||||
|
||||
```bash
|
||||
nanobot onboard
|
||||
```
|
||||
|
||||
**2. Configure** (`~/.nanobot/config.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"openrouter": {
|
||||
"apiKey": "sk-or-v1-xxx"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**3. Chat**
|
||||
|
||||
```bash
|
||||
nanobot agent -m "What is 2+2?"
|
||||
```
|
||||
|
||||
That's it! You have a working AI assistant in 2 minutes.
|
||||
|
||||
## 💬 Chat Apps
|
||||
|
||||
Talk to your nanobot through Telegram or WhatsApp — anytime, anywhere.
|
||||
|
||||
| Channel | Setup |
|
||||
|---------|-------|
|
||||
| **Telegram** | Easy (just a token) |
|
||||
| **WhatsApp** | Medium (scan QR) |
|
||||
|
||||
<details>
|
||||
<summary><b>Telegram</b> (Recommended)</summary>
|
||||
|
||||
**1. Create a bot**
|
||||
- Open Telegram, search `@BotFather`
|
||||
- Send `/newbot`, follow prompts
|
||||
- Copy the token
|
||||
|
||||
**2. Configure**
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"enabled": true,
|
||||
"token": "YOUR_BOT_TOKEN",
|
||||
"allowFrom": ["YOUR_USER_ID"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> Get your user ID from `@userinfobot` on Telegram.
|
||||
|
||||
**3. Run**
|
||||
|
||||
```bash
|
||||
nanobot gateway
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>WhatsApp</b></summary>
|
||||
|
||||
Requires **Node.js ≥18**.
|
||||
|
||||
**1. Link device**
|
||||
|
||||
```bash
|
||||
nanobot channels login
|
||||
# Scan QR with WhatsApp → Settings → Linked Devices
|
||||
```
|
||||
|
||||
**2. Configure**
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"whatsapp": {
|
||||
"enabled": true,
|
||||
"allowFrom": ["+1234567890"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**3. Run** (two terminals)
|
||||
|
||||
```bash
|
||||
# Terminal 1
|
||||
nanobot channels login
|
||||
|
||||
# Terminal 2
|
||||
nanobot gateway
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## ⚙️ Configuration
|
||||
|
||||
<details>
|
||||
<summary><b>Full config example</b></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": "anthropic/claude-opus-4-5"
|
||||
}
|
||||
},
|
||||
"providers": {
|
||||
"openrouter": {
|
||||
"apiKey": "sk-or-v1-xxx"
|
||||
}
|
||||
},
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"enabled": true,
|
||||
"token": "123456:ABC...",
|
||||
"allowFrom": ["123456789"]
|
||||
},
|
||||
"whatsapp": {
|
||||
"enabled": false
|
||||
}
|
||||
},
|
||||
"tools": {
|
||||
"web": {
|
||||
"search": {
|
||||
"apiKey": "BSA..."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
**API Keys:**
|
||||
- **OpenRouter**: https://openrouter.ai/keys
|
||||
- **Brave Search** (optional): https://brave.com/search/api/
|
||||
|
||||
## CLI Reference
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `nanobot onboard` | Initialize config & workspace |
|
||||
| `nanobot agent -m "..."` | Chat with the agent |
|
||||
| `nanobot agent` | Interactive chat mode |
|
||||
| `nanobot gateway` | Start the gateway |
|
||||
| `nanobot status` | Show status |
|
||||
| `nanobot channels login` | Link WhatsApp (scan QR) |
|
||||
| `nanobot channels status` | Show channel status |
|
||||
|
||||
<details>
|
||||
<summary><b>Scheduled Tasks (Cron)</b></summary>
|
||||
|
||||
```bash
|
||||
# Add a job
|
||||
nanobot cron add --name "daily" --message "Good morning!" --cron "0 9 * * *"
|
||||
nanobot cron add --name "hourly" --message "Check status" --every 3600
|
||||
|
||||
# List jobs
|
||||
nanobot cron list
|
||||
|
||||
# Remove a job
|
||||
nanobot cron remove <job_id>
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## 📁 Project Structure
|
||||
|
||||
```
|
||||
nanobot/
|
||||
├── agent/ # 🧠 Core agent logic
|
||||
│ ├── loop.py # Agent loop (LLM ↔ tool execution)
|
||||
│ ├── context.py # Prompt builder
|
||||
│ ├── memory.py # Persistent memory
|
||||
│ ├── skills.py # Skills loader
|
||||
│ └── tools/ # Built-in tools
|
||||
├── skills/ # 🎯 Bundled skills (github, weather, tmux...)
|
||||
├── channels/ # 📱 Telegram, WhatsApp
|
||||
├── bus/ # 🚌 Message routing
|
||||
├── cron/ # ⏰ Scheduled tasks
|
||||
├── providers/ # 🤖 LLM providers (OpenRouter, etc.)
|
||||
├── session/ # 💬 Conversation sessions
|
||||
├── config/ # ⚙️ Configuration
|
||||
└── cli/ # 🖥️ Commands
|
||||
```
|
||||
|
||||
## 🗺️ Roadmap
|
||||
|
||||
- [ ] **Multi-modal** — See and hear (images, voice, video)
|
||||
- [ ] **Long-term memory** — Never forget important context
|
||||
- [ ] **Better reasoning** — Multi-step planning and reflection
|
||||
- [ ] **More integrations** — Discord, Slack, email, calendar
|
||||
- [ ] **Self-improvement** — Learn from feedback and mistakes
|
||||
|
||||
**Want to help?** Pick an item and [open a PR](https://github.com/HKUDS/nanobot/pulls)!
|
||||
|
||||
## 🤝 Contribute
|
||||
|
||||
PRs welcome! The codebase is intentionally small and readable.
|
||||
|
||||
Reference in New Issue
Block a user