diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..d925f32c6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,82 @@ +This file provides guidance to AI coding agents working with this repository. + +## Project Overview + +nanobot is a lightweight, open-source AI agent framework written in Python with a React/TypeScript WebUI. It centers around a small agent loop that receives messages from chat channels, invokes an LLM provider, executes tools, and manages session memory. + +## Development Commands + +```bash +# Python: run single test / lint +pytest tests/test_openai_api.py::test_function -v +ruff check nanobot/ + +# WebUI: dev server (proxies API/WS to gateway :8765), build, test +# Build outputs to ../nanobot/web/dist (bundled into the Python wheel) +cd webui && bun run dev # or NANOBOT_API_URL=... bun run dev +cd webui && bun run build +cd webui && bun run test + +# Gateway +nanobot gateway +``` + +## High-Level Architecture + +### Core Data Flow + +Messages flow through an async `MessageBus` (`nanobot/bus/queue.py`) that decouples chat channels from the agent core: + +1. **Channels** (`nanobot/channels/`) receive messages from external platforms and publish `InboundMessage` events to the bus. +2. **`AgentLoop`** (`nanobot/agent/loop.py`) consumes inbound messages, builds context, and coordinates the turn. +3. **`AgentRunner`** (`nanobot/agent/runner.py`) handles the actual LLM conversation loop: send messages to the provider, receive tool calls, execute tools, and stream responses. +4. Responses are published as `OutboundMessage` events back to the appropriate channel. + +### Key Subsystems + +- **Agent Loop** (`nanobot/agent/loop.py`, `runner.py`): The core processing engine. `AgentLoop` manages session keys, hooks, and context building. `AgentRunner` executes the multi-turn LLM conversation with tool execution. +- **LLM Providers** (`nanobot/providers/`): Provider implementations (Anthropic, OpenAI-compatible, OpenAI Responses API, Azure, Bedrock, GitHub Copilot, OpenAI Codex, etc.) built on a common base (`base.py`). Includes image generation (`image_generation.py`) and audio transcription (`transcription.py`). `factory.py` and `registry.py` handle instantiation and model discovery. +- **Channels** (`nanobot/channels/`): Platform integrations (Telegram, Discord, Slack, Feishu, Matrix, WhatsApp, QQ, WeChat, WeCom, DingTalk, Email, MoChat, MS Teams, WebSocket). `manager.py` discovers and coordinates them. Channels are auto-discovered via `pkgutil` scan + entry-point plugins. +- **Tools** (`nanobot/agent/tools/`): Agent capabilities exposed to the LLM: filesystem (read/write/edit/list), shell execution (with sandbox backends), web search/fetch, MCP servers, cron, notebook editing, subagent spawning, long-running tasks / sustained goals (`long_task.py`), image generation, and self-modification. Tools are auto-discovered via `pkgutil` scan + entry-point plugins. +- **Memory** (`nanobot/agent/memory.py`): Session history persistence with Dream two-phase memory consolidation. Uses atomic writes with fsync for durability. +- **Session Management** (`nanobot/session/`): Per-session history, context compaction, TTL-based auto-compaction (`manager.py`), and sustained goal state tracking (`goal_state.py`). +- **Config** (`nanobot/config/schema.py`, `loader.py`): Pydantic-based configuration loaded from `~/.nanobot/config.json`. Supports camelCase aliases for JSON compatibility. +- **Bridge** (`bridge/`): TypeScript services (e.g. WhatsApp bridge) bundled into the wheel via `pyproject.toml` `force-include`. +- **WebUI** (`webui/`): Vite-based React SPA that talks to the gateway over a WebSocket multiplex protocol. The dev server proxies `/api`, `/webui`, `/auth`, and WebSocket traffic to the gateway. +- **API Server** (`nanobot/api/server.py`): OpenAI-compatible HTTP API (`/v1/chat/completions`, `/v1/models`) for programmatic access. +- **Command Router** (`nanobot/command/`): Slash command routing and built-in command handlers. +- **Heartbeat** (`nanobot/templates/HEARTBEAT.md`): Periodic task list checked via `cron` jobs (legacy dedicated service removed). +- **Pairing** (`nanobot/pairing/`): DM sender approval store with persistent pairing codes per channel. +- **Skills** (`nanobot/skills/`): Built-in skill definitions (long-goal, cron, github, image-generation, etc.) loaded into agent context. +- **Security** (`nanobot/security/`): PTH file guard and other security measures activated at CLI entry. + +### Entry Points + +- **CLI**: `nanobot/cli/commands.py` +- **Python SDK**: `nanobot/nanobot.py` + +## Project-Specific Notes + +- Architecture constraints: [`.agent/design.md`](.agent/design.md) +- Security boundaries: [`.agent/security.md`](.agent/security.md) +- Common gotchas: [`.agent/gotchas.md`](.agent/gotchas.md) + +## Branching Strategy + +See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full two-branch model (`main` vs `nightly`) and PR guidelines. + +## Code Style + +- Python 3.11+, asyncio throughout. +- Line length: 100. +- Linting: `ruff` with rules E, F, I, N, W (E501 ignored). +- pytest with `asyncio_mode = "auto"`. + +## Common File Locations + +- Config schema: `nanobot/config/schema.py` +- Provider base / new provider template: `nanobot/providers/base.py` +- Channel base / new channel template: `nanobot/channels/base.py` +- Tool registry: `nanobot/agent/tools/registry.py` +- WebUI dev proxy config: `webui/vite.config.ts` +- Tests mirror the `nanobot/` package structure. diff --git a/CLAUDE.md b/CLAUDE.md index 4408c18ce..43c994c2d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,84 +1 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -nanobot is a lightweight, open-source AI agent framework written in Python with a React/TypeScript WebUI. It centers around a small agent loop that receives messages from chat channels, invokes an LLM provider, executes tools, and manages session memory. - -## Development Commands - -```bash -# Python: run single test / lint -pytest tests/test_openai_api.py::test_function -v -ruff check nanobot/ - -# WebUI: dev server (proxies API/WS to gateway :8765), build, test -# Build outputs to ../nanobot/web/dist (bundled into the Python wheel) -cd webui && bun run dev # or NANOBOT_API_URL=... bun run dev -cd webui && bun run build -cd webui && bun run test - -# Gateway -nanobot gateway -``` - -## High-Level Architecture - -### Core Data Flow - -Messages flow through an async `MessageBus` (`nanobot/bus/queue.py`) that decouples chat channels from the agent core: - -1. **Channels** (`nanobot/channels/`) receive messages from external platforms and publish `InboundMessage` events to the bus. -2. **`AgentLoop`** (`nanobot/agent/loop.py`) consumes inbound messages, builds context, and coordinates the turn. -3. **`AgentRunner`** (`nanobot/agent/runner.py`) handles the actual LLM conversation loop: send messages to the provider, receive tool calls, execute tools, and stream responses. -4. Responses are published as `OutboundMessage` events back to the appropriate channel. - -### Key Subsystems - -- **Agent Loop** (`nanobot/agent/loop.py`, `runner.py`): The core processing engine. `AgentLoop` manages session keys, hooks, and context building. `AgentRunner` executes the multi-turn LLM conversation with tool execution. -- **LLM Providers** (`nanobot/providers/`): Provider implementations (Anthropic, OpenAI-compatible, OpenAI Responses API, Azure, Bedrock, GitHub Copilot, OpenAI Codex, etc.) built on a common base (`base.py`). Includes image generation (`image_generation.py`) and audio transcription (`transcription.py`). `factory.py` and `registry.py` handle instantiation and model discovery. -- **Channels** (`nanobot/channels/`): Platform integrations (Telegram, Discord, Slack, Feishu, Matrix, WhatsApp, QQ, WeChat, WeCom, DingTalk, Email, MoChat, MS Teams, WebSocket). `manager.py` discovers and coordinates them. Channels are auto-discovered via `pkgutil` scan + entry-point plugins. -- **Tools** (`nanobot/agent/tools/`): Agent capabilities exposed to the LLM: filesystem (read/write/edit/list), shell execution (with sandbox backends), web search/fetch, MCP servers, cron, notebook editing, subagent spawning, long-running tasks / sustained goals (`long_task.py`), image generation, and self-modification. Tools are auto-discovered via `pkgutil` scan + entry-point plugins. -- **Memory** (`nanobot/agent/memory.py`): Session history persistence with Dream two-phase memory consolidation. Uses atomic writes with fsync for durability. -- **Session Management** (`nanobot/session/`): Per-session history, context compaction, TTL-based auto-compaction (`manager.py`), and sustained goal state tracking (`goal_state.py`). -- **Config** (`nanobot/config/schema.py`, `loader.py`): Pydantic-based configuration loaded from `~/.nanobot/config.json`. Supports camelCase aliases for JSON compatibility. -- **Bridge** (`bridge/`): TypeScript services (e.g. WhatsApp bridge) bundled into the wheel via `pyproject.toml` `force-include`. -- **WebUI** (`webui/`): Vite-based React SPA that talks to the gateway over a WebSocket multiplex protocol. The dev server proxies `/api`, `/webui`, `/auth`, and WebSocket traffic to the gateway. -- **API Server** (`nanobot/api/server.py`): OpenAI-compatible HTTP API (`/v1/chat/completions`, `/v1/models`) for programmatic access. -- **Command Router** (`nanobot/command/`): Slash command routing and built-in command handlers. -- **Heartbeat** (`nanobot/templates/HEARTBEAT.md`): Periodic task list checked via `cron` jobs (legacy dedicated service removed). -- **Pairing** (`nanobot/pairing/`): DM sender approval store with persistent pairing codes per channel. -- **Skills** (`nanobot/skills/`): Built-in skill definitions (long-goal, cron, github, image-generation, etc.) loaded into agent context. -- **Security** (`nanobot/security/`): PTH file guard and other security measures activated at CLI entry. - -### Entry Points - -- **CLI**: `nanobot/cli/commands.py` -- **Python SDK**: `nanobot/nanobot.py` - -## Project-Specific Notes - -- Architecture constraints: [`.agent/design.md`](.agent/design.md) -- Security boundaries: [`.agent/security.md`](.agent/security.md) -- Common gotchas: [`.agent/gotchas.md`](.agent/gotchas.md) - -## Branching Strategy - -See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full two-branch model (`main` vs `nightly`) and PR guidelines. - -## Code Style - -- Python 3.11+, asyncio throughout. -- Line length: 100. -- Linting: `ruff` with rules E, F, I, N, W (E501 ignored). -- pytest with `asyncio_mode = "auto"`. - -## Common File Locations - -- Config schema: `nanobot/config/schema.py` -- Provider base / new provider template: `nanobot/providers/base.py` -- Channel base / new channel template: `nanobot/channels/base.py` -- Tool registry: `nanobot/agent/tools/registry.py` -- WebUI dev proxy config: `webui/vite.config.ts` -- Tests mirror the `nanobot/` package structure. +@AGENTS.md