Your lightweight open-source personal agent.
Python agent-frameworkai-agentai-agentschatbotchatopsdiscord-botllm-agentsllmslocal-llmmcpmodel-context-protocolmulti-agentopenai-compatibleopenclawpersonal-ai-assistantpythonself-hostedtelegram-bot-ai-assistantwebuiworkflow-automation
refactor(providers): separate API capabilities from registry
chengyongru1df2df68234a
diff --git a/docs/development.md b/docs/development.mdindex ab6d4f77f..f746bd4cb 100644--- a/docs/development.md+++ b/docs/development.md@@ -72,7 +72,7 @@ Replace `OpenAICompatProvider(api_type=...)` with `OpenAICompatProvider(model_apModelAPICapabilities(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 Providerdiff --git a/nanobot/config/schema.py b/nanobot/config/schema.pyindex 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_apifrom nanobot.config.timezone import detect_system_timezonefrom nanobot.config_base import Basefrom nanobot.cron.types import CronSchedule-from nanobot.providers.registry import ModelAPICapabilities, RequestAPI+from nanobot.providers.model_api import ModelAPICapabilities, RequestAPIif TYPE_CHECKING:from nanobot.agent.tools.cli_apps import CliAppsToolConfigdiff --git a/nanobot/providers/github_copilot_provider.py b/nanobot/providers/github_copilot_provider.pyindex 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 OAuthTokenfrom oauth_cli_kit.storage import FileTokenStoragefrom nanobot.providers.base import LLMResponse, ProviderCallContext+from nanobot.providers.model_api import ModelAPICapabilities, RequestAPIfrom 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_nameDEFAULT_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.pynew file mode 100644index 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.pyindex 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_matchesif TYPE_CHECKING:from openai import AsyncOpenAI as AsyncOpenAITypediff --git a/nanobot/providers/registry.py b/nanobot/providers/registry.pyindex 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 annotationsfrom dataclasses import dataclass-from typing import Any, Literal, cast-from urllib.parse import urlsplit+from typing import Anyfrom 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,+ )@propertydef model_api_configurable(self) -> bool:diff --git a/nanobot/providers/routing.py b/nanobot/providers/routing.pyindex 8c4089477..7e83c3a7f 100644--- a/nanobot/providers/routing.py+++ b/nanobot/providers/routing.py@@ -5,14 +5,8 @@ from __future__ import annotationsfrom dataclasses import dataclassfrom 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)