Skip to content

architecture.md

Latest commit

 

History

History
212 lines (152 loc) · 8.34 KB

architecture.md

File metadata and controls

212 lines (152 loc) · 8.34 KB

Architecture

This page maps nanobot's runtime behavior to source files. Use it when you are debugging internals, reviewing a PR, adding a provider/channel/tool, or trying to understand where a user-visible behavior comes from.

For the product-level mental model, read concepts.md first.

Core Flow

flowchart LR
    Channel["Channel<br/>CLI, WebUI, chat apps"] --> Bus["MessageBus<br/>InboundMessage"]
    Bus --> Loop["AgentLoop<br/>session, workspace, context"]
    Loop --> Runner["AgentRunner<br/>provider/tool loop"]
    Runner --> Provider["Provider<br/>LLM backend"]
    Provider --> Runner
    Runner --> Tools["Tools<br/>files, shell, web, MCP, cron"]
    Tools --> Runner
    Runner --> Loop
    Loop --> Outbound["MessageBus<br/>OutboundMessage"]
    Outbound --> Channel

    Loop -. reads/writes .-> State["Session, memory,<br/>hooks, skills, templates"]
Loading

Main files:

Area Files
Message events and queue nanobot/bus/events.py, nanobot/bus/queue.py
Turn orchestration nanobot/agent/loop.py
Provider/tool conversation loop nanobot/agent/runner.py
Context construction nanobot/agent/context.py
Session storage and compaction nanobot/session/manager.py
Long-term memory and Dream nanobot/agent/memory.py

Agent Loop vs Agent Runner

AgentLoop owns the channel-facing turn:

  • receives inbound messages;
  • determines the effective session and workspace scope;
  • builds context;
  • wires hooks, progress, and channel metadata;
  • publishes outbound messages.

AgentRunner owns the model-facing loop:

  • sends messages to the selected provider;
  • handles streaming deltas and reasoning blocks;
  • executes tool calls;
  • feeds tool results back into the model;
  • stops when a final answer is produced or runtime limits are hit.

Keep this split in mind when debugging. If a problem is about channel routing, session keys, workspace selection, or outbound delivery, start in agent/loop.py. If it is about provider calls, tool calls, streaming, or iteration limits, start in agent/runner.py.

Providers

Provider metadata is centralized in nanobot/providers/registry.py. Configuration fields live in nanobot/config/schema.py.

Provider selection uses:

  • explicit agents.defaults.provider or preset provider;
  • provider registry keywords;
  • API key prefixes and API base URL hints;
  • local provider fallback when apiBase is configured;
  • gateway fallback for providers that can route many model families.

Provider implementations live in nanobot/providers/. Most hosted providers use the OpenAI-compatible implementation, while Anthropic, Azure OpenAI, AWS Bedrock, OpenAI Codex, and GitHub Copilot have specialized paths.

Useful docs:

Channels

Channels translate external platforms into InboundMessage events and send OutboundMessage events back to the platform.

Main files:

Area Files
Base channel contract nanobot/channels/base.py
Built-in channels nanobot/channels/*.py
Discovery and lifecycle nanobot/channels/manager.py
WebSocket/WebUI channel nanobot/channels/websocket.py

Channels are discovered through built-in module scanning and plugin entry points. A custom channel should follow channel-plugin-guide.md.

WebUI and Gateway

nanobot gateway starts:

  • enabled chat channels;
  • the WebSocket channel when configured;
  • workspace-scoped cron service;
  • system jobs such as Dream and heartbeat;
  • the health endpoint on gateway.port.

The packaged WebUI is served by the WebSocket channel, not the health endpoint:

Surface Default
Health endpoint http://127.0.0.1:18790/health
WebUI/WebSocket http://127.0.0.1:8765

WebUI source lives in webui/. The production build is written to nanobot/web/dist/ and bundled into the wheel.

Useful docs:

Tools

Tools are discovered from nanobot/agent/tools/ and plugin entry points.

Important files:

Tool area Files
Tool base and schema nanobot/agent/tools/base.py, nanobot/agent/tools/schema.py
Discovery nanobot/agent/tools/registry.py
Shell execution nanobot/agent/tools/shell.py
Filesystem tools nanobot/agent/tools/filesystem.py
Web search/fetch nanobot/agent/tools/web.py
MCP tools nanobot/agent/tools/mcp.py
Cron nanobot/agent/tools/cron.py, nanobot/cron/
Image generation nanobot/agent/tools/image_generation.py
Runtime self-inspection nanobot/agent/tools/self.py

Tool behavior is part of the model contract. Keep user-visible tool names, schemas, and error messages stable unless a change is intentional.

Config and Paths

The config schema lives in nanobot/config/schema.py. Loading and saving live in nanobot/config/loader.py. Runtime path helpers live in nanobot/config/paths.py.

Defaults:

Path Default
Config ~/.nanobot/config.json
Workspace ~/.nanobot/workspace/
Sessions <workspace>/sessions/*.jsonl
Memory <workspace>/memory/
Cron store <workspace>/cron/jobs.json
WebUI/media/log runtime data config directory subdirectories such as webui/, media/, and logs/

The schema accepts both camelCase and snake_case keys, but saves config with camelCase aliases.

Memory and Sessions

Session history is the near-term conversation replay. Memory is the longer-term workspace state.

Store File area
Session JSONL files <workspace>/sessions/
Long-term memory <workspace>/memory/MEMORY.md
Consolidation source history <workspace>/memory/history.jsonl
Bootstrap identity files <workspace>/SOUL.md, <workspace>/USER.md, templates under nanobot/templates/

Dream is implemented in nanobot/agent/memory.py and scheduled by the runtime when enabled.

Security Boundaries

Security-sensitive code paths include:

Boundary Files
Workspace scope nanobot/security/workspace_access.py, nanobot/security/workspace_policy.py
Shell sandboxing nanobot/agent/tools/shell.py
SSRF/network checks nanobot/security/network.py, nanobot/agent/tools/web.py
PTH guard and CLI startup security nanobot/security/ and CLI entrypoints
Channel access control channel config in nanobot/channels/*.py

When changing tools, channels, file access, WebUI workspace behavior, or network fetching, treat security as part of the functional behavior and update docs if the user-facing boundary changes.

Extension Points

Extension How
Provider Add ProviderSpec in providers/registry.py, add schema field in config/schema.py, implement provider only if the generic backend is not enough
Channel Implement BaseChannel, expose an entry point, follow channel-plugin-guide.md
Tool Implement a tool under agent/tools/ or expose a plugin entry point
MCP Add tools.mcpServers config
Skill Add workspace skill files under <workspace>/skills/ or built-in skills under nanobot/skills/

Prefer existing registry/discovery patterns over ad hoc wiring.

Testing and Verification

Common checks:

pytest tests/test_openai_api.py::test_function -v
ruff check nanobot/
cd webui && bun run test
cd webui && bun run build

Choose tests based on the changed surface:

Change Minimum useful verification
Provider behavior Provider unit tests or a mocked API path; nanobot agent -m "Hello!" with safe config when possible
Channel behavior Channel tests plus nanobot gateway startup path
WebUI behavior WebUI tests/build and, for routing/settings/chat changes, browser-level verification through the gateway
Tool behavior Tool unit tests and an agent-run path when schema or model-facing behavior changes
Docs Link checks, command accuracy against CLI/schema, and git diff --check

For user-facing flows, prefer at least one verification path through the public surface the user actually touches: CLI command, HTTP endpoint, WebSocket/WebUI, chat channel, or packaged import.