The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
"""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 = ""