Skip to content

Your lightweight open-source personal agent.

refactor(providers): separate API capabilities from registry

chengyongru1df2df68234a
diff --git a/docs/development.md b/docs/development.md
index ab6d4f77f..f746bd4cb 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -72,7 +72,7 @@ Replace `OpenAICompatProvider(api_type=...)` with `OpenAICompatProvider(model_ap
ModelAPICapabilities(supported_apis=("responses",), preferred_api="responses")
```
-These types are defined in `nanobot.providers.registry`. The temporary `apiType` configuration migration applies to JSON configuration and Settings inputs; it does not preserve the old Python constructor arguments.
+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
diff --git a/nanobot/config/schema.py b/nanobot/config/schema.py
index 4ad67acf5..80e42a3ec 100644
--- a/nanobot/config/schema.py
+++ b/nanobot/config/schema.py
@@ -11,7 +11,7 @@ from nanobot.config.provider_api_migration import migrate_legacy_provider_api
from nanobot.config.timezone import detect_system_timezone
from nanobot.config_base import Base
from nanobot.cron.types import CronSchedule
-from nanobot.providers.registry import ModelAPICapabilities, RequestAPI
+from nanobot.providers.model_api import ModelAPICapabilities, RequestAPI
if TYPE_CHECKING:
from nanobot.agent.tools.cli_apps import CliAppsToolConfig
diff --git a/nanobot/providers/github_copilot_provider.py b/nanobot/providers/github_copilot_provider.py
index 3c1f07a03..a04a7f896 100644
--- a/nanobot/providers/github_copilot_provider.py
+++ b/nanobot/providers/github_copilot_provider.py
@@ -19,18 +19,14 @@ from oauth_cli_kit.models import OAuthToken
from oauth_cli_kit.storage import FileTokenStorage
from nanobot.providers.base import LLMResponse, ProviderCallContext
+from nanobot.providers.model_api import ModelAPICapabilities, RequestAPI
from nanobot.providers.oauth_model_catalog import (
OAuthCatalogAuthRequiredError,
OAuthModelCatalog,
OAuthModelCatalogSnapshot,
)
from nanobot.providers.openai_compat_provider import OpenAICompatProvider
-from nanobot.providers.registry import (
- ModelAPICapabilities,
- ProviderModelSpec,
- RequestAPI,
- find_by_name,
-)
+from nanobot.providers.registry import ProviderModelSpec, find_by_name
DEFAULT_GITHUB_DEVICE_CODE_URL = "https://github.com/login/device/code"
DEFAULT_GITHUB_ACCESS_TOKEN_URL = "https://github.com/login/oauth/access_token"
diff --git a/nanobot/providers/model_api.py b/nanobot/providers/model_api.py
new file mode 100644
index 000000000..2736ac153
--- /dev/null
+++ b/nanobot/providers/model_api.py
@@ -0,0 +1,136 @@
+"""Declarative request API capabilities and automatic model defaults."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, cast
+from urllib.parse import urlsplit
+
+RequestAPI = Literal["chat_completions", "responses", "anthropic_messages"]
+ProviderAPI = Literal[
+ "chat_completions", "responses", "anthropic_messages", "bedrock_converse", "transcription",
+]
+
+
+def is_direct_openai_base(api_base: str | None) -> bool:
+ """Return whether the endpoint matches the direct OpenAI routing rule."""
+ if not api_base:
+ return True
+ normalized = api_base.strip().lower().rstrip("/")
+ return "api.openai.com" in normalized and "openrouter" not in normalized
+
+
+def _api_base_identity(api_base: str) -> tuple[str, str | None, int | None, str]:
+ """Normalize an endpoint's origin and optional OpenAI-compatible /v1 suffix."""
+ parsed = urlsplit(api_base.strip())
+ port = parsed.port
+ return (
+ parsed.scheme,
+ parsed.hostname,
+ port if port is not None else {"http": 80, "https": 443}.get(parsed.scheme),
+ parsed.path.rstrip("/").removesuffix("/v1"),
+ )
+
+
+def is_hosted_web_search_type(value: object) -> bool:
+ return isinstance(value, str) and (
+ value == "web_search" or value.startswith("web_search_")
+ )
+
+
+def is_hosted_web_search_tool(tool: object) -> bool:
+ if not isinstance(tool, dict):
+ return False
+ return is_hosted_web_search_type(cast(dict[object, object], tool).get("type"))
+
+
+def hosted_web_search_enabled(
+ extra_body: dict[str, Any], default_tools: tuple[str, ...] = (),
+) -> bool:
+ if "tools" in extra_body:
+ tools = extra_body["tools"]
+ return isinstance(tools, list) and any(
+ is_hosted_web_search_tool(tool) for tool in cast(list[object], tools)
+ )
+ return any(is_hosted_web_search_type(value) for value in default_tools)
+
+
+@dataclass(frozen=True)
+class ModelAPICapabilities:
+ """APIs declared for one model, including its preferred request surface."""
+
+ supported_apis: tuple[RequestAPI, ...] = ("chat_completions",)
+ preferred_api: RequestAPI = "chat_completions"
+
+
+@dataclass(frozen=True)
+class ResponsesCapabilities:
+ """Provider capabilities for the shared OpenAI Responses execution path.
+
+ ``reasoning_replay`` selects whether multi-turn reasoning is retained as
+ encrypted server content, plaintext local history, or not requested.
+ ``endpoint_models`` limits automatic model rules to named API bases;
+ ``models`` applies those rules regardless of the configured endpoint.
+ """
+
+ models: tuple[str, ...] = ()
+ model_prefixes: tuple[str, ...] = ()
+ route_reasoning: bool = False
+ requires_direct_openai_base: bool = False
+ reasoning_replay: Literal["none", "encrypted", "plaintext"] = "none"
+ supports_native_compaction: bool = False
+ allows_chat_fallback: bool = True
+ endpoint_models: tuple[tuple[str, tuple[str, ...]], ...] = ()
+
+ def matches_model(self, model: str, *, api_base: str | None = None) -> bool:
+ """Match curated models, restricting endpoint defaults when a base is supplied."""
+ model_name = model.lower()
+ wire_name = model_name.rsplit("/", 1)[-1]
+ supported_models = self.models + tuple(
+ model_id
+ for base, models in self.endpoint_models
+ if api_base is None or _api_base_identity(api_base) == _api_base_identity(base)
+ for model_id in models
+ )
+ return any(
+ model_name == supported.lower()
+ or model_name.endswith(f"/{supported.lower()}")
+ for supported in supported_models
+ ) or any(wire_name.startswith(prefix.lower()) for prefix in self.model_prefixes)
+
+ def model_api(
+ self, model: str, reasoning_effort: str | None = None,
+ *, api_base: str | None = None,
+ ) -> ModelAPICapabilities:
+ """Resolve the provider's curated API defaults for one model."""
+ if not self.matches_model(model, api_base=api_base) and not (
+ self.route_reasoning and reasoning_effort and reasoning_effort.lower() != "none"
+ ):
+ return ModelAPICapabilities()
+ apis: tuple[RequestAPI, ...] = (
+ ("responses", "chat_completions") if self.allows_chat_fallback else ("responses",)
+ )
+ return ModelAPICapabilities(supported_apis=apis, preferred_api="responses")
+
+ def default_model_api(
+ self,
+ model: str,
+ reasoning_effort: str | None = None,
+ *,
+ api_base: str | None = None,
+ default_api_base: str = "",
+ extra_body: dict[str, Any] | None = None,
+ default_tools: tuple[str, ...] = (),
+ ) -> ModelAPICapabilities:
+ """Apply endpoint, reasoning, and hosted-tool rules to automatic selection."""
+ body = extra_body or {}
+ effective_base = api_base or default_api_base or None
+ # Explicit hosted tools require Responses; defaults follow the endpoint's model rules.
+ search_model_base = None if hosted_web_search_enabled(body) else effective_base
+ if hosted_web_search_enabled(body, default_tools) and (
+ self.route_reasoning or self.matches_model(model, api_base=search_model_base)
+ ):
+ return ModelAPICapabilities(("responses",), "responses")
+ if self.requires_direct_openai_base and not is_direct_openai_base(api_base):
+ return ModelAPICapabilities()
+ return self.model_api(model, reasoning_effort, api_base=effective_base)
diff --git a/nanobot/providers/openai_compat_provider.py b/nanobot/providers/openai_compat_provider.py
index 2aea244a7..20f22d29d 100644
--- a/nanobot/providers/openai_compat_provider.py
+++ b/nanobot/providers/openai_compat_provider.py
@@ -34,14 +34,14 @@ from nanobot.providers.base import (
tool_arguments_json_for_replay,
)
from nanobot.providers.images import prepare_inline_images
-from nanobot.providers.openai_responses import ResponsesBackend, responses_state_matches
-from nanobot.providers.registry import (
+from nanobot.providers.model_api import (
ModelAPICapabilities,
ResponsesCapabilities,
hosted_web_search_enabled,
is_direct_openai_base,
is_hosted_web_search_tool,
)
+from nanobot.providers.openai_responses import ResponsesBackend, responses_state_matches
if TYPE_CHECKING:
from openai import AsyncOpenAI as AsyncOpenAIType
diff --git a/nanobot/providers/registry.py b/nanobot/providers/registry.py
index a0f989df0..6cf125429 100644
--- a/nanobot/providers/registry.py
+++ b/nanobot/providers/registry.py
@@ -13,66 +13,18 @@ Every entry writes out all fields so you can copy-paste as a template.
from __future__ import annotations
from dataclasses import dataclass
-from typing import Any, Literal, cast
-from urllib.parse import urlsplit
+from typing import Any
from pydantic.alias_generators import to_snake
-RequestAPI = Literal["chat_completions", "responses", "anthropic_messages"]
-ProviderAPI = Literal[
- "chat_completions", "responses", "anthropic_messages", "bedrock_converse", "transcription",
-]
-
-
-def is_direct_openai_base(api_base: str | None) -> bool:
- """Return whether the endpoint matches the direct OpenAI routing rule."""
- if not api_base:
- return True
- normalized = api_base.strip().lower().rstrip("/")
- return "api.openai.com" in normalized and "openrouter" not in normalized
-
-
-def _api_base_identity(api_base: str) -> tuple[str, str | None, int | None, str]:
- """Normalize an endpoint's origin and optional OpenAI-compatible /v1 suffix."""
- parsed = urlsplit(api_base.strip())
- port = parsed.port
- return (
- parsed.scheme,
- parsed.hostname,
- port if port is not None else {"http": 80, "https": 443}.get(parsed.scheme),
- parsed.path.rstrip("/").removesuffix("/v1"),
- )
-
-
-def is_hosted_web_search_type(value: object) -> bool:
- return isinstance(value, str) and (
- value == "web_search" or value.startswith("web_search_")
- )
-
-
-def is_hosted_web_search_tool(tool: object) -> bool:
- if not isinstance(tool, dict):
- return False
- return is_hosted_web_search_type(cast(dict[object, object], tool).get("type"))
-
-
-def hosted_web_search_enabled(
- extra_body: dict[str, Any], default_tools: tuple[str, ...] = (),
-) -> bool:
- if "tools" in extra_body:
- tools = extra_body["tools"]
- return isinstance(tools, list) and any(
- is_hosted_web_search_tool(tool) for tool in cast(list[object], tools)
- )
- return any(is_hosted_web_search_type(value) for value in default_tools)
-
-
-@dataclass(frozen=True)
-class ModelAPICapabilities:
- """APIs declared for one model, including its preferred request surface."""
-
- supported_apis: tuple[RequestAPI, ...] = ("chat_completions",)
- preferred_api: RequestAPI = "chat_completions"
+from nanobot.providers.model_api import ModelAPICapabilities as ModelAPICapabilities
+from nanobot.providers.model_api import ProviderAPI as ProviderAPI
+from nanobot.providers.model_api import RequestAPI as RequestAPI
+from nanobot.providers.model_api import ResponsesCapabilities as ResponsesCapabilities
+from nanobot.providers.model_api import hosted_web_search_enabled as hosted_web_search_enabled
+from nanobot.providers.model_api import is_direct_openai_base as is_direct_openai_base
+from nanobot.providers.model_api import is_hosted_web_search_tool as is_hosted_web_search_tool
+from nanobot.providers.model_api import is_hosted_web_search_type as is_hosted_web_search_type
@dataclass(frozen=True)
@@ -89,56 +41,6 @@ class ProviderModelSpec:
api: ModelAPICapabilities | None = None
-@dataclass(frozen=True)
-class ResponsesCapabilities:
- """Provider capabilities for the shared OpenAI Responses execution path.
-
- ``reasoning_replay`` selects whether multi-turn reasoning is retained as
- encrypted server content, plaintext local history, or not requested.
- ``endpoint_models`` limits automatic model rules to named API bases;
- ``models`` applies those rules regardless of the configured endpoint.
- """
-
- models: tuple[str, ...] = ()
- model_prefixes: tuple[str, ...] = ()
- route_reasoning: bool = False
- requires_direct_openai_base: bool = False
- reasoning_replay: Literal["none", "encrypted", "plaintext"] = "none"
- supports_native_compaction: bool = False
- allows_chat_fallback: bool = True
- endpoint_models: tuple[tuple[str, tuple[str, ...]], ...] = ()
-
- def matches_model(self, model: str, *, api_base: str | None = None) -> bool:
- """Match curated models, restricting endpoint defaults when a base is supplied."""
- model_name = model.lower()
- wire_name = model_name.rsplit("/", 1)[-1]
- supported_models = self.models + tuple(
- model_id
- for base, models in self.endpoint_models
- if api_base is None or _api_base_identity(api_base) == _api_base_identity(base)
- for model_id in models
- )
- return any(
- model_name == supported.lower()
- or model_name.endswith(f"/{supported.lower()}")
- for supported in supported_models
- ) or any(wire_name.startswith(prefix.lower()) for prefix in self.model_prefixes)
-
- def model_api(
- self, model: str, reasoning_effort: str | None = None,
- *, api_base: str | None = None,
- ) -> ModelAPICapabilities:
- """Resolve the provider's curated API defaults for one model."""
- if not self.matches_model(model, api_base=api_base) and not (
- self.route_reasoning and reasoning_effort and reasoning_effort.lower() != "none"
- ):
- return ModelAPICapabilities()
- apis: tuple[RequestAPI, ...] = (
- ("responses", "chat_completions") if self.allows_chat_fallback else ("responses",)
- )
- return ModelAPICapabilities(supported_apis=apis, preferred_api="responses")
-
-
@dataclass(frozen=True)
class ProviderSpec:
"""One LLM provider's metadata. See PROVIDERS below for real examples.
@@ -272,21 +174,13 @@ class ProviderSpec:
extra_body: dict[str, Any] | None = None,
) -> ModelAPICapabilities:
"""Resolve automatic API defaults without constructing or probing a client."""
- capabilities = self.responses
- if capabilities is None:
- return ModelAPICapabilities()
- model_name = self.request_model_name(model)
- body = extra_body or {}
- effective_base = api_base or self.default_api_base or None
- # Explicit hosted tools require Responses; defaults follow the endpoint's model rules.
- search_model_base = None if hosted_web_search_enabled(body) else effective_base
- if hosted_web_search_enabled(body, self.responses_default_tools) and (
- capabilities.route_reasoning or capabilities.matches_model(model_name, api_base=search_model_base)
- ):
- return ModelAPICapabilities(("responses",), "responses")
- if capabilities.requires_direct_openai_base and not is_direct_openai_base(api_base):
+ if self.responses is None:
return ModelAPICapabilities()
- return capabilities.model_api(model_name, reasoning_effort, api_base=effective_base)
+ return self.responses.default_model_api(
+ self.request_model_name(model), reasoning_effort,
+ api_base=api_base, default_api_base=self.default_api_base,
+ extra_body=extra_body, default_tools=self.responses_default_tools,
+ )
@property
def model_api_configurable(self) -> bool:
diff --git a/nanobot/providers/routing.py b/nanobot/providers/routing.py
index 8c4089477..7e83c3a7f 100644
--- a/nanobot/providers/routing.py
+++ b/nanobot/providers/routing.py
@@ -5,14 +5,8 @@ from __future__ import annotations
from dataclasses import dataclass
from nanobot.config.schema import Config, ModelAPIConfig, ModelPresetConfig, ProviderConfig
-from nanobot.providers.registry import (
- ModelAPICapabilities,
- ProviderAPI,
- ProviderSpec,
- RequestAPI,
- create_dynamic_spec,
- find_by_name,
-)
+from nanobot.providers.model_api import ModelAPICapabilities, ProviderAPI, RequestAPI
+from nanobot.providers.registry import ProviderSpec, create_dynamic_spec, find_by_name
@dataclass(frozen=True)