Skip to content

Your lightweight open-source personal agent.

7.2 KB
Raw Blame

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.

  1. Add a ProviderSpec entry to PROVIDERS:
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",
)
  1. Add a field to ProvidersConfig in nanobot/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.py owns provider names, aliases, default models, and adapter loading.
  • nanobot/providers/transcription.py owns provider-specific HTTP behavior.

Credentials still live under providers.<provider> so chat channels and WebUI resolve API keys and API bases the same way.

  1. Add provider credentials to ProvidersConfig.
class ProvidersConfig(BaseModel):
    ...
    my_stt: ProviderConfig = Field(default_factory=ProviderConfig)
  1. Add a ProviderSpec in nanobot/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,
)
  1. 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:
        ...
  1. 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",),
)
  1. 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
  1. Update user-facing docs.

Add the provider to configuration.md where users choose transcription.provider, but keep implementation details in this development guide.