- nanobot: Ultra-Lightweight Personal AI Agent
- 
+ 
Thanks for visiting โจ nanobot!
-
- nanobot is for educational, research, and technical exchange purposes only -
+ \ No newline at end of file diff --git a/docs/PYTHON_SDK.md b/docs/PYTHON_SDK.md deleted file mode 100644 index 2b51055a..00000000 --- a/docs/PYTHON_SDK.md +++ /dev/null @@ -1,138 +0,0 @@ -# Python SDK - -> **Note:** This interface is currently an experiment in the latest source code version and is planned to officially ship in `v0.1.5`. - -Use nanobot programmatically โ load config, run the agent, get results. - -## Quick Start - -```python -import asyncio -from nanobot import Nanobot - -async def main(): - bot = Nanobot.from_config() - result = await bot.run("What time is it in Tokyo?") - print(result.content) - -asyncio.run(main()) -``` - -## API - -### `Nanobot.from_config(config_path?, *, workspace?)` - -Create a `Nanobot` from a config file. - -| Param | Type | Default | Description | -|-------|------|---------|-------------| -| `config_path` | `str \| Path \| None` | `None` | Path to `config.json`. Defaults to `~/.nanobot/config.json`. | -| `workspace` | `str \| Path \| None` | `None` | Override workspace directory from config. | - -Raises `FileNotFoundError` if an explicit path doesn't exist. - -### `await bot.run(message, *, session_key?, hooks?)` - -Run the agent once. Returns a `RunResult`. - -| Param | Type | Default | Description | -|-------|------|---------|-------------| -| `message` | `str` | *(required)* | The user message to process. | -| `session_key` | `str` | `"sdk:default"` | Session identifier for conversation isolation. Different keys get independent history. | -| `hooks` | `list[AgentHook] \| None` | `None` | Lifecycle hooks for this run only. | - -```python -# Isolated sessions โ each user gets independent conversation history -await bot.run("hi", session_key="user-alice") -await bot.run("hi", session_key="user-bob") -``` - -### `RunResult` - -| Field | Type | Description | -|-------|------|-------------| -| `content` | `str` | The agent's final text response. | -| `tools_used` | `list[str]` | Tool names invoked during the run. | -| `messages` | `list[dict]` | Raw message history (for debugging). | - -## Hooks - -Hooks let you observe or modify the agent loop without touching internals. - -Subclass `AgentHook` and override any method: - -| Method | When | -|--------|------| -| `before_iteration(ctx)` | Before each LLM call | -| `on_stream(ctx, delta)` | On each streamed token | -| `on_stream_end(ctx)` | When streaming finishes | -| `before_execute_tools(ctx)` | Before tool execution (inspect `ctx.tool_calls`) | -| `after_iteration(ctx, response)` | After each LLM response | -| `finalize_content(ctx, content)` | Transform final output text | - -### Example: Audit Hook - -```python -from nanobot.agent import AgentHook, AgentHookContext - -class AuditHook(AgentHook): - def __init__(self): - self.calls = [] - - async def before_execute_tools(self, ctx: AgentHookContext) -> None: - for tc in ctx.tool_calls: - self.calls.append(tc.name) - print(f"[audit] {tc.name}({tc.arguments})") - -hook = AuditHook() -result = await bot.run("List files in /tmp", hooks=[hook]) -print(f"Tools used: {hook.calls}") -``` - -### Composing Hooks - -Pass multiple hooks โ they run in order, errors in one don't block others: - -```python -result = await bot.run("hi", hooks=[AuditHook(), MetricsHook()]) -``` - -Under the hood this uses `CompositeHook` for fan-out with error isolation. - -### `finalize_content` Pipeline - -Unlike the async methods (fan-out), `finalize_content` is a pipeline โ each hook's output feeds the next: - -```python -class Censor(AgentHook): - def finalize_content(self, ctx, content): - return content.replace("secret", "***") if content else content -``` - -## Full Example - -```python -import asyncio -from nanobot import Nanobot -from nanobot.agent import AgentHook, AgentHookContext - -class TimingHook(AgentHook): - async def before_iteration(self, ctx: AgentHookContext) -> None: - import time - ctx.metadata["_t0"] = time.time() - - async def after_iteration(self, ctx, response) -> None: - import time - elapsed = time.time() - ctx.metadata.get("_t0", 0) - print(f"[timing] iteration took {elapsed:.2f}s") - -async def main(): - bot = Nanobot.from_config(workspace="/my/project") - result = await bot.run( - "Explain the main function", - hooks=[TimingHook()], - ) - print(result.content) - -asyncio.run(main()) -``` diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..5158f802 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,30 @@ +# nanobot Docs + +For the latest documentation, visit [nanobot.wiki](https://nanobot.wiki/docs/0.1.5/getting-started/nanobot-overview). + +The pages in this directory track the current repository and may move faster than the published website. + +## Core Docs + +| Topic | Repo docs | +|---|---| +| Install and quick start | [`quick-start.md`](./quick-start.md) | +| Chat apps | [`chat-apps.md`](./chat-apps.md) | +| Agent social network | [`agent-social-network.md`](./agent-social-network.md) | +| Configuration | [`configuration.md`](./configuration.md) | +| Multiple instances | [`multiple-instances.md`](./multiple-instances.md) | +| CLI reference | [`cli-reference.md`](./cli-reference.md) | +| In-chat commands | [`chat-commands.md`](./chat-commands.md) | +| OpenAI-compatible API | [`openai-api.md`](./openai-api.md) | +| Deployment | [`deployment.md`](./deployment.md) | + +## Advanced Docs + +| Topic | Repo docs | +|---|---| +| Memory | [`memory.md`](./memory.md) | +| Python SDK | [`python-sdk.md`](./python-sdk.md) | +| Channel plugin guide | [`channel-plugin-guide.md`](./channel-plugin-guide.md) | +| WebSocket channel | [`websocket.md`](./websocket.md) | +| Custom tools | [`my-tool.md`](./my-tool.md) | + diff --git a/docs/agent-social-network.md b/docs/agent-social-network.md new file mode 100644 index 00000000..74579b8b --- /dev/null +++ b/docs/agent-social-network.md @@ -0,0 +1,10 @@ +# Agent Social Network + +๐ nanobot is capable of linking to the agent social network (agent community). **Just send one message and your nanobot joins automatically!** + +| Platform | How to Join (send this message to your bot) | +|----------|-------------| +| [**Moltbook**](https://www.moltbook.com/) | `Read https://moltbook.com/skill.md and follow the instructions to join Moltbook` | +| [**ClawdChat**](https://clawdchat.ai/) | `Read https://clawdchat.ai/skill.md and follow the instructions to join ClawdChat` | + +Simply send the command above to your nanobot (via CLI or any chat channel), and it will handle the rest. diff --git a/docs/CHANNEL_PLUGIN_GUIDE.md b/docs/channel-plugin-guide.md similarity index 99% rename from docs/CHANNEL_PLUGIN_GUIDE.md rename to docs/channel-plugin-guide.md index 12a41685..d37a9288 100644 --- a/docs/CHANNEL_PLUGIN_GUIDE.md +++ b/docs/channel-plugin-guide.md @@ -19,7 +19,7 @@ We'll build a minimal webhook channel that receives messages via HTTP POST and s ### Project Structure -``` +```text nanobot-channel-webhook/ โโโ nanobot_channel_webhook/ โ โโโ __init__.py # re-export WebhookChannel diff --git a/docs/chat-apps.md b/docs/chat-apps.md new file mode 100644 index 00000000..9332bdc0 --- /dev/null +++ b/docs/chat-apps.md @@ -0,0 +1,661 @@ +# Chat Apps + +Connect nanobot to your favorite chat platform. Want to build your own? See the [Channel Plugin Guide](./channel-plugin-guide.md). + +| Channel | What you need | +|---------|---------------| +| **Telegram** | Bot token from @BotFather | +| **Discord** | Bot token + Message Content intent | +| **WhatsApp** | QR code scan (`nanobot channels login whatsapp`) | +| **WeChat (Weixin)** | QR code scan (`nanobot channels login weixin`) | +| **Feishu** | App ID + App Secret | +| **DingTalk** | App Key + App Secret | +| **Slack** | Bot token + App-Level token | +| **Matrix** | Homeserver URL + Access token | +| **Email** | IMAP/SMTP credentials | +| **QQ** | App ID + App Secret | +| **Wecom** | Bot ID + Bot Secret | +| **Microsoft Teams** | App ID + App Password + public HTTPS endpoint | +| **Mochat** | Claw token (auto-setup available) | + +๐ 24/7 Real-Time Market Analysis |
+ ๐ Full-Stack Software Engineer |
+ ๐ Smart Daily Routine Manager |
+ ๐ Personal Knowledge Assistant |
+
|---|---|---|---|
|
+
|
+
|
+
|
+
| Discovery โข Insights โข Trends | +Develop โข Deploy โข Scale | +Schedule โข Automate โข Organize | +Learn โข Memory โข Reasoning | +
