Your lightweight open-source personal agent.
Development
This page collects contributor-facing notes for extending nanobot. User-facing setup and runtime options live in configuration.md.
For source and test entry points by task, start with the development navigation. For browser interface changes, use the WebUI change map. For Python setup and contribution checks, see CONTRIBUTING.md. The sections below cover provider extensions.
Adding an LLM Provider
nanobot uses the provider registry in nanobot/providers/registry.py as the source of truth for LLM provider metadata. Most OpenAI-compatible providers need only two changes.
- Add a
ProviderSpecentry toPROVIDERS:
ProviderSpec(
name="myprovider",
keywords=("myprovider", "mymodel"),
env_key="MYPROVIDER_API_KEY",
request_apis=("chat_completions", "responses"),
display_name="My Provider",
default_api_base="https://api.myprovider.com/v1",
)
- Add a field to
ProvidersConfiginnanobot/config/schema.py:
class ProvidersConfig(BaseModel):
...
myprovider: ProviderConfig = Field(default_factory=ProviderConfig)
Environment variables, config matching, provider status, and WebUI credential display derive from those two entries.
Every ProviderSpec must declare request_apis. This lists request formats implemented by the adapter; endpoint and model support are configured separately through connection and preset API declarations. Use anthropic_messages for native Anthropic adapters, bedrock_converse for Bedrock, and transcription for transcription-only providers.
Useful ProviderSpec options:
| Field | Description |
|---|---|
default_api_base |
Default OpenAI-compatible base URL. |
env_extras |
Additional environment variables derived from the provider config. |
model_overrides |
Per-model request parameter overrides. |
is_gateway |
Provider can route many model families, like OpenRouter. |
detect_by_key_prefix |
Match configured gateways by API-key prefix. |
detect_by_base_keyword |
Match configured gateways by API base URL. |
strip_model_prefix |
Strip provider/ before sending the model to the upstream API. |
supports_max_completion_tokens |
Use max_completion_tokens instead of max_tokens. |
responses |
ResponsesCapabilities with automatic model rules, reasoning replay, and fallback policy. |
is_transcription_only |
Provider has credentials but cannot serve chat completions. |
Request API routing
resolve_provider_route in nanobot/providers/routing.py validates connection and preset declarations and selects the adapter. Built-in OpenAI connection declarations set an overridable default; custom connection declarations also limit the preset's allowed APIs.
ProviderSpec.default_model_api resolves automatic model rules from the registry. Copilot uses the account's last successfully discovered supported_endpoints when available. The WebUI preview calls resolve_automatic_model_api without probing endpoints or consulting circuit-breaker state; it reports a preference, not a guarantee of remote support.
Custom presets selecting anthropic_messages use the Anthropic adapter for history, tools, thinking, and streaming. They retain the connection's credentials, base URL, headers, query parameters, body additions, proxy, and model-prefix rules. Reasoning replay and native compaction remain provider-owned; a Responses declaration alone does not enable OpenAI-native compaction on a custom gateway.
Python API migration
Provider integrations must supply ProviderSpec.request_apis. Replace the former responses_models argument with responses=ResponsesCapabilities(models=(...)). Use models for rules shared by an endpoint and its proxies. For a rule tied to a specific endpoint, use endpoint_models:
ResponsesCapabilities(
endpoint_models=(("https://api.myprovider.com/v1", ("mymodel",)),),
)
Endpoint rules compare the URL origin and path, treating an optional trailing /v1 as equivalent. Explicit preset API declarations override automatic rules.
Replace OpenAICompatProvider(api_type=...) with OpenAICompatProvider(model_api=...). Omitting model_api preserves automatic selection. To require Responses, pass:
ModelAPICapabilities(supported_apis=("responses",), preferred_api="responses")
API types and automatic selection rules are defined in nanobot.providers.model_api. The registry owns ProviderSpec, model metadata, and provider declarations; it also re-exports the API types. The temporary apiType configuration migration applies to JSON configuration and Settings inputs; it does not preserve the old Python constructor arguments.
Adding a Transcription Provider
Transcription is intentionally split into two layers:
nanobot/audio/transcription_registry.pyowns provider names, aliases, default models, and adapter loading.nanobot/providers/transcription.pyowns provider-specific HTTP behavior.
Credentials still live under providers.<provider> so chat channels and WebUI resolve API keys and API bases the same way.
- Add provider credentials to
ProvidersConfig.
class ProvidersConfig(BaseModel):
...
my_stt: ProviderConfig = Field(default_factory=ProviderConfig)
- Add a
ProviderSpecinnanobot/providers/registry.py.
For transcription-only providers, set is_transcription_only=True so they show up in credential/settings surfaces but stay out of chat model selection.
ProviderSpec(
name="my_stt",
keywords=("my_stt",),
env_key="MY_STT_API_KEY",
request_apis=("transcription",),
display_name="My STT",
default_api_base="https://api.example.com/v1",
is_transcription_only=True,
)
- Add an adapter class in
nanobot/providers/transcription.py.
Adapters receive resolved credentials and settings. They return an empty string for provider errors so channel voice messages fail quietly instead of crashing the agent loop.
class MySTTTranscriptionProvider:
def __init__(
self,
api_key: str | None = None,
api_base: str | None = None,
language: str | None = None,
model: str | None = None,
):
self.api_key = api_key or os.environ.get("MY_STT_API_KEY")
self.api_base = api_base or "https://api.example.com/v1"
self.language = language or None
self.model = model or "my-default-stt-model"
async def transcribe(self, file_path: str | Path) -> str:
...
- Register the adapter in
nanobot/audio/transcription_registry.py.
TranscriptionProviderSpec(
name="my_stt",
default_model="my-default-stt-model",
adapter="nanobot.providers.transcription:MySTTTranscriptionProvider",
aliases=("mystt",),
)
- Add tests.
At minimum, cover:
- config resolution in
tests/providers/test_transcription.py - adapter request/response behavior and retry/error handling
- WebUI settings payload/update behavior in
tests/webui/test_settings_api.py - provider brand mapping if the provider appears in Settings
- Update user-facing docs.
Add the provider to configuration.md where users choose transcription.provider, but keep implementation details in this development guide.