"""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/`` UA string, with a stable fallback. Used by ``ProviderProfile.fetch_models`` so the catalog probe is not served the default ``Python-urllib/`` 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 `` 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 `` 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": , ...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 '.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 ` 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 `` 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/`` 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 = ""