base.py 39 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747
  1. """Provider profile base class.
  2. A ProviderProfile declares everything about an inference provider in one place:
  3. auth, endpoints, client quirks, request-time quirks. The transport reads this
  4. instead of receiving 20+ boolean flags.
  5. Provider profiles are DECLARATIVE — they describe the provider's behavior.
  6. They do NOT own client construction, credential rotation, or streaming.
  7. Those stay on AIAgent.
  8. """
  9. from __future__ import annotations
  10. import logging
  11. import threading
  12. from dataclasses import KW_ONLY, dataclass, field
  13. from typing import TYPE_CHECKING, Any, Callable
  14. if TYPE_CHECKING:
  15. from agent.account_usage import AccountUsageSnapshot
  16. logger = logging.getLogger(__name__)
  17. # Sentinel for "omit temperature entirely" (Kimi: server manages it)
  18. OMIT_TEMPERATURE = object()
  19. def _profile_user_agent() -> str:
  20. """Return a ``hermes-cli/<version>`` UA string, with a stable fallback.
  21. Used by ``ProviderProfile.fetch_models`` so the catalog probe is not
  22. served the default ``Python-urllib/<ver>`` UA — some providers
  23. (OpenCode Zen, etc.) sit behind a WAF that returns 403 for that.
  24. """
  25. try:
  26. from hermes_cli.version_info import get_version_info # lazy: avoid layer cycle at import time
  27. return f"hermes-cli/{get_version_info().base_version}"
  28. except Exception:
  29. return "hermes-cli"
  30. _RESOLVE_LOCK = threading.RLock() # re-entrant: a callback may read another LazyHeaders
  31. class LazyHeaders(dict[str, str]):
  32. """``default_headers`` whose callable values (a User-Agent carrying the release) run on first read.
  33. A source checkout resolves the release from git, and every CLI start imports all provider plugins
  34. (``hermes_cli.config`` lists their env vars), so headers built at import made every command pay git
  35. subprocesses for a request it may never send. Keys are stored up front, so ``in``/``len`` stay lazy,
  36. and the class stays a real ``dict``: plugins copy, merge, mutate and serialize ``default_headers``.
  37. Every method that reads or writes a value resolves first; ``__iter__`` is overridden so CPython's
  38. ``dict(x)``/``{**x}``/``f(**x)`` merge leaves its raw-storage fast path for ``keys()`` +
  39. ``__getitem__``, and ``json.dumps`` takes ``items()`` because the stored keys make the dict
  40. non-empty. Copies (``.copy()``, ``|``, ``copy``/``pickle``) are plain resolved dicts.
  41. """
  42. __slots__ = ("_pending",)
  43. def __init__(self, *args: Any, **kwargs: Any) -> None:
  44. super().__init__(*args, **kwargs)
  45. self._pending = any(callable(value) for value in dict.values(self))
  46. def _resolved(self) -> LazyHeaders:
  47. if self._pending:
  48. # One resolver: concurrent first reads (parallel aux clients) would each walk git.
  49. with _RESOLVE_LOCK:
  50. if self._pending:
  51. for key, value in list(dict.items(self)):
  52. if callable(value):
  53. dict.__setitem__(self, key, value())
  54. self._pending = False
  55. return self
  56. def __getitem__(self, key: str) -> str:
  57. return dict.__getitem__(self._resolved(), key)
  58. def __iter__(self):
  59. return dict.__iter__(self._resolved())
  60. def __reversed__(self):
  61. return dict.__reversed__(self._resolved())
  62. def __repr__(self) -> str:
  63. return dict.__repr__(self._resolved())
  64. def __eq__(self, other: object) -> bool:
  65. return dict.__eq__(self._resolved(), other._resolved() if isinstance(other, LazyHeaders) else other)
  66. def __ne__(self, other: object) -> bool:
  67. equal = self.__eq__(other)
  68. return equal if equal is NotImplemented else not equal
  69. def __or__(self, other: Any) -> Any:
  70. return dict.__or__(self._resolved(), other)
  71. def __ror__(self, other: Any) -> Any:
  72. return dict.__or__(other, self._resolved()) if isinstance(other, dict) else NotImplemented
  73. def __ior__(self, other: Any) -> LazyHeaders:
  74. return dict.__ior__(self._resolved(), other)
  75. def __reduce__(self) -> tuple:
  76. return (dict, (dict.copy(self._resolved()),))
  77. def get(self, key: str, default: Any = None) -> Any:
  78. return dict.get(self._resolved(), key, default)
  79. def keys(self):
  80. return dict.keys(self._resolved())
  81. def values(self):
  82. return dict.values(self._resolved())
  83. def items(self):
  84. return dict.items(self._resolved())
  85. def copy(self) -> dict[str, str]:
  86. return dict.copy(self._resolved())
  87. def __setitem__(self, key: str, value: str) -> None:
  88. dict.__setitem__(self._resolved(), key, value)
  89. def __delitem__(self, key: str) -> None:
  90. dict.__delitem__(self._resolved(), key)
  91. def pop(self, *args: Any) -> Any:
  92. return dict.pop(self._resolved(), *args)
  93. def popitem(self) -> tuple[str, str]:
  94. return dict.popitem(self._resolved())
  95. def setdefault(self, key: str, default: Any = None) -> Any:
  96. return dict.setdefault(self._resolved(), key, default)
  97. def update(self, *args: Any, **kwargs: Any) -> None:
  98. dict.update(self._resolved(), *args, **kwargs)
  99. @dataclass
  100. class ProviderProfile:
  101. """Base provider profile — subclass or instantiate with overrides."""
  102. # ── Identity ─────────────────────────────────────────────
  103. name: str
  104. api_mode: str = "chat_completions"
  105. aliases: tuple = ()
  106. # ── Human-readable metadata ───────────────────────────────
  107. display_name: str = "" # e.g. "GMI Cloud" — shown in picker/labels
  108. description: str = "" # e.g. "GMI Cloud (multi-model direct API)" — picker subtitle
  109. signup_url: str = "" # e.g. "https://www.gmicloud.ai/" — shown during setup
  110. # True when the provider is pre-release / not for public listing. Discovery surfaces (provider
  111. # pickers, the setup provider list, the dashboard accounts tab) skip it unless ``listed()``
  112. # says otherwise; resolution by name is untouched, so an explicit ``model.provider`` /
  113. # ``hermes auth add <name>`` keeps working.
  114. hidden: bool = False
  115. # ── Auth & endpoints ─────────────────────────────────────
  116. env_vars: tuple = ()
  117. base_url: str = ""
  118. models_url: str = "" # explicit models endpoint; falls back to {base_url}/models
  119. auth_type: str = "api_key" # api_key|oauth_device_code|oauth_external|external_process|aws_sdk|plugin-defined
  120. # None preserves transport defaults (external-process clients default to non-streaming).
  121. # True opts a streaming-capable process client in; False disables streaming for this provider.
  122. supports_streaming: bool | None = field(default=None, kw_only=True)
  123. supports_health_check: bool = True # False → doctor skips /models probe for this provider
  124. # False → fetch_models returns None without a network call (catalog comes from an SDK/subprocess).
  125. supports_model_listing: bool = True
  126. # ── Provider-owned auth (optional; non-api-key plugins) ──────────
  127. # ``auth_handler(action, args) -> bool``: ``hermes auth add|status|logout|refresh <name>`` calls it
  128. # FIRST with the parsed CLI namespace; truthy = the plugin owned the action, falsy = built-in path.
  129. # ``refresh_credential(entry) -> Mapping | None``: the credential pool's refresh of a pooled OAuth
  130. # row — return the rotated fields (``access_token``, ``refresh_token``, ``expires_at_ms`` …) or raise.
  131. # Both own their own token endpoints; Hermes passes no secrets beyond the pooled row itself.
  132. # ``classify_api_error(error, *, status_code, error_code, message, body, model) -> Mapping | None``:
  133. # consulted by ``agent.error_classifier.classify_api_error`` for THIS provider's failures only, after
  134. # the generic ``transform_api_error_classification`` plugin hooks and before the built-in pipeline.
  135. # Return ``{"reason": <FailoverReason name>, ...hint flags}`` to override, ``None`` to decline.
  136. auth_handler: Callable[[str, Any], Any] | None = None
  137. refresh_credential: Callable[[Any], Any] | None = None
  138. classify_api_error: Callable[..., Any] | None = None
  139. # ── Vision support ────────────────────────────────────────
  140. # True when the provider's API accepts image content inside
  141. # tool-result messages natively. Set on providers that expose
  142. # multimodal models via tool results (Anthropic Messages API,
  143. # OpenAI Chat Completions, Gemini, MiniMax, etc.).
  144. # Falls back to model-catalog lookup when False and the provider
  145. # has no registered profile.
  146. supports_vision: bool = False
  147. # True when the provider's API accepts list-type tool message
  148. # content (multipart with image_url parts). Defaults to True for
  149. # backward compatibility. Set to False for providers that accept
  150. # multimodal user messages but reject list-type tool content
  151. # (e.g. Xiaomi MiMo, which returns 400 "text is not set").
  152. supports_vision_tool_messages: bool = True
  153. # True only when this provider's Chat Completions endpoint explicitly
  154. # documents ``prompt_cache_key`` as an accepted request body field. This
  155. # is deliberately opt-in: many OpenAI-compatible endpoints reject unknown
  156. # top-level fields rather than ignoring them.
  157. supports_prompt_cache_key: bool = False
  158. # Private replay carriers use a namespaced '<provider>.native_assistant' type
  159. # in reasoning_details. Only this profile may receive its matching carrier;
  160. # other providers (including an unregistered fallback) get ordinary details only.
  161. native_reasoning_details_type: str | None = None
  162. # ── External-process providers (auth_type="external_process") ──
  163. # An agent CLI driven over stdio (ACP) rather than an HTTP endpoint. These
  164. # describe how to launch it; hermes_cli/auth.py's
  165. # resolve_external_process_provider_credentials() reads them instead of
  166. # hardcoding one vendor's binary. Env vars are checked in order and win
  167. # over the static defaults, so an operator can point at a custom build.
  168. process_command: str = "" # default binary, e.g. "kimchi"
  169. process_args: tuple = () # default argv tail, e.g. ("--mode", "acp")
  170. process_command_env_vars: tuple = () # env overrides for the binary, in priority order
  171. process_args_env_var: str = "" # env override for argv (shlex-split)
  172. # ── Model catalog ─────────────────────────────────────────
  173. # fallback_models: curated list shown in /model picker when live fetch fails.
  174. # Only agentic models that support tool calling should appear here.
  175. fallback_models: tuple = ()
  176. # model_aliases: short name -> id in fallback_models, for providers whose catalog is not
  177. # in models.dev (external processes); `/model <alias>` resolves here before core guessing.
  178. model_aliases: dict = field(default_factory=dict)
  179. # hostname: base hostname for URL→provider reverse-mapping in model_metadata.py
  180. # e.g. "api.gmi-serving.com". Derived from base_url when empty.
  181. hostname: str = ""
  182. # ── Client-level quirks (set once at client construction) ─
  183. default_headers: dict[str, str] = field(default_factory=dict)
  184. # ── Request-level quirks ─────────────────────────────────
  185. # Temperature: None = use caller's default, OMIT_TEMPERATURE = don't send
  186. fixed_temperature: Any = None
  187. default_max_tokens: int | None = None
  188. # ``response_format`` types the API rejects outright (e.g. ("json_schema",)); aux requests omit them up front.
  189. unsupported_response_formats: tuple = ()
  190. default_aux_model: str = (
  191. "" # cheap model for auxiliary tasks (compression, vision, etc.)
  192. )
  193. # empty = use main model
  194. # Per-model metadata in the canonical model_overrides schema. Partial entries
  195. # patch catalog metadata; explicit user overrides still win. Exact model IDs.
  196. model_capabilities: dict[str, dict[str, Any]] = field(default_factory=dict)
  197. # Every field below was added after the released positional layout above: keyword-only, so a
  198. # plugin subclass's own positional options keep their constructor slots.
  199. _: KW_ONLY
  200. # ── L6: provider-owned setup + sign-in surfaces (all optional; None/empty = core's generic path) ──
  201. # ``account_card``: Accounts-tab card overrides ``{name, flow, cli_command, docs_url}`` for the
  202. # Desktop/dashboard (``/api/providers/oauth``); non-empty also lists a Keys-tab profile there.
  203. account_card: dict[str, str] = field(default_factory=dict)
  204. # ``account_status() -> Mapping``: that card's live status (``logged_in``, ``source``, ``source_label``…);
  205. # subprocess- and network-free, it runs on every Accounts list. None = ``auth.get_auth_status(name)``.
  206. account_status: Callable[[], Any] | None = None
  207. # In-app device-code sign-in (Desktop "Login" button; the card's flow becomes ``device_code``):
  208. # ``start_device_login() -> {user_code, verification_url, expires_in, interval, state}`` asks the
  209. # provider for a code; ``poll_device_login(state) -> {status: pending|approved|denied|expired,
  210. # interval?, credential?, message?}`` makes ONE poll; ``save_device_login(credential)`` persists it.
  211. # Core owns the wait loop and cancellation and calls save inside the session's profile scope.
  212. start_device_login: Callable[[], Any] | None = None
  213. poll_device_login: Callable[[Any], Any] | None = None
  214. save_device_login: Callable[[Any], None] | None = None
  215. # ``model_setup_flow(config, current_model, args)``: this provider's own ``hermes model`` step
  216. # (credential prompt, catalog, persist); None = the generic flow for its auth_type.
  217. model_setup_flow: Callable[[Any, str, Any], Any] | None = None
  218. # ``setup_reasoning_efforts(model) -> tuple | None``: levels the setup effort picker offers for
  219. # *model*; ``()`` = no reasoning control, None = the generic ladder gated by models.dev.
  220. setup_reasoning_efforts: Callable[[str], Any] | None = None
  221. # ── Hooks (override in subclass for complex providers) ───
  222. def fetch_account_usage(
  223. self, *, base_url: str | None = None, api_key: str | None = None
  224. ) -> AccountUsageSnapshot | None:
  225. """Return an account-usage snapshot for this provider, if available.
  226. The ``/usage`` command invokes this only when no built-in account
  227. usage fetcher owns the provider. Implementations may make their
  228. provider-specific request and must return an ``AccountUsageSnapshot``
  229. or ``None``; exceptions fail open at the dispatch boundary.
  230. """
  231. return None
  232. def resolve_aux_model(self, *, vision: bool = False) -> str:
  233. """Return a LIVE cheap-model id for auxiliary tasks, or "".
  234. ``default_aux_model`` is a hardcoded id in source, so it rots: when the
  235. provider retires that model every auxiliary call spends a round-trip
  236. 404ing before the retry net catches it. Providers that publish a
  237. machine-readable recommendation should override this and query it, so
  238. the cheap tier tracks the upstream catalog instead of a constant a human
  239. has to remember to bump.
  240. Contract: cheap to call (implementations must cache — this runs on
  241. client-resolution paths), never raises, and returns "" when it has no
  242. answer so the caller falls through to ``default_aux_model``.
  243. """
  244. return ""
  245. def get_hostname(self) -> str:
  246. """Return the provider's base hostname for URL-based detection.
  247. Uses self.hostname if set explicitly, otherwise derives it from base_url.
  248. e.g. 'https://api.gmi-serving.com/v1' → 'api.gmi-serving.com'
  249. """
  250. if self.hostname:
  251. return self.hostname
  252. if self.base_url:
  253. from urllib.parse import urlparse
  254. return urlparse(self.base_url).hostname or ""
  255. return ""
  256. def prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
  257. """Provider-specific message preprocessing.
  258. Called AFTER codex field sanitization, BEFORE developer role swap.
  259. Default: pass-through.
  260. """
  261. return messages
  262. def build_extra_body(
  263. self, *, session_id: str | None = None, **context: Any
  264. ) -> dict[str, Any]:
  265. """Provider-specific extra_body fields.
  266. Merged into the API kwargs extra_body. Default: empty dict.
  267. """
  268. return {}
  269. def default_reasoning_config(self, model: str | None = None) -> dict | None:
  270. """Reasoning config the main loop sends when ``agent.reasoning_effort`` is unset.
  271. None (default) hands the unset state to ``build_api_kwargs_extras`` as ``reasoning_config=None``,
  272. where each profile already decides (Nous/OpenRouter fill medium; Anthropic omits). A profile
  273. that would otherwise leave the route's own default in charge returns the config here so the
  274. agent records it as what went on the wire (the reasoning-rejection ladder reads that).
  275. """
  276. return None
  277. def build_api_kwargs_extras(
  278. self,
  279. *,
  280. reasoning_config: dict | None = None,
  281. **context: Any,
  282. ) -> tuple[dict[str, Any], dict[str, Any]]:
  283. """Provider-specific kwargs split between extra_body and top-level api_kwargs.
  284. Returns (extra_body_additions, top_level_kwargs).
  285. The transport merges extra_body_additions into extra_body, and
  286. top_level_kwargs directly into api_kwargs.
  287. This split exists because some providers put reasoning config in
  288. extra_body (OpenRouter: extra_body.reasoning) while others put it
  289. as top-level api_kwargs (Kimi: api_kwargs.reasoning_effort).
  290. Default: ({}, {}).
  291. """
  292. return {}, {}
  293. def build_client_kwargs_extras(self, **context: Any) -> dict[str, Any]:
  294. """Provider-specific OpenAI client keyword arguments.
  295. Values are defaults: explicit runtime/custom-provider settings win.
  296. The returned mapping must be cheap to build and must not perform I/O.
  297. """
  298. return {}
  299. def default_vision_model(self) -> str | None:
  300. """Return a default vision model id for this provider, or None.
  301. Overrideable hook for providers that discover their vision default at
  302. runtime (e.g. from a live catalog) rather than pinning one in code.
  303. Keeps provider-specific vision discovery inside the provider's plugin
  304. instead of a name-check branch in shared vision resolution.
  305. Default: None (no provider-specific vision model — the caller falls
  306. back to the user's chat model or the aggregator chain).
  307. """
  308. return None
  309. def get_model_context_length(self, model: str) -> int | None:
  310. """Provider-qualified context bound; explicit user overrides take precedence."""
  311. return None
  312. def get_usage_cost(self, model: str, usage: Any) -> Any | None:
  313. """Optional CostResult from canonical usage; distinguish estimates from invoices."""
  314. return None
  315. def get_max_tokens(self, model: str | None) -> int | None:
  316. """Return the default max_tokens cap for *model*.
  317. Overrideable hook for providers that need per-model output caps —
  318. e.g. a relay that fronts several upstream backends, each with a
  319. different completion-token limit. The transport calls this when
  320. the user hasn't set an explicit max_tokens.
  321. Default: return self.default_max_tokens (the static profile field),
  322. ignoring the model name. Override in a subclass to vary the cap
  323. per-model.
  324. """
  325. return self.default_max_tokens
  326. def supported_reasoning_efforts(
  327. self, model: str | None
  328. ) -> tuple[str, ...] | None:
  329. """Declared reasoning-effort vocabulary for *model* on this provider.
  330. Overrideable hook for providers whose gateway validates
  331. ``reasoning.effort`` per model instead of ignoring or clamping
  332. unknown levels server-side (Ramp Router derives this from its live
  333. ``/v1/models`` catalog). The Responses transport consults it before
  334. falling back to its built-in per-backend vocabularies; it is the
  335. profile-declared analog of the OpenRouter catalog clamp on the
  336. chat-completions path (``openrouter_model_reasoning_capabilities``).
  337. Tri-state contract:
  338. - ``None`` — unknown/undeclared: the transport keeps its default
  339. vocabulary for the wire (this base implementation).
  340. - ``()`` — the model accepts NO reasoning parameters at all; the
  341. transport must omit reasoning fields entirely (some gateways
  342. return HTTP 400 rather than ignoring them).
  343. - non-empty tuple — clamp the requested effort onto these levels
  344. (``agent.reasoning_effort.clamp_effort`` semantics: nearest
  345. weaker supported level, never escalate).
  346. Implementations are called on the per-request hot path and must not
  347. block on network I/O — answer from a cache and return None while
  348. cold.
  349. """
  350. return None
  351. # ── L1 wire seams (per-model wire, endpoint-keyed headers, max-tokens param) ──
  352. # Endpoint-keyed hooks take the request's ``base_url``: core asks the named provider's profile first,
  353. # then any registered profile overriding the hook (``agent.provider_route_hooks``), so a ``custom``
  354. # route pointed at this provider's host is served too. Return None / ``{}`` for an endpoint that is
  355. # not yours. All four are pure: no I/O unless the docstring says so.
  356. def api_mode_for_model(self, model: str, *, api_key: str | None = None) -> str | None:
  357. """Wire (``api_mode``) this provider serves *model* on, or None to keep the static ``api_mode``.
  358. ``api_key=None`` is the pure hot path (agent init, fallback, aux client builds): answer from the
  359. id alone. A string ``api_key`` comes from resolution-time callers (``/model``, runtime resolve),
  360. which may consult a cached live catalog with that credential to normalize the id first.
  361. """
  362. return None
  363. def client_headers(
  364. self, *, base_url: str, api_key: str = "", has_images: bool = False,
  365. ) -> dict[str, str] | None:
  366. """Default headers for an OpenAI client built for *base_url*, or None when this profile has no
  367. endpoint-specific headers there (core then uses the static ``default_headers``). ``has_images``
  368. asks for the headers of a request-scoped client carrying native image parts. Core merges user
  369. ``model.default_headers`` over the result and re-adds missing keys on snapshot rebuilds."""
  370. return None
  371. def request_headers(self, *, base_url: str, model: str = "", user_initiated: bool = False) -> dict[str, str]:
  372. """Per-request headers (``extra_headers``) for *base_url*; ``user_initiated`` is True only on the
  373. first attempt of a user turn's first API call (attribution). Pure: core memoizes the answer per argument set."""
  374. return {}
  375. def max_tokens_param(self, *, base_url: str, model: str = "") -> str | None:
  376. """``"max_completion_tokens"`` / ``"max_tokens"`` for requests to *base_url*, or None for the
  377. core heuristic (direct OpenAI / Azure host or newer OpenAI model families). Pure: memoized per arguments."""
  378. return None
  379. def listed(self) -> bool:
  380. """Whether discovery surfaces may offer this provider.
  381. Every non-``hidden`` profile is listed. A ``hidden`` (pre-release) one surfaces once the user
  382. opted in by name (``hermes auth add <name>`` put a row in its credential pool), so the
  383. pickers can then offer it. Reads auth.json only: it runs on every picker build.
  384. """
  385. if not self.hidden:
  386. return True
  387. from hermes_cli.auth import read_credential_pool # lazy: providers/ must not import hermes_cli at load
  388. return bool(read_credential_pool(self.name))
  389. def create_client(self, **client_kwargs: Any) -> Any | None:
  390. """Return a provider-specific client, or ``None`` for the standard one.
  391. Most providers speak OpenAI-compatible HTTP and want the shared
  392. ``openai.OpenAI`` client the core builds — they inherit this and return
  393. ``None``. A provider whose wire protocol is not HTTP at all (the ACP
  394. subprocess shims) or which needs a native SDK overrides this and
  395. returns its own client object.
  396. ``client_kwargs`` is the same mapping the core would have passed to
  397. ``openai.OpenAI`` (``api_key``, ``base_url``, ``command``, ``args``,
  398. timeouts, headers…). Unknown keys must be tolerated: the core adds to
  399. this mapping over time, so an override should accept ``**kwargs`` and
  400. pick what it needs rather than enumerate.
  401. Returning ``None`` (the default) is always safe — the caller falls
  402. through to its existing construction path.
  403. This is the hook that lets a provider ship *outside* this tree: with it,
  404. a profile registered from ``~/.hermes/plugins/model-providers/`` or a
  405. pip entry point can supply its own transport without any core edit. See
  406. ``website/docs/developer-guide/model-provider-plugin.md``.
  407. """
  408. return None
  409. def setup_status(self, **kwargs: Any) -> dict[str, Any] | None:
  410. """External-process providers: ``{available, logged_in, plan, detail, login_command}`` from the
  411. CLI itself so setup can gate on login. ``None`` = nothing to report beyond executable presence."""
  412. return None
  413. def discover_models(self, **kwargs: Any) -> list[dict[str, Any]] | None:
  414. """External-process providers: the account's live picker as ``[{id, label, note}]`` without
  415. any inference request; ``None`` falls back to ``fallback_models``."""
  416. return None
  417. def fetch_models(
  418. self,
  419. *,
  420. api_key: str | None = None,
  421. base_url: str | None = None,
  422. timeout: float = 8.0,
  423. ) -> list[str] | None:
  424. """Fetch the live model list from the provider's models endpoint.
  425. Returns a list of model ID strings, or None if the fetch failed or
  426. the provider does not support live model listing.
  427. Resolution order for the endpoint URL:
  428. 1. base_url + "/models", but ONLY when the caller passed a base_url
  429. that differs from this profile's default (a user-configured
  430. model.base_url pointing at a proxy/custom endpoint). Callers
  431. pass base_url unconditionally — falling back to the profile
  432. default when the user configured nothing — so equality with
  433. self.base_url means "not customised" and must not shadow
  434. models_url.
  435. 2. self.models_url (explicit override — use when the models
  436. endpoint differs from the inference base URL, e.g. OpenRouter
  437. exposes a public catalog at /api/v1/models while inference is
  438. at /api/v1)
  439. 3. self.base_url + "/models" (standard OpenAI-compat fallback)
  440. The default implementation sends Bearer auth when api_key is given
  441. and forwards self.default_headers. Override to customise auth, path,
  442. response shape, or to return None for providers with no REST catalog.
  443. Callers must always fall back to the static _PROVIDER_MODELS list
  444. when this returns None.
  445. """
  446. if not self.supports_model_listing:
  447. return None
  448. caller_base = (base_url or "").strip()
  449. effective_base = caller_base or self.base_url
  450. custom_base = bool(caller_base) and (
  451. caller_base.rstrip("/") != (self.base_url or "").rstrip("/")
  452. )
  453. if custom_base:
  454. url = caller_base.rstrip("/") + "/models"
  455. else:
  456. url = (self.models_url or "").strip()
  457. if not url:
  458. if not effective_base:
  459. return None
  460. url = effective_base.rstrip("/") + "/models"
  461. import json
  462. import urllib.request
  463. from hermes_cli.urllib_security import open_credentialed_url
  464. req = urllib.request.Request(url)
  465. if api_key:
  466. req.add_header("Authorization", f"Bearer {api_key}")
  467. req.add_header("Accept", "application/json")
  468. # Some providers (e.g. OpenCode Zen) sit behind a WAF that blocks
  469. # the default ``Python-urllib/<ver>`` User-Agent. Set a generic
  470. # hermes-cli UA so the catalog endpoint is reachable.
  471. req.add_header("User-Agent", _profile_user_agent())
  472. for k, v in self.default_headers.items():
  473. req.add_header(k, v)
  474. try:
  475. with open_credentialed_url(req, timeout=timeout) as resp:
  476. data = json.loads(resp.read().decode())
  477. items = data if isinstance(data, list) else data.get("data", [])
  478. from hermes_cli.chat_catalog import chat_catalog_ids
  479. return chat_catalog_ids(items)
  480. except Exception as exc:
  481. logger.debug("fetch_models(%s): %s", self.name, exc)
  482. return None
  483. # ── Lane L4: catalog / metadata seams ─────────────────────
  484. # Hosts (exact or any subdomain) that serve THIS provider's API, so a ``custom`` endpoint or an
  485. # auto-routed aux client at one of them is recognised as this provider (``providers.profile_for_host``).
  486. # It also makes ``reasoning_payload`` the reasoning gate there, except on hosts core gates itself
  487. # (OpenRouter, Ollama Cloud, Nous Portal, Vercel AI Gateway, the ``lmstudio`` provider).
  488. hostnames: tuple = ()
  489. # Hosts that identify this provider's catalog for model metadata (context length, models.dev) but
  490. # take other credentials; matched only by ``profile_for_host(url, metadata=True)``.
  491. metadata_hostnames: tuple = ()
  492. # models.dev provider id when it differs from ``name`` (e.g. ``fireworks`` -> ``fireworks-ai``).
  493. models_dev_id: str = ""
  494. def live_context_length(self, model: str, *, api_key: str = "", base_url: str = "") -> int | None:
  495. """Context window from the provider's live, credentialed catalog; consulted after the persistent cache."""
  496. return None
  497. def normalize_model_id(self, model: str, *, api_key: str = "") -> str | None:
  498. """Provider-native id for *model* (alias table, catalog repair); None = core's generic normalization."""
  499. return None
  500. # ── Lane L2: provider-owned credential seams ──────────────────────────────
  501. # Credentials are commonly ambient (another tool's login, a token exported for other purposes):
  502. # never auto-detected as the inference provider, and the auxiliary fallback chain skips the
  503. # provider unless the user explicitly configured it.
  504. ambient_credentials: bool = field(default=False, kw_only=True)
  505. def resolve_api_key_secret(self) -> tuple[str, str] | None:
  506. """Provider-owned ``(runtime_api_key, source)`` resolution; None = generic env/pool ladder."""
  507. return None
  508. def runtime_base_url(self, *, api_key: str, default: str, env_url: str) -> str | None:
  509. """Runtime base URL derived from the credential (e.g. an account endpoint); None = env or default."""
  510. return None
  511. def prepare_pool_entry(self, entry: Any, api_key: str) -> str:
  512. """Turn the selected pool row's secret into the runtime key (may update ``entry``); default as-is."""
  513. return api_key
  514. def seed_pool_credentials(self, *, suppressed_sources: frozenset[str],
  515. explicitly_configured: bool) -> list[dict] | None:
  516. """Pool rows ``{source, access_token, base_url, label}`` this provider seeds itself; skip any source in
  517. ``suppressed_sources`` (``hermes auth remove``). Plain data, so it crosses ``plugins.isolation: host``.
  518. Overriding it replaces generic env seeding (that loop would overwrite exchanged tokens with the raw env
  519. value), so an override returns ``[]`` for none; only the base implementation keeps generic env seeding."""
  520. return None
  521. def remove_credential_source(self, source: str) -> tuple[tuple[str, ...], tuple[str, ...]] | None:
  522. """``hermes auth remove`` of *source*: ``(sources_to_suppress, hints)``; None = generic removal."""
  523. return None
  524. def refresh_runtime_credentials(self, *, reason: str) -> tuple[str, str | None] | None:
  525. """Re-mint the live client's ``(api_key, base_url or None)`` on ``reason`` (``unauthorized`` |
  526. ``stale`` | ``auxiliary_unauthorized``); None = nothing fresher. Error path only, I/O allowed."""
  527. return None
  528. def is_stale_credential_error(self, *, status_code: int | None, message: str) -> bool:
  529. """True when a non-auth error really means the credential went stale (pure, no I/O)."""
  530. return False
  531. def credential_refresh_notice(self, *, reason: str) -> str:
  532. """Status line after ``refresh_runtime_credentials(reason=...)`` succeeded; "" = generic wording."""
  533. return ""
  534. def request_rejection_hint(self, *, status_code: int | None, base_url: str) -> tuple[str, ...]:
  535. """User-facing lines explaining an endpoint's hard rejection of *any* route (pure); default none."""
  536. return ()
  537. def external_auth_evidence(self) -> tuple[bool, str | None] | None:
  538. """Subprocess-free ``(verified, source)`` login evidence for an external CLI; None = binary resolves."""
  539. return None
  540. def missing_credentials_hint(self) -> str | None:
  541. """One sentence appended to every "No usable credentials found" surface (runtime resolution, CLI and
  542. Desktop readiness), e.g. the provider's own sign-in command; None = the generic message alone."""
  543. return None
  544. # ── Lane L3: Responses-route quirks and message-level reasoning carriers ───
  545. # Every field and hook below applies only on hosts the profile declares in ``hostnames``;
  546. # the defaults are the generic wire. Hot path: answers must be pure and cheap (no I/O). A hook that
  547. # raises is logged once and answers the default for the rest of the session (provider_route_hooks).
  548. responses_replay_item_ids: bool = True # replayed Responses ``message`` items keep their ``id``
  549. responses_prompt_cache_key: bool = True # the Responses body carries ``prompt_cache_key``
  550. responses_issuer_kind: str = "" # persisted stamp for encrypted reasoning minted here ("" = URL-derived)
  551. responses_trusts_completed_status: bool = True # False: a reasoning-only ``completed`` response continues
  552. responses_native_compaction: bool = True # False: never send ``context_management``
  553. responses_profile_reasoning: bool = False # True: ``reasoning`` = ``reasoning_payload`` + summary, no ``include``
  554. message_carrier_opaque: str = "" # top-level assistant key of an opaque reasoning blob (latest streamed wins)
  555. message_carrier_text: str = "" # top-level assistant key of readable reasoning text (streamed parts concatenate)
  556. replays_tool_call_signatures: bool = False # tool calls keep Gemini ``extra_content`` signatures (by provider name)
  557. def reasoning_payload(self, model: str | None, reasoning_config: dict | None, *, base_url: str) -> dict | None:
  558. """Verbatim ``reasoning`` object the endpoint takes for *model* (catalog-clamped), or None for none.
  559. Pure: memoized per arguments."""
  560. return None
  561. def replay_message_carriers(self, values: dict[str, Any], *, model: str | None, base_url: str) -> dict[str, Any]:
  562. """Captured message carriers (``message_carrier_*`` keys) to put back on a replayed assistant message.
  563. Decide from which keys are present, not their content: core asks once per (model, base_url, key set)
  564. and replays the same keys for every message with that key set (an answer whose values are not
  565. copies of input values is asked per message)."""
  566. return {}
  567. def replays_function_thought_signature(self, *, model: str | None, base_url: str) -> bool:
  568. """True when replayed tool calls keep ``function.thought_signature`` (stripped everywhere else).
  569. Pure: memoized per arguments."""
  570. return False
  571. # --- I2-cat: provider-owned catalog sources ---
  572. # ``picker_catalog(force_refresh) -> list | None``: the provider's own model-picker catalog (own
  573. # credential lookup, live fetch, curated fallback); set = a live source, tried before the generic
  574. # profile fetch like a built-in per-provider fetcher. None return falls through to that path.
  575. picker_catalog: Callable[[bool], Any] | None = field(default=None, kw_only=True)
  576. # Curated ids registered as this provider's row of core's static catalog (model detection,
  577. # defaults, validation) the way a built-in provider's curated list is; empty = no row.
  578. static_models: tuple = field(default=(), kw_only=True)
  579. # Credential files (``~`` allowed) whose mtime is folded into every cached catalog's fingerprint.
  580. catalog_credential_files: tuple = field(default=(), kw_only=True)
  581. def probe_models(
  582. self, *, base_url: str, api_key: str | None = None, timeout: float = 5.0,
  583. ) -> tuple[list[str] | None, str, str] | None:
  584. """``(model ids or None, probed_url, resolved_base_url)`` for a ``/models`` probe of *base_url*
  585. this provider answers from its own catalog; None = the generic HTTP probe."""
  586. return None
  587. def invalidate_catalog_cache(self) -> None:
  588. """Drop in-process catalog memos (``/model --refresh``); default none."""
  589. # --- I2-static: provider-table placement ---
  590. picker_after: str = "" # provider slug this row follows in the provider list ("" = appended)
  591. picker_group: tuple = () # (group_id, label, description): fold with same-group rows in interactive pickers
  592. catalog_aliases: bool = False # ``aliases`` also normalize in the model catalog (``/model``, pickers)
  593. aggregator: bool = False # catalog re-exposes many vendors' models (vendor/family ids, alias resolution)
  594. # HermesOverlay fields (transport, auth_type, extra_env_vars, base_url_override, base_url_env_var) for
  595. # the provider's models.dev-keyed definition, keyed by ``models_dev_id`` or ``name``; {} = none.
  596. provider_overlay: dict = field(default_factory=dict)
  597. # Extra names that normalize to the ``provider_overlay`` definition (its id, else ``name``); () = none.
  598. overlay_aliases: tuple = ()
  599. # --- I2-auth: hermes-auth registry row mirrored from this profile (hermes_cli/auth_plugin_providers.py) ---
  600. # auth_type of the registry row when credential resolution differs from the setup flow ``auth_type`` names
  601. # (an env-token provider with its own login); "" = ``auth_type``.
  602. registry_auth_type: str = ""
  603. # Env var overriding ``base_url`` on the registry row when it is not listed in ``env_vars``; "" = none.
  604. base_url_env_var: str = ""
  605. # Registry id this provider's row sits right after, keeping its place in priority-ordered scans
  606. # (aux api-key chain, env auto-detect); "" or an unknown id = appended.
  607. registry_after: str = ""