providers.py 38 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678
  1. """Single source of truth for provider identity in Hermes Agent."""
  2. from __future__ import annotations
  3. import logging
  4. from dataclasses import dataclass
  5. from typing import Any, Dict, List, Optional, Tuple
  6. from utils import base_url_host_matches, base_url_hostname
  7. logger = logging.getLogger(__name__)
  8. # -- Hermes overlay: metadata models.dev doesn't provide ----------------------
  9. @dataclass(frozen=True)
  10. class HermesOverlay:
  11. """Hermes-specific provider metadata layered on top of models.dev."""
  12. transport: str = "openai_chat" # openai_chat | anthropic_messages | codex_responses
  13. is_aggregator: bool = False
  14. auth_type: str = "api_key" # api_key | oauth_device_code | oauth_external | external_process
  15. extra_env_vars: tuple[str, ...] = () # env vars models.dev doesn't list
  16. base_url_override: str = "" # override if models.dev URL is wrong/missing
  17. base_url_env_var: str = "" # env var for user-custom base URL
  18. HERMES_OVERLAYS: dict[str, HermesOverlay] = {
  19. "moa": HermesOverlay(auth_type="virtual", base_url_override="moa://local"),
  20. "openrouter": HermesOverlay(is_aggregator=True, base_url_env_var="OPENROUTER_BASE_URL"),
  21. "nous": HermesOverlay(auth_type="oauth_device_code", base_url_override="https://inference-api.nousresearch.com/v1"),
  22. "openai-codex": HermesOverlay(transport="codex_responses", auth_type="oauth_external",
  23. base_url_override="https://chatgpt.com/backend-api/codex"),
  24. "openai-api": HermesOverlay(transport="codex_responses", base_url_override="https://api.openai.com/v1",
  25. base_url_env_var="OPENAI_BASE_URL"),
  26. "xai-oauth": HermesOverlay(transport="codex_responses", auth_type="oauth_external",
  27. base_url_override="https://api.x.ai/v1", base_url_env_var="XAI_BASE_URL"),
  28. "qwen-oauth": HermesOverlay(auth_type="oauth_external", base_url_override="https://portal.qwen.ai/v1",
  29. base_url_env_var="HERMES_QWEN_BASE_URL"),
  30. "lmstudio": HermesOverlay(extra_env_vars=("LM_API_KEY",), base_url_override="http://127.0.0.1:1234/v1",
  31. base_url_env_var="LM_BASE_URL"),
  32. "anthropic": HermesOverlay(transport="anthropic_messages", extra_env_vars=("ANTHROPIC_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN")),
  33. "zai": HermesOverlay(extra_env_vars=("GLM_API_KEY", "ZAI_API_KEY", "Z_AI_API_KEY"), base_url_env_var="GLM_BASE_URL"),
  34. "kimi-for-coding": HermesOverlay(base_url_env_var="KIMI_BASE_URL"),
  35. "stepfun": HermesOverlay(extra_env_vars=("STEPFUN_API_KEY",),
  36. base_url_override="https://api.stepfun.ai/step_plan/v1",
  37. base_url_env_var="STEPFUN_BASE_URL"),
  38. "minimax": HermesOverlay(transport="anthropic_messages", base_url_env_var="MINIMAX_BASE_URL"),
  39. "minimax-oauth": HermesOverlay(transport="anthropic_messages", auth_type="oauth_external",
  40. base_url_override="https://api.minimax.io/anthropic"),
  41. "minimax-cn": HermesOverlay(transport="anthropic_messages", base_url_env_var="MINIMAX_CN_BASE_URL"),
  42. "deepseek": HermesOverlay(base_url_env_var="DEEPSEEK_BASE_URL"),
  43. "alibaba": HermesOverlay(base_url_env_var="DASHSCOPE_BASE_URL"),
  44. "alibaba-coding-plan": HermesOverlay(base_url_env_var="ALIBABA_CODING_PLAN_BASE_URL"),
  45. "vercel": HermesOverlay(is_aggregator=True),
  46. "opencode": HermesOverlay(is_aggregator=True, base_url_env_var="OPENCODE_ZEN_BASE_URL"),
  47. "opencode-go": HermesOverlay(is_aggregator=True, base_url_env_var="OPENCODE_GO_BASE_URL"),
  48. "kilo": HermesOverlay(is_aggregator=True, base_url_env_var="KILOCODE_BASE_URL"),
  49. "huggingface": HermesOverlay(is_aggregator=True, base_url_env_var="HF_BASE_URL"),
  50. "novita": HermesOverlay(is_aggregator=True, base_url_env_var="NOVITA_BASE_URL"),
  51. "xai": HermesOverlay(transport="codex_responses", base_url_override="https://api.x.ai/v1", base_url_env_var="XAI_BASE_URL"),
  52. "nvidia": HermesOverlay(base_url_override="https://integrate.api.nvidia.com/v1", base_url_env_var="NVIDIA_BASE_URL"),
  53. "xiaomi": HermesOverlay(base_url_env_var="XIAOMI_BASE_URL"),
  54. "tencent-tokenhub": HermesOverlay(base_url_env_var="TOKENHUB_BASE_URL"),
  55. "tencent-tokenplan": HermesOverlay(transport="anthropic_messages",
  56. base_url_override="https://api.lkeap.cloud.tencent.com/plan/anthropic",
  57. base_url_env_var="TOKENPLAN_BASE_URL"),
  58. "arcee": HermesOverlay(base_url_override="https://api.arcee.ai/api/v1", base_url_env_var="ARCEE_BASE_URL"),
  59. # models.dev lists CommandCode under CMD_API_KEY; the plugin profile and docs use COMMANDCODE_API_KEY.
  60. "commandcode": HermesOverlay(extra_env_vars=("COMMANDCODE_API_KEY",),
  61. base_url_override="https://api.commandcode.ai/provider/v1",
  62. base_url_env_var="COMMANDCODE_BASE_URL"),
  63. "gmi": HermesOverlay(extra_env_vars=("GMI_API_KEY",), base_url_override="https://api.gmi-serving.com/v1",
  64. base_url_env_var="GMI_BASE_URL"),
  65. "fireworks": HermesOverlay(extra_env_vars=("FIREWORKS_API_KEY",),
  66. base_url_override="https://api.fireworks.ai/inference/v1"),
  67. "actual": HermesOverlay(transport="chat_completions", extra_env_vars=("ACTUAL_API_KEY",),
  68. base_url_override="https://api.actual.inc/v1", base_url_env_var="ACTUAL_BASE_URL"),
  69. "upstage": HermesOverlay(extra_env_vars=("UPSTAGE_API_KEY",), base_url_override="https://api.upstage.ai/v1",
  70. base_url_env_var="UPSTAGE_BASE_URL"),
  71. "nebius-token-factory": HermesOverlay(extra_env_vars=("NEBIUS_API_KEY", "NEBIUS_TOKEN_FACTORY_API_KEY"),
  72. base_url_override="https://api.tokenfactory.nebius.com/v1",
  73. base_url_env_var="NEBIUS_BASE_URL"),
  74. "ollama-cloud": HermesOverlay(base_url_override="https://ollama.com/v1", base_url_env_var="OLLAMA_BASE_URL"),
  75. # Azure Foundry serves OpenAI- and Anthropic-style endpoints; transport comes from model.api_mode.
  76. "azure-foundry": HermesOverlay(base_url_env_var="AZURE_FOUNDRY_BASE_URL"),
  77. "bedrock": HermesOverlay(transport="bedrock_converse", auth_type="aws_sdk"),
  78. # Vertex is OAuth2 (service-account JSON / ADC), resolved by agent/vertex_adapter.py. Without an
  79. # overlay get_provider("vertex") is None and auxiliary_client._preserve_provider_with_base_url
  80. # would treat a Vertex MoA slot as an unknown custom endpoint, losing the identity
  81. # _refresh_provider_credentials() needs to re-mint an expired token on 401.
  82. "vertex": HermesOverlay(auth_type="vertex"),
  83. }
  84. # -- Resolved provider -------------------------------------------------------
  85. @dataclass
  86. class ProviderDef:
  87. """Complete provider definition — merged from models.dev + overlay + user config."""
  88. id: str
  89. name: str
  90. transport: str # openai_chat | anthropic_messages | codex_responses
  91. api_key_env_vars: tuple[str, ...] # all env vars to check for API key
  92. base_url: str = ""
  93. base_url_env_var: str = ""
  94. is_aggregator: bool = False
  95. auth_type: str = "api_key"
  96. doc: str = ""
  97. source: str = "" # "models.dev", "hermes", "user-config"
  98. # -- Aliases: human-friendly / legacy names grouped by canonical (models.dev where possible) id;
  99. # ``ALIASES`` is the inverted lookup table. ---------------------------------------------------
  100. _ALIAS_GROUPS: dict[str, tuple[str, ...]] = {
  101. "openrouter": ("openai",), "zai": ("glm", "z-ai", "z.ai", "zhipu"), "xai": ("x-ai", "x.ai", "grok"),
  102. "xai-oauth": ("grok-oauth", "xai-oauth", "x-ai-oauth", "xai-grok-oauth"),
  103. "nvidia": ("nim", "nvidia-nim", "build-nvidia", "nemotron"),
  104. "kimi-for-coding": ("kimi", "kimi-coding", "kimi-coding-cn", "moonshot"),
  105. "stepfun": ("step", "stepfun-coding-plan"), "minimax-cn": ("minimax-china", "minimax_cn"),
  106. "anthropic": ("claude", "claude-code"), "openai-codex": ("chatgpt", "chatgpt-codex"),
  107. "vercel": ("ai-gateway", "aigateway", "vercel-ai-gateway"),
  108. "opencode": ("opencode-zen", "zen"), "opencode-go": ("go", "opencode-go-sub"), "kilo": ("kilocode", "kilo-code", "kilo-gateway"),
  109. "deepseek": ("deep-seek",), "alibaba": ("dashscope", "aliyun", "qwen", "alibaba-cloud"),
  110. "alibaba-coding-plan": ("alibaba_coding", "alibaba-coding", "alibaba_coding_plan"),
  111. "huggingface": ("hf", "hugging-face", "huggingface-hub"), "novita": ("novita-ai", "novitaai"),
  112. "xiaomi": ("mimo", "xiaomi-mimo"), "tencent-tokenhub": ("tencent", "tokenhub", "tencent-cloud", "tencentmaas"),
  113. "tencent-tokenplan": ("tokenplan", "tencent-lkeap"),
  114. "bedrock": ("aws", "aws-bedrock", "amazon-bedrock", "amazon"), "arcee": ("arcee-ai", "arceeai"),
  115. "gmi": ("gmi-cloud", "gmicloud"), "fireworks": ("fireworks-ai", "fw"), "upstage": ("solar",),
  116. "actual": ("actual-computer", "actualcomputer", "aci"),
  117. "nebius-token-factory": ("nebius", "nebius-tokenfactory", "nebius-tf", "token-factory", "tokenfactory"),
  118. "lmstudio": ("lmstudio", "lm-studio", "lm_studio"),
  119. # Local OpenAI-compatible servers route through the generic "custom" provider,
  120. # matching hermes_cli.auth and hermes_cli.models so every layer agrees. Issue #62213.
  121. "custom": ("ollama", "local", "vllm", "llamacpp", "llama.cpp", "llama-cpp"),
  122. }
  123. ALIASES: dict[str, str] = {alias: canon for canon, aliases in _ALIAS_GROUPS.items() for alias in aliases}
  124. # -- Display labels for providers not in the models.dev catalog ---------------
  125. _LABEL_OVERRIDES: dict[str, str] = {
  126. "moa": "Mixture of Agents", "nous": "Nous Portal", "openai-codex": "ChatGPT or Codex Subscription",
  127. "stepfun": "StepFun Step Plan", "xiaomi": "Xiaomi MiMo", "gmi": "GMI Cloud",
  128. "upstage": "Upstage Solar", "actual": "Actual Computer", "tencent-tokenhub": "Tencent TokenHub",
  129. "nebius-token-factory": "Nebius Token Factory", "tencent-tokenplan": "Tencent TokenPlan", "lmstudio": "LM Studio",
  130. "custom": "Custom endpoint", "bedrock": "AWS Bedrock", "vertex": "Google Vertex AI", "ollama-cloud": "Ollama Cloud",
  131. "xai-oauth": "xAI Grok OAuth (SuperGrok / Premium+)",
  132. }
  133. # -- Transport → API mode mapping ---------------------------------------------
  134. TRANSPORT_TO_API_MODE: dict[str, str] = {
  135. "openai_chat": "chat_completions", "anthropic_messages": "anthropic_messages",
  136. "codex_responses": "codex_responses", "bedrock_converse": "bedrock_converse",
  137. }
  138. # -- Helper functions ---------------------------------------------------------
  139. def _overlay_profiles() -> list:
  140. """Registered profiles that declare a ``provider_overlay`` (no plugin-dir rescan on a miss)."""
  141. from providers import list_providers
  142. return [prof for prof in list_providers() if prof.provider_overlay]
  143. def _overlay_profile(name: str, profiles: Optional[list] = None):
  144. """The overlay-declaring profile *name* (its id, models.dev id or an overlay alias) belongs to, or
  145. None. *profiles*: an ``_overlay_profiles()`` result a loop already fetched."""
  146. if not name:
  147. return None
  148. return next((prof for prof in (_overlay_profiles() if profiles is None else profiles)
  149. if name in (prof.name, prof.models_dev_id, *prof.overlay_aliases)), None)
  150. def _profile_overlay_key(prof) -> str:
  151. return prof.models_dev_id or prof.name
  152. def hermes_overlays() -> dict[str, HermesOverlay]:
  153. """``HERMES_OVERLAYS`` plus the overlays registered profiles declare (``provider_overlay``)."""
  154. merged = dict(HERMES_OVERLAYS)
  155. for prof in _overlay_profiles():
  156. merged.setdefault(_profile_overlay_key(prof), HermesOverlay(**prof.provider_overlay))
  157. return merged
  158. _STATIC_CANONICAL_IDS: frozenset[str] = frozenset()
  159. def _is_static_canonical(key: str) -> bool:
  160. """Whether *key* is a built-in canonical id (static tables + the auth registry's built-in rows).
  161. Those never take a profile overlay's name, so ``normalize_provider`` answers them without
  162. the per-home profile scan. Asked mid-``hermes_cli.auth`` import (plugin discovery), before its
  163. built-in set exists, only the local tables answer and nothing is cached.
  164. """
  165. global _STATIC_CANONICAL_IDS
  166. if not _STATIC_CANONICAL_IDS:
  167. try:
  168. from hermes_cli.auth import BUILTIN_PROVIDER_IDS
  169. except ImportError:
  170. return key in HERMES_OVERLAYS or key in _ALIAS_GROUPS
  171. _STATIC_CANONICAL_IDS = BUILTIN_PROVIDER_IDS | frozenset(_ALIAS_GROUPS) | frozenset(HERMES_OVERLAYS)
  172. return key in _STATIC_CANONICAL_IDS
  173. def normalize_provider(name: str, overlay_profiles: Optional[list] = None) -> str:
  174. """Resolve aliases and normalise casing to a canonical provider id.
  175. *overlay_profiles*: an ``_overlay_profiles()`` result, so a loop over many names reads the
  176. profile list once instead of per name."""
  177. key = name.strip().lower()
  178. if key in ALIASES:
  179. return ALIASES[key]
  180. prof = None if _is_static_canonical(key) else _overlay_profile(key, overlay_profiles)
  181. return _profile_overlay_key(prof) if prof is not None else key
  182. def _get_overlay(canonical: str) -> tuple[Optional[HermesOverlay], str]:
  183. """``(overlay, label)`` for a canonical id: the static table, else a profile's ``provider_overlay``,
  184. labelled with the profile's ``display_name`` also when keyed by its models.dev id: without a
  185. models.dev catalog (offline, blocked) that label is the one picker rows and headings show."""
  186. if canonical in HERMES_OVERLAYS:
  187. return HERMES_OVERLAYS[canonical], _LABEL_OVERRIDES.get(canonical, canonical)
  188. prof = _overlay_profile(canonical)
  189. if prof is None or _profile_overlay_key(prof) != canonical:
  190. return None, canonical
  191. return HermesOverlay(**prof.provider_overlay), _LABEL_OVERRIDES.get(canonical, prof.display_name or canonical)
  192. def is_actual_route(provider: str = "", base_url: str = "") -> bool:
  193. """Identify Actual by provider/alias or its hosted endpoint, including custom routes."""
  194. return (
  195. normalize_provider(provider or "") == "actual"
  196. or base_url_hostname(base_url) == "api.actual.inc"
  197. )
  198. def _models_dev_info(canonical: str, allow_network: bool = True):
  199. """models.dev entry or None. Single-arg call on the default path: test sites monkeypatch
  200. ``get_provider_info`` with single-arg lambdas."""
  201. try:
  202. from agent.models_dev import get_provider_info as _mdev_provider
  203. return _mdev_provider(canonical) if allow_network else _mdev_provider(canonical, allow_network=False)
  204. except Exception:
  205. return None
  206. def _overlay_pdef(canonical, ov: HermesOverlay, name, env_vars, base_url, doc, source) -> ProviderDef:
  207. return ProviderDef(id=canonical, name=name, transport=ov.transport, api_key_env_vars=env_vars, base_url=base_url,
  208. base_url_env_var=ov.base_url_env_var, is_aggregator=ov.is_aggregator, auth_type=ov.auth_type, doc=doc,
  209. source=source)
  210. def _plugin_alias_owner(canonical: str) -> str:
  211. """The plugin profile's id when *canonical* is only one of its ``aliases``, else *canonical*.
  212. A plugin alias that is also a models.dev provider id (``meta`` -> ``meta-ai``, ``azure`` ->
  213. ``azure-foundry``) otherwise resolved to the bare models.dev entry whenever the catalog
  214. loaded and to the plugin when it did not, so ``--provider meta`` persisted a different
  215. provider depending on the network. ``hermes_cli.auth.resolve_provider`` already answers the
  216. plugin id. Built-in ids and overlay profiles keep what ``normalize_provider`` gave them.
  217. The owner comes from the registry's own lookup, so the bound home's plugin claiming the alias
  218. wins over a bundled one, exactly as ``get_provider_profile`` would pick it."""
  219. if not canonical or _is_static_canonical(canonical):
  220. return canonical
  221. from providers import get_provider_profile, list_providers
  222. profiles = list_providers()
  223. if any(prof.name == canonical for prof in profiles) or not any(
  224. canonical in prof.aliases for prof in profiles):
  225. return canonical
  226. owner = get_provider_profile(canonical)
  227. if owner is None or canonical not in owner.aliases or owner.provider_overlay:
  228. return canonical
  229. return owner.name
  230. def get_provider(name: str, *, allow_network: bool = True) -> Optional[ProviderDef]:
  231. """Look up a built-in provider by id or alias: models.dev catalog merged with the Hermes overlay;
  232. Hermes-only overlay (nous, openai-codex, …); plugin provider profiles with a concrete endpoint."""
  233. canonical = _plugin_alias_owner(normalize_provider(name))
  234. from hermes_cli.left_core_migration import provider_left_core
  235. if provider_left_core(canonical): # its plugin is not loaded: models.dev must not stand in for it
  236. return None
  237. mdev_info = _models_dev_info(canonical, allow_network)
  238. overlay, overlay_label = _get_overlay(canonical)
  239. if mdev_info is not None:
  240. ov = overlay or HermesOverlay()
  241. env_vars = list(mdev_info.env)
  242. for ev in ov.extra_env_vars:
  243. if ev not in env_vars:
  244. env_vars.append(ev)
  245. return _overlay_pdef(canonical, ov, mdev_info.name, tuple(env_vars), ov.base_url_override or mdev_info.api,
  246. mdev_info.doc, "models.dev")
  247. if overlay is not None:
  248. return _overlay_pdef(canonical, overlay, overlay_label, overlay.extra_env_vars,
  249. overlay.base_url_override, "", "hermes")
  250. # Plugin-registered profiles (plugins/model-providers/<name>/) absent from models.dev and
  251. # HERMES_OVERLAYS would otherwise be "Unknown provider" in /model, --provider and model-switch
  252. # even though the picker lists them. Only profiles with a literal or env-configured endpoint
  253. # resolve at this rung: placeholder profiles like ``custom`` (aliases ollama/local/vllm) ship
  254. # an empty base_url and are completed by config.yaml custom_providers — resolving them would
  255. # preempt resolve_provider_full's custom step and collapse keyed ``custom:<name>`` ids to bare
  256. # custom. Profiles whose endpoint is minted at runtime resolve at the END of
  257. # resolve_provider_full, after every user-configured rung.
  258. pdef = _plugin_profile_pdef(canonical)
  259. if pdef is None or not (pdef.base_url or (pdef.auth_type == "api_key" and pdef.api_key_env_vars and pdef.base_url_env_var)):
  260. return None
  261. return pdef
  262. def _plugin_profile_pdef(name: str) -> Optional[ProviderDef]:
  263. """The registered ``ProviderProfile`` for *name* (or one of its aliases) as a ProviderDef; the
  264. id is the profile's canonical name so an alias switch persists and resolves credentials under
  265. the same identity as the profile itself. URL-shaped env vars are the endpoint, not the key."""
  266. try:
  267. from providers import get_provider_profile as _profile
  268. prof = _profile(name)
  269. except Exception:
  270. return None
  271. if prof is None:
  272. return None
  273. env_vars = tuple(prof.env_vars or ())
  274. url_vars = tuple(v for v in env_vars if v.endswith(("_BASE_URL", "_URL")))
  275. key_vars = tuple(v for v in env_vars if v not in url_vars)
  276. api_mode_to_transport = {v: k for k, v in TRANSPORT_TO_API_MODE.items()}
  277. # A mode outside the reverse table is a plugin-registered dialect: keep its name so
  278. # ``determine_api_mode`` can check the transport registry instead of degrading it.
  279. mode = (prof.api_mode or "").strip()
  280. return ProviderDef(id=prof.name, name=prof.display_name or prof.name or name,
  281. transport=api_mode_to_transport.get(mode, mode or "openai_chat"),
  282. api_key_env_vars=key_vars, base_url=(prof.base_url or "").strip(),
  283. base_url_env_var=next(iter(url_vars), ""),
  284. auth_type=prof.auth_type or "api_key", source="plugin-profile")
  285. def get_label(provider_id: str) -> str:
  286. """Human-readable display name: label override, else models.dev name, else the id."""
  287. canonical = normalize_provider(provider_id)
  288. if canonical in _LABEL_OVERRIDES:
  289. return _LABEL_OVERRIDES[canonical]
  290. pdef = get_provider(canonical)
  291. return pdef.name if pdef else canonical
  292. def is_aggregator(provider: str) -> bool:
  293. """Return True when the provider is a multi-model aggregator."""
  294. provider_norm = normalize_provider(provider or "")
  295. if provider_norm.startswith("custom:"):
  296. return True
  297. pdef = get_provider(provider_norm)
  298. return pdef.is_aggregator if pdef else False
  299. # Flat-namespace resellers (opencode-go, opencode-zen) are flagged ``is_aggregator=True`` because
  300. # their live ``/v1/models`` returns bare model IDs ("deepseek-v4-flash") rather than
  301. # ``vendor/model`` routing slugs — model_switch searches their flat catalog on that flag. But they
  302. # are NOT routing aggregators: every listed model is first-party under their own subscription, so
  303. # picker dedup (build_models_payload) must not strip a reseller's "minimax-m3" just because a
  304. # user's custom proxy serves a same-named model. Normalized ids: "opencode-zen" -> "opencode".
  305. _FLAT_NAMESPACE_RESELLERS: frozenset[str] = frozenset({"opencode-go", "opencode"})
  306. def is_routing_aggregator(provider: str) -> bool:
  307. """True only for TRUE routing aggregators (OpenRouter, named ``custom:*`` proxies) — excludes
  308. flat-namespace resellers whose catalog is first-party. Use for "would selecting this model
  309. silently re-route away from the intended provider?" (picker dedup)."""
  310. provider_norm = normalize_provider(provider or "")
  311. if provider_norm in _FLAT_NAMESPACE_RESELLERS:
  312. return False
  313. return is_aggregator(provider_norm)
  314. def is_official_openai_host(base_url: str) -> bool:
  315. """True when *base_url* points at OpenAI's official API host family. Hostname-parsed matching
  316. only — never substring — so lookalike hosts (``api.openai.com.attacker.test``) and path-segment
  317. spoofs (``proxy.test/api.openai.com/v1``) are rejected; a genuine ``*.api.openai.com``
  318. subdomain requires control of openai.com DNS.
  319. A genuine ``*.api.openai.com`` subdomain requires control of openai.com DNS, so the dot-suffix match
  320. does not reopen the #32243 spoofing hole. Delegates to ``utils.base_url_host_matches``, which owns the
  321. exact-or-dot-suffix hostname contract (userinfo/port stripped, lowercased, trailing dot removed) — one
  322. implementation, not two.
  323. """
  324. return base_url_host_matches(base_url, "api.openai.com")
  325. # Exact hostnames that are Responses-API-native: api.meta.ai only achieves prompt-cache hits on
  326. # Responses with prompt_cache_retention (chat/completions stays cache-cold); api.router.com (Ramp
  327. # Router) keeps reasoning validation/summaries and prompt caching on /v1/responses and serves
  328. # /v1/chat/completions as a minimal shim.
  329. _RESPONSES_NATIVE_HOSTS: frozenset[str] = frozenset({"api.meta.ai", "api.router.com"})
  330. def host_mandated_api_mode(base_url: str = "") -> Optional[str]:
  331. """Return the wire protocol a specific endpoint *requires*, or None. Some hosts accept exactly
  332. one API mode (api.openai.com 400s chat/completions for reasoning models with tools); these are
  333. *mandatory*: a session carrying a stale api_mode (a /model switch that kept the previous
  334. provider's ``chat_completions``) must be overridden, not merely filled in when empty.
  335. Exact-hostname matching only — never substring — so lookalike hosts and path-segment spoofs are
  336. not treated as the real endpoint."""
  337. if not base_url:
  338. return None
  339. url_lower = base_url.rstrip("/").lower()
  340. hostname = base_url_hostname(base_url)
  341. if hostname == "api.actual.inc":
  342. return "chat_completions"
  343. # Exact-hostname matching only — never bare substring — so lookalike hosts
  344. # (api.openai.com.attacker.test) and path-segment spoofs (proxy.test/api.openai.com/v1) are NOT treated
  345. # as the real endpoint. (#32243)
  346. if hostname == "api.kimi.com" and "/coding" in url_lower:
  347. return "anthropic_messages"
  348. if hostname == "api.anthropic.com" or url_lower.endswith("/anthropic"):
  349. return "anthropic_messages"
  350. # Official OpenAI host family (canonical + us./eu. data-residency hosts) mandates Responses;
  351. # the shared predicate keeps this in lockstep with catalog filtering and listing authority.
  352. if is_official_openai_host(base_url) or hostname in _RESPONSES_NATIVE_HOSTS:
  353. # Ramp Router (api.router.com) is Responses-native: reasoning-effort validation, reasoning
  354. # summaries, and prompt caching live on /v1/responses, and /v1/chat/completions is only a minimal
  355. # compatibility shim (docs.router.com/api/endpoint). Exact-hostname match per #32243.
  356. return "codex_responses"
  357. if hostname.startswith("bedrock-runtime.") and base_url_host_matches(base_url, "amazonaws.com"):
  358. return "bedrock_converse"
  359. return None
  360. def nous_api_mode(model: str = "") -> str:
  361. """Wire protocol for a Nous Portal model. Portal serves its ``anthropic/*`` catalog on a native
  362. Messages route alongside OpenAI-compatible chat/completions for everything else.
  363. ``anthropic/*`` rides chat/completions by default for now (``nous.anthropic_wire``). Measured
  364. 2026-09-06, 20 concurrent sessions x 6 tool calls on Fable 5.1, same account and hour: the
  365. native route re-wrote the previous turn on 14-20% of consecutive calls (4 runs; the cache read
  366. stopped at the prior breakpoint with byte-identical prefixes), chat/completions 0 of 320 pairs.
  367. That is 15-20% of a fan-out's cache-write bill. The cause is inside the portal's native route
  368. (NousResearch/api#227 carries the diagnostics); flip the default back to ``native`` when it is
  369. fixed. Cost of ``chat``: prior-turn thinking travels as OpenAI-style reasoning fields instead of
  370. signed native blocks, and cache_control scopes are translated by the portal's adapter.
  371. Empty/unknown model defaults to ``chat_completions`` (the historical Nous transport)."""
  372. if str(model or "").strip().lower().startswith("anthropic/"):
  373. # ``auto`` starts on chat too: it is safe on every upstream, and ``agent/nous_wire.py``
  374. # promotes the session to native from the first response when the upstream allows it.
  375. return "anthropic_messages" if _nous_anthropic_wire() == "native" else "chat_completions"
  376. return "chat_completions"
  377. def _nous_anthropic_wire() -> str:
  378. """``nous.anthropic_wire``: ``"chat"`` (default), ``"native"``, or ``"auto"`` (chat, then per-session
  379. promotion decided from the first response; see ``agent/nous_wire.py``). Anything else reads as ``chat``."""
  380. try:
  381. from hermes_cli.config import load_config_readonly
  382. value = str(((load_config_readonly().get("nous") or {}).get("anthropic_wire")) or "chat").strip().lower()
  383. except Exception:
  384. return "chat"
  385. return value if value in ("native", "auto") else "chat"
  386. def determine_api_mode(provider: str, base_url: str = "", model: str = "") -> str:
  387. """API mode (wire protocol) for a provider/endpoint: host-mandated mode, then Nous dual-wire
  388. (model-derived — the overlay alone says openai_chat and would pin Claude on the wrong wire),
  389. then the known provider's transport, then bedrock, else ``chat_completions``."""
  390. if is_actual_route(provider, base_url):
  391. return "chat_completions"
  392. mandated = host_mandated_api_mode(base_url)
  393. if mandated is not None:
  394. return mandated
  395. if (provider or "").strip().lower() in {"nous", "nous-portal", "nousresearch"}:
  396. return nous_api_mode(model)
  397. pdef = get_provider(provider)
  398. if pdef is not None:
  399. if pdef.transport in TRANSPORT_TO_API_MODE:
  400. return TRANSPORT_TO_API_MODE[pdef.transport]
  401. # A plugin profile's transport IS its api_mode when a plugin registered that dialect.
  402. from agent.transports import registered_api_modes
  403. return pdef.transport if pdef.transport in registered_api_modes() else "chat_completions"
  404. if provider == "bedrock":
  405. return "bedrock_converse"
  406. return "chat_completions"
  407. # -- Provider from user config ------------------------------------------------
  408. def _user_pdef(pid: str, name: str, base_url: str, key_env: str, transport: str = "openai_chat") -> ProviderDef:
  409. """``source="user-config"`` ProviderDef shared by ``providers:`` and ``custom_providers:`` entries."""
  410. return ProviderDef(id=pid, name=name, transport=transport, api_key_env_vars=(key_env,) if key_env else (),
  411. base_url=base_url, is_aggregator=False, auth_type="api_key", source="user-config")
  412. def resolve_user_provider(name: str, user_config: dict[str, Any]) -> Optional[ProviderDef]:
  413. """Resolve a provider from the user's config.yaml ``providers:`` section.
  414. A ``providers.<name>`` block that carries no endpoint (``api``/``url``/``base_url``) is not a
  415. custom-endpoint definition — it is tuning for a BUILT-IN provider of the same name (e.g.
  416. ``providers.bedrock: {stale_timeout_seconds: 600}``, the documented path in
  417. ``agent/turn_recovery.py`` / ``thinking_timeout_guidance.py``). Resolving it here would shadow
  418. the built-in's real transport/base_url/auth_type with an empty ``openai_chat``/``api_key``
  419. stub, routing e.g. AWS Bedrock through the generic custom-endpoint ``/models`` probe (#110402).
  420. """
  421. entry = user_config.get(name) if isinstance(user_config, dict) and user_config else None
  422. if not isinstance(entry, dict):
  423. return None
  424. base_url = entry.get("api", "") or entry.get("url", "") or entry.get("base_url", "") or ""
  425. if not base_url:
  426. return None
  427. return _user_pdef(name, entry.get("name", "") or name, base_url,
  428. entry.get("key_env") or entry.get("api_key_env") or "",
  429. entry.get("transport", "openai_chat") or "openai_chat")
  430. def custom_provider_slug(display_name: str, provider_key: str = "") -> str:
  431. """Stable ``custom:`` identity for a configured provider: keyed ``providers:`` entries use their
  432. config key (survives display-name changes); legacy ``custom_providers:`` entries have no key,
  433. so their normalized display name is the identity."""
  434. identity = str(provider_key or "").strip() or str(display_name or "").strip()
  435. normalized = identity.lower().replace(" ", "-")
  436. return normalized if normalized.startswith("custom:") else f"custom:{normalized}"
  437. def custom_provider_aliases(display_name: str, provider_key: str = "") -> frozenset[str]:
  438. """Return every current and legacy identity accepted for one endpoint."""
  439. aliases: set[str] = set()
  440. for value in (display_name, provider_key):
  441. raw = str(value or "").strip().lower()
  442. if not raw:
  443. continue
  444. normalized = raw.replace(" ", "-")
  445. aliases.update({raw, normalized, custom_provider_slug(normalized)})
  446. if normalized.startswith("custom:"):
  447. suffix = normalized.split(":", 1)[1]
  448. if suffix:
  449. aliases.update({suffix, f"custom:{normalized}"})
  450. return frozenset(aliases)
  451. def resolve_custom_provider(name: str, custom_providers: Optional[list[dict[str, Any]]]) -> Optional[ProviderDef]:
  452. """Resolve a provider from the user's config.yaml ``custom_providers`` list. A stored bare
  453. ``"custom"`` (corrupt state from a prior model-switch bug) falls back to the first valid entry
  454. so existing configs self-heal."""
  455. requested = (name or "").strip().lower()
  456. if not requested or not custom_providers or not isinstance(custom_providers, list):
  457. return None
  458. first_valid: Optional[ProviderDef] = None
  459. # If the stored provider is the bare string "custom" (corrupt state from a prior model-switch bug), fall
  460. # back to the first custom provider entry so existing configs self-heal. (GH #17478)
  461. for entry in custom_providers:
  462. if not isinstance(entry, dict):
  463. continue
  464. display_name = (entry.get("name") or "").strip()
  465. api_url = (entry.get("base_url", "") or entry.get("url", "") or entry.get("api", "") or "").strip()
  466. if not display_name or not api_url:
  467. continue
  468. provider_key = (entry.get("provider_key") or "").strip()
  469. pdef = _user_pdef(custom_provider_slug(display_name, provider_key), display_name, api_url,
  470. (entry.get("key_env") or "").strip())
  471. if first_valid is None:
  472. first_valid = pdef
  473. if requested in custom_provider_aliases(display_name, provider_key):
  474. return pdef
  475. if requested == "custom" and first_valid:
  476. return first_valid
  477. return None
  478. def _lossy_alias_registry_pdef(raw: str, canonical: str) -> Optional[ProviderDef]:
  479. """Exact Hermes registry ids win over LOSSY alias collapsing (kimi-coding-cn must stay distinct
  480. from kimi-coding instead of collapsing through the shared models.dev alias "kimi-for-coding").
  481. A collapse is lossy only when MULTIPLE registry providers normalize to the same canonical name;
  482. single-entry rewrites (a Hermes id -> its models.dev id) are correct routing and keep resolving
  483. through the built-in chain so overlay transports apply."""
  484. try:
  485. from hermes_cli.auth import PROVIDER_REGISTRY as _AUTH_PROVIDER_REGISTRY
  486. _pcfg = _AUTH_PROVIDER_REGISTRY.get(raw)
  487. if _pcfg is None:
  488. return None
  489. overlays = _overlay_profiles()
  490. _rows = [_row for _rid, _row in _AUTH_PROVIDER_REGISTRY.items() if normalize_provider(_rid, overlays) == canonical]
  491. # A profile-declared overlay routes its own mirrored alias keys through the built-in chain.
  492. if all(_row is _pcfg for _row in _rows) and _overlay_profile(canonical, overlays) is not None:
  493. return None
  494. if len(_rows) > 1:
  495. return ProviderDef(id=_pcfg.id, name=_pcfg.name, transport="openai_chat",
  496. api_key_env_vars=tuple(_pcfg.api_key_env_vars or ()), base_url=_pcfg.inference_base_url or "",
  497. source="hermes-auth-registry")
  498. except Exception:
  499. pass
  500. return None
  501. # The local llama.cpp runtime's provider id + aliases: ONE definition, shared by the resolver rung
  502. # below and the picker's Local row (``hermes_cli/inventory.py``) — the two drifting apart is what
  503. # made the row's own id unresolvable.
  504. LLAMACPP_PROVIDER_ID = "llamacpp"
  505. LLAMACPP_ALIASES: tuple[str, ...] = (LLAMACPP_PROVIDER_ID, "llama.cpp", "llama-cpp")
  506. def _has_staged_local_models() -> bool:
  507. """True when GGUFs are staged under the Hermes home's ``models/`` — the model the picker's Local
  508. row offers, which the runtime seam serves by booting/attaching a server on selection."""
  509. try:
  510. from hermes_cli.local_runtime.bootstrap import staged_model_ids
  511. return bool(staged_model_ids())
  512. except Exception:
  513. return False
  514. def _llamacpp_pdef() -> Optional[ProviderDef]:
  515. """The llamacpp aliases are a real provider whenever the managed server (or a detected external
  516. one) resolves — reachability is the credential — OR a model is staged for the runtime to serve.
  517. The picker's Local row is built from staged GGUFs and is deliberately offline-first (selection
  518. starts the server through the runtime seam), so requiring a live endpoint before admitting the id
  519. made that row offer a provider the resolver rejected ("Unknown provider 'llamacpp'"). Without
  520. this rung model-switch rejected the very provider the Local Models 'Use' flow writes to config."""
  521. try:
  522. from hermes_cli.config import load_config_readonly
  523. from hermes_cli.local_runtime.endpoint import resolve_llamacpp_endpoint
  524. endpoint = resolve_llamacpp_endpoint(config=load_config_readonly(), wait_for_boot_s=0)
  525. except Exception:
  526. endpoint = None
  527. if not endpoint and not _has_staged_local_models():
  528. return None
  529. return ProviderDef(id=LLAMACPP_PROVIDER_ID, name="Local", transport="openai_chat", api_key_env_vars=(),
  530. base_url=(endpoint or {}).get("base_url", ""), source="local-runtime")
  531. def resolve_provider_full(name: str, user_providers: Optional[dict[str, Any]] = None,
  532. custom_providers: Optional[list[dict[str, Any]]] = None) -> Optional[ProviderDef]:
  533. """Full resolution chain: user ``providers.<raw name>`` -> lossy-alias registry id -> built-in
  534. (models.dev + overlays) -> user providers (canonical, then raw) -> ``custom_providers`` ->
  535. managed llamacpp -> models.dev directly. User-defined ``providers.<name>`` is tried FIRST on
  536. the raw (pre-alias) name: a configured ``providers.openai`` pointing at api.openai.com must not
  537. be hijacked by the legacy "openai" -> "openrouter" alias."""
  538. canonical = normalize_provider(name)
  539. raw = name.strip().lower()
  540. if user_providers:
  541. user_pdef = resolve_user_provider(raw, user_providers)
  542. if user_pdef is not None:
  543. return user_pdef
  544. if canonical != raw:
  545. pdef = _lossy_alias_registry_pdef(raw, canonical)
  546. if pdef is not None:
  547. return pdef
  548. pdef = get_provider(canonical)
  549. if pdef is not None:
  550. if pdef.source == "plugin-profile" and user_providers:
  551. user_pdef = resolve_user_provider(pdef.id, user_providers)
  552. if user_pdef is not None:
  553. return user_pdef
  554. return pdef
  555. if user_providers:
  556. for candidate in (canonical, raw):
  557. user_pdef = resolve_user_provider(candidate, user_providers)
  558. if user_pdef is not None:
  559. return user_pdef
  560. custom_pdef = resolve_custom_provider(name, custom_providers)
  561. if custom_pdef is not None:
  562. return custom_pdef
  563. if raw in LLAMACPP_ALIASES:
  564. pdef = _llamacpp_pdef()
  565. if pdef is not None:
  566. return pdef
  567. try:
  568. mdev_info = _models_dev_info(canonical)
  569. if mdev_info is not None:
  570. return ProviderDef(id=canonical, name=mdev_info.name, transport="openai_chat", api_key_env_vars=mdev_info.env,
  571. base_url=mdev_info.api, source="models.dev")
  572. except Exception:
  573. pass
  574. # Plugin profiles whose endpoint is minted at runtime (empty base_url, e.g. a token exchange
  575. # that also returns the host) are still real providers: /model --provider, the model picker
  576. # and `hermes model` must not reject them as unknown. Last rung, so every user-configured
  577. # entry above wins; the bare ``custom`` placeholder is excluded because model-switch completes
  578. # it from the current endpoint (see get_provider).
  579. pdef = _plugin_profile_pdef(canonical)
  580. return pdef if pdef is not None and pdef.id != "custom" else None