model_switch.py 103 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990
  1. """Shared model-switching logic for the CLI and gateway /model commands.
  2. Pipeline: parse flags -> alias resolution -> provider resolution -> credential resolution ->
  3. normalize model name -> metadata lookup -> build result. Provider switching uses ``--provider``
  4. exclusively; colons are reserved for OpenRouter variant suffixes (``:free``, ``:extended``)."""
  5. from __future__ import annotations
  6. import logging
  7. import os
  8. import re
  9. from contextlib import suppress
  10. from dataclasses import dataclass, field
  11. from typing import Any, NamedTuple, Optional
  12. from hermes_cli.providers import (
  13. LLAMACPP_ALIASES, ProviderDef, custom_provider_aliases, determine_api_mode, get_label,
  14. host_mandated_api_mode, is_aggregator, normalize_provider, resolve_provider_full)
  15. from hermes_cli.model_normalize import normalize_model_for_provider
  16. from agent.models_dev import (
  17. ModelCapabilities, ModelInfo, get_model_capabilities, get_model_info, list_provider_models)
  18. from utils import base_url_host_matches, base_url_hostname, base_url_origin
  19. # Re-exported: callers/tests patch hermes_cli.model_switch.<name>.
  20. from hermes_cli.model_switch_providers import list_authenticated_providers
  21. logger = logging.getLogger(__name__)
  22. def _declared_model_ids(value: Any) -> list[str]:
  23. """Configured model IDs from ``{"id": {...}}``, ``["a", "b"]``, ``[{"id"|"name": ...}]`` or ``"a"``."""
  24. if isinstance(value, str):
  25. candidates: Any = [value]
  26. elif isinstance(value, dict):
  27. # Pre-fix Hermes wrote sentinel keys inside the user-facing ``models`` mapping.
  28. candidates = (k for k in value if k not in ("__explicit_model_allowlist__", "__discovered_model_catalog__"))
  29. elif isinstance(value, (list, tuple)):
  30. candidates = (_declared_item_id(item) if isinstance(item, dict) else item for item in value)
  31. else:
  32. return []
  33. ids: list[str] = []
  34. seen: set[str] = set()
  35. for candidate in candidates:
  36. if not isinstance(candidate, str):
  37. continue # non-str items are dropped
  38. model_id = candidate.strip()
  39. if model_id and model_id.lower() not in seen:
  40. seen.add(model_id.lower())
  41. ids.append(model_id)
  42. return ids
  43. def _declared_item_id(item: dict) -> Any:
  44. """``id`` of a ``[{"id": ...}]`` entry, falling back to ``name`` when blank/missing."""
  45. model_id = item.get("id")
  46. return model_id if isinstance(model_id, str) and model_id.strip() else item.get("name")
  47. def _entry_models_discovered(entry: Any) -> bool:
  48. """True when the entry's ``models`` mapping was auto-discovered by Hermes.
  49. Current shape: entry-level ``models_discovered: true``. Older versions wrote an in-mapping
  50. ``__discovered_model_catalog__: true`` sentinel — accepted on read (the next save migrates it)."""
  51. if not isinstance(entry, dict):
  52. return False
  53. models = entry.get("models")
  54. return entry.get("models_discovered") is True or (
  55. isinstance(models, dict) and models.get("__discovered_model_catalog__") is True)
  56. def _models_config_is_allowlist(value: Any, discovered: bool = False) -> bool:
  57. """True when ``models:`` is an intentional ID allowlist.
  58. A mapping like ``{model_id: {context_length: N}}`` is per-model *metadata* written by
  59. ``_save_custom_provider`` / the wizard, not a catalog narrow (treating it as one made GUI
  60. pickers show only the saved default for keyless Ollama while the CLI live-probed). List and
  61. string shapes remain allowlists for no-key endpoints; pin a dict catalog with
  62. ``discover_models: false``. A catalog Hermes itself persisted (``discovered``) is never a pin."""
  63. if discovered:
  64. return False
  65. if isinstance(value, str):
  66. return bool(value.strip())
  67. if isinstance(value, (list, tuple)):
  68. return bool(_declared_model_ids(value))
  69. return False # None, dict (per-model metadata), or anything else
  70. def _bare_custom_provider_def(current_base_url: str) -> Optional[ProviderDef]:
  71. """ProviderDef for a direct ``model.provider: custom`` endpoint."""
  72. base_url = _clean(current_base_url)
  73. if not base_url:
  74. return None
  75. return ProviderDef(
  76. id="custom", name="Custom endpoint", transport="openai_chat", api_key_env_vars=(),
  77. base_url=base_url, is_aggregator=False, auth_type="api_key", source="model-config")
  78. # --- Non-agentic model warning
  79. _HERMES_MODEL_WARNING = (
  80. "Nous Research Hermes 3 & 4 models are NOT agentic and are not designed "
  81. "for use with Hermes Agent. They lack the tool-calling capabilities "
  82. "required for agent workflows. Consider using an agentic model instead "
  83. "(Claude, GPT, Gemini, DeepSeek, etc.).")
  84. # Match only the real Nous Research Hermes 3 / 4 chat families; a bare substring check
  85. # false-positived on tool-capable local Modelfiles like ``hermes-brain:qwen3-14b-ctx16k``.
  86. # match: NousResearch/Hermes-3-Llama-3.1-70B, hermes-4-405b, openrouter/hermes3:70b
  87. # no match: hermes-brain:qwen3-14b-ctx16k, qwen3:14b, claude-opus-4-6
  88. _NOUS_HERMES_NON_AGENTIC_RE = re.compile(r"(?:^|[/:])hermes[-_ ]?[34](?:[-_.:]|$)", re.IGNORECASE)
  89. # Opaque proxy model IDs (Palantir Foundry: ``ri.language-model-service..language-model.<slug>``)
  90. # are noise in status output; the provider_label already carries the routing context. Stripped
  91. # for DISPLAY ONLY — never for wire-side comparison, persistence, config writes or alias lookup.
  92. _OPAQUE_MODEL_PREFIXES: tuple[str, ...] = ("ri.language-model-service..language-model.",)
  93. def format_model_for_display(model_name: str) -> str:
  94. """Human-friendly form of *model_name* for CLI status output (display only, never wire-side)."""
  95. for prefix in _OPAQUE_MODEL_PREFIXES:
  96. if model_name and model_name.startswith(prefix):
  97. return model_name[len(prefix):] or model_name
  98. return model_name
  99. def is_nous_hermes_non_agentic(model_name: str) -> bool:
  100. """True if *model_name* is a real Nous Hermes 3/4 chat model (single owner; cli.py uses it too)."""
  101. return bool(model_name and _NOUS_HERMES_NON_AGENTIC_RE.search(model_name))
  102. def _check_hermes_model_warning(model_name: str) -> str:
  103. """Warning string if *model_name* is a Nous Hermes 3/4 chat model, else ""."""
  104. return _HERMES_MODEL_WARNING if is_nous_hermes_non_agentic(model_name) else ""
  105. # --- Model aliases -- short names -> (vendor, family) with NO version numbers,
  106. # resolved dynamically against the live models.dev catalog.
  107. class ModelIdentity(NamedTuple):
  108. """Vendor slug and family prefix used for catalog resolution."""
  109. vendor: str
  110. family: str
  111. MODEL_ALIASES: dict[str, ModelIdentity] = {
  112. "sonnet": ModelIdentity("anthropic", "claude-sonnet"),
  113. "opus": ModelIdentity("anthropic", "claude-opus"),
  114. "haiku": ModelIdentity("anthropic", "claude-haiku"),
  115. "claude": ModelIdentity("anthropic", "claude"),
  116. "gpt5": ModelIdentity("openai", "gpt-5"),
  117. "gpt": ModelIdentity("openai", "gpt"),
  118. "codex": ModelIdentity("openai", "codex"),
  119. "o3": ModelIdentity("openai", "o3"),
  120. "o4": ModelIdentity("openai", "o4"),
  121. "gemini": ModelIdentity("google", "gemini"),
  122. "deepseek": ModelIdentity("deepseek", "deepseek-chat"),
  123. "grok": ModelIdentity("x-ai", "grok"),
  124. "llama": ModelIdentity("meta-llama", "llama"),
  125. "qwen": ModelIdentity("qwen", "qwen"),
  126. "minimax": ModelIdentity("minimax", "minimax"),
  127. "nemotron": ModelIdentity("nvidia", "nemotron"),
  128. "kimi": ModelIdentity("moonshotai", "kimi"),
  129. "glm": ModelIdentity("z-ai", "glm"),
  130. "step": ModelIdentity("stepfun", "step"),
  131. "mimo": ModelIdentity("xiaomi", "mimo"),
  132. "trinity": ModelIdentity("arcee-ai", "trinity")}
  133. # --- Direct aliases — exact model+provider+base_url for endpoints outside the
  134. # models.dev catalog (Ollama Cloud, local servers). Checked BEFORE catalog
  135. # resolution; loaded from config.yaml ``model_aliases:`` / ``model.aliases``.
  136. class DirectAlias(NamedTuple):
  137. """Exact model mapping that bypasses catalog resolution.
  138. ``api_key`` / ``key_env`` carry the alias endpoint's OWN credential. Without them the switch
  139. would keep the *default* provider's key, which 401s against the alias host and sends that
  140. provider's secret to an unrelated third party. Both default so positional
  141. ``DirectAlias(model, provider, base_url)`` keeps working.
  142. See #83612.
  143. """
  144. model: str
  145. provider: str
  146. base_url: str
  147. api_key: str = ""
  148. key_env: str = ""
  149. # Built-in direct aliases (extended via config.yaml model_aliases:)
  150. _BUILTIN_DIRECT_ALIASES: dict[str, DirectAlias] = {}
  151. def _clean(value: Any) -> str:
  152. """``str(value or "").strip()`` — the config-field normaliser used throughout this module."""
  153. return str(value or "").strip()
  154. # Merged dict (builtins + user config); populated by _load_direct_aliases()
  155. DIRECT_ALIASES: dict[str, DirectAlias] = {}
  156. def _load_direct_aliases(cfg: Optional[dict] = None) -> dict[str, DirectAlias]:
  157. """Load direct aliases from config.yaml (or from the caller's *cfg* snapshot).
  158. ``model_aliases:`` entries are dicts (``model``, ``provider``, ``base_url``, optional
  159. ``api_key`` — literal or ``"${VAR}"`` — / ``key_env``); with neither credential field the key
  160. is resolved from the alias HOST, never from the previously active provider. ``model.aliases``
  161. never overrides ``model_aliases``; its string entries (``ds-flash: deepseek/deepseek-v4-flash``)
  162. take the provider from the ``provider/`` prefix, else the current provider.
  163. See #83612.
  164. """
  165. merged = dict(_BUILTIN_DIRECT_ALIASES)
  166. try:
  167. if cfg is None:
  168. from hermes_cli.config import load_config
  169. cfg = load_config()
  170. user_aliases = cfg.get("model_aliases")
  171. if isinstance(user_aliases, dict):
  172. for name, entry in user_aliases.items():
  173. if isinstance(entry, dict) and entry.get("model", ""):
  174. merged[name.strip().lower()] = DirectAlias(
  175. model=entry.get("model", ""), provider=entry.get("provider", "custom"),
  176. base_url=entry.get("base_url", ""), api_key=_clean(entry.get("api_key", "")),
  177. key_env=_clean(entry.get("key_env", "")))
  178. model_section = cfg.get("model", {})
  179. simple_aliases = model_section.get("aliases") if isinstance(model_section, dict) else None
  180. if isinstance(simple_aliases, dict):
  181. current_provider = model_section.get("provider", "")
  182. for name, value in simple_aliases.items():
  183. key = name.strip().lower()
  184. if not key or key in merged:
  185. continue
  186. if isinstance(value, dict):
  187. model = _clean(value.get("model"))
  188. if model:
  189. merged[key] = DirectAlias(
  190. model=model, provider=_clean(value.get("provider")) or current_provider or "custom",
  191. base_url=_clean(value.get("base_url", "")),
  192. api_key=_clean(value.get("api_key", "")),
  193. key_env=_clean(value.get("key_env", "")))
  194. elif isinstance(value, str) and value.strip():
  195. val = value.strip()
  196. provider, model = val.split("/", 1) if "/" in val else (current_provider, val)
  197. merged[key] = DirectAlias(
  198. model=model.strip(), provider=provider.strip() or current_provider, base_url="")
  199. except Exception:
  200. pass
  201. return merged
  202. # Identity of the config the cached aliases were built from. The cache is process-global but its
  203. # source is profile-local: unkeyed, the first profile to resolve an alias would pin its definitions
  204. # — and, since entries carry `api_key`, its credentials — for every later profile. Same shape
  205. # `load_config()` keys on, so a profile switch (path) and a key rotation (mtime/size) both invalidate.
  206. _DIRECT_ALIAS_IDENTITY: Optional[tuple] = None
  207. # Copy of what the loader last produced. Callers and tests seed DIRECT_ALIASES both by rebinding
  208. # and by editing in place, so only comparing against what we wrote tells our stale cache from
  209. # someone else's contents.
  210. _DIRECT_ALIAS_LOADED: Optional[dict] = None
  211. def _direct_alias_source_identity() -> Optional[tuple]:
  212. """Identity of the active profile's alias source; None means "do not reuse the cache"."""
  213. try:
  214. from hermes_constants import get_config_path
  215. path = get_config_path()
  216. except Exception:
  217. return None
  218. from hermes_cli.config_backend import config_cache_version
  219. try:
  220. version = config_cache_version(path)
  221. except OSError:
  222. # A missing config is still a definite identity for this profile.
  223. return (str(path), None)
  224. except Exception:
  225. return None
  226. return (str(path), version)
  227. def _ensure_direct_aliases() -> None:
  228. """Load direct aliases for the ACTIVE profile, caching per config identity.
  229. Mutates DIRECT_ALIASES in place (never rebinds) so ``from ... import DIRECT_ALIASES``
  230. references in callers stay valid."""
  231. global _DIRECT_ALIAS_IDENTITY, _DIRECT_ALIAS_LOADED
  232. identity = _direct_alias_source_identity()
  233. if DIRECT_ALIASES and (
  234. # Contents are not what we loaded — seeded or edited by a caller. Not ours to discard.
  235. DIRECT_ALIASES != _DIRECT_ALIAS_LOADED
  236. # Ours, and still the same config file at the same signature.
  237. or (identity is not None and identity == _DIRECT_ALIAS_IDENTITY)):
  238. return
  239. loaded = _load_direct_aliases()
  240. DIRECT_ALIASES.clear()
  241. DIRECT_ALIASES.update(loaded)
  242. _DIRECT_ALIAS_IDENTITY = identity
  243. _DIRECT_ALIAS_LOADED = dict(loaded)
  244. def direct_alias_api_key(alias: DirectAlias) -> str:
  245. """Resolve a direct alias's own credential, or "" when it has none.
  246. Precedence: ``api_key: "${VAR}"`` (env indirection) > literal ``api_key`` > ``key_env``.
  247. Env reads go through the per-profile secret scope: a raw ``os.environ`` read hands this
  248. profile whatever key the process env holds — another profile's, under the multiplexed gateway."""
  249. raw = (alias.api_key or "").strip()
  250. if raw.startswith("${") and raw.endswith("}"):
  251. return _scoped_key_env(raw[2:-1].strip())
  252. if raw:
  253. return raw
  254. return _scoped_key_env((alias.key_env or "").strip())
  255. def direct_alias_runtime_request(alias: DirectAlias) -> tuple[str, Optional[str]]:
  256. """``(requested_provider, explicit_api_key)`` for resolving *alias*.
  257. Single owner of the invariant that a URL-bearing direct alias resolves its credential for
  258. the alias HOST, never for its provider label: a label like ``anthropic`` on an unrelated URL
  259. would otherwise reach that provider's explicit-runtime branch and put the live vendor token
  260. on the foreign wire. Bare ``custom`` is host-gated, so an authoritative URL still resolves
  261. its vendor key and a foreign one resolves none. An alias with no base_url keeps its label —
  262. there is no foreign host, and the label is the only routing information.
  263. See #28660.
  264. """
  265. return ("custom" if alias.base_url else (alias.provider or "custom")), direct_alias_api_key(alias) or None
  266. # Hosts where plaintext HTTP is not a downgrade — no network hop to intercept.
  267. _LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1", "0.0.0.0"})
  268. def _may_reuse_session_credential(session_base_url: str, alias_base_url: str) -> bool:
  269. """Whether the session's key may follow a switch to *alias_base_url*.
  270. Same hostname is NOT sufficient: ``http://h`` and ``https://h:8443`` are different trust
  271. boundaries, and an alias that drops the scheme would put a live bearer secret on the wire in
  272. the clear. Require an identical (scheme, host, port) and refuse plaintext outside loopback."""
  273. session = base_url_origin(session_base_url)
  274. alias = base_url_origin(alias_base_url)
  275. if not session[1] or session != alias:
  276. return False
  277. scheme, hostname, _ = alias
  278. return scheme == "https" or hostname in _LOOPBACK_HOSTS
  279. class StartupModelRoute(NamedTuple):
  280. """Model/provider pair resolved before an agent is constructed."""
  281. model: str
  282. provider: str = ""
  283. base_url: str = ""
  284. api_key: str = ""
  285. def resolve_startup_model_route(
  286. raw_model: str, *, explicit_provider: str = "", current_provider: str = "",
  287. user_providers: Optional[dict] = None,
  288. custom_providers: Optional[list] = None, alias_config: Optional[dict] = None) -> Optional[StartupModelRoute]:
  289. """Resolve aliases, ``provider:model`` and configured ``provider/model`` input at startup.
  290. ``HermesCLI`` is constructed before the interactive ``/model`` pipeline runs; resolving here
  291. keeps startup from attaching the configured default provider to an explicitly requested
  292. model. ``provider/model`` strings are consumed only for providers present in user config. When
  293. ``current_provider`` is a routing aggregator and the raw string is an aggregator-native slug
  294. (``anthropic/claude-opus-4.6`` on OpenRouter) the input stays on the aggregator — a
  295. ``providers:`` block for the same vendor must not steal the route. ``alias_config`` is a
  296. caller's config snapshot to read aliases from instead of the process-global cache."""
  297. raw = _clean(raw_model)
  298. if not raw:
  299. return None
  300. if alias_config is None:
  301. _ensure_direct_aliases()
  302. aliases = DIRECT_ALIASES if alias_config is None else _load_direct_aliases(alias_config)
  303. direct = aliases.get(raw.lower())
  304. if direct is not None:
  305. if explicit_provider:
  306. # An explicit --provider wins over the alias's own label; the alias contributes
  307. # model/base_url only.
  308. return StartupModelRoute(model=direct.model, provider=explicit_provider, base_url=direct.base_url)
  309. # Same owner as the interactive /model and oneshot paths: credential for the alias HOST.
  310. # Resolve through the SAME owner the interactive /model and oneshot paths use: a URL-bearing alias
  311. # must resolve its credential for the alias HOST, never for its provider label — a label like
  312. # ``anthropic`` on a foreign URL would otherwise reach that provider's explicit-runtime branch and
  313. # put the live vendor token on the foreign wire (#28660).
  314. alias_provider, alias_key = direct_alias_runtime_request(direct)
  315. return StartupModelRoute(
  316. model=direct.model, provider=alias_provider, base_url=direct.base_url, api_key=alias_key or "")
  317. if explicit_provider:
  318. return None
  319. # ``custom:<name>:<model>`` / ``<provider>:<model>`` — the same qualified form ``/model``
  320. # accepts. Left undecoded, the configured default provider receives the unsplit string as
  321. # the model name and the whole prompt goes to its endpoint before it 404s (#73943). The
  322. # configured ids come from the caller's config, the same source the ``/`` branch below uses.
  323. from hermes_cli.models import parse_model_input
  324. from hermes_cli.providers import custom_provider_slug
  325. custom_ids = {custom_provider_slug(str(entry.get("name") or key), str(key))
  326. for key, entry in (user_providers or {}).items() if isinstance(entry, dict)}
  327. custom_ids.update(custom_provider_slug(str(entry.get("name") or ""))
  328. for entry in (custom_providers or []) if isinstance(entry, dict) and _clean(entry.get("name")))
  329. qualified_provider, qualified_model = parse_model_input(raw, "", custom_ids=custom_ids)
  330. if qualified_provider:
  331. return StartupModelRoute(model=qualified_model, provider=qualified_provider)
  332. if "/" not in raw:
  333. return None
  334. prefix, model = (part.strip() for part in raw.split("/", 1))
  335. if not prefix or not model:
  336. return None
  337. if current_provider:
  338. try:
  339. from hermes_cli.providers import is_routing_aggregator, normalize_provider as _norm_prov
  340. if is_routing_aggregator(_norm_prov(current_provider)):
  341. from hermes_cli.models import _find_openrouter_slug
  342. if _find_openrouter_slug(raw):
  343. return None
  344. except Exception:
  345. pass
  346. configured = {str(name).strip().lower() for name in (user_providers or {}) if str(name).strip()}
  347. configured.update(
  348. f"custom:{entry.get('name', '').strip().lower()}"
  349. for entry in (custom_providers or [])
  350. if isinstance(entry, dict) and _clean(entry.get("name")))
  351. try:
  352. from hermes_cli.models import normalize_provider
  353. canonical = normalize_provider(prefix)
  354. except Exception:
  355. canonical = prefix.lower()
  356. if prefix.lower() in configured:
  357. provider = prefix
  358. elif canonical.lower() in configured:
  359. provider = canonical
  360. else:
  361. return None
  362. return None if is_aggregator(canonical) else StartupModelRoute(model=model, provider=provider)
  363. # --- Result dataclasses
  364. @dataclass
  365. class ModelSwitchResult:
  366. """Result of a model switch attempt."""
  367. success: bool
  368. new_model: str = ""
  369. target_provider: str = ""
  370. provider_changed: bool = False
  371. api_key: str = ""
  372. base_url: str = ""
  373. api_mode: str = ""
  374. request_overrides: Optional[dict] = None
  375. error_message: str = ""
  376. warning_message: str = ""
  377. # Window plans only: the Large-model warning (display only, never a confirm). Empty for every other
  378. # account and model, so their switch output is unchanged.
  379. usage_notice: str = ""
  380. provider_label: str = ""
  381. resolved_via_alias: str = ""
  382. capabilities: Optional[ModelCapabilities] = None
  383. runtime_capabilities: Optional[dict[str, bool]] = None
  384. model_info: Optional[ModelInfo] = None
  385. is_global: bool = False
  386. # The resolved direct alias's own ``base_url`` (and the credential decided for it) replaced the
  387. # provider's route. ``resolved_via_alias`` alone is also set by a built-in shortcut, an endpointless
  388. # entry or a process provider's declared id, which name a model like a plain pick.
  389. alias_endpoint_applied: bool = False
  390. @dataclass(frozen=True)
  391. class ModelFlagParseResult:
  392. """Parsed flags for a /model command."""
  393. model_input: str
  394. explicit_provider: str = ""
  395. reasoning_effort: str = ""
  396. is_global: bool = False
  397. force_refresh: bool = False
  398. is_session: bool = False
  399. is_once: bool = False
  400. # --- Flag parsing
  401. _BOOL_FLAGS = {"--global": "is_global", "--session": "is_session", "--refresh": "force_refresh", "--once": "is_once"}
  402. _VALUE_FLAGS = {"--provider": "explicit_provider", "--reasoning": "reasoning_effort"}
  403. def parse_model_flags_detailed(raw_args: str) -> ModelFlagParseResult:
  404. """Parse /model flags: ``--provider X``, ``--reasoning <level>``, ``--global``, ``--session``,
  405. ``--refresh``, ``--once``.
  406. ``--once`` is parsed here but interpreted by each caller (each frontend has its own
  407. live-session restore hook). ``is_global`` / ``is_session`` are raw flag presences; the
  408. effective persistence decision belongs to :func:`resolve_persist_behavior`. ``reasoning_effort``
  409. is the raw level word (validated by :func:`hermes_constants.parse_reasoning_effort` at apply
  410. time) so a model pick and its effort travel as ONE request on every surface."""
  411. # Telegram/iOS auto-convert ``--`` to an em/en dash: normalize a single Unicode dash before
  412. # a flag keyword.
  413. raw_args = re.sub(r'[\u2012\u2013\u2014\u2015](provider|reasoning|global|session|refresh|once)', r'--\1', raw_args)
  414. # Hand-rolled: model IDs may contain colons/slashes and the historical parser did not
  415. # require shell quoting.
  416. flags: dict[str, bool] = dict.fromkeys(_BOOL_FLAGS.values(), False)
  417. values: dict[str, str] = dict.fromkeys(_VALUE_FLAGS.values(), "")
  418. filtered: list[str] = []
  419. tokens = iter(raw_args.split())
  420. for tok in tokens:
  421. if tok in _BOOL_FLAGS:
  422. flags[_BOOL_FLAGS[tok]] = True
  423. elif tok in _VALUE_FLAGS and (value := next(tokens, None)) is not None:
  424. values[_VALUE_FLAGS[tok]] = value
  425. else:
  426. filtered.append(tok) # a trailing bare ``--provider`` stays part of the model text
  427. return ModelFlagParseResult(model_input=" ".join(filtered).strip(), **values, **flags)
  428. def resolve_persist_behavior(
  429. is_global: bool, is_session: bool, is_once: bool = False, explicit_provider: str = "") -> bool:
  430. """Decide whether a ``/model`` switch should persist to ``config.yaml``.
  431. Order: ``--once`` / ``--session`` -> False; ``--global`` -> True; no default configured yet
  432. (neither ``model.default`` nor ``model.provider`` — a fresh install's first pick) -> True, so
  433. the pick does not evaporate into whatever ``*_API_KEY`` is lying around on the next launch;
  434. ``model.persist_switch_by_default`` -> True (the user's explicit opt-in to persistence);
  435. ``--provider`` without a persist flag -> False (exploratory). A flat-string ``model`` IS a configured
  436. default; an unreadable config -> False.
  437. 1. ``--once`` explicitly opts out → ``False`` (next turn only). 2. ``--session`` explicitly opts out →
  438. ``False`` (this session only). 3. 4. Applies to every surface (CLI, gateway, Desktop picker) so no
  439. client has to hardcode ``--global``. 5. ``model.persist_switch_by_default: true`` also covers provider picks (a pick between two providers sharing one ``base_url`` is tenant selection on the same backend, not exploration;
  440. session-scoping it silently serves the next chat with the other twin's key). 6. Without that opt-in, provider switches stay exploratory — the user is trying a different backend for this conversation, not reconfiguring the default. The key defaults to ``False`` (a plain ``/model <name>`` affects only the current session); users who want the old persist-by-default behavior can set it to ``true``; a one-off ``--global`` always persists, and ``--session`` / ``--once`` always opt out. See #86414.
  441. """
  442. if is_once or is_session:
  443. return False
  444. if is_global:
  445. return True
  446. try:
  447. from hermes_cli.config import load_config
  448. model_cfg = load_config().get("model")
  449. except Exception:
  450. return False
  451. if isinstance(model_cfg, dict):
  452. if not (model_cfg.get("default") or model_cfg.get("provider")):
  453. return True
  454. if bool(model_cfg.get("persist_switch_by_default", False)):
  455. return True
  456. if explicit_provider:
  457. return False
  458. return False
  459. return not model_cfg
  460. # --- Single-owner /model request parsing + effective-model resolution. Surfaces
  461. # (cli.py, gateway/slash_commands.py, tui_gateway/server.py, api_server.py)
  462. # map error codes to their own copy but never re-derive the semantics.
  463. # Error codes emitted by parse_model_switch_args().
  464. MODEL_SWITCH_ERR_ONCE_WITH_GLOBAL = "once_with_global"
  465. MODEL_SWITCH_ERR_ONCE_REQUIRES_TARGET = "once_requires_target"
  466. MODEL_SWITCH_ERR_BAD_REASONING = "bad_reasoning"
  467. MODEL_SWITCH_ERR_RESET_WITH_FLAGS = "reset_with_flags"
  468. # Canonical (surface-neutral) error copy. Surfaces prepend their own decoration (" ✗ " in the
  469. # CLI, "❌ " in the gateway) but MUST NOT change the core sentence — it is shared user-visible copy.
  470. MODEL_SWITCH_ERROR_TEXT = {
  471. MODEL_SWITCH_ERR_ONCE_WITH_GLOBAL: "/model --once cannot be combined with --global",
  472. MODEL_SWITCH_ERR_ONCE_REQUIRES_TARGET: "/model --once requires a model or provider.",
  473. MODEL_SWITCH_ERR_BAD_REASONING: "/model --reasoning takes none, minimal, low, medium, high, xhigh, max or ultra.",
  474. MODEL_SWITCH_ERR_RESET_WITH_FLAGS: (
  475. "/model reset takes no flags — it clears this session's model override so the "
  476. "configured default applies again.")}
  477. # ``/model reset`` clears the session's /model override instead of switching to a model named
  478. # "reset". Deliberately NOT aliased to "default": MoA's default preset is literally named
  479. # "default", so ``/model default`` keeps resolving through exact_moa_preset_name(). A model whose
  480. # bare id is "reset" stays reachable by its qualified slug (``vendor/reset``, ``vendor:reset``).
  481. MODEL_SWITCH_RESET_TOKEN = "reset"
  482. @dataclass(frozen=True)
  483. class ModelSwitchRequest:
  484. """A fully parsed /model command request.
  485. ``scope`` is the *requested* persistence scope from the flags alone: ``"once"`` |
  486. ``"session"`` | ``"global"`` | ``"default"`` (the effective decision then belongs to
  487. :func:`resolve_persist_behavior`). ``errors`` carries ``MODEL_SWITCH_ERR_*`` codes rendered
  488. via :data:`MODEL_SWITCH_ERROR_TEXT`. ``model_input`` keeps it a drop-in for
  489. :class:`ModelFlagParseResult` consumers."""
  490. raw: str
  491. target: str
  492. explicit_provider: str = ""
  493. reasoning_effort: str = ""
  494. is_global: bool = False
  495. is_session: bool = False
  496. is_once: bool = False
  497. force_refresh: bool = False
  498. scope: str = "default"
  499. errors: tuple = ()
  500. @property
  501. def model_input(self) -> str:
  502. return self.target
  503. def error_messages(self) -> list:
  504. """Canonical (undercorated) error strings for this request."""
  505. return [MODEL_SWITCH_ERROR_TEXT[code] for code in self.errors]
  506. @property
  507. def is_reset(self) -> bool:
  508. """``/model reset`` with no flags: clear the session override, keep the conversation."""
  509. return self.target.strip().lower() == MODEL_SWITCH_RESET_TOKEN and not self.errors
  510. def parse_model_switch_args(raw: str) -> ModelSwitchRequest:
  511. """The ONE parser for every /model surface: tokenization plus flag-conflict validation.
  512. ``--once`` + ``--global`` -> ``MODEL_SWITCH_ERR_ONCE_WITH_GLOBAL``; ``--once`` with neither
  513. a model nor ``--provider`` -> ``MODEL_SWITCH_ERR_ONCE_REQUIRES_TARGET``; an unknown
  514. ``--reasoning`` level -> ``MODEL_SWITCH_ERR_BAD_REASONING``; ``reset`` with any flag ->
  515. ``MODEL_SWITCH_ERR_RESET_WITH_FLAGS`` (see :attr:`ModelSwitchRequest.is_reset`). Targets pass through
  516. untouched (bare names, ``vendor/model``, ``vendor:model``) for :func:`switch_model`."""
  517. raw = str(raw or "")
  518. parsed = parse_model_flags_detailed(raw)
  519. errors: list = []
  520. if parsed.is_once and parsed.is_global:
  521. errors.append(MODEL_SWITCH_ERR_ONCE_WITH_GLOBAL)
  522. if parsed.is_once and not parsed.model_input and not parsed.explicit_provider:
  523. errors.append(MODEL_SWITCH_ERR_ONCE_REQUIRES_TARGET)
  524. if parsed.reasoning_effort:
  525. from hermes_constants import parse_reasoning_effort
  526. if parse_reasoning_effort(parsed.reasoning_effort) is None:
  527. errors.append(MODEL_SWITCH_ERR_BAD_REASONING)
  528. if parsed.model_input.strip().lower() == MODEL_SWITCH_RESET_TOKEN and (
  529. parsed.explicit_provider or parsed.reasoning_effort or parsed.is_global
  530. or parsed.is_session or parsed.is_once):
  531. errors.append(MODEL_SWITCH_ERR_RESET_WITH_FLAGS)
  532. # First matching flag wins: once > session > global > default.
  533. scope = next((name for name, on in (("once", parsed.is_once), ("session", parsed.is_session),
  534. ("global", parsed.is_global)) if on), "default")
  535. return ModelSwitchRequest(
  536. raw=raw, target=parsed.model_input, scope=scope, errors=tuple(errors),
  537. **{f: getattr(parsed, f)
  538. for f in ("explicit_provider", "reasoning_effort", "is_global", "is_session", "is_once", "force_refresh")})
  539. def _effective_model_candidate(value: Any) -> str:
  540. """Extract a model-name candidate from a str / dict / attr-object."""
  541. if isinstance(value, str):
  542. return value.strip()
  543. if isinstance(value, dict):
  544. return _clean(value.get("model"))
  545. model_attr = getattr(value, "model", None)
  546. return _clean(model_attr) if model_attr is not None else ""
  547. def resolve_effective_model(
  548. session_overrides: Any = None, channel_config: Any = None, global_config: Any = "") -> str:
  549. """Resolve the effective model: session override > channel > global.
  550. Single owner of the precedence rule gateway/run.py and api_server.py each used to encode.
  551. Each argument may be a model string, a dict with a ``"model"`` key, or an object with a
  552. ``.model`` attribute; empty entries fall through to the next tier."""
  553. for tier in (session_overrides, channel_config, global_config):
  554. candidate = _effective_model_candidate(tier)
  555. if candidate:
  556. return candidate
  557. return ""
  558. # --- Alias resolution
  559. def _model_sort_key(model_id: str, prefix: str) -> tuple:
  560. """Sort key preferring higher versions after the family prefix, then ranked suffix tokens.
  561. With prefix ``"mimo"``: ``mimo-v2.5-pro`` -> (-2.5, 0, 'pro'), ``mimo-v2.5`` -> (-2.5, 1, ''),
  562. ``mimo-v2-omni`` -> (-2.0, 1, 'omni')."""
  563. # Strip the prefix (and optional "/" separator for aggregator slugs)
  564. rest = model_id[len(prefix):].removeprefix("/").lstrip("-").strip()
  565. nums, suffix_buf = _split_version_suffix(rest)
  566. suffix = suffix_buf.lower().strip("-_.").strip()
  567. # YYYYMMDD date stamps (claude-opus-4-20250514) are snapshot markers, not version components,
  568. # and would dwarf real point versions; keep them as a trailing tiebreaker so bare IDs sort
  569. # before their dated snapshots and newer snapshots before older. The 19_000_101 threshold
  570. # reclassifies only 8-digit stamps (mistral-large-2411, gpt-4-0613 keep sorting as versions).
  571. version_key = tuple(-n for n in nums if n < 19_000_101) # negate: higher sorts first
  572. date_stamp = max((n for n in nums if n >= 19_000_101), default=0.0)
  573. date_key = (0.0, 0.0) if date_stamp == 0.0 else (1.0, -date_stamp)
  574. # Suffix quality: pro/max/plus/turbo (0) > no suffix / omni / flash / mini (1). "sol" is the
  575. # flagship tier of the GPT-5.6 series (sol > terra > luna); without it `/model gpt` would
  576. # tiebreak alphabetically onto luna, the cheapest. GPT-6 put "astra" above "sol": both rank 0 and
  577. # the alphabetical tiebreak lands on astra, so `/model gpt` still resolves to the flagship.
  578. suffix_rank = 0 if suffix in ("pro", "max", "plus", "turbo", "sol", "astra") else 1
  579. return version_key + (suffix_rank, suffix) + date_key
  580. def _split_version_suffix(rest: str) -> tuple[list[float], str]:
  581. """``"v2.5-pro"`` -> ``([2.5], "pro")``; ``"-omni"`` -> ``([], "omni")``.
  582. Version tokens are ``v``-optional digit/dot runs separated by ``-``/``_``; a second dot inside
  583. a run starts a new component; the first character that is neither starts the suffix."""
  584. nums: list[float] = []
  585. run, pos = "", 0
  586. def _flush() -> None:
  587. nonlocal run
  588. try:
  589. nums.append(float(run.rstrip(".")))
  590. except ValueError:
  591. pass
  592. run = ""
  593. while pos < len(rest):
  594. ch = rest[pos]
  595. if ch in "-_.":
  596. pos += 1
  597. continue
  598. if not (ch in "vV" or ch.isdigit()):
  599. break
  600. if ch in "vV":
  601. pos += 1
  602. while pos < len(rest) and (rest[pos].isdigit() or rest[pos] == "."):
  603. if rest[pos] == "." and "." in run:
  604. _flush()
  605. else:
  606. run += rest[pos]
  607. pos += 1
  608. _flush()
  609. if pos < len(rest) and rest[pos] not in "-_":
  610. break
  611. return nums, rest[pos:]
  612. class AmbiguousAliasError(Exception):
  613. """Alias family-matches multiple catalog models; caller must disambiguate.
  614. Raised by :func:`resolve_alias` instead of silently picking one via version-sort heuristics.
  615. ``candidates`` is sorted best-guess-first (see :func:`_model_sort_key`) for display only."""
  616. def __init__(self, alias: str, provider: str, candidates: list[str]):
  617. self.alias = alias
  618. self.provider = provider
  619. self.candidates = candidates
  620. super().__init__(f"alias {alias!r} matches {len(candidates)} models on {provider}")
  621. def _ambiguous_alias_message(err: AmbiguousAliasError) -> str:
  622. """User-facing disambiguation list for an ambiguous alias."""
  623. shown = err.candidates[:10]
  624. lines = "\n".join(f" {i}. {m}" for i, m in enumerate(shown, 1))
  625. hidden = len(err.candidates) - len(shown)
  626. more = f"\n … and {hidden} more" if hidden > 0 else ""
  627. return (
  628. f"'{err.alias}' matches {len(err.candidates)} models on "
  629. f"{err.provider} — not switching automatically:\n{lines}{more}\n"
  630. f"Pick one with /model <exact-model-name>.")
  631. def _provider_identity(name: str, user_providers: Optional[dict] = None,
  632. custom_providers: Optional[list] = None) -> str:
  633. """Id a provider name routes to, e.g. ``custom:<name>`` for a legacy ``custom_providers``
  634. entry, so an alias naming it by its bare name compares equal to the resolved provider."""
  635. pdef = resolve_provider_full(name, user_providers, custom_providers) if name else None
  636. return pdef.id if pdef is not None else normalize_provider(name or "")
  637. def resolve_alias(raw_input: str, current_provider: str, user_providers: Optional[dict] = None,
  638. custom_providers: Optional[list] = None) -> Optional[tuple[str, str, str]]:
  639. """Resolve a short alias against the current provider's catalog.
  640. Direct aliases (and reverse lookup by exact model id) win; then :data:`MODEL_ALIASES` is
  641. matched against the provider's models.dev catalog by ``vendor/family`` prefix (``family``
  642. for non-aggregators). Returns ``(provider, resolved_model_id, alias_name)`` or None; raises
  643. :class:`AmbiguousAliasError` when several catalog models match."""
  644. key = raw_input.strip().lower()
  645. _ensure_direct_aliases()
  646. direct = DIRECT_ALIASES.get(key)
  647. if direct is not None:
  648. return (direct.provider, direct.model, key)
  649. # Reverse lookup so full names ("kimi-k2.5") route through direct aliases instead of
  650. # falling through to the catalog/OpenRouter. Several aliases may expose one model id on
  651. # different providers: prefer the one served by current_provider, since insertion order is
  652. # not a routing decision and the wrong alias hands back another provider's base_url.
  653. reverse_fallback: Optional[tuple[str, str, str]] = None
  654. current_id = _provider_identity(current_provider, user_providers, custom_providers)
  655. for alias_name, da in DIRECT_ALIASES.items():
  656. if da.model.lower() != key:
  657. continue
  658. if _provider_identity(da.provider, user_providers, custom_providers) == current_id:
  659. return (da.provider, da.model, alias_name)
  660. if reverse_fallback is None:
  661. reverse_fallback = (da.provider, da.model, alias_name)
  662. if reverse_fallback is not None:
  663. return reverse_fallback
  664. process_catalog, process_aliases = _external_process_catalog(current_provider)
  665. if process_catalog:
  666. # Process providers own their model IDs and aliases (models.dev knows nothing about
  667. # them); a typed id or family alias that they declare must not leave the provider.
  668. declared = _external_process_match(process_catalog, process_aliases, key, provider=current_provider)
  669. if declared is not None:
  670. return (current_provider, declared, key)
  671. identity = MODEL_ALIASES.get(key)
  672. if identity is None:
  673. return None
  674. vendor, family = identity
  675. if process_catalog:
  676. declared = _external_process_match(process_catalog, process_aliases, family, provider=current_provider)
  677. return (current_provider, declared, key) if declared else None
  678. # models.dev catalog merged with static _PROVIDER_MODELS entries it may be missing.
  679. catalog = list_provider_models(current_provider)
  680. try:
  681. from hermes_cli.models import static_catalog
  682. seen = {m.lower() for m in catalog}
  683. catalog.extend(m for m in static_catalog(current_provider) if m.lower() not in seen)
  684. except Exception:
  685. pass
  686. prefix = f"{vendor}/{family}" if is_aggregator(current_provider) else family
  687. matches = [mid for mid in catalog if mid.lower().startswith(prefix.lower())]
  688. if not matches:
  689. return None
  690. # Version-sort for display, but NEVER silently pick among multiple candidates: the
  691. # heuristics have repeatedly guessed wrong (dated snapshots outranking point releases,
  692. # suffix tiebreaks landing on the cheapest tier).
  693. matches.sort(key=lambda m: _model_sort_key(m, prefix))
  694. if len(matches) > 1:
  695. raise AmbiguousAliasError(key, current_provider, matches)
  696. return (current_provider, matches[0], key)
  697. def _external_process_catalog(provider: str) -> tuple[list[str], dict[str, str]]:
  698. """``(declared model ids, own aliases)`` of an ``external_process`` profile, else empty."""
  699. from providers import get_provider_profile
  700. profile = get_provider_profile(provider)
  701. if profile is None or profile.auth_type != "external_process":
  702. return [], {}
  703. return list(profile.fallback_models), {k.lower(): v for k, v in profile.model_aliases.items()}
  704. def _external_process_match(catalog: list[str], aliases: dict[str, str], typed: str, *, provider: str) -> str | None:
  705. """Provider alias, exact id, else the single declared id that extends it (``claude-opus-5``
  706. -> ``claude-opus-5[1m]``); several candidates raise so nothing is picked silently."""
  707. wanted = typed.strip().lower()
  708. if wanted in aliases:
  709. return aliases[wanted]
  710. exact = next((m for m in catalog if m.lower() == wanted), None)
  711. if exact is not None:
  712. return exact
  713. matches = [m for m in catalog if m.lower().startswith(wanted)]
  714. if len(matches) > 1:
  715. raise AmbiguousAliasError(wanted, provider, matches)
  716. return matches[0] if matches else None
  717. def get_authenticated_provider_slugs(
  718. current_provider: str = "", user_providers: dict | None = None, custom_providers: list | None = None
  719. ) -> list[str]:
  720. """Slugs of providers that have credentials (models.dev in-memory cache + disk catalog cache;
  721. stale catalogs warm in the background, never in this call)."""
  722. try:
  723. return [p["slug"] for p in list_authenticated_providers(
  724. current_provider=current_provider, user_providers=user_providers,
  725. custom_providers=custom_providers, max_models=0, non_blocking_catalogs=True)]
  726. except Exception:
  727. return []
  728. def _resolve_alias_fallback(
  729. raw_input: str, authenticated_providers: list[str] = (), user_providers: Optional[dict] = None,
  730. custom_providers: Optional[list] = None) -> Optional[tuple[str, str, str]]:
  731. """Resolve an alias on the user's authenticated providers (``("openrouter", "nous")`` when none given).
  732. AmbiguousAliasError propagates: the alias exists on this provider, the user just has to
  733. choose — trying the next provider would silently switch them somewhere they didn't ask for."""
  734. results = (resolve_alias(raw_input, p, user_providers, custom_providers)
  735. for p in authenticated_providers or ("openrouter", "nous"))
  736. return next((r for r in results if r is not None), None)
  737. def effective_context_pin(
  738. config_context_length: int | None, model: str, provider: str, base_url: str = "",
  739. configured_model: str | None = None, configured_provider: str | None = None,
  740. configured_base_url: str | None = None) -> int | None:
  741. """The ``model.context_length`` pin that still applies to ``model`` on this route, or None when the
  742. route changed from the configured one (the pin belongs to that model). Fail-closed: None on error."""
  743. if config_context_length is None or not (configured_model or configured_provider or configured_base_url):
  744. return config_context_length
  745. try:
  746. from hermes_cli.route_identity import should_clear_context_pin
  747. clear = should_clear_context_pin(
  748. configured_model, model, configured_base_url, base_url, configured_provider, provider)
  749. except Exception: # any route-identity failure drops the pin, as resolve_display_context_length always did
  750. logger.debug("context pin route check failed for %s", model, exc_info=True)
  751. return None
  752. return None if clear else config_context_length
  753. def resolve_display_context_length(
  754. model: str, provider: str, base_url: str = "", api_key: str = "",
  755. model_info: Optional[ModelInfo] = None, custom_providers: list | None = None,
  756. config_context_length: int | None = None, configured_model: str | None = None,
  757. configured_provider: str | None = None,
  758. configured_base_url: str | None = None) -> Optional[int]:
  759. """Context length to show in /model output.
  760. models.dev reports per-vendor context but provider-enforced limits can be lower (Codex OAuth
  761. caps gpt-5.5 at 272k), so ``agent.model_metadata.get_model_context_length`` is authoritative
  762. (it also honors ``custom_providers[].models.<id>.context_length``); ``model_info.context_window``
  763. is the fallback. A ``config_context_length`` pin is dropped when the route changed.
  764. When ``custom_providers`` is provided, per-model ``context_length`` overrides from
  765. ``custom_providers[].models.<id>.context_length`` are honored — this closes #15779 where ``/model``
  766. switch ignored user-set overrides.
  767. """
  768. config_context_length = effective_context_pin(
  769. config_context_length, model, provider, base_url, configured_model, configured_provider, configured_base_url)
  770. try:
  771. from agent.model_metadata import get_model_context_length
  772. ctx = get_model_context_length(
  773. model, base_url=base_url or "", api_key=api_key or "", provider=provider or None,
  774. custom_providers=custom_providers, config_context_length=config_context_length)
  775. if ctx:
  776. return int(ctx)
  777. except Exception:
  778. pass
  779. if model_info is not None and model_info.context_window:
  780. return int(model_info.context_window)
  781. return None
  782. async def resolve_display_context_length_async(model: str, provider: str, **kwargs) -> Optional[int]:
  783. """Thread-offloaded :func:`resolve_display_context_length` (same keyword arguments) — the sync
  784. version runs blocking provider probes that async gateway handlers must not run on the loop."""
  785. import asyncio
  786. return await asyncio.to_thread(resolve_display_context_length, model, provider, **kwargs)
  787. # --- Configured-provider detection for typed model names
  788. def _configured_provider_matches(
  789. model_name: str, user_providers: Optional[dict], custom_providers: Optional[list]
  790. ) -> dict[str, str]:
  791. """``{provider_slug: canonical_model_id}`` for every configured provider whose declared models
  792. (``models``, ``model``, ``default_model`` — exact, case-insensitive, never fuzzy) contain
  793. ``model_name``, so a typed name routes to the provider that declares it instead of being
  794. soft-accepted by the current provider (openai-codex) as an unknown hidden model.
  795. Used by :func:`switch_model` to route a *typed* model name to the provider that actually declares it in
  796. user/custom provider config, instead of leaving it on the current provider. See #45006.
  797. """
  798. if not model_name or not model_name.strip():
  799. return {}
  800. target = model_name.strip().lower()
  801. candidates: list[tuple[str, dict]] = []
  802. if isinstance(user_providers, dict):
  803. candidates += [(slug, cfg) for slug, cfg in user_providers.items()
  804. if isinstance(slug, str) and isinstance(cfg, dict)]
  805. # Callers (gateway, TUI, CLI) pass both ``providers:`` and the compat ``custom_providers`` view,
  806. # which re-lists every ``providers.<slug>`` row as ``custom:<name>``; a hand-migrated config may
  807. # also keep the same endpoint in both sections. Either is one provider, not two (#112788) — but
  808. # the duplicate is folded at the MATCH level, not dropped as a candidate: a model only the legacy
  809. # row declares still routes to the shared endpoint instead of falling through to the current
  810. # provider.
  811. rows = {slug: _configured_provider_identity(slug, cfg) for slug, cfg in candidates}
  812. entries = [(f"custom:{e['name']}", e) for e in _custom_entries(custom_providers)
  813. if isinstance(e.get("name"), str) and e["name"].strip()]
  814. matches: dict[str, str] = {}
  815. for slug, cfg in candidates + entries:
  816. hit = next((mid for key in ("models", "model", "default_model")
  817. for mid in _declared_model_ids(cfg.get(key)) if mid.lower() == target), None)
  818. if hit:
  819. owner = _duplicates_configured_row(slug, cfg, rows) if slug not in rows else None
  820. matches.setdefault(owner or slug, hit) # first declaration wins
  821. return matches
  822. def _configured_provider_identity(slug: str, cfg: dict) -> tuple[str, str, str, str]:
  823. """``(name, endpoint, credential, api_mode)`` of one configured provider, read through the same
  824. normalizer that builds the compat view, so a ``providers.<slug>`` row, its ``custom:<name>``
  825. projection and a legacy duplicate of the same endpoint reduce to one tuple. Any difference in
  826. endpoint, credential identity or wire protocol keeps two rows distinct."""
  827. from hermes_cli.config_providers import _canonical_api_mode, _normalize_custom_provider_entry
  828. # ``provider_key`` is the compat view's stamp, not a config key: drop it so the normalizer does
  829. # not warn about it as unknown.
  830. entry = _normalize_custom_provider_entry({k: v for k, v in cfg.items() if k != "provider_key"},
  831. provider_key="" if slug.startswith("custom:") else slug) or cfg
  832. name = (_clean(entry.get("name")).lower() or slug.removeprefix("custom:").lower()).replace(" ", "-")
  833. base_url = _clean(entry.get("base_url") or entry.get("url") or entry.get("api")).rstrip("/").lower()
  834. api_key, key_env = _clean(entry.get("api_key")), _clean(entry.get("key_env") or entry.get("api_key_env"))
  835. if api_key.startswith("${") and api_key.endswith("}"):
  836. api_key, key_env = "", api_key[2:-1].strip()
  837. credential = (f"key:{api_key}" if api_key else f"env:{key_env}" if key_env
  838. else f"cmd:{_clean(entry.get('key_cmd'))}" if _clean(entry.get("key_cmd")) else "")
  839. api_mode = _clean(entry.get("api_mode") or entry.get("transport"))
  840. return name, base_url, credential, _canonical_api_mode(api_mode).lower() if api_mode else ""
  841. def _duplicates_configured_row(
  842. slug: str, entry: dict, rows: dict[str, tuple[str, str, str, str]]) -> Optional[str]:
  843. """Slug of the ``providers.<slug>`` row a ``custom_providers`` entry is a second view of, else
  844. None: the row's compat projection (``provider_key`` names the slug AND it points at the same
  845. endpoint with the same credential — on the raw-list fallback a hand-written provider_key aimed
  846. at another endpoint or another key stays a candidate) or a legacy duplicate with the same
  847. provider identity."""
  848. identity = _configured_provider_identity(slug, entry)
  849. provider_key = _clean(entry.get("provider_key")).lower()
  850. return next((row_slug for row_slug, row in rows.items()
  851. if identity == row or (provider_key == row_slug.lower() and identity[1:3] == row[1:3])), None)
  852. def _current_provider_match(st: _Switch, cfg_matches: dict[str, str]) -> Optional[str]:
  853. """The slug in *cfg_matches* the session already runs on: an exact hit, or — for a session on
  854. the compat projection slug (``custom:relay``) of ``providers.relay`` — that row's slug, so a
  855. same-provider switch keeps the caller's slug instead of flipping it (#112788)."""
  856. if st.current_provider in cfg_matches:
  857. return st.current_provider
  858. current = _clean(st.current_provider).lower()
  859. providers = st.user_providers if isinstance(st.user_providers, dict) else {}
  860. return next((slug for slug in cfg_matches if isinstance(providers.get(slug), dict)
  861. and current in custom_provider_aliases(str(providers[slug].get("name") or ""), slug)), None)
  862. def _resolve_named_custom_model_id(model_name: str, target_provider: str, custom_providers: Optional[list]) -> str:
  863. """Map a picker-prefixed custom model selection (``prefix/model``) to its configured ID."""
  864. provider = _clean(target_provider).lower()
  865. if not provider.startswith("custom:") or "/" not in model_name:
  866. return model_name
  867. prefix, candidate = (part.strip() for part in model_name.split("/", 1))
  868. if not prefix or not candidate:
  869. return model_name
  870. for entry in _custom_entries(custom_providers):
  871. entry_slugs = _entry_aliases(entry)
  872. if provider in entry_slugs and f"custom:{prefix.lower()}" in entry_slugs:
  873. for model_id in _declared_model_ids(entry.get("models")):
  874. if model_id.lower() == candidate.lower():
  875. return model_id
  876. return model_name
  877. def _custom_entries(custom_providers: Any) -> list[dict]:
  878. """The dict-shaped entries of a ``custom_providers:`` list (anything else is ignored)."""
  879. return [e for e in custom_providers if isinstance(e, dict)] if isinstance(custom_providers, list) else []
  880. def _entry_aliases(entry: dict) -> frozenset[str]:
  881. return custom_provider_aliases(str(entry.get("name") or ""), str(entry.get("provider_key") or ""))
  882. # --- Core model-switching pipeline
  883. def _entry_configured_key(cfg: dict, read_env) -> str:
  884. """Inline ``api_key`` (a ``${VAR}`` template resolves via *read_env*), else
  885. ``key_env``/``api_key_env`` via *read_env*."""
  886. key = _clean(cfg.get("api_key", ""))
  887. if key.startswith("${") and key.endswith("}"):
  888. key = read_env(key[2:-1])
  889. if not key:
  890. key_env = _clean(cfg.get("key_env") or cfg.get("api_key_env"))
  891. key = read_env(key_env) if key_env else ""
  892. return key
  893. def _ollama_configured_base() -> tuple[dict, str]:
  894. from hermes_cli.models import _get_provider_config_dict
  895. cfg = _get_provider_config_dict("ollama")
  896. return cfg, _clean(cfg.get("base_url") or cfg.get("api") or cfg.get("url"))
  897. def _unknown_provider_message(explicit_provider: str) -> str:
  898. from hermes_cli.left_core_migration import provider_install_hint
  899. if moved := provider_install_hint(explicit_provider):
  900. return f"Unknown provider '{explicit_provider}'. {moved}"
  901. msg = (
  902. f"Unknown provider '{explicit_provider}'. Check 'hermes model' for available "
  903. f"providers, or define it in config.yaml under 'providers:'.")
  904. try: # Surface common config issues that cause provider resolution failures
  905. from hermes_cli.config import validate_config_structure
  906. issues = validate_config_structure()
  907. if issues:
  908. msg += "\n\nRun 'hermes doctor' — config issues detected:" + "".join(f"\n • {ci.message}" for ci in issues[:3])
  909. except Exception:
  910. pass
  911. return msg
  912. def _aggregator_alias_error(
  913. explicit_provider: str, target_provider: str, current_provider: str, user_providers, custom_providers,
  914. ) -> str:
  915. """Guard against silent aggregator hops: a vendor alias like bare "openai" resolves to an
  916. aggregator ("openrouter"); if that aggregator has no credentials, refuse instead of switching
  917. the user onto an unauthed endpoint (HTTP 401) and point at the real direct provider."""
  918. from hermes_cli.models import _AGGREGATOR_PROVIDERS
  919. from hermes_cli.providers import ALIASES
  920. explicit_norm = explicit_provider.strip().lower()
  921. alias_target = ALIASES.get(explicit_norm)
  922. if not (
  923. alias_target and alias_target == target_provider and target_provider != explicit_norm
  924. and target_provider in _AGGREGATOR_PROVIDERS):
  925. return ""
  926. authed = get_authenticated_provider_slugs(
  927. current_provider=current_provider, user_providers=user_providers, custom_providers=custom_providers)
  928. if target_provider in authed:
  929. return ""
  930. suggestions = [s for s in authed if s.startswith(explicit_norm) and s != explicit_norm]
  931. hint = f" Did you mean: {', '.join(suggestions)}?" if suggestions else ""
  932. return (
  933. f"Provider '{explicit_norm}' is an alias that routes "
  934. f"through {get_label(target_provider)}, which "
  935. f"has no credentials configured.{hint}")
  936. def _aggregator_catalog_match(new_model: str, catalog: list) -> str | None:
  937. """Exact (case-insensitive) match on full id, then on the bare part after ``vendor/``."""
  938. wanted = new_model.lower()
  939. return next((mid for mid in catalog if mid.lower() == wanted), None) or next(
  940. (mid for mid in catalog if "/" in mid and mid.split("/", 1)[1].lower() == wanted), None)
  941. def _config_declares_model(
  942. new_model: str, target_provider: str, base_url: str, user_providers, custom_providers) -> bool:
  943. """A model declared in the user's ``providers:``/``custom_providers:`` config is accepted even
  944. when the remote /v1/models does not list it (cloud/aliased models). Custom entries match by
  945. slug alias or by base_url."""
  946. if user_providers:
  947. from hermes_cli.config import is_provider_enabled
  948. cfg = user_providers.get(target_provider)
  949. if cfg is not None and is_provider_enabled(cfg) and new_model in _declared_model_ids(cfg.get("models", {})):
  950. return True
  951. for entry in _custom_entries(custom_providers):
  952. if (target_provider.lower() in _entry_aliases(entry) or entry.get("base_url", "") == base_url) and (
  953. new_model == entry.get("model", "") or new_model in _declared_model_ids(entry.get("models", {}))
  954. ):
  955. return True
  956. return False
  957. def _apply_direct_alias_endpoint(st: _Switch, da: DirectAlias) -> None:
  958. """Route a direct alias to its own base_url and decide its credential (mutates ``st``).
  959. Credentials were resolved against the DEFAULT provider; carrying that key onto the alias
  960. endpoint both 401s and ships the default provider's secret to an unrelated host. The alias's
  961. own endpoint decides: its declared key; else the session key only for the SAME ORIGIN; else a
  962. fresh resolution against the alias base_url (env-key fallbacks are host-gated: OLLAMA_API_KEY
  963. resolves for ollama.com, OPENROUTER_API_KEY never reaches an unrelated host)."""
  964. from hermes_cli.models_local import _same_ollama_native_root
  965. from hermes_cli.runtime_provider import resolve_runtime_provider
  966. alias_key = direct_alias_api_key(da)
  967. same_host = _may_reuse_session_credential(st.base_url, da.base_url)
  968. if alias_key:
  969. st.base_url, st.api_key = da.base_url, alias_key
  970. elif st.api_key and st.api_key != "no-key-required" and same_host:
  971. # Same origin: the key is host-appropriate and re-resolving would only repeat the work.
  972. st.base_url = da.base_url
  973. else:
  974. try:
  975. req, explicit = direct_alias_runtime_request(da)
  976. alias_runtime = resolve_runtime_provider(
  977. requested=req, explicit_api_key=explicit, explicit_base_url=da.base_url, target_model=st.new_model)
  978. except Exception:
  979. alias_runtime = {}
  980. st.base_url = alias_runtime.get("base_url", "") or da.base_url
  981. # The resolver reports "no key found" as the `no-key-required` placeholder; normalise so
  982. # a same-host credential still outranks it.
  983. resolved_key = alias_runtime.get("api_key", "")
  984. if resolved_key == "no-key-required":
  985. resolved_key = ""
  986. st.api_key = resolved_key or (st.api_key if same_host else "") or "no-key-required"
  987. # providers.ollama refinement: pick up the configured key only for the configured native
  988. # root; drop key and provider-level headers for any other origin. Skipped when the alias
  989. # declared its own credential (explicit api_key/key_env outranks a provider-level config key).
  990. if not alias_key and st.target_provider.strip().lower() == "ollama":
  991. ollama_cfg, ollama_cfg_base = _ollama_configured_base()
  992. if ollama_cfg_base and _same_ollama_native_root(st.base_url, ollama_cfg_base):
  993. configured_key = _entry_configured_key(ollama_cfg, lambda n: os.environ.get(n, "").strip())
  994. if configured_key:
  995. st.api_key = configured_key
  996. else:
  997. # Different origin, or no configured root to safely associate the headers with.
  998. st.validation_headers, st.suppress_ollama_headers, st.api_key = {}, True, "no-key-required"
  999. st.api_key = st.api_key or "no-key-required"
  1000. st.api_mode = "" # clear so determine_api_mode re-detects from URL
  1001. def _moa_default_preset() -> str:
  1002. try:
  1003. from hermes_cli.config import load_config
  1004. from hermes_cli.moa_config import normalize_moa_config
  1005. return normalize_moa_config(load_config().get("moa") or {})["default_preset"]
  1006. except Exception:
  1007. return "default"
  1008. @dataclass
  1009. class _Switch:
  1010. """Mutable state threaded through the ``switch_model`` steps.
  1011. The routing steps settle ``target_provider`` / ``new_model`` / ``resolved_alias`` (and may
  1012. promote a config-routed ``providers.<slug>`` to ``explicit_provider`` so the credential step
  1013. resolves its block); the credential step fills ``api_key`` / ``base_url`` / ``api_mode`` /
  1014. ``validation_headers``."""
  1015. raw_input: str
  1016. current_provider: str
  1017. current_model: str
  1018. current_base_url: str
  1019. current_api_key: str
  1020. is_global: bool
  1021. explicit_provider: str
  1022. user_providers: Optional[dict]
  1023. custom_providers: Optional[list]
  1024. new_model: str = ""
  1025. target_provider: str = ""
  1026. resolved_alias: str = ""
  1027. alias_endpoint_applied: bool = False
  1028. provider_label: str = ""
  1029. api_key: str = ""
  1030. base_url: str = ""
  1031. api_mode: str = ""
  1032. validation_headers: dict = field(default_factory=dict)
  1033. suppress_ollama_headers: bool = False
  1034. validation: dict = field(default_factory=dict)
  1035. def fail(self, message: str, **fields) -> ModelSwitchResult:
  1036. return ModelSwitchResult(success=False, is_global=self.is_global, error_message=message, **fields)
  1037. def fail_on_target(self, message: str) -> ModelSwitchResult:
  1038. """Failure carrying the already-settled ``target_provider`` / ``provider_label``."""
  1039. return self.fail(message, target_provider=self.target_provider, provider_label=self.provider_label)
  1040. @property
  1041. def provider_changed(self) -> bool:
  1042. return self.target_provider != self.current_provider
  1043. def resolve_runtime(self, **kwargs) -> None:
  1044. """Fill api_key / base_url / api_mode / validation_headers from ``resolve_runtime_provider``
  1045. for ``new_model``; headers keep their current value when the resolver returns none."""
  1046. from hermes_cli.runtime_provider import resolve_runtime_provider
  1047. rt = resolve_runtime_provider(target_model=self.new_model, **kwargs)
  1048. self.api_key, self.base_url = rt.get("api_key", ""), rt.get("base_url", "")
  1049. self.api_mode = rt.get("api_mode", "")
  1050. self.validation_headers = rt.get("extra_headers") or self.validation_headers
  1051. def _route_explicit_provider(st: _Switch) -> Optional[ModelSwitchResult]:
  1052. """PATH A (``--provider`` given): resolve the provider, auto-detect a model from a local
  1053. endpoint when none was typed, then resolve the alias on the TARGET provider."""
  1054. pdef = resolve_provider_full(st.explicit_provider, st.user_providers, st.custom_providers)
  1055. if pdef is None and st.explicit_provider.strip().lower() == "custom":
  1056. pdef = _bare_custom_provider_def(st.current_base_url)
  1057. if pdef is None:
  1058. return st.fail(_unknown_provider_message(st.explicit_provider))
  1059. st.target_provider, st.provider_label = pdef.id, pdef.name # label is re-derived in the credential step
  1060. if st.target_provider == "moa" and not st.new_model:
  1061. st.new_model = _moa_default_preset()
  1062. agg_err = _aggregator_alias_error(
  1063. st.explicit_provider, st.target_provider, st.current_provider, st.user_providers, st.custom_providers)
  1064. if agg_err:
  1065. return st.fail_on_target(agg_err)
  1066. if not st.new_model:
  1067. if not pdef.base_url:
  1068. return st.fail_on_target(
  1069. f"Provider '{pdef.name}' has no base URL configured. "
  1070. f"Specify a model: /model <model-name> --provider {st.explicit_provider}")
  1071. from hermes_cli.runtime_provider import _auto_detect_local_model
  1072. st.new_model = _auto_detect_local_model(pdef.base_url)
  1073. if not st.new_model:
  1074. return st.fail_on_target(
  1075. f"No model detected on {pdef.name} ({pdef.base_url}). "
  1076. f"Specify the model explicitly: /model <model-name> --provider {st.explicit_provider}")
  1077. try:
  1078. alias_result = resolve_alias(st.new_model, st.target_provider, st.user_providers, st.custom_providers)
  1079. except AmbiguousAliasError as err:
  1080. return st.fail(_ambiguous_alias_message(err), target_provider=st.target_provider)
  1081. if alias_result is not None:
  1082. alias_provider, st.new_model, alias_name = alias_result
  1083. # Adopt the alias (and with it its base_url and key) only when it belongs to the provider
  1084. # the user named: a reverse model-id match may land on another provider's alias, and
  1085. # honouring it would send the turn to that provider's endpoint under this one's identity.
  1086. if (_provider_identity(alias_provider, st.user_providers, st.custom_providers)
  1087. == _provider_identity(st.target_provider, st.user_providers, st.custom_providers)):
  1088. st.resolved_alias = alias_name
  1089. return None
  1090. def _route_alias_fallback(st: _Switch, key: str) -> Optional[ModelSwitchResult]:
  1091. """Step b: the alias exists but not on the current provider -> try the user's authenticated providers."""
  1092. authed = get_authenticated_provider_slugs(
  1093. current_provider=st.current_provider, user_providers=st.user_providers, custom_providers=st.custom_providers,
  1094. )
  1095. try:
  1096. fallback_result = _resolve_alias_fallback(st.raw_input, authed, st.user_providers, st.custom_providers)
  1097. except AmbiguousAliasError as err:
  1098. return st.fail(_ambiguous_alias_message(err))
  1099. if fallback_result is None:
  1100. identity = MODEL_ALIASES[key]
  1101. return st.fail(
  1102. f"Alias '{key}' maps to {identity.vendor}/{identity.family} "
  1103. f"but no matching model was found in any provider catalog. "
  1104. f"Try specifying the full model name.")
  1105. st.target_provider, st.new_model, st.resolved_alias = fallback_result
  1106. logger.debug(
  1107. "Alias '%s' resolved via fallback to %s on %s", st.resolved_alias, st.new_model, st.target_provider)
  1108. return None
  1109. def _convert_vendor_colon_slug(st: _Switch) -> None:
  1110. """Step c: ``vendor:model`` -> ``vendor/model``. Only without a slash: with one, the colon is
  1111. a variant tag (:free, :extended, :fast) that must be preserved.
  1112. On an aggregator every ``left:right`` is a slug. Elsewhere the colon is converted only when
  1113. ``left`` names a provider Hermes knows, so ``/model alibaba:qwen3.6-plus`` routes like
  1114. ``alibaba/qwen3.6-plus`` (#9748) while Ollama-style tags (``qwen3.5:4b``) stay intact."""
  1115. raw_input = st.raw_input
  1116. colon_pos = raw_input.find(":")
  1117. cur_norm = str(st.current_provider).strip().lower()
  1118. if colon_pos <= 0 or "/" in raw_input or cur_norm.startswith("custom") or cur_norm == "ollama":
  1119. return
  1120. left = raw_input[:colon_pos].strip().lower()
  1121. right = raw_input[colon_pos + 1:].strip()
  1122. if not left or not right:
  1123. return
  1124. if not is_aggregator(st.current_provider) and not _names_known_provider(left, st):
  1125. return
  1126. st.new_model = f"{left}/{right}"
  1127. logger.debug("Converted vendor:model '%s' to slug '%s'", raw_input, st.new_model)
  1128. def _names_known_provider(name: str, st: _Switch) -> bool:
  1129. """Whether ``name`` is a built-in provider id/alias or a provider the user configured."""
  1130. from hermes_cli.providers import get_provider
  1131. if resolve_provider_full(name, st.user_providers, st.custom_providers) is not None:
  1132. return True
  1133. try:
  1134. return get_provider(name, allow_network=False) is not None
  1135. except Exception:
  1136. return False
  1137. def _route_configured_provider(st: _Switch) -> Optional[ModelSwitchResult] | bool:
  1138. """Step d.5: a model declared in user/custom provider config routes there BEFORE
  1139. detect_provider_for_model() guesses from static catalogs and before a soft-accepting current
  1140. provider (openai-codex) can swallow it as an unknown hidden model. Returns a failure result,
  1141. ``True`` when routed, else ``False``."""
  1142. cfg_matches = _configured_provider_matches(st.new_model, st.user_providers, st.custom_providers)
  1143. if not cfg_matches:
  1144. return False
  1145. current_slug = _current_provider_match(st, cfg_matches)
  1146. if current_slug is not None:
  1147. st.new_model = cfg_matches[current_slug]
  1148. return True
  1149. match_slugs = sorted(cfg_matches)
  1150. if len(match_slugs) > 1:
  1151. return st.fail(
  1152. f"'{st.new_model}' is declared by multiple configured "
  1153. f"providers ({', '.join(match_slugs)}). Re-run with "
  1154. f"--provider <slug> to choose which one to use.")
  1155. st.target_provider = match_slugs[0]
  1156. st.new_model = cfg_matches[st.target_provider]
  1157. logger.debug("Configured-provider detection routed '%s' to %s", st.new_model, st.target_provider)
  1158. # providers.<slug> endpoints resolve in the credential block via resolve_user_provider(),
  1159. # which is gated on explicit_provider; custom:* slugs resolve at runtime directly.
  1160. if isinstance(st.user_providers, dict) and st.target_provider in st.user_providers:
  1161. st.explicit_provider = st.target_provider
  1162. return True
  1163. def _route_from_model_input(st: _Switch) -> Optional[ModelSwitchResult]:
  1164. """PATH B (no ``--provider``): MoA preset / alias on the current provider (a) -> alias
  1165. fallback (b) or ``vendor:model`` conversion (c) -> aggregator catalog search (d) ->
  1166. configured-provider match (d.5) -> detect_provider_for_model() as last resort (e)."""
  1167. from hermes_cli.models import detect_provider_for_model
  1168. raw_input, current_provider = st.raw_input, st.current_provider
  1169. try:
  1170. from hermes_cli.config import load_config
  1171. from hermes_cli.moa_config import exact_moa_preset_name, normalize_moa_config
  1172. moa_match = exact_moa_preset_name(normalize_moa_config(load_config().get("moa") or {}), raw_input)
  1173. except Exception:
  1174. moa_match = None # MoA config unreadable: fall through to plain alias resolution
  1175. if moa_match:
  1176. st.target_provider, st.new_model, st.resolved_alias = "moa", moa_match, ""
  1177. else:
  1178. try:
  1179. alias_result = resolve_alias(raw_input, current_provider, st.user_providers, st.custom_providers)
  1180. except AmbiguousAliasError as err:
  1181. return st.fail(_ambiguous_alias_message(err))
  1182. if alias_result is not None:
  1183. st.target_provider, st.new_model, st.resolved_alias = alias_result
  1184. logger.debug("Alias '%s' resolved to %s on %s", st.resolved_alias, st.new_model, st.target_provider)
  1185. elif raw_input.strip().lower() in MODEL_ALIASES:
  1186. fail = _route_alias_fallback(st, raw_input.strip().lower())
  1187. if fail is not None:
  1188. return fail
  1189. else:
  1190. _convert_vendor_colon_slug(st)
  1191. # Step d: if the CURRENT provider's live catalog resolved the model, step e must not
  1192. # second-guess and switch providers — flat-namespace resellers (opencode-go/zen) return bare
  1193. # ids that coincidentally match native providers' static catalogs.
  1194. resolved_in_current_catalog = False
  1195. if is_aggregator(st.target_provider) and not st.resolved_alias:
  1196. catalog = list_provider_models(st.target_provider)
  1197. if catalog:
  1198. matched = _aggregator_catalog_match(st.new_model, catalog)
  1199. if matched is not None:
  1200. st.new_model, resolved_in_current_catalog = matched, True
  1201. # Steps d.5 / e only apply while the request is still unrouted on the current provider.
  1202. if st.resolved_alias or resolved_in_current_catalog or st.target_provider != current_provider:
  1203. return None
  1204. if current_provider == "nous":
  1205. # The welcome host serves nous/welcome only; a model outside it needs an account or a key.
  1206. # Never hop to another provider on the user's behalf here (there is no key to hop to).
  1207. from hermes_cli.anon_auth import GUEST_MODEL, route_is_welcome_host
  1208. if route_is_welcome_host(st.current_base_url) and st.new_model != GUEST_MODEL:
  1209. return st.fail(
  1210. f"{st.new_model} needs a Nous account or an API key. "
  1211. "Use /login to sign in, or /model to pick another provider.")
  1212. config_routed = _route_configured_provider(st) # d.5 — deliberately NOT gated on ``not is_custom``
  1213. if isinstance(config_routed, ModelSwitchResult):
  1214. return config_routed
  1215. is_custom = (
  1216. current_provider in {"custom", "local"} or current_provider.startswith("custom:")
  1217. or base_url_hostname(st.current_base_url or "") in ("localhost", "127.0.0.1"))
  1218. if not config_routed and not is_custom: # e
  1219. detected = detect_provider_for_model(st.new_model, current_provider)
  1220. if detected:
  1221. st.target_provider, st.new_model = detected
  1222. return None
  1223. def _switch_provider_label(st: _Switch) -> str:
  1224. label = get_label(st.target_provider)
  1225. if st.target_provider == "custom" and st.current_base_url:
  1226. label = "Custom endpoint"
  1227. if st.target_provider.startswith("custom:"):
  1228. custom_pdef = resolve_provider_full(st.target_provider, st.user_providers, st.custom_providers)
  1229. if custom_pdef is not None:
  1230. label = custom_pdef.name
  1231. return label
  1232. def _creds_for_switched_provider(st: _Switch) -> Optional[ModelSwitchResult]:
  1233. """Credentials when the provider changed or ``--provider`` was given.
  1234. ``providers.<name>`` blocks carry their own base_url + transport + key reference;
  1235. resolve_runtime_provider() resolves by provider NAME and would re-resolve a block named
  1236. "openai" from scratch (or hop to an aggregator), so use the pdef's endpoint directly."""
  1237. user_pdef = None
  1238. explicit_norm = st.explicit_provider.strip().lower()
  1239. if st.explicit_provider and st.user_providers:
  1240. from hermes_cli.providers import resolve_user_provider
  1241. user_pdef = (resolve_user_provider(explicit_norm, st.user_providers)
  1242. or resolve_user_provider(st.target_provider, st.user_providers))
  1243. if user_pdef is not None and user_pdef.base_url:
  1244. ucfg = st.user_providers.get(explicit_norm) or st.user_providers.get(st.target_provider) or {}
  1245. # Key reads go through the per-profile secret scope (multiplexed gateway).
  1246. ukey = _entry_configured_key(ucfg, _scoped_key_env)
  1247. st.validation_headers = _extra_headers_from_config(ucfg)
  1248. try:
  1249. st.resolve_runtime(
  1250. requested=st.target_provider, explicit_api_key=ukey or None, explicit_base_url=user_pdef.base_url)
  1251. st.api_key, st.base_url = st.api_key or ukey, st.base_url or user_pdef.base_url
  1252. except Exception:
  1253. st.api_key, st.base_url, st.api_mode = ukey, user_pdef.base_url, ""
  1254. elif st.target_provider == "custom" and st.current_base_url:
  1255. # A bare-custom session switching models stays on its endpoint (#45597). Arriving from
  1256. # ANOTHER provider (the per-turn config sync adopting ``provider: custom``) the configured
  1257. # endpoint wins, or the new model is paired with the old provider's host and key (#73680).
  1258. # With nothing configured the resolver either raises (st.* keep the session values) or
  1259. # lands on OpenRouter's default or the ``OPENROUTER_BASE_URL`` mirror (#74143, #10622) —
  1260. # the session endpoint is kept in all three cases.
  1261. key, url = st.current_api_key, st.current_base_url
  1262. if st.current_provider != "custom":
  1263. with suppress(Exception):
  1264. st.resolve_runtime(requested="custom")
  1265. if st.base_url and not _fell_back_to_openrouter_default(st):
  1266. key, url = st.api_key, st.base_url
  1267. st.api_key, st.base_url = key, url
  1268. st.api_mode = determine_api_mode(st.target_provider, st.base_url)
  1269. else:
  1270. # A URL-bearing LOCAL direct alias (ollama, vllm — labels that resolve to `custom`)
  1271. # supplies its endpoint HERE as well as in _apply_direct_alias_endpoint: the resolver
  1272. # refuses such an alias with no endpoint configured anywhere, and this alias does have
  1273. # one. A built-in label (anthropic, openai, …) must NOT get the alias URL: its resolver
  1274. # would pair the vendor key with the foreign host, and _apply_direct_alias_endpoint then
  1275. # sees a same-origin credential and keeps it (#28660).
  1276. from hermes_cli.runtime_provider import _resolves_to_custom
  1277. da = DIRECT_ALIASES.get(st.resolved_alias) if st.resolved_alias else None
  1278. alias_url = da.base_url if da is not None and _resolves_to_custom(st.target_provider) else None
  1279. try:
  1280. st.resolve_runtime(requested=st.target_provider, explicit_base_url=alias_url or None)
  1281. except Exception as e:
  1282. if st.target_provider.strip().lower() in LLAMACPP_ALIASES:
  1283. # A local-runtime alias has no credential to add: the seam's own message ("server
  1284. # isn't running" / "turned off") is the actionable one, the auth hint below is noise.
  1285. return st.fail_on_target(str(e))
  1286. return st.fail_on_target(
  1287. f"{st.provider_label} is not connected: no API key or login was found for it. Add one with "
  1288. f"`hermes auth add {st.target_provider}`, or pick a connected provider in /model.\n"
  1289. f" Details: {e}")
  1290. return None
  1291. def _creds_for_current_provider(st: _Switch) -> None:
  1292. """Credentials when staying on the current provider. Mid-session ``/model <name>`` on a local
  1293. Ollama-compatible endpoint keeps the endpoint in use; re-resolving bare ``custom`` from config
  1294. can fall through to an unrelated default provider."""
  1295. from hermes_cli.models_local import _get_ollama_request_headers, _same_ollama_native_root
  1296. keep_current_ollama_endpoint = False
  1297. ollama_headers: dict[str, str] = {}
  1298. if st.current_provider == "custom" and st.current_base_url:
  1299. try:
  1300. from hermes_cli.models_local import should_use_ollama_native_catalog
  1301. ollama_headers = _get_ollama_request_headers()
  1302. _, configured_ollama_base = _ollama_configured_base()
  1303. # Provider-level Ollama headers only belong to the configured native root; without
  1304. # one there is no safe origin for them.
  1305. if not configured_ollama_base or not _same_ollama_native_root(st.current_base_url, configured_ollama_base):
  1306. ollama_headers = {}
  1307. st.suppress_ollama_headers = True
  1308. keep_current_ollama_endpoint = should_use_ollama_native_catalog(
  1309. st.current_provider, st.current_base_url, headers=ollama_headers)
  1310. except (ImportError, OSError, RuntimeError, TypeError, ValueError):
  1311. keep_current_ollama_endpoint = False
  1312. if keep_current_ollama_endpoint:
  1313. st.api_key = st.current_api_key or "no-key-required"
  1314. st.base_url = st.current_base_url
  1315. st.api_mode = determine_api_mode(st.current_provider, st.base_url)
  1316. st.validation_headers = ollama_headers
  1317. else:
  1318. try:
  1319. st.resolve_runtime(requested=st.current_provider)
  1320. except Exception:
  1321. pass
  1322. # Bare ``custom``/``local`` sessions whose base_url is session-only (not a trusted config
  1323. # ``model.base_url``) re-resolve to the OpenRouter DEFAULT — a host the user never picked
  1324. # (#74143). Keep the session endpoint + key then (also when the resolver came back empty,
  1325. # whatever host the session is on); a config-backed custom URL still wins so key/endpoint
  1326. # rotation is not pinned to a stale session.
  1327. if (
  1328. st.current_provider in {"custom", "local"} and st.current_base_url
  1329. and (not st.base_url or _fell_back_to_openrouter_default(st))
  1330. ):
  1331. st.base_url, st.api_key = st.current_base_url, st.current_api_key
  1332. st.api_mode = determine_api_mode(st.current_provider, st.base_url)
  1333. def _fell_back_to_openrouter_default(st: _Switch) -> bool:
  1334. """The bare-``custom`` resolver ended on an OpenRouter endpoint that is not a custom endpoint
  1335. the user configured: the built-in default host, or the ``OPENROUTER_BASE_URL`` mirror — the
  1336. credential ladder's last rung (#10622), which ``provider: custom`` reaches only when no
  1337. ``CUSTOM_BASE_URL`` / trusted ``model.base_url`` exists."""
  1338. mirror = _openrouter_mirror_base_url()
  1339. if mirror and st.base_url.rstrip("/") == mirror and not _custom_endpoint_source():
  1340. return True
  1341. return (base_url_host_matches(st.base_url, "openrouter.ai")
  1342. and not base_url_host_matches(st.current_base_url, "openrouter.ai"))
  1343. def _custom_endpoint_source() -> str:
  1344. """The endpoint the credential ladder prefers over its OpenRouter rung for bare ``custom``:
  1345. ``CUSTOM_BASE_URL``, else the config's ``model.base_url`` when that config backs bare custom.
  1346. Non-empty means a resolved URL matching the mirror came from a configured custom endpoint (two
  1347. env vars pointed at one proxy), so the mirror guard must not call it a fallback."""
  1348. from agent.secret_scope import get_secret_str
  1349. try:
  1350. env_url = (get_secret_str("CUSTOM_BASE_URL", "") or "").strip()
  1351. if env_url:
  1352. return env_url
  1353. from hermes_cli.runtime_provider import (
  1354. _config_base_url_trustworthy_for_bare_custom, _get_model_config)
  1355. model_cfg = _get_model_config() or {}
  1356. base = model_cfg.get("base_url") if isinstance(model_cfg.get("base_url"), str) else ""
  1357. provider = model_cfg.get("provider") if isinstance(model_cfg.get("provider"), str) else ""
  1358. base = (base or "").strip()
  1359. return base if base and _config_base_url_trustworthy_for_bare_custom(base, provider) else ""
  1360. except Exception:
  1361. return ""
  1362. def _openrouter_mirror_base_url() -> str:
  1363. """``OPENROUTER_BASE_URL``, read the way the resolver reads it (env, or the profile's secret
  1364. scope). A guard read, not a credential fetch: a read that fails — unscoped under multiplexing —
  1365. must leave the mirror undetected so its caller keeps the session endpoint, rather than raising
  1366. out of ``switch_model`` where the resolver's own read of the same name is suppressed."""
  1367. from agent.secret_scope import get_secret_str
  1368. try:
  1369. return (get_secret_str("OPENROUTER_BASE_URL", "") or "").strip().rstrip("/")
  1370. except Exception:
  1371. return ""
  1372. def _resolve_switch_credentials(st: _Switch) -> Optional[ModelSwitchResult]:
  1373. """COMMON PATH part 1: credentials, direct-alias endpoint override, and the api_mode for the
  1374. final (provider, base_url) before validation."""
  1375. st.provider_label = _switch_provider_label(st)
  1376. st.api_key, st.base_url = st.current_api_key, st.current_base_url
  1377. if st.provider_changed or st.explicit_provider:
  1378. fail = _creds_for_switched_provider(st)
  1379. if fail is not None:
  1380. return fail
  1381. else:
  1382. _creds_for_current_provider(st)
  1383. # Direct alias override: use the alias's exact base_url if set.
  1384. if st.resolved_alias:
  1385. _ensure_direct_aliases()
  1386. da = DIRECT_ALIASES.get(st.resolved_alias)
  1387. if da is not None and da.base_url:
  1388. _apply_direct_alias_endpoint(st, da)
  1389. st.alias_endpoint_applied = True
  1390. # Fills an empty mode (alias cleared it) and overrides a STALE mode carried from previous
  1391. # session state when the host mandates one wire protocol (e.g. gpt-5.x on api.openai.com
  1392. # would otherwise 400 on tools+reasoning). ``codex_app_server`` is the resolver's
  1393. # ``model.openai_runtime`` opt-in, not a wire protocol the host can mandate: keep it.
  1394. from hermes_cli.providers import is_actual_route
  1395. mandated_mode = "chat_completions" if is_actual_route(st.target_provider, st.base_url) else host_mandated_api_mode(st.base_url)
  1396. if mandated_mode is not None and st.api_mode != "codex_app_server":
  1397. st.api_mode = mandated_mode
  1398. st.api_mode = st.api_mode or determine_api_mode(st.target_provider, st.base_url)
  1399. return None
  1400. def _validate_switch(st: _Switch) -> Optional[ModelSwitchResult]:
  1401. """COMMON PATH part 2: normalize the model name for the target provider, validate it, and
  1402. accept config-declared models the remote catalog lacks."""
  1403. from hermes_cli.models_local import _get_ollama_request_headers
  1404. from hermes_cli.models_validate import validate_requested_model
  1405. st.new_model = _resolve_named_custom_model_id(st.new_model, st.target_provider, st.custom_providers)
  1406. st.new_model = normalize_model_for_provider(st.new_model, st.target_provider)
  1407. from hermes_cli.chat_catalog import is_known_non_chat_model
  1408. if is_known_non_chat_model(st.new_model):
  1409. return st.fail(
  1410. f"`{st.new_model}` is a generation model and cannot be used for chat. "
  1411. "Pick a chat model, or use image generation for image models.",
  1412. new_model=st.new_model, target_provider=st.target_provider,
  1413. provider_label=st.provider_label,
  1414. )
  1415. if st.target_provider.strip().lower() == "ollama":
  1416. headers = {} if st.suppress_ollama_headers else (st.validation_headers or _get_ollama_request_headers())
  1417. else:
  1418. headers = st.validation_headers or (
  1419. _extra_headers_from_config(st.user_providers.get(st.target_provider))
  1420. if st.user_providers and st.target_provider in st.user_providers else None)
  1421. # A ``providers.<key>`` endpoint is the user's own: validate it as a custom endpoint (an id its
  1422. # listing lacks is soft-accepted) whether the slug arrived as ``custom:<key>`` or the bare key
  1423. # the picker rows carry — otherwise the bare spelling fell into the built-in live-listing
  1424. # branch and hard-rejected the very model the user selected.
  1425. validate_as = st.target_provider
  1426. if not validate_as.lower().startswith("custom"):
  1427. pdef = resolve_provider_full(validate_as, st.user_providers, st.custom_providers)
  1428. # A settings-only ``providers.<slug>`` block (no endpoint of its own) is not a
  1429. # user-defined endpoint: only a block declaring a base_url takes the custom
  1430. # validation branch (#120020; mirrors ``_lap_lmstudio_row``'s endpoint test).
  1431. if pdef is not None and pdef.source == "user-config" and (pdef.base_url or ""):
  1432. validate_as = f"custom:{validate_as}"
  1433. try:
  1434. validation = validate_requested_model(
  1435. st.new_model, validate_as, api_key=st.api_key, base_url=st.base_url,
  1436. api_mode=st.api_mode or None, headers=headers)
  1437. except Exception as e:
  1438. validation = {"accepted": False, "persist": False, "recognized": False,
  1439. "message": f"Could not validate `{st.new_model}`: {e}"}
  1440. if not validation.get("accepted"):
  1441. if not _config_declares_model(
  1442. st.new_model, st.target_provider, st.base_url, st.user_providers, st.custom_providers):
  1443. return st.fail(
  1444. validation.get("message", "Invalid model"),
  1445. new_model=st.new_model, target_provider=st.target_provider, provider_label=st.provider_label)
  1446. validation = {"accepted": True, "persist": True, "recognized": False, "message": validation.get("message", "")}
  1447. st.validation = validation
  1448. return None
  1449. def _opencode_api_mode(provider: str, model: str, api_key: str) -> str:
  1450. # Re-derive api_mode from the effective model rather than the persisted api_mode: the opencode providers
  1451. # serve both anthropic_messages and chat_completions models, so the previous session's mode must not
  1452. # leak across /model switches. Refs #16878.
  1453. # opencode-zen/go must always re-derive api_mode from the target model (not the stale persisted
  1454. # api_mode), because the same provider serves both anthropic_messages (e.g. minimax-m2.7) and
  1455. # chat_completions (e.g. deepseek-v4-flash) and switching models via /model would otherwise carry the
  1456. # previous mode forward, stripping /v1 from base_url for chat_completions models and 404'ing. Refs
  1457. # #16878.
  1458. from hermes_cli.models import opencode_model_api_mode
  1459. return opencode_model_api_mode(provider, model)
  1460. def _nous_api_mode(provider: str, model: str, api_key: str) -> str:
  1461. # Portal serves anthropic/* on /v1/messages and everything else on /chat/completions;
  1462. # re-derive from the FINAL model so alias clears / empty fallbacks cannot leave Claude on the
  1463. # OpenAI wire.
  1464. from hermes_cli.providers import nous_api_mode
  1465. return nous_api_mode(model)
  1466. # Per-provider api_mode overrides applied after validation, keyed on the final target provider
  1467. # (the key sets are disjoint, so exactly one — or none — fires).
  1468. _PROVIDER_API_MODE_OVERRIDES: dict[str, Any] = {
  1469. **dict.fromkeys(("opencode-zen", "opencode-go", "opencode"), _opencode_api_mode),
  1470. **dict.fromkeys(("nous", "nous-portal", "nousresearch"), _nous_api_mode)}
  1471. def model_derived_api_mode(provider: str, model: str, api_key: str = "") -> Optional[str]:
  1472. """api_mode re-derived from the FINAL model for providers that serve several wire formats behind one
  1473. endpoint (OpenCode Zen/Go and custom providers extending a family slug, Nous, and any provider profile
  1474. declaring ``api_mode_for_model``); None when the provider's wire is fixed by its endpoint. A persisted
  1475. api_mode from an earlier model of such a provider is never authoritative — resume paths must call this
  1476. instead of honoring the row (#96066)."""
  1477. from hermes_cli.models import opencode_provider_family
  1478. key = str(provider or "").strip().lower()
  1479. override = _PROVIDER_API_MODE_OVERRIDES.get(opencode_provider_family(key) or key)
  1480. if override is None and key:
  1481. from providers import get_provider_profile
  1482. profile = get_provider_profile(key)
  1483. if profile is not None:
  1484. from agent.provider_route_hooks import model_api_mode
  1485. return model_api_mode(profile, model, api_key=api_key or "")
  1486. return override(key, model, api_key) if override is not None else None
  1487. def _build_switch_result(st: _Switch) -> ModelSwitchResult:
  1488. """COMMON PATH part 3: final api_mode / base_url shaping, metadata, warnings."""
  1489. derived = model_derived_api_mode(st.target_provider, st.new_model, st.api_key)
  1490. if derived is not None:
  1491. st.api_mode = derived
  1492. if not st.api_mode:
  1493. st.api_mode = determine_api_mode(st.target_provider, st.base_url, model=st.new_model)
  1494. # OpenCode base URLs end with /v1 for OpenAI-compatible models but the Anthropic SDK prepends
  1495. # its own /v1/messages: strip for anthropic_messages, re-append for
  1496. # chat_completions/codex_responses (mirrors resolve_runtime_provider).
  1497. from hermes_cli.models import normalize_opencode_base_url, opencode_provider_family
  1498. if opencode_provider_family(st.target_provider) is not None and isinstance(st.base_url, str):
  1499. st.base_url = normalize_opencode_base_url(st.target_provider, st.api_mode, st.base_url)
  1500. capabilities = get_model_capabilities(st.target_provider, st.new_model, allow_network=True)
  1501. from agent.native_compaction import resolve_native_compaction_capabilities
  1502. runtime_capabilities = resolve_native_compaction_capabilities(
  1503. model=st.new_model, base_url=st.base_url, provider=st.target_provider,
  1504. is_codex_backend=st.target_provider.strip().lower() == "openai-codex")
  1505. model_info = get_model_info(st.target_provider, st.new_model, allow_network=True)
  1506. warnings = [w for w in (st.validation.get("message"), _check_hermes_model_warning(st.new_model)) if w]
  1507. from hermes_cli.model_picker_usage import large_model_notice
  1508. usage_notice = large_model_notice(st.new_model, st.target_provider, fetch=True) or ""
  1509. # Carry the switched provider's request_overrides (custom_providers ``extra_body`` such as
  1510. # chat_template_kwargs) so the gateway applies them like the default-provider path does.
  1511. request_overrides = None
  1512. try:
  1513. from hermes_cli.runtime_provider import _get_named_custom_provider, _custom_provider_request_overrides
  1514. cp_for_ro = _get_named_custom_provider(st.target_provider)
  1515. request_overrides = _custom_provider_request_overrides(cp_for_ro) or None if cp_for_ro else None
  1516. except Exception:
  1517. request_overrides = None
  1518. return ModelSwitchResult(
  1519. success=True, new_model=st.new_model, target_provider=st.target_provider,
  1520. provider_changed=st.provider_changed, api_key=st.api_key, base_url=st.base_url, api_mode=st.api_mode,
  1521. request_overrides=dict(request_overrides or {}), warning_message=" | ".join(warnings) if warnings else "",
  1522. usage_notice=usage_notice, provider_label=st.provider_label, resolved_via_alias=st.resolved_alias, capabilities=capabilities,
  1523. runtime_capabilities={
  1524. k: v for k, v in runtime_capabilities.items() if isinstance(k, str) and isinstance(v, bool)},
  1525. model_info=model_info, is_global=st.is_global, alias_endpoint_applied=st.alias_endpoint_applied)
  1526. def switch_model(
  1527. raw_input: str, current_provider: str, current_model: str, current_base_url: str = "",
  1528. current_api_key: str = "", is_global: bool = False, explicit_provider: str = "",
  1529. user_providers: dict | None = None, custom_providers: list | None = None) -> ModelSwitchResult:
  1530. """Core model-switching pipeline shared between CLI and gateway.
  1531. Route (PATH A with ``--provider``, else PATH B) -> credentials -> validation -> result; each
  1532. step returns a failure :class:`ModelSwitchResult` to stop the chain, or ``None`` to continue.
  1533. ``user_providers`` / ``custom_providers`` are the config.yaml ``providers:`` dict and
  1534. ``custom_providers:`` list."""
  1535. st = _Switch(
  1536. raw_input=raw_input, current_provider=current_provider, current_model=current_model,
  1537. current_base_url=current_base_url, current_api_key=current_api_key, is_global=is_global,
  1538. explicit_provider=explicit_provider, user_providers=user_providers, custom_providers=custom_providers,
  1539. new_model=raw_input.strip(), target_provider=current_provider)
  1540. route = _route_explicit_provider if explicit_provider else _route_from_model_input
  1541. for step in (route, _resolve_switch_credentials, _validate_switch):
  1542. fail = step(st)
  1543. if fail is not None:
  1544. return fail
  1545. return _build_switch_result(st)
  1546. def model_selection_config_updates(result: ModelSwitchResult, current_model_cfg: Any) -> dict[str, Any]:
  1547. """The ONE config.yaml shape a persisted model selection produces, as ``model.<key>`` -> value
  1548. (``None`` = clear). ``current_model_cfg`` is the on-disk ``model:`` block (raw).
  1549. base_url/api_mode are freshly resolved for the target route, so they are always synced —
  1550. ``None`` when the target has none — otherwise the OLD provider's endpoint/wire-protocol lingers
  1551. (#25106). A context pin is dropped only when its route identity changed (fail-closed).
  1552. Non-custom targets resolve credentials from env/auth.json/the pool, so an inline
  1553. ``model.api_key`` is a leftover that would contaminate later custom resolution. For custom
  1554. targets the inline key belongs to ONE endpoint: it survives only a same-route re-pick (same
  1555. provider and base_url) — ``custom:a`` -> ``custom:b`` must not hand endpoint A's secret to B.
  1556. The ``key_env`` / ``api_key_env`` credential POINTER (written by custom-endpoint activation
  1557. and, for REGISTRY providers too, by the Desktop settings UI (#106336); resolved by
  1558. runtime_provider / auxiliary_client / ``auth._model_level_key_env``) clears only when the
  1559. route changed: left behind it routes the NEW provider's requests to the OLD endpoint's env
  1560. var, but a same-provider same-base_url model re-pick keeps it whatever the provider is. The
  1561. dashboard re-adds an explicitly submitted key / the target provider's own pointer after this
  1562. (``_apply_main_model_assignment`` / ``_resolve_assignment_credentials``)."""
  1563. model_cfg = current_model_cfg if isinstance(current_model_cfg, dict) else {}
  1564. updates: dict[str, Any] = {
  1565. "default": result.new_model, "provider": result.target_provider,
  1566. "base_url": result.base_url or None, "api_mode": result.api_mode or None,
  1567. }
  1568. if "context_length" in model_cfg:
  1569. from hermes_cli.route_identity import should_clear_context_pin
  1570. if should_clear_context_pin(
  1571. model_cfg.get("default") or model_cfg.get("model"), result.new_model,
  1572. model_cfg.get("base_url"), result.base_url, model_cfg.get("provider"), result.target_provider):
  1573. updates["context_length"] = None
  1574. target = str(result.target_provider or "").strip().lower()
  1575. route_changed = selection_route_changed(model_cfg, result)
  1576. stale = ["api_key", "api"] if (not target.startswith("custom") or route_changed) else []
  1577. if route_changed:
  1578. stale += ["key_env", "api_key_env"]
  1579. for key in stale:
  1580. if key in model_cfg:
  1581. updates[key] = None
  1582. return updates
  1583. def selection_route_changed(model_cfg: dict, result: ModelSwitchResult) -> bool:
  1584. """Provider or endpoint differs between a ``model:`` block and the switch target. The one
  1585. route-identity test for endpoint-bound credentials (inline keys, ``key_env``, launch keys)."""
  1586. from hermes_cli.route_identity import normalize_route_base_url
  1587. if str(model_cfg.get("provider") or "").strip().lower() != str(result.target_provider or "").strip().lower():
  1588. return True
  1589. return normalize_route_base_url(model_cfg.get("base_url")) != normalize_route_base_url(result.base_url)
  1590. def apply_model_selection(model_cfg: Any, result: ModelSwitchResult, *, mask_cleared: bool = False) -> dict:
  1591. """Apply the canonical shape to an in-memory ``model:`` dict (``None`` = key removed) for
  1592. callers that save a whole config document they are already mutating.
  1593. ``mask_cleared``: a key the switch clears that *model_cfg* holds is set to ``None`` instead of
  1594. removed. For a document saved to Remote Config, where *model_cfg* is the EFFECTIVE block and
  1595. a removal only drops the profile override, so an upper level's old-endpoint ``api_key`` /
  1596. ``key_env`` / ``context_length`` would still apply at the new endpoint (contract §5.4: a
  1597. stored null is "no value"). The same rule :func:`persist_model_selection` applies."""
  1598. return _merge_selection_updates(model_cfg, model_selection_config_updates(result, model_cfg),
  1599. mask_cleared=mask_cleared)
  1600. def _merge_selection_updates(model_cfg: Any, updates: dict[str, Any], *, mask_cleared: bool = False) -> dict:
  1601. model_cfg = dict(model_cfg) if isinstance(model_cfg, dict) else {}
  1602. for key, value in updates.items():
  1603. if value is None and not (mask_cleared and key in model_cfg):
  1604. model_cfg.pop(key, None)
  1605. else:
  1606. model_cfg[key] = value
  1607. return model_cfg
  1608. def remote_model_selection_guard(before: Any, after: Any) -> None:
  1609. """Remote Config: refuse a whole-document model assignment when any ``model.*`` key it
  1610. changes is locked by an upper level. A bulk save omits a locked key instead of raising, which
  1611. would land the rest of the route (a new endpoint with the old provider, say) half-applied;
  1612. :func:`persist_model_selection` gets the same all-or-nothing refusal from its one keyed write.
  1613. No-op for the file backend."""
  1614. from hermes_cli.config_backend import ConfigLockedError, get_config_backend, supports_file_tooling
  1615. if supports_file_tooling():
  1616. return
  1617. from hermes_constants import get_hermes_home
  1618. before = before if isinstance(before, dict) else {}
  1619. after = after if isinstance(after, dict) else {}
  1620. backend, home = get_config_backend(), get_hermes_home()
  1621. for key in sorted(set(before) | set(after)):
  1622. if before.get(key, _MISSING) != after.get(key, _MISSING):
  1623. level = backend.locked(home, f"model.{key}")
  1624. if level:
  1625. raise ConfigLockedError(f"model.{key}", level)
  1626. _MISSING = object()
  1627. def persist_model_selection(result: ModelSwitchResult, config_path: Any = None) -> None:
  1628. """Write a successful :func:`switch_model` result to ``config_path`` (default:
  1629. ``HERMES_HOME/config.yaml`` — the context override or ``HERMES_HOME`` at call time).
  1630. Build the complete selection from one raw snapshot, preserving sibling settings and secret
  1631. references, then publish once. Per-key publication can leave a mixed route after a failed
  1632. write or an overlapping selection. ``should_clear_context_pin`` can do cold-start disk I/O
  1633. — async callers run this on a worker thread.
  1634. The replace deletes keys missing from the snapshot, so every route decision (and its disk
  1635. I/O) is made from a pre-read BEFORE the snapshot; read -> merge -> replace is then a pure
  1636. in-memory section. Only when another writer changed ``model:`` in between are the updates
  1637. recomputed against the fresh block. ``_CONFIG_LOCK`` is in-process only: a cross-process
  1638. config lock, once one exists, must wrap the same section."""
  1639. from pathlib import Path
  1640. from hermes_cli.config import _CONFIG_LOCK, atomic_config_replace, get_config_path, read_user_config_raw
  1641. from hermes_cli.config_backend import supports_file_tooling, write_config_keys
  1642. path = Path(config_path) if config_path else get_config_path()
  1643. planned_from = read_user_config_raw(path).get("model")
  1644. updates = model_selection_config_updates(result, planned_from)
  1645. if not supports_file_tooling():
  1646. # No config file (Remote Config): one keyed write, so a lock on any key refuses the whole
  1647. # switch instead of a document save silently omitting the locked part. The planned-from
  1648. # block is the EFFECTIVE one, so a key it holds may come from an upper level, where a
  1649. # profile-level unset cannot reach it (contract §5.4): an inherited old-endpoint api_key
  1650. # would stay active at the new endpoint. A key the switch clears and the effective block
  1651. # still holds is therefore masked with null ("no value"); an absent one is just unset.
  1652. from hermes_cli.config_backend import Changes, write_changes
  1653. held = planned_from if isinstance(planned_from, dict) else {}
  1654. masked = _merge_selection_updates(held, updates, mask_cleared=True)
  1655. write_changes(path, Changes(
  1656. set={f"model.{k}": masked[k] for k in updates if k in masked},
  1657. unset=tuple(f"model.{k}" for k in updates if k not in masked)))
  1658. return
  1659. with _CONFIG_LOCK:
  1660. config = read_user_config_raw(path)
  1661. model_cfg = config.get("model")
  1662. if model_cfg != planned_from:
  1663. updates = model_selection_config_updates(result, model_cfg)
  1664. merged = _merge_selection_updates(model_cfg, updates)
  1665. if isinstance(model_cfg, dict):
  1666. # A YAML anchor on ``model:`` reused elsewhere (``vision: *route``) loads as ONE shared
  1667. # dict; edit it in place so every alias carries the new route, as the shared node on
  1668. # disk will. A fresh copy left the alias stale and the round-trip merge wrote it back.
  1669. model_cfg.clear()
  1670. model_cfg.update(merged)
  1671. else:
  1672. config["model"] = merged
  1673. atomic_config_replace(path, config)
  1674. try: # owner-only: config files contain API keys
  1675. os.chmod(path, 0o600)
  1676. except (OSError, NotImplementedError):
  1677. pass
  1678. def _extra_headers_from_config(entry: Any) -> dict[str, str]:
  1679. if not isinstance(entry, dict):
  1680. return {}
  1681. from hermes_cli.config import normalize_extra_headers
  1682. return normalize_extra_headers(entry.get("extra_headers"))
  1683. def _scoped_key_env(name: str) -> str:
  1684. """Read a provider key env var the way the chat path does, honouring the per-profile scope.
  1685. With a secret scope installed (multiplexed gateway turn, dashboard/kanban workers) the scope's
  1686. verdict is authoritative: a hit is this profile's key, a miss must not borrow another profile's
  1687. value from the process env or the default ``.env``. Multiplexing on with no scope fails closed
  1688. (``UnscopedSecretError`` -> ""). Otherwise resolve through ``get_env_prefer_dotenv`` — the
  1689. chain ``client_lifecycle`` uses for the actual request — so a ``key_env`` that lives only in
  1690. ``$HERMES_HOME/.env`` authenticates the ``/model`` verification probe (#109315) and a rotated
  1691. ``.env`` beats a stale value inherited from the parent shell."""
  1692. if not name:
  1693. return ""
  1694. try:
  1695. from agent.secret_scope import current_secret_scope, get_secret, is_multiplex_active
  1696. if current_secret_scope() is not None or is_multiplex_active():
  1697. return (get_secret(name, "") or "").strip()
  1698. from agent.credential_pool import get_env_prefer_dotenv
  1699. return (get_env_prefer_dotenv(name) or "").strip()
  1700. except Exception:
  1701. return ""