| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747 |
- """Provider profile base class.
- A ProviderProfile declares everything about an inference provider in one place:
- auth, endpoints, client quirks, request-time quirks. The transport reads this
- instead of receiving 20+ boolean flags.
- Provider profiles are DECLARATIVE — they describe the provider's behavior.
- They do NOT own client construction, credential rotation, or streaming.
- Those stay on AIAgent.
- """
- from __future__ import annotations
- import logging
- import threading
- from dataclasses import KW_ONLY, dataclass, field
- from typing import TYPE_CHECKING, Any, Callable
- if TYPE_CHECKING:
- from agent.account_usage import AccountUsageSnapshot
- logger = logging.getLogger(__name__)
- # Sentinel for "omit temperature entirely" (Kimi: server manages it)
- OMIT_TEMPERATURE = object()
- def _profile_user_agent() -> str:
- """Return a ``hermes-cli/<version>`` UA string, with a stable fallback.
- Used by ``ProviderProfile.fetch_models`` so the catalog probe is not
- served the default ``Python-urllib/<ver>`` UA — some providers
- (OpenCode Zen, etc.) sit behind a WAF that returns 403 for that.
- """
- try:
- from hermes_cli.version_info import get_version_info # lazy: avoid layer cycle at import time
- return f"hermes-cli/{get_version_info().base_version}"
- except Exception:
- return "hermes-cli"
- _RESOLVE_LOCK = threading.RLock() # re-entrant: a callback may read another LazyHeaders
- class LazyHeaders(dict[str, str]):
- """``default_headers`` whose callable values (a User-Agent carrying the release) run on first read.
- A source checkout resolves the release from git, and every CLI start imports all provider plugins
- (``hermes_cli.config`` lists their env vars), so headers built at import made every command pay git
- subprocesses for a request it may never send. Keys are stored up front, so ``in``/``len`` stay lazy,
- and the class stays a real ``dict``: plugins copy, merge, mutate and serialize ``default_headers``.
- Every method that reads or writes a value resolves first; ``__iter__`` is overridden so CPython's
- ``dict(x)``/``{**x}``/``f(**x)`` merge leaves its raw-storage fast path for ``keys()`` +
- ``__getitem__``, and ``json.dumps`` takes ``items()`` because the stored keys make the dict
- non-empty. Copies (``.copy()``, ``|``, ``copy``/``pickle``) are plain resolved dicts.
- """
- __slots__ = ("_pending",)
- def __init__(self, *args: Any, **kwargs: Any) -> None:
- super().__init__(*args, **kwargs)
- self._pending = any(callable(value) for value in dict.values(self))
- def _resolved(self) -> LazyHeaders:
- if self._pending:
- # One resolver: concurrent first reads (parallel aux clients) would each walk git.
- with _RESOLVE_LOCK:
- if self._pending:
- for key, value in list(dict.items(self)):
- if callable(value):
- dict.__setitem__(self, key, value())
- self._pending = False
- return self
- def __getitem__(self, key: str) -> str:
- return dict.__getitem__(self._resolved(), key)
- def __iter__(self):
- return dict.__iter__(self._resolved())
- def __reversed__(self):
- return dict.__reversed__(self._resolved())
- def __repr__(self) -> str:
- return dict.__repr__(self._resolved())
- def __eq__(self, other: object) -> bool:
- return dict.__eq__(self._resolved(), other._resolved() if isinstance(other, LazyHeaders) else other)
- def __ne__(self, other: object) -> bool:
- equal = self.__eq__(other)
- return equal if equal is NotImplemented else not equal
- def __or__(self, other: Any) -> Any:
- return dict.__or__(self._resolved(), other)
- def __ror__(self, other: Any) -> Any:
- return dict.__or__(other, self._resolved()) if isinstance(other, dict) else NotImplemented
- def __ior__(self, other: Any) -> LazyHeaders:
- return dict.__ior__(self._resolved(), other)
- def __reduce__(self) -> tuple:
- return (dict, (dict.copy(self._resolved()),))
- def get(self, key: str, default: Any = None) -> Any:
- return dict.get(self._resolved(), key, default)
- def keys(self):
- return dict.keys(self._resolved())
- def values(self):
- return dict.values(self._resolved())
- def items(self):
- return dict.items(self._resolved())
- def copy(self) -> dict[str, str]:
- return dict.copy(self._resolved())
- def __setitem__(self, key: str, value: str) -> None:
- dict.__setitem__(self._resolved(), key, value)
- def __delitem__(self, key: str) -> None:
- dict.__delitem__(self._resolved(), key)
- def pop(self, *args: Any) -> Any:
- return dict.pop(self._resolved(), *args)
- def popitem(self) -> tuple[str, str]:
- return dict.popitem(self._resolved())
- def setdefault(self, key: str, default: Any = None) -> Any:
- return dict.setdefault(self._resolved(), key, default)
- def update(self, *args: Any, **kwargs: Any) -> None:
- dict.update(self._resolved(), *args, **kwargs)
- @dataclass
- class ProviderProfile:
- """Base provider profile — subclass or instantiate with overrides."""
- # ── Identity ─────────────────────────────────────────────
- name: str
- api_mode: str = "chat_completions"
- aliases: tuple = ()
- # ── Human-readable metadata ───────────────────────────────
- display_name: str = "" # e.g. "GMI Cloud" — shown in picker/labels
- description: str = "" # e.g. "GMI Cloud (multi-model direct API)" — picker subtitle
- signup_url: str = "" # e.g. "https://www.gmicloud.ai/" — shown during setup
- # True when the provider is pre-release / not for public listing. Discovery surfaces (provider
- # pickers, the setup provider list, the dashboard accounts tab) skip it unless ``listed()``
- # says otherwise; resolution by name is untouched, so an explicit ``model.provider`` /
- # ``hermes auth add <name>`` keeps working.
- hidden: bool = False
- # ── Auth & endpoints ─────────────────────────────────────
- env_vars: tuple = ()
- base_url: str = ""
- models_url: str = "" # explicit models endpoint; falls back to {base_url}/models
- auth_type: str = "api_key" # api_key|oauth_device_code|oauth_external|external_process|aws_sdk|plugin-defined
- # None preserves transport defaults (external-process clients default to non-streaming).
- # True opts a streaming-capable process client in; False disables streaming for this provider.
- supports_streaming: bool | None = field(default=None, kw_only=True)
- supports_health_check: bool = True # False → doctor skips /models probe for this provider
- # False → fetch_models returns None without a network call (catalog comes from an SDK/subprocess).
- supports_model_listing: bool = True
- # ── Provider-owned auth (optional; non-api-key plugins) ──────────
- # ``auth_handler(action, args) -> bool``: ``hermes auth add|status|logout|refresh <name>`` calls it
- # FIRST with the parsed CLI namespace; truthy = the plugin owned the action, falsy = built-in path.
- # ``refresh_credential(entry) -> Mapping | None``: the credential pool's refresh of a pooled OAuth
- # row — return the rotated fields (``access_token``, ``refresh_token``, ``expires_at_ms`` …) or raise.
- # Both own their own token endpoints; Hermes passes no secrets beyond the pooled row itself.
- # ``classify_api_error(error, *, status_code, error_code, message, body, model) -> Mapping | None``:
- # consulted by ``agent.error_classifier.classify_api_error`` for THIS provider's failures only, after
- # the generic ``transform_api_error_classification`` plugin hooks and before the built-in pipeline.
- # Return ``{"reason": <FailoverReason name>, ...hint flags}`` to override, ``None`` to decline.
- auth_handler: Callable[[str, Any], Any] | None = None
- refresh_credential: Callable[[Any], Any] | None = None
- classify_api_error: Callable[..., Any] | None = None
- # ── Vision support ────────────────────────────────────────
- # True when the provider's API accepts image content inside
- # tool-result messages natively. Set on providers that expose
- # multimodal models via tool results (Anthropic Messages API,
- # OpenAI Chat Completions, Gemini, MiniMax, etc.).
- # Falls back to model-catalog lookup when False and the provider
- # has no registered profile.
- supports_vision: bool = False
- # True when the provider's API accepts list-type tool message
- # content (multipart with image_url parts). Defaults to True for
- # backward compatibility. Set to False for providers that accept
- # multimodal user messages but reject list-type tool content
- # (e.g. Xiaomi MiMo, which returns 400 "text is not set").
- supports_vision_tool_messages: bool = True
- # True only when this provider's Chat Completions endpoint explicitly
- # documents ``prompt_cache_key`` as an accepted request body field. This
- # is deliberately opt-in: many OpenAI-compatible endpoints reject unknown
- # top-level fields rather than ignoring them.
- supports_prompt_cache_key: bool = False
- # Private replay carriers use a namespaced '<provider>.native_assistant' type
- # in reasoning_details. Only this profile may receive its matching carrier;
- # other providers (including an unregistered fallback) get ordinary details only.
- native_reasoning_details_type: str | None = None
- # ── External-process providers (auth_type="external_process") ──
- # An agent CLI driven over stdio (ACP) rather than an HTTP endpoint. These
- # describe how to launch it; hermes_cli/auth.py's
- # resolve_external_process_provider_credentials() reads them instead of
- # hardcoding one vendor's binary. Env vars are checked in order and win
- # over the static defaults, so an operator can point at a custom build.
- process_command: str = "" # default binary, e.g. "kimchi"
- process_args: tuple = () # default argv tail, e.g. ("--mode", "acp")
- process_command_env_vars: tuple = () # env overrides for the binary, in priority order
- process_args_env_var: str = "" # env override for argv (shlex-split)
- # ── Model catalog ─────────────────────────────────────────
- # fallback_models: curated list shown in /model picker when live fetch fails.
- # Only agentic models that support tool calling should appear here.
- fallback_models: tuple = ()
- # model_aliases: short name -> id in fallback_models, for providers whose catalog is not
- # in models.dev (external processes); `/model <alias>` resolves here before core guessing.
- model_aliases: dict = field(default_factory=dict)
- # hostname: base hostname for URL→provider reverse-mapping in model_metadata.py
- # e.g. "api.gmi-serving.com". Derived from base_url when empty.
- hostname: str = ""
- # ── Client-level quirks (set once at client construction) ─
- default_headers: dict[str, str] = field(default_factory=dict)
- # ── Request-level quirks ─────────────────────────────────
- # Temperature: None = use caller's default, OMIT_TEMPERATURE = don't send
- fixed_temperature: Any = None
- default_max_tokens: int | None = None
- # ``response_format`` types the API rejects outright (e.g. ("json_schema",)); aux requests omit them up front.
- unsupported_response_formats: tuple = ()
- default_aux_model: str = (
- "" # cheap model for auxiliary tasks (compression, vision, etc.)
- )
- # empty = use main model
- # Per-model metadata in the canonical model_overrides schema. Partial entries
- # patch catalog metadata; explicit user overrides still win. Exact model IDs.
- model_capabilities: dict[str, dict[str, Any]] = field(default_factory=dict)
- # Every field below was added after the released positional layout above: keyword-only, so a
- # plugin subclass's own positional options keep their constructor slots.
- _: KW_ONLY
- # ── L6: provider-owned setup + sign-in surfaces (all optional; None/empty = core's generic path) ──
- # ``account_card``: Accounts-tab card overrides ``{name, flow, cli_command, docs_url}`` for the
- # Desktop/dashboard (``/api/providers/oauth``); non-empty also lists a Keys-tab profile there.
- account_card: dict[str, str] = field(default_factory=dict)
- # ``account_status() -> Mapping``: that card's live status (``logged_in``, ``source``, ``source_label``…);
- # subprocess- and network-free, it runs on every Accounts list. None = ``auth.get_auth_status(name)``.
- account_status: Callable[[], Any] | None = None
- # In-app device-code sign-in (Desktop "Login" button; the card's flow becomes ``device_code``):
- # ``start_device_login() -> {user_code, verification_url, expires_in, interval, state}`` asks the
- # provider for a code; ``poll_device_login(state) -> {status: pending|approved|denied|expired,
- # interval?, credential?, message?}`` makes ONE poll; ``save_device_login(credential)`` persists it.
- # Core owns the wait loop and cancellation and calls save inside the session's profile scope.
- start_device_login: Callable[[], Any] | None = None
- poll_device_login: Callable[[Any], Any] | None = None
- save_device_login: Callable[[Any], None] | None = None
- # ``model_setup_flow(config, current_model, args)``: this provider's own ``hermes model`` step
- # (credential prompt, catalog, persist); None = the generic flow for its auth_type.
- model_setup_flow: Callable[[Any, str, Any], Any] | None = None
- # ``setup_reasoning_efforts(model) -> tuple | None``: levels the setup effort picker offers for
- # *model*; ``()`` = no reasoning control, None = the generic ladder gated by models.dev.
- setup_reasoning_efforts: Callable[[str], Any] | None = None
- # ── Hooks (override in subclass for complex providers) ───
- def fetch_account_usage(
- self, *, base_url: str | None = None, api_key: str | None = None
- ) -> AccountUsageSnapshot | None:
- """Return an account-usage snapshot for this provider, if available.
- The ``/usage`` command invokes this only when no built-in account
- usage fetcher owns the provider. Implementations may make their
- provider-specific request and must return an ``AccountUsageSnapshot``
- or ``None``; exceptions fail open at the dispatch boundary.
- """
- return None
- def resolve_aux_model(self, *, vision: bool = False) -> str:
- """Return a LIVE cheap-model id for auxiliary tasks, or "".
- ``default_aux_model`` is a hardcoded id in source, so it rots: when the
- provider retires that model every auxiliary call spends a round-trip
- 404ing before the retry net catches it. Providers that publish a
- machine-readable recommendation should override this and query it, so
- the cheap tier tracks the upstream catalog instead of a constant a human
- has to remember to bump.
- Contract: cheap to call (implementations must cache — this runs on
- client-resolution paths), never raises, and returns "" when it has no
- answer so the caller falls through to ``default_aux_model``.
- """
- return ""
- def get_hostname(self) -> str:
- """Return the provider's base hostname for URL-based detection.
- Uses self.hostname if set explicitly, otherwise derives it from base_url.
- e.g. 'https://api.gmi-serving.com/v1' → 'api.gmi-serving.com'
- """
- if self.hostname:
- return self.hostname
- if self.base_url:
- from urllib.parse import urlparse
- return urlparse(self.base_url).hostname or ""
- return ""
- def prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
- """Provider-specific message preprocessing.
- Called AFTER codex field sanitization, BEFORE developer role swap.
- Default: pass-through.
- """
- return messages
- def build_extra_body(
- self, *, session_id: str | None = None, **context: Any
- ) -> dict[str, Any]:
- """Provider-specific extra_body fields.
- Merged into the API kwargs extra_body. Default: empty dict.
- """
- return {}
- def default_reasoning_config(self, model: str | None = None) -> dict | None:
- """Reasoning config the main loop sends when ``agent.reasoning_effort`` is unset.
- None (default) hands the unset state to ``build_api_kwargs_extras`` as ``reasoning_config=None``,
- where each profile already decides (Nous/OpenRouter fill medium; Anthropic omits). A profile
- that would otherwise leave the route's own default in charge returns the config here so the
- agent records it as what went on the wire (the reasoning-rejection ladder reads that).
- """
- return None
- def build_api_kwargs_extras(
- self,
- *,
- reasoning_config: dict | None = None,
- **context: Any,
- ) -> tuple[dict[str, Any], dict[str, Any]]:
- """Provider-specific kwargs split between extra_body and top-level api_kwargs.
- Returns (extra_body_additions, top_level_kwargs).
- The transport merges extra_body_additions into extra_body, and
- top_level_kwargs directly into api_kwargs.
- This split exists because some providers put reasoning config in
- extra_body (OpenRouter: extra_body.reasoning) while others put it
- as top-level api_kwargs (Kimi: api_kwargs.reasoning_effort).
- Default: ({}, {}).
- """
- return {}, {}
- def build_client_kwargs_extras(self, **context: Any) -> dict[str, Any]:
- """Provider-specific OpenAI client keyword arguments.
- Values are defaults: explicit runtime/custom-provider settings win.
- The returned mapping must be cheap to build and must not perform I/O.
- """
- return {}
- def default_vision_model(self) -> str | None:
- """Return a default vision model id for this provider, or None.
- Overrideable hook for providers that discover their vision default at
- runtime (e.g. from a live catalog) rather than pinning one in code.
- Keeps provider-specific vision discovery inside the provider's plugin
- instead of a name-check branch in shared vision resolution.
- Default: None (no provider-specific vision model — the caller falls
- back to the user's chat model or the aggregator chain).
- """
- return None
- def get_model_context_length(self, model: str) -> int | None:
- """Provider-qualified context bound; explicit user overrides take precedence."""
- return None
- def get_usage_cost(self, model: str, usage: Any) -> Any | None:
- """Optional CostResult from canonical usage; distinguish estimates from invoices."""
- return None
- def get_max_tokens(self, model: str | None) -> int | None:
- """Return the default max_tokens cap for *model*.
- Overrideable hook for providers that need per-model output caps —
- e.g. a relay that fronts several upstream backends, each with a
- different completion-token limit. The transport calls this when
- the user hasn't set an explicit max_tokens.
- Default: return self.default_max_tokens (the static profile field),
- ignoring the model name. Override in a subclass to vary the cap
- per-model.
- """
- return self.default_max_tokens
- def supported_reasoning_efforts(
- self, model: str | None
- ) -> tuple[str, ...] | None:
- """Declared reasoning-effort vocabulary for *model* on this provider.
- Overrideable hook for providers whose gateway validates
- ``reasoning.effort`` per model instead of ignoring or clamping
- unknown levels server-side (Ramp Router derives this from its live
- ``/v1/models`` catalog). The Responses transport consults it before
- falling back to its built-in per-backend vocabularies; it is the
- profile-declared analog of the OpenRouter catalog clamp on the
- chat-completions path (``openrouter_model_reasoning_capabilities``).
- Tri-state contract:
- - ``None`` — unknown/undeclared: the transport keeps its default
- vocabulary for the wire (this base implementation).
- - ``()`` — the model accepts NO reasoning parameters at all; the
- transport must omit reasoning fields entirely (some gateways
- return HTTP 400 rather than ignoring them).
- - non-empty tuple — clamp the requested effort onto these levels
- (``agent.reasoning_effort.clamp_effort`` semantics: nearest
- weaker supported level, never escalate).
- Implementations are called on the per-request hot path and must not
- block on network I/O — answer from a cache and return None while
- cold.
- """
- return None
- # ── L1 wire seams (per-model wire, endpoint-keyed headers, max-tokens param) ──
- # Endpoint-keyed hooks take the request's ``base_url``: core asks the named provider's profile first,
- # then any registered profile overriding the hook (``agent.provider_route_hooks``), so a ``custom``
- # route pointed at this provider's host is served too. Return None / ``{}`` for an endpoint that is
- # not yours. All four are pure: no I/O unless the docstring says so.
- def api_mode_for_model(self, model: str, *, api_key: str | None = None) -> str | None:
- """Wire (``api_mode``) this provider serves *model* on, or None to keep the static ``api_mode``.
- ``api_key=None`` is the pure hot path (agent init, fallback, aux client builds): answer from the
- id alone. A string ``api_key`` comes from resolution-time callers (``/model``, runtime resolve),
- which may consult a cached live catalog with that credential to normalize the id first.
- """
- return None
- def client_headers(
- self, *, base_url: str, api_key: str = "", has_images: bool = False,
- ) -> dict[str, str] | None:
- """Default headers for an OpenAI client built for *base_url*, or None when this profile has no
- endpoint-specific headers there (core then uses the static ``default_headers``). ``has_images``
- asks for the headers of a request-scoped client carrying native image parts. Core merges user
- ``model.default_headers`` over the result and re-adds missing keys on snapshot rebuilds."""
- return None
- def request_headers(self, *, base_url: str, model: str = "", user_initiated: bool = False) -> dict[str, str]:
- """Per-request headers (``extra_headers``) for *base_url*; ``user_initiated`` is True only on the
- first attempt of a user turn's first API call (attribution). Pure: core memoizes the answer per argument set."""
- return {}
- def max_tokens_param(self, *, base_url: str, model: str = "") -> str | None:
- """``"max_completion_tokens"`` / ``"max_tokens"`` for requests to *base_url*, or None for the
- core heuristic (direct OpenAI / Azure host or newer OpenAI model families). Pure: memoized per arguments."""
- return None
- def listed(self) -> bool:
- """Whether discovery surfaces may offer this provider.
- Every non-``hidden`` profile is listed. A ``hidden`` (pre-release) one surfaces once the user
- opted in by name (``hermes auth add <name>`` put a row in its credential pool), so the
- pickers can then offer it. Reads auth.json only: it runs on every picker build.
- """
- if not self.hidden:
- return True
- from hermes_cli.auth import read_credential_pool # lazy: providers/ must not import hermes_cli at load
- return bool(read_credential_pool(self.name))
- def create_client(self, **client_kwargs: Any) -> Any | None:
- """Return a provider-specific client, or ``None`` for the standard one.
- Most providers speak OpenAI-compatible HTTP and want the shared
- ``openai.OpenAI`` client the core builds — they inherit this and return
- ``None``. A provider whose wire protocol is not HTTP at all (the ACP
- subprocess shims) or which needs a native SDK overrides this and
- returns its own client object.
- ``client_kwargs`` is the same mapping the core would have passed to
- ``openai.OpenAI`` (``api_key``, ``base_url``, ``command``, ``args``,
- timeouts, headers…). Unknown keys must be tolerated: the core adds to
- this mapping over time, so an override should accept ``**kwargs`` and
- pick what it needs rather than enumerate.
- Returning ``None`` (the default) is always safe — the caller falls
- through to its existing construction path.
- This is the hook that lets a provider ship *outside* this tree: with it,
- a profile registered from ``~/.hermes/plugins/model-providers/`` or a
- pip entry point can supply its own transport without any core edit. See
- ``website/docs/developer-guide/model-provider-plugin.md``.
- """
- return None
- def setup_status(self, **kwargs: Any) -> dict[str, Any] | None:
- """External-process providers: ``{available, logged_in, plan, detail, login_command}`` from the
- CLI itself so setup can gate on login. ``None`` = nothing to report beyond executable presence."""
- return None
- def discover_models(self, **kwargs: Any) -> list[dict[str, Any]] | None:
- """External-process providers: the account's live picker as ``[{id, label, note}]`` without
- any inference request; ``None`` falls back to ``fallback_models``."""
- return None
- def fetch_models(
- self,
- *,
- api_key: str | None = None,
- base_url: str | None = None,
- timeout: float = 8.0,
- ) -> list[str] | None:
- """Fetch the live model list from the provider's models endpoint.
- Returns a list of model ID strings, or None if the fetch failed or
- the provider does not support live model listing.
- Resolution order for the endpoint URL:
- 1. base_url + "/models", but ONLY when the caller passed a base_url
- that differs from this profile's default (a user-configured
- model.base_url pointing at a proxy/custom endpoint). Callers
- pass base_url unconditionally — falling back to the profile
- default when the user configured nothing — so equality with
- self.base_url means "not customised" and must not shadow
- models_url.
- 2. self.models_url (explicit override — use when the models
- endpoint differs from the inference base URL, e.g. OpenRouter
- exposes a public catalog at /api/v1/models while inference is
- at /api/v1)
- 3. self.base_url + "/models" (standard OpenAI-compat fallback)
- The default implementation sends Bearer auth when api_key is given
- and forwards self.default_headers. Override to customise auth, path,
- response shape, or to return None for providers with no REST catalog.
- Callers must always fall back to the static _PROVIDER_MODELS list
- when this returns None.
- """
- if not self.supports_model_listing:
- return None
- caller_base = (base_url or "").strip()
- effective_base = caller_base or self.base_url
- custom_base = bool(caller_base) and (
- caller_base.rstrip("/") != (self.base_url or "").rstrip("/")
- )
- if custom_base:
- url = caller_base.rstrip("/") + "/models"
- else:
- url = (self.models_url or "").strip()
- if not url:
- if not effective_base:
- return None
- url = effective_base.rstrip("/") + "/models"
- import json
- import urllib.request
- from hermes_cli.urllib_security import open_credentialed_url
- req = urllib.request.Request(url)
- if api_key:
- req.add_header("Authorization", f"Bearer {api_key}")
- req.add_header("Accept", "application/json")
- # Some providers (e.g. OpenCode Zen) sit behind a WAF that blocks
- # the default ``Python-urllib/<ver>`` User-Agent. Set a generic
- # hermes-cli UA so the catalog endpoint is reachable.
- req.add_header("User-Agent", _profile_user_agent())
- for k, v in self.default_headers.items():
- req.add_header(k, v)
- try:
- with open_credentialed_url(req, timeout=timeout) as resp:
- data = json.loads(resp.read().decode())
- items = data if isinstance(data, list) else data.get("data", [])
- from hermes_cli.chat_catalog import chat_catalog_ids
- return chat_catalog_ids(items)
- except Exception as exc:
- logger.debug("fetch_models(%s): %s", self.name, exc)
- return None
- # ── Lane L4: catalog / metadata seams ─────────────────────
- # Hosts (exact or any subdomain) that serve THIS provider's API, so a ``custom`` endpoint or an
- # auto-routed aux client at one of them is recognised as this provider (``providers.profile_for_host``).
- # It also makes ``reasoning_payload`` the reasoning gate there, except on hosts core gates itself
- # (OpenRouter, Ollama Cloud, Nous Portal, Vercel AI Gateway, the ``lmstudio`` provider).
- hostnames: tuple = ()
- # Hosts that identify this provider's catalog for model metadata (context length, models.dev) but
- # take other credentials; matched only by ``profile_for_host(url, metadata=True)``.
- metadata_hostnames: tuple = ()
- # models.dev provider id when it differs from ``name`` (e.g. ``fireworks`` -> ``fireworks-ai``).
- models_dev_id: str = ""
- def live_context_length(self, model: str, *, api_key: str = "", base_url: str = "") -> int | None:
- """Context window from the provider's live, credentialed catalog; consulted after the persistent cache."""
- return None
- def normalize_model_id(self, model: str, *, api_key: str = "") -> str | None:
- """Provider-native id for *model* (alias table, catalog repair); None = core's generic normalization."""
- return None
- # ── Lane L2: provider-owned credential seams ──────────────────────────────
- # Credentials are commonly ambient (another tool's login, a token exported for other purposes):
- # never auto-detected as the inference provider, and the auxiliary fallback chain skips the
- # provider unless the user explicitly configured it.
- ambient_credentials: bool = field(default=False, kw_only=True)
- def resolve_api_key_secret(self) -> tuple[str, str] | None:
- """Provider-owned ``(runtime_api_key, source)`` resolution; None = generic env/pool ladder."""
- return None
- def runtime_base_url(self, *, api_key: str, default: str, env_url: str) -> str | None:
- """Runtime base URL derived from the credential (e.g. an account endpoint); None = env or default."""
- return None
- def prepare_pool_entry(self, entry: Any, api_key: str) -> str:
- """Turn the selected pool row's secret into the runtime key (may update ``entry``); default as-is."""
- return api_key
- def seed_pool_credentials(self, *, suppressed_sources: frozenset[str],
- explicitly_configured: bool) -> list[dict] | None:
- """Pool rows ``{source, access_token, base_url, label}`` this provider seeds itself; skip any source in
- ``suppressed_sources`` (``hermes auth remove``). Plain data, so it crosses ``plugins.isolation: host``.
- Overriding it replaces generic env seeding (that loop would overwrite exchanged tokens with the raw env
- value), so an override returns ``[]`` for none; only the base implementation keeps generic env seeding."""
- return None
- def remove_credential_source(self, source: str) -> tuple[tuple[str, ...], tuple[str, ...]] | None:
- """``hermes auth remove`` of *source*: ``(sources_to_suppress, hints)``; None = generic removal."""
- return None
- def refresh_runtime_credentials(self, *, reason: str) -> tuple[str, str | None] | None:
- """Re-mint the live client's ``(api_key, base_url or None)`` on ``reason`` (``unauthorized`` |
- ``stale`` | ``auxiliary_unauthorized``); None = nothing fresher. Error path only, I/O allowed."""
- return None
- def is_stale_credential_error(self, *, status_code: int | None, message: str) -> bool:
- """True when a non-auth error really means the credential went stale (pure, no I/O)."""
- return False
- def credential_refresh_notice(self, *, reason: str) -> str:
- """Status line after ``refresh_runtime_credentials(reason=...)`` succeeded; "" = generic wording."""
- return ""
- def request_rejection_hint(self, *, status_code: int | None, base_url: str) -> tuple[str, ...]:
- """User-facing lines explaining an endpoint's hard rejection of *any* route (pure); default none."""
- return ()
- def external_auth_evidence(self) -> tuple[bool, str | None] | None:
- """Subprocess-free ``(verified, source)`` login evidence for an external CLI; None = binary resolves."""
- return None
- def missing_credentials_hint(self) -> str | None:
- """One sentence appended to every "No usable credentials found" surface (runtime resolution, CLI and
- Desktop readiness), e.g. the provider's own sign-in command; None = the generic message alone."""
- return None
- # ── Lane L3: Responses-route quirks and message-level reasoning carriers ───
- # Every field and hook below applies only on hosts the profile declares in ``hostnames``;
- # the defaults are the generic wire. Hot path: answers must be pure and cheap (no I/O). A hook that
- # raises is logged once and answers the default for the rest of the session (provider_route_hooks).
- responses_replay_item_ids: bool = True # replayed Responses ``message`` items keep their ``id``
- responses_prompt_cache_key: bool = True # the Responses body carries ``prompt_cache_key``
- responses_issuer_kind: str = "" # persisted stamp for encrypted reasoning minted here ("" = URL-derived)
- responses_trusts_completed_status: bool = True # False: a reasoning-only ``completed`` response continues
- responses_native_compaction: bool = True # False: never send ``context_management``
- responses_profile_reasoning: bool = False # True: ``reasoning`` = ``reasoning_payload`` + summary, no ``include``
- message_carrier_opaque: str = "" # top-level assistant key of an opaque reasoning blob (latest streamed wins)
- message_carrier_text: str = "" # top-level assistant key of readable reasoning text (streamed parts concatenate)
- replays_tool_call_signatures: bool = False # tool calls keep Gemini ``extra_content`` signatures (by provider name)
- def reasoning_payload(self, model: str | None, reasoning_config: dict | None, *, base_url: str) -> dict | None:
- """Verbatim ``reasoning`` object the endpoint takes for *model* (catalog-clamped), or None for none.
- Pure: memoized per arguments."""
- return None
- def replay_message_carriers(self, values: dict[str, Any], *, model: str | None, base_url: str) -> dict[str, Any]:
- """Captured message carriers (``message_carrier_*`` keys) to put back on a replayed assistant message.
- Decide from which keys are present, not their content: core asks once per (model, base_url, key set)
- and replays the same keys for every message with that key set (an answer whose values are not
- copies of input values is asked per message)."""
- return {}
- def replays_function_thought_signature(self, *, model: str | None, base_url: str) -> bool:
- """True when replayed tool calls keep ``function.thought_signature`` (stripped everywhere else).
- Pure: memoized per arguments."""
- return False
- # --- I2-cat: provider-owned catalog sources ---
- # ``picker_catalog(force_refresh) -> list | None``: the provider's own model-picker catalog (own
- # credential lookup, live fetch, curated fallback); set = a live source, tried before the generic
- # profile fetch like a built-in per-provider fetcher. None return falls through to that path.
- picker_catalog: Callable[[bool], Any] | None = field(default=None, kw_only=True)
- # Curated ids registered as this provider's row of core's static catalog (model detection,
- # defaults, validation) the way a built-in provider's curated list is; empty = no row.
- static_models: tuple = field(default=(), kw_only=True)
- # Credential files (``~`` allowed) whose mtime is folded into every cached catalog's fingerprint.
- catalog_credential_files: tuple = field(default=(), kw_only=True)
- def probe_models(
- self, *, base_url: str, api_key: str | None = None, timeout: float = 5.0,
- ) -> tuple[list[str] | None, str, str] | None:
- """``(model ids or None, probed_url, resolved_base_url)`` for a ``/models`` probe of *base_url*
- this provider answers from its own catalog; None = the generic HTTP probe."""
- return None
- def invalidate_catalog_cache(self) -> None:
- """Drop in-process catalog memos (``/model --refresh``); default none."""
- # --- I2-static: provider-table placement ---
- picker_after: str = "" # provider slug this row follows in the provider list ("" = appended)
- picker_group: tuple = () # (group_id, label, description): fold with same-group rows in interactive pickers
- catalog_aliases: bool = False # ``aliases`` also normalize in the model catalog (``/model``, pickers)
- aggregator: bool = False # catalog re-exposes many vendors' models (vendor/family ids, alias resolution)
- # HermesOverlay fields (transport, auth_type, extra_env_vars, base_url_override, base_url_env_var) for
- # the provider's models.dev-keyed definition, keyed by ``models_dev_id`` or ``name``; {} = none.
- provider_overlay: dict = field(default_factory=dict)
- # Extra names that normalize to the ``provider_overlay`` definition (its id, else ``name``); () = none.
- overlay_aliases: tuple = ()
- # --- I2-auth: hermes-auth registry row mirrored from this profile (hermes_cli/auth_plugin_providers.py) ---
- # auth_type of the registry row when credential resolution differs from the setup flow ``auth_type`` names
- # (an env-token provider with its own login); "" = ``auth_type``.
- registry_auth_type: str = ""
- # Env var overriding ``base_url`` on the registry row when it is not listed in ``env_vars``; "" = none.
- base_url_env_var: str = ""
- # Registry id this provider's row sits right after, keeping its place in priority-ordered scans
- # (aux api-key chain, env auto-detect); "" or an unknown id = appended.
- registry_after: str = ""
|