models.py 125 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661
  1. """Provider/model catalogs: discovery, caching, and identity helpers.
  2. Origin module; cohesive clusters live in siblings and are re-imported here so
  3. ``hermes_cli.models.<name>`` stays the stable import/monkeypatch surface:
  4. ``models_catalog_static`` (curated tables, provider registry, aliases), ``models_reasoning_caps``,
  5. ``models_local`` (Ollama / LM Studio), ``models_pricing``, ``models_validate``.
  6. """
  7. from __future__ import annotations
  8. import contextvars
  9. import copy
  10. import gzip
  11. import json
  12. import logging
  13. import os
  14. import re
  15. import sys
  16. import threading
  17. import urllib.parse
  18. import urllib.request
  19. import urllib.error
  20. import time
  21. from pathlib import Path
  22. from typing import Any, Optional, TYPE_CHECKING
  23. if TYPE_CHECKING:
  24. from typing import TypeGuard
  25. from agent.proxy_bypass import is_loopback_host
  26. from hermes_cli.route_identity import normalize_route_base_url
  27. from hermes_cli.urllib_security import open_credentialed_url
  28. from hermes_cli.version_info import hermes_user_agent
  29. from hermes_cli.models_catalog_static import (
  30. CuratedFallbackModels,
  31. CANONICAL_PROVIDERS,
  32. OPENROUTER_MODELS,
  33. PREFERRED_SILENT_DEFAULT_MODEL,
  34. VERCEL_AI_GATEWAY_MODELS,
  35. _AGGREGATOR_PROVIDERS,
  36. _AZURE_FOUNDRY_RESPONSES_PREFIXES,
  37. _BORROWED_MODEL_PROVIDERS,
  38. _LIVE_FIRST_PICKER_PROVIDERS,
  39. _MODELS_DEV_PREFERRED,
  40. _OPENAI_FAST_MODE_PREFIXES,
  41. _OPENAI_ULTRAFAST_MODELS,
  42. _PROVIDER_ALIASES,
  43. _PROVIDER_LABELS,
  44. _PROVIDER_MODELS,
  45. _PROVIDER_RETIRED_ALIASES,
  46. _SILENT_DEFAULT_PROVIDERS,
  47. _xai_finalize_catalog)
  48. from hermes_cli.models_reasoning_caps import (
  49. _OPENROUTER_CATALOG_URL,
  50. _seed_reasoning_caps)
  51. from hermes_cli.models_local import (
  52. _OLLAMA_LOCAL_MODELS_CACHE,
  53. _OLLAMA_LOCAL_MODELS_CACHE_TTL,
  54. _OLLAMA_LOCAL_PROBE_FAILURE_CACHE,
  55. _OLLAMA_LOCAL_PROBE_REACHABLE,
  56. _get_ollama_base_url,
  57. _get_ollama_native_headers,
  58. _ollama_local_catalog,
  59. _ollama_probe_cache_key,
  60. _root_for_ollama_native_api,
  61. fetch_ollama_cloud_models)
  62. logger = logging.getLogger(__name__)
  63. def _urlopen_model_catalog_request(req: urllib.request.Request, *, timeout: float, ssl_context=None):
  64. """Open catalog requests without forwarding headers across origins."""
  65. return open_credentialed_url(req, timeout=timeout, ssl_context=ssl_context)
  66. def _get_json(
  67. url: str, *, timeout: float, headers: Optional[dict[str, str]] = None, opener=None, **open_kwargs: Any
  68. ) -> Any:
  69. """GET ``url`` and parse the JSON body. ``opener`` defaults to the catalog opener (resolved at
  70. call time so monkeypatching ``_urlopen_model_catalog_request`` still applies). Raises on failure."""
  71. req = urllib.request.Request(url, headers=headers or {})
  72. with (opener or _urlopen_model_catalog_request)(req, timeout=timeout, **open_kwargs) as resp:
  73. body = resp.read()
  74. if req.get_header("Accept-encoding") == "gzip" and resp.headers.get("Content-Encoding", "").lower() == "gzip":
  75. body = gzip.decompress(body)
  76. return json.loads(body.decode())
  77. def _read_json_cache(path: Path, *, errors=Exception) -> Optional[dict]:
  78. """Load a JSON-object cache file; None when missing, unreadable, or not a dict."""
  79. try:
  80. with open(path, encoding="utf-8-sig") as fh:
  81. data = json.load(fh)
  82. except errors:
  83. return None
  84. return data if isinstance(data, dict) else None
  85. def _write_json_cache(path: Path, data: Any, **dump_kwargs: Any) -> None:
  86. """Atomically persist a cache file (creating parents). Raises on failure — callers decide
  87. whether a failed cache write is worth logging."""
  88. from utils import atomic_json_write
  89. from hermes_constants import mkdir_under_hermes_home
  90. mkdir_under_hermes_home(path.parent)
  91. atomic_json_write(path, data, **dump_kwargs)
  92. def _merge_unique(primary: list[str], secondary: list[str], key=lambda m: str(m).lower()) -> list[str]:
  93. """``primary`` verbatim, then ``secondary`` entries whose ``key`` is new (deduped as it goes)."""
  94. merged, seen = list(primary), {key(m) for m in primary}
  95. for m in secondary:
  96. k = key(m)
  97. if k not in seen:
  98. seen.add(k)
  99. merged.append(m)
  100. return merged
  101. def _custom_provider_ssl_context(base_url: str):
  102. """Use the same trust decision for urllib catalogs and HTTPX metadata/chat."""
  103. from agent.model_metadata_http import resolve_verify
  104. verify = resolve_verify(base_url)
  105. if verify is True:
  106. return None
  107. if verify is False:
  108. import ssl
  109. context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
  110. context.check_hostname = False
  111. context.verify_mode = ssl.CERT_NONE
  112. return context
  113. return verify
  114. # Process-lifetime picker lists refreshed from the live catalogs (see fetch_*_models).
  115. _openrouter_catalog_cache: list[tuple[str, str]] | None = None
  116. # The in-memory ``_openrouter_catalog_cache`` is per-process, so without a disk cache every cold
  117. # picker open re-downloads the full ~686KB /api/v1/models catalog. The *curated* result
  118. # (post-filter) is persisted under the same TTL the catalog manifest uses, so both layers go
  119. # stale together.
  120. def _openrouter_catalog_disk_ttl() -> float:
  121. """Same TTL as the catalog manifest this list is filtered from (honours ``model_catalog.ttl_minutes``)."""
  122. from hermes_cli.model_catalog import refresh_interval_seconds
  123. return refresh_interval_seconds()
  124. def _openrouter_catalog_disk_path() -> Path:
  125. from hermes_constants import get_hermes_home
  126. return get_hermes_home() / "cache" / "openrouter_curated_catalog.json"
  127. def _read_openrouter_catalog_disk(*, allow_stale: bool = False) -> list[tuple[str, str]] | None:
  128. """Fresh curated catalog from disk, or None (missing, corrupt, expired, or empty).
  129. ``allow_stale`` ignores the TTL — the cache-only read path prefers a stale copy over a live GET."""
  130. obj = _read_json_cache(_openrouter_catalog_disk_path())
  131. if obj is None:
  132. return None
  133. try:
  134. if not allow_stale and time.time() - float(obj.get("fetched_at", 0)) > _openrouter_catalog_disk_ttl():
  135. return None
  136. except (TypeError, ValueError):
  137. return None
  138. items = obj.get("curated")
  139. if not isinstance(items, list):
  140. return None
  141. out = [(str(it[0]), str(it[1])) for it in items if isinstance(it, (list, tuple)) and len(it) == 2]
  142. return out or None
  143. def _write_openrouter_catalog_disk(curated: list[tuple[str, str]]) -> None:
  144. try:
  145. _write_json_cache(
  146. _openrouter_catalog_disk_path(),
  147. {"fetched_at": time.time(), "curated": [list(c) for c in curated]})
  148. except Exception as exc:
  149. logger.debug("openrouter curated catalog disk write failed: %s", exc)
  150. _ai_gateway_catalog_cache: list[tuple[str, str]] | None = None
  151. # ---------------------------------------------------------------------------
  152. # Nous Portal free-model helpers — the Portal models endpoint is the source of truth for what is
  153. # offered (free or paid); we surface it as-is, no local allowlist filtering.
  154. # ---------------------------------------------------------------------------
  155. def _zero_priced(pricing: Any, keys: tuple[str, str], default: str) -> bool:
  156. """True when both pricing fields parse to 0 (missing fields read as ``default``)."""
  157. if not isinstance(pricing, dict):
  158. return False
  159. try:
  160. return all(float(pricing.get(k, default)) == 0 for k in keys)
  161. except (TypeError, ValueError):
  162. return False
  163. def _is_subscription_billed(entry: Any) -> bool:
  164. """The gateway bills this catalog row to a subscription the account holds, not to credits."""
  165. return isinstance(entry, dict) and entry.get("billing_mode") == "subscription"
  166. def _is_model_free(model_id: str, pricing: dict[str, dict[str, str]]) -> bool:
  167. """Return True if *model_id* costs no credits: zero-cost prompt AND completion pricing, or a row
  168. the gateway bills to a subscription."""
  169. entry = pricing.get(model_id)
  170. return bool(entry) and (_is_subscription_billed(entry) or _zero_priced(entry, ("prompt", "completion"), "1"))
  171. def partition_nous_models_by_tier(
  172. model_ids: list[str], pricing: dict[str, dict[str, str]], free_tier: bool
  173. ) -> tuple[list[str], list[str]]:
  174. """Split Nous models into (selectable, unavailable): free-tier users may only select free models
  175. (paid ones are returned as unavailable, shown grayed out)."""
  176. if not free_tier or not pricing: # no pricing → can't determine, show everything
  177. return (model_ids, [])
  178. selectable = [mid for mid in model_ids if _is_model_free(mid, pricing)]
  179. return (selectable, [mid for mid in model_ids if mid not in selectable])
  180. def _union_with_portal_recommendations(
  181. tier_key: str, curated_ids: list[str], pricing: dict[str, dict[str, str]], portal_base_url: str,
  182. *, force_refresh: bool, synthesize_free_pricing: bool,
  183. ) -> tuple[list[str], dict[str, dict[str, str]]]:
  184. """Append the Portal's ``<tier_key>`` recommendations missing from ``curated_ids``.
  185. Curated models show first, Portal-only picks follow. Failures (network, parse, missing field)
  186. silently return the inputs unchanged — never block the picker on a Portal-side hiccup.
  187. """
  188. try:
  189. payload = fetch_nous_recommended_models(portal_base_url, force_refresh=force_refresh)
  190. except Exception:
  191. payload = None
  192. block = payload.get(tier_key) if isinstance(payload, dict) else None
  193. entries = block if isinstance(block, list) else []
  194. portal_ids = [name for entry in entries if (name := _extract_model_name(entry))]
  195. if not portal_ids:
  196. return (list(curated_ids), dict(pricing))
  197. augmented_pricing = dict(pricing)
  198. if synthesize_free_pricing:
  199. for mid in portal_ids:
  200. augmented_pricing.setdefault(mid, {"prompt": "0", "completion": "0"})
  201. seen = set(curated_ids)
  202. return (list(curated_ids) + [mid for mid in portal_ids if mid not in seen], augmented_pricing)
  203. def union_with_portal_free_recommendations(
  204. curated_ids: list[str], pricing: dict[str, dict[str, str]], portal_base_url: str = "", *,
  205. force_refresh: bool = False) -> tuple[list[str], dict[str, dict[str, str]]]:
  206. """Curated list + pricing plus the Portal's ``freeRecommendedModels``; Portal-only free picks get a
  207. synthetic $0 pricing entry so tier partitioning sees them as free."""
  208. return _union_with_portal_recommendations(
  209. "freeRecommendedModels", curated_ids, pricing, portal_base_url,
  210. force_refresh=force_refresh, synthesize_free_pricing=True)
  211. def union_with_portal_paid_recommendations(
  212. curated_ids: list[str], pricing: dict[str, dict[str, str]], portal_base_url: str = "", *,
  213. force_refresh: bool = False) -> tuple[list[str], dict[str, dict[str, str]]]:
  214. """Curated list plus the Portal's ``paidRecommendedModels``; ``pricing`` is deliberately left untouched."""
  215. return _union_with_portal_recommendations(
  216. "paidRecommendedModels", curated_ids, pricing, portal_base_url,
  217. force_refresh=force_refresh, synthesize_free_pricing=False)
  218. def union_with_nous_on_sale_models(curated_ids: list[str], pricing: dict[str, dict[str, Any]]) -> list[str]:
  219. """Curated list plus every paid Nous model the gateway is discounting right now, deepest
  220. discount first. A sale lives only in ``/v1/models`` ``pricing.original``, so without this the
  221. picker badges discounts on curated rows but never shows a discounted model the curated list and
  222. Portal recommendations omit. Free rows stay with ``freeRecommendedModels``; rows the gateway
  223. marks tool-less (``"tools": False``) are skipped because Hermes is tool-calling-first, and
  224. image/video generation rows are skipped because they are not chat models."""
  225. from math import isfinite
  226. from hermes_cli.models_pricing import _price_float, compute_sale_discount
  227. seen = set(curated_ids)
  228. on_sale: list[tuple[int, str]] = []
  229. for mid, entry in (pricing or {}).items():
  230. if mid in seen or not isinstance(entry, dict) or entry.get("tools") is False or entry.get("generation"):
  231. continue
  232. sale = compute_sale_discount(entry.get("prompt", ""), entry.get("completion", ""), entry.get("original"))
  233. # Badge percentages are rounded: a nearly-free paid row can display 100% off.
  234. paid = any(
  235. (rate := _price_float(entry.get(key), positive=True)) is not None and isfinite(rate)
  236. for key in ("prompt", "completion")
  237. )
  238. if sale is not None and isinstance(entry.get("original"), dict) and paid:
  239. on_sale.append((-sale[0], mid))
  240. return list(curated_ids) + [mid for _, mid in sorted(on_sale)]
  241. # Free-tier detection cache, per profile — short so an account upgrade shows within minutes.
  242. _FREE_TIER_CACHE_TTL: int = 180 # seconds
  243. _free_tier_cache: dict[str, tuple[bool, float]] = {} # profile key -> (result, timestamp)
  244. def _pricing_profile_key() -> str:
  245. """Stable profile identity for process-local pricing caches."""
  246. from hermes_constants import hermes_home_key
  247. return hermes_home_key()
  248. def get_cached_nous_free_tier() -> Optional[bool]:
  249. """This profile's live cached entitlement, or ``None`` if unknown/expired."""
  250. cached = _free_tier_cache.get(_pricing_profile_key())
  251. if cached is None or time.monotonic() - cached[1] >= _FREE_TIER_CACHE_TTL:
  252. return None
  253. return cached[0]
  254. def check_nous_free_tier(*, force_fresh: bool = False, cached_only: bool = False) -> bool:
  255. """True only when the Nous Portal user is KNOWN to be free-tier (unknown/error → False so this
  256. never blocks users). Cached ``_FREE_TIER_CACHE_TTL`` seconds so an upgrade shows within minutes.
  257. ``cached_only`` returns the live cached answer or the fail-open ``False`` without contacting Portal."""
  258. now = time.monotonic()
  259. profile_key = _pricing_profile_key()
  260. if not force_fresh:
  261. cached_result = get_cached_nous_free_tier()
  262. if cached_result is not None:
  263. return cached_result
  264. if cached_only:
  265. return False
  266. try:
  267. from hermes_cli.nous_account import get_nous_portal_account_info
  268. result = get_nous_portal_account_info(force_fresh=force_fresh).is_free_tier
  269. except Exception:
  270. result = False # default to paid on error — don't block users
  271. _free_tier_cache[profile_key] = (result, now)
  272. return result
  273. # ---------------------------------------------------------------------------
  274. # Nous Portal recommended models — curated paid/free suggestions plus dedicated compaction (aux)
  275. # and vision picks, TTL-cached per process. Fields read: {paid,free}RecommendedModels:
  276. # [{modelName}], {paid,free}Recommended{Compaction,Vision}Model: {modelName} | null
  277. # ---------------------------------------------------------------------------
  278. NOUS_RECOMMENDED_MODELS_MIRROR = "https://web-assets.nousresearch.com/dynamic"
  279. _NOUS_MIRROR_TIMEOUT: float = 2.0 # seconds: a hanging mirror delays the Portal fallback by at most this
  280. _NOUS_RECOMMENDED_CACHE_TTL: int = 600 # seconds (10 minutes)
  281. # (result_dict, monotonic timestamp), scoped to the profile and portal.
  282. _nous_recommended_cache: dict[tuple[str, str], tuple[dict[str, Any], float]] = {}
  283. def _nous_recommended_disk_path() -> Path:
  284. from hermes_constants import get_hermes_home
  285. return get_hermes_home() / "cache" / "nous_recommended_cache.json"
  286. def _read_nous_recommended_disk(base: str) -> tuple[dict[str, Any], float] | None:
  287. """Return the last good payload and its age for the freshness check."""
  288. blob = _read_json_cache(_nous_recommended_disk_path(), errors=(OSError, json.JSONDecodeError, UnicodeDecodeError))
  289. entry = (blob or {}).get(base)
  290. data = entry.get("data") if isinstance(entry, dict) else None
  291. if not isinstance(data, dict) or not data:
  292. return None
  293. try:
  294. age = time.time() - float(entry.get("ts", 0))
  295. except (TypeError, ValueError, OverflowError):
  296. age = float("inf")
  297. return data, age
  298. def _write_nous_recommended_disk(base: str, data: dict[str, Any]) -> None:
  299. """Merge ``data`` into the per-base disk map atomically; failures are debug-logged (the in-process
  300. cache still works)."""
  301. if not data:
  302. return
  303. path = _nous_recommended_disk_path()
  304. try:
  305. blob = _read_json_cache(path, errors=(OSError, json.JSONDecodeError, UnicodeDecodeError)) or {}
  306. blob[base] = {"data": data, "ts": time.time()}
  307. _write_json_cache(path, blob, indent=2)
  308. except OSError as exc:
  309. logger.debug("nous recommended-models disk cache write failed: %s", exc)
  310. def fetch_nous_recommended_models(
  311. portal_base_url: str = "", timeout: float = 5.0, *, force_refresh: bool = False
  312. ) -> dict[str, Any]:
  313. """Fetch the Portal's public recommended models (no auth): its R2 mirror, else the Portal itself.
  314. Results are reused for ``_NOUS_RECOMMENDED_CACHE_TTL`` s across restarts unless ``force_refresh``;
  315. stale disk data is the fallback on failure, and reading it never renews its freshness."""
  316. base = (portal_base_url or "https://portal.nousresearch.com").rstrip("/")
  317. now = time.monotonic()
  318. cache_key = (_pricing_profile_key(), base)
  319. cached = _nous_recommended_cache.get(cache_key)
  320. if not force_refresh and cached is not None and now - cached[1] < _NOUS_RECOMMENDED_CACHE_TTL:
  321. return cached[0]
  322. disk = _read_nous_recommended_disk(base)
  323. if not force_refresh and disk is not None and 0 <= disk[1] < _NOUS_RECOMMENDED_CACHE_TTL:
  324. data, age = disk
  325. _nous_recommended_cache[cache_key] = (data, now - age)
  326. return data
  327. parts = urllib.parse.urlsplit(base)
  328. mirror = [] if is_loopback_host(parts.hostname) else [
  329. (f"{NOUS_RECOMMENDED_MODELS_MIRROR}/{parts.netloc}", min(timeout, _NOUS_MIRROR_TIMEOUT))]
  330. for origin, origin_timeout in [*mirror, (base, timeout)]: # the Portal itself when its mirror is missing (404) or failing
  331. try:
  332. data = _get_json(f"{origin}/api/nous/recommended-models", timeout=origin_timeout,
  333. headers={"Accept": "application/json", "Accept-Encoding": "gzip"})
  334. except Exception:
  335. continue
  336. if isinstance(data, dict) and data:
  337. _write_nous_recommended_disk(base, data)
  338. break
  339. else:
  340. data = disk[0] if disk is not None else {}
  341. _nous_recommended_cache[cache_key] = (data, now)
  342. return data
  343. def _resolve_nous_portal_url() -> str:
  344. """Best-effort lookup of the Portal base URL the user is authed against."""
  345. try:
  346. from hermes_cli.auth import DEFAULT_NOUS_PORTAL_URL, get_provider_auth_state
  347. state = get_provider_auth_state("nous") or {}
  348. portal = str(state.get("portal_base_url") or "").strip()
  349. return (portal or str(DEFAULT_NOUS_PORTAL_URL)).rstrip("/")
  350. except Exception:
  351. return "https://portal.nousresearch.com"
  352. def _extract_model_name(entry: Any) -> Optional[str]:
  353. """Pull the ``modelName`` field from a recommended-model entry, else None."""
  354. model_name = entry.get("modelName") if isinstance(entry, dict) else None
  355. return model_name.strip() if isinstance(model_name, str) and model_name.strip() else None
  356. def get_nous_recommended_aux_model(
  357. *, vision: bool = False, free_tier: Optional[bool] = None, portal_base_url: str = "",
  358. force_refresh: bool = False) -> Optional[str]:
  359. """The Portal's recommended model for an auxiliary task: free tier → free pick only; paid tier →
  360. paid pick, falling back to the free one when the Portal returned ``null`` (staged rollouts)."""
  361. base = portal_base_url or _resolve_nous_portal_url()
  362. payload = fetch_nous_recommended_models(base, force_refresh=force_refresh)
  363. if not payload:
  364. return None
  365. if free_tier is None:
  366. try:
  367. free_tier = check_nous_free_tier()
  368. except Exception:
  369. free_tier = False # assume paid on detection error — paid users see both fields anyway
  370. kind = "Vision" if vision else "Compaction"
  371. tiers = ("free",) if free_tier else ("paid", "free")
  372. return next((n for t in tiers if (n := _extract_model_name(payload.get(f"{t}Recommended{kind}Model")))), None)
  373. def get_preferred_silent_default_model(provider: str = "openrouter") -> str:
  374. """Silent-default model id: the cached remote catalog's ``"default": true`` label (never hits the
  375. network — safe on hot paths), else :data:`PREFERRED_SILENT_DEFAULT_MODEL`."""
  376. try:
  377. from hermes_cli.model_catalog import get_default_model_from_cache
  378. labeled = get_default_model_from_cache(provider)
  379. if labeled:
  380. return labeled
  381. except Exception:
  382. pass
  383. return PREFERRED_SILENT_DEFAULT_MODEL
  384. def _is_anthropic_frontier_tier(model_id: Optional[str]) -> bool:
  385. """Return True for Anthropic frontier-tier models (Opus + Fable).
  386. Both tiers are the priciest Anthropic offerings and are unsafe defaults
  387. for a freshly-authenticated provider picker or any other silent fallback:
  388. paid users landing on a frontier tier have no opportunity to opt out
  389. before the choice pins their main model and inherits into every cron job
  390. that doesn't override ``model.provider``.
  391. Anchored on the ``claude-`` family prefix, then the ``opus-`` / ``fable-``
  392. tier token (after vendor-strip and lowercase normalization), so the
  393. predicate survives future Anthropic releases (``claude-opus-5-0``,
  394. ``claude-fable-6``, etc.) and rejects community / distill models whose
  395. slug merely *contains* the substring ``opus`` (e.g. ``qwopus3.6-27b-coder``).
  396. Sonnet and Haiku are deliberately NOT classified as frontier here — they
  397. remain reasonable auto-default candidates.
  398. """
  399. raw = _strip_vendor_prefix(str(model_id or ""))
  400. base = raw.split(":")[0].lower()
  401. if not base.startswith("claude-"):
  402. return False
  403. return ("opus-" in base) or ("fable-" in base)
  404. def pick_silent_default_model(model_ids: list[str], provider: str = "openrouter") -> str:
  405. """Pick a cost-safe silent default from an available-models list.
  406. Shared policy for every surface that must choose a model on the user's
  407. behalf without an interactive confirmation (GUI onboarding
  408. recommended-default, empty-model runtime fallback, provider-set-but-
  409. model-missing resolution):
  410. 1. If the catalog-labeled preferred default (see
  411. :func:`get_preferred_silent_default_model`) is present in
  412. ``model_ids``, return it.
  413. 2. Else, return the first entry that is NOT an Anthropic frontier tier
  414. (Opus / Fable — see :func:`_is_anthropic_frontier_tier`). Catalog
  415. ordering is preserved, so a freshly-released cheaper model still
  416. wins over a leftover Sonnet.
  417. 3. Else (every entry is a frontier tier), return ``model_ids[0]`` so the
  418. picker is never empty — defensive last resort only.
  419. 4. Else (empty list), return ``\"\"``.
  420. This hardened fallback closes the hole where a Portal-augmented list
  421. that didn't carry the catalog label fell through to ``model_ids[0]``
  422. (currently ``anthropic/claude-fable-5``) and billed the most expensive
  423. Anthropic flagship for traffic the user never opted into.
  424. """
  425. if not model_ids:
  426. return ""
  427. preferred = get_preferred_silent_default_model(provider)
  428. if preferred in model_ids:
  429. return preferred
  430. non_frontier = [mid for mid in model_ids if not _is_anthropic_frontier_tier(mid)]
  431. if non_frontier:
  432. return non_frontier[0]
  433. return model_ids[0]
  434. def recommended_nous_default_model() -> dict[str, Any]:
  435. """The model a Nous account lands on without choosing one, honouring the account's tier.
  436. Curated catalog plus the Portal's recommendations for the tier, narrowed to the org's policy,
  437. then (free tier) to the rows the tier may select, then :func:`pick_silent_default_model`.
  438. Contacts the Portal for a fresh tier read, so never call it on a hot path. Returns
  439. ``{"provider": "nous", "model": str, "free_tier": bool}``; ``model`` may be ``""`` when nothing
  440. is selectable (callers degrade). Shared by ``GET /api/model/recommended-default`` and the
  441. sign-in completion in ``hermes_cli.anon_auth`` so both land on the same model.
  442. """
  443. from hermes_cli import model_picker_usage, models_pricing as mp
  444. from hermes_cli.auth import get_provider_auth_state
  445. model_ids = get_curated_nous_model_ids()
  446. pricing = mp.get_pricing_for_provider("nous") or {}
  447. free_tier = check_nous_free_tier(force_fresh=True)
  448. try:
  449. portal_url = (get_provider_auth_state("nous") or {}).get("portal_base_url", "") or ""
  450. except Exception:
  451. portal_url = ""
  452. # Narrow to policy BEFORE the tier split, so a rescued id still has to pass the free/paid predicate.
  453. policy_allowed = mp.nous_policy_allowed_ids()
  454. union = union_with_portal_free_recommendations if free_tier else union_with_portal_paid_recommendations
  455. model_ids, pricing = union(model_ids, pricing, portal_url)
  456. model_ids = mp.restrict_to_nous_policy(model_ids, policy_allowed, rescue_empty=True)
  457. if free_tier:
  458. model_ids, _unavailable = partition_nous_models_by_tier(model_ids, pricing, free_tier=True)
  459. # Never default onto a subscription-billed row: spending that plan is the user's call.
  460. model_ids = [mid for mid in model_ids if not _is_subscription_billed(pricing.get(mid))] or model_ids
  461. model = "" if free_tier else model_picker_usage.window_plan_default(model_ids, pricing)
  462. return {"provider": "nous", "model": model or pick_silent_default_model(model_ids, provider="nous"),
  463. "free_tier": bool(free_tier)}
  464. def static_catalog(provider: str) -> list[str]:
  465. """Curated ids for *provider*: its built-in row, else the bound home's profile ``static_models``.
  466. Resolved per lookup, never copied into the shared table: two served homes may register the same
  467. provider name with different models (or only one of them has the plugin)."""
  468. if provider in _PROVIDER_MODELS:
  469. return _PROVIDER_MODELS[provider]
  470. from providers import get_provider_profile
  471. profile = get_provider_profile(provider) if provider else None
  472. return list(profile.static_models) if profile is not None else []
  473. def static_catalog_providers() -> list[str]:
  474. """Every provider with a static catalog row in the bound home: built-ins, then plugin profiles."""
  475. from providers import list_providers
  476. plugin_rows = [p.name for p in list_providers() if p.static_models and p.name not in _PROVIDER_MODELS]
  477. return [*_PROVIDER_MODELS, *dict.fromkeys(plugin_rows)]
  478. def get_default_model_for_provider(provider: str) -> str:
  479. """Cost-safe default model for a provider, or "" — the NON-INTERACTIVE fallback when a provider
  480. is configured but no model was ever selected."""
  481. models = static_catalog(provider)
  482. if provider in _SILENT_DEFAULT_PROVIDERS:
  483. preferred = get_preferred_silent_default_model(provider)
  484. # Trust the preferred default even without a static catalog (OpenRouter's picker list is
  485. # fetched live; its curated snapshot carries the default).
  486. if preferred and (preferred in models or not models):
  487. return preferred
  488. return models[0] if models else ""
  489. def _openrouter_model_is_free(pricing: Any) -> bool:
  490. return _zero_priced(pricing, ("prompt", "completion"), "0")
  491. def _openrouter_model_supports_tools(item: Any) -> bool:
  492. """True when ``supported_parameters`` advertises ``tools`` (hermes-agent is tool-calling-first).
  493. Permissive when the field is absent/malformed: some OpenRouter-compatible gateways (Nous Portal,
  494. private mirrors) don't populate it, and the picker must not silently empty for them.
  495. Ported from Kilo-Org/kilocode#9068.
  496. """
  497. params = item.get("supported_parameters") if isinstance(item, dict) else None
  498. return "tools" in params if isinstance(params, list) else True
  499. # Reasoning-capability cache slots, one set per catalog (OpenRouter, Nous Portal). The logic
  500. # lives in models_reasoning_caps and reads/writes these by name so tests can reset them here.
  501. # ``*_cache``: model id → parsed caps for the process lifetime; ``*_failed_at``: monotonic time
  502. # of the last failed fetch (60s re-fetch suppression); the flags are once-per-process guards.
  503. _openrouter_reasoning_caps_cache: dict[str, Optional[dict[str, Any]]] | None = None
  504. _openrouter_reasoning_caps_failed_at: float | None = None
  505. _openrouter_caps_disk_checked = False
  506. _openrouter_caps_warm_started = False
  507. _nous_reasoning_caps_cache: dict[str, Optional[dict[str, Any]]] | None = None
  508. _nous_reasoning_caps_failed_at: float | None = None
  509. _nous_caps_disk_checked = False
  510. _nous_caps_warm_started = False
  511. from agent.reasoning_effort import CODEX_ASTRA_EFFORTS, clamp_effort as _clamp_effort, is_astra_model
  512. def clamp_reasoning_effort_to_supported(
  513. effort: Optional[str], supported_efforts: Optional[list[str]]) -> Optional[str]:
  514. """Thin wrapper over :func:`agent.reasoning_effort.clamp_effort`: keep a supported level verbatim,
  515. else the nearest WEAKER supported level (never silently escalate cost), else the weakest; unknown
  516. supported-sets and bespoke level names pass through unchanged."""
  517. return _clamp_effort(effort, supported_efforts)
  518. def _fetch_live_catalog_index(url: str, timeout: float, opener) -> Optional[tuple[list, dict[str, dict[str, Any]]]]:
  519. """GET an OpenAI-style ``/models`` listing → ``(raw data array, {id: item})``, or None when the
  520. endpoint is unreachable or the payload has no ``data`` list."""
  521. try:
  522. payload = _get_json(url, timeout=timeout, headers={"Accept": "application/json"}, opener=opener)
  523. except Exception:
  524. return None
  525. live_items = payload.get("data", [])
  526. if not isinstance(live_items, list):
  527. return None
  528. live_by_id = {
  529. mid: item for item in live_items if isinstance(item, dict) and (mid := str(item.get("id") or "").strip())
  530. }
  531. return live_items, live_by_id
  532. def fetch_openrouter_models(
  533. timeout: float = 8.0, *, force_refresh: bool = False, cache_only: bool = False) -> list[tuple[str, str]]:
  534. """Return the curated OpenRouter picker list, refreshed from the live catalog when possible.
  535. ``cache_only`` never opens a socket: memory, then disk (stale accepted), then the in-repo snapshot."""
  536. # The curated list is filtered from this profile's manifest (``model_catalog.*`` config, its
  537. # ``<home>/cache`` copy), so a routed profile keeps its own slot instead of the module one.
  538. from hermes_cli.models_profile_cache import profile_slot_get, profile_slot_set
  539. _me = sys.modules[__name__]
  540. cached = profile_slot_get(_me, "_openrouter_catalog_cache")
  541. if cached is not None and not force_refresh:
  542. return list(cached)
  543. # Cold process: serve from the persisted disk cache when fresh so the
  544. # picker doesn't re-download the full ~686KB catalog on every open.
  545. if not force_refresh:
  546. disk = _read_openrouter_catalog_disk(allow_stale=cache_only)
  547. if disk:
  548. if not cache_only: # a stale copy is served, never memoized as fresh
  549. profile_slot_set(_me, "_openrouter_catalog_cache", disk)
  550. return list(disk)
  551. if cache_only:
  552. return list(OPENROUTER_MODELS)
  553. # Remote catalog manifest first, in-repo snapshot when unreachable; the live /v1/models filter
  554. # (tool support, free pricing) is applied on top either way.
  555. try:
  556. from hermes_cli.model_catalog import get_curated_openrouter_models
  557. remote = get_curated_openrouter_models()
  558. except Exception:
  559. remote = None
  560. fallback = list(remote) if remote else list(OPENROUTER_MODELS)
  561. live = _fetch_live_catalog_index(_OPENROUTER_CATALOG_URL, timeout, _urlopen_model_catalog_request)
  562. if live is None:
  563. return list(cached or fallback)
  564. live_items, live_by_id = live
  565. # Free warm-up for the reasoning-capability cache: same payload the caps fetch would pull.
  566. global _openrouter_reasoning_caps_cache
  567. seeded = _seed_reasoning_caps(_OPENROUTER_CATALOG_URL, live_items)
  568. if _openrouter_reasoning_caps_cache is None and seeded is not None:
  569. _openrouter_reasoning_caps_cache = seeded
  570. curated: list[tuple[str, str]] = []
  571. silent_default = get_preferred_silent_default_model("openrouter")
  572. for preferred_id, _ in fallback:
  573. live_item = live_by_id.get(preferred_id)
  574. # Hide models without tool-calling support — selecting one fails at the first tool call.
  575. if live_item is None or not _openrouter_model_supports_tools(live_item):
  576. continue
  577. # Hide models that don't advertise tool-calling support — hermes-agent requires it and surfacing
  578. # them leads to immediate runtime failures when the user selects them. Ported from
  579. # Kilo-Org/kilocode#9068.
  580. if preferred_id == silent_default:
  581. desc = "default" # keep the silent-default badge through the live refresh
  582. else:
  583. desc = "free" if _openrouter_model_is_free(live_item.get("pricing")) else ""
  584. curated.append((preferred_id, desc))
  585. if not curated:
  586. return list(cached or fallback)
  587. if not curated[0][1]:
  588. curated[0] = (curated[0][0], "recommended")
  589. profile_slot_set(_me, "_openrouter_catalog_cache", curated)
  590. _write_openrouter_catalog_disk(curated)
  591. return list(curated)
  592. def model_ids(*, force_refresh: bool = False) -> list[str]:
  593. """Return just the OpenRouter model-id strings."""
  594. return [mid for mid, _ in fetch_openrouter_models(force_refresh=force_refresh)]
  595. def get_curated_nous_model_ids() -> list[str]:
  596. """Curated Nous Portal model ids: the remote catalog manifest, else the in-repo
  597. ``_PROVIDER_MODELS["nous"]`` snapshot. Always a list."""
  598. try:
  599. from hermes_cli.model_catalog import get_curated_nous_models
  600. remote = get_curated_nous_models()
  601. except Exception:
  602. remote = None
  603. return list(remote or _PROVIDER_MODELS.get("nous", []))
  604. def _ai_gateway_model_is_free(pricing: Any) -> bool:
  605. return _zero_priced(pricing, ("input", "output"), "0")
  606. def fetch_ai_gateway_models(
  607. timeout: float = 8.0, *, force_refresh: bool = False) -> list[tuple[str, str]]:
  608. """Return the curated AI Gateway picker list, refreshed from the live catalog when possible."""
  609. global _ai_gateway_catalog_cache
  610. if _ai_gateway_catalog_cache is not None and not force_refresh:
  611. return list(_ai_gateway_catalog_cache)
  612. from hermes_constants import AI_GATEWAY_BASE_URL
  613. fallback = list(VERCEL_AI_GATEWAY_MODELS)
  614. live = _fetch_live_catalog_index(f"{AI_GATEWAY_BASE_URL.rstrip('/')}/models", timeout, _urlopen_model_catalog_request)
  615. if live is None:
  616. return list(_ai_gateway_catalog_cache or fallback)
  617. _, live_by_id = live
  618. curated = [
  619. (pid, "free" if _ai_gateway_model_is_free(live_by_id[pid].get("pricing")) else "")
  620. for pid, _ in fallback if pid in live_by_id]
  621. if not curated:
  622. return list(_ai_gateway_catalog_cache or fallback)
  623. # A free Moonshot model in the live catalog is auto-promoted to #1 as "recommended".
  624. free_moonshot = next(
  625. (mid for mid, item in live_by_id.items()
  626. if mid.startswith("moonshotai/") and _ai_gateway_model_is_free(item.get("pricing"))),
  627. None)
  628. if free_moonshot:
  629. curated = [(free_moonshot, "recommended")] + [(mid, desc) for mid, desc in curated if mid != free_moonshot]
  630. else:
  631. curated[0] = (curated[0][0], "recommended")
  632. _ai_gateway_catalog_cache = curated
  633. return list(curated)
  634. def ai_gateway_model_ids(*, force_refresh: bool = False) -> list[str]:
  635. """Return just the AI Gateway model-id strings."""
  636. return [mid for mid, _ in fetch_ai_gateway_models(force_refresh=force_refresh)]
  637. # ---------------------------------------------------------------------------
  638. # Provider identity: ``provider:model`` parsing, auto-detection, labels
  639. # ---------------------------------------------------------------------------
  640. # All provider IDs and aliases valid on the left of the ``provider:model`` syntax.
  641. _KNOWN_PROVIDER_NAMES: set[str] = set(_PROVIDER_LABELS) | set(_PROVIDER_ALIASES) | {"openrouter", "custom"}
  642. _CONFIG_ERRORS = (ImportError, OSError, RuntimeError, TypeError, ValueError, AttributeError)
  643. def _configured_custom_provider_ids() -> set[str]:
  644. """Return routable custom-provider IDs configured by the user."""
  645. ids = {"custom"}
  646. try:
  647. from hermes_cli.config import load_config
  648. from hermes_cli.providers import custom_provider_slug
  649. config = load_config()
  650. providers = config.get("providers", {})
  651. if isinstance(providers, dict):
  652. ids.update(custom_provider_slug(str(entry.get("name") or key), str(key))
  653. for key, entry in providers.items() if isinstance(entry, dict))
  654. legacy = config.get("custom_providers", [])
  655. if isinstance(legacy, list):
  656. ids.update(
  657. custom_provider_slug(str(entry.get("name") or "")) for entry in legacy if isinstance(entry, dict))
  658. except _CONFIG_ERRORS:
  659. pass
  660. return ids
  661. def _provider_has_credentials(pid: str) -> bool:
  662. try:
  663. from hermes_cli.auth import get_auth_status, has_usable_secret
  664. if pid == "custom":
  665. return bool((_get_custom_base_url() or "").strip())
  666. if pid == "openrouter":
  667. from hermes_cli.model_switch import _scoped_key_env
  668. return has_usable_secret(_scoped_key_env("OPENROUTER_API_KEY"))
  669. status = get_auth_status(pid)
  670. return bool(status.get("logged_in") or status.get("configured"))
  671. except Exception:
  672. return False
  673. def list_available_providers() -> list[dict[str, str]]:
  674. """``{id, label, aliases, authenticated}`` per listed provider (shared with ``hermes model`` / ``/model``)."""
  675. from hermes_cli.models_catalog_static import listed_canonical_providers
  676. aliases_for: dict[str, list[str]] = {}
  677. for alias, canonical in _PROVIDER_ALIASES.items():
  678. aliases_for.setdefault(canonical, []).append(alias)
  679. return [
  680. {
  681. "id": pid,
  682. "label": _PROVIDER_LABELS.get(pid, pid),
  683. "aliases": aliases_for.get(pid, []),
  684. "authenticated": _provider_has_credentials(pid)}
  685. for pid in [p.slug for p in listed_canonical_providers()] + ["custom"]]
  686. def parse_model_input(
  687. raw: str, current_provider: str, *, custom_ids: Optional[set[str]] = None) -> tuple[str, str]:
  688. """Parse ``/model`` input into ``(provider, model)``. The colon is a provider delimiter only when
  689. the left side is a known provider/alias, so ``anthropic/claude-3.5-sonnet:beta`` stays a model.
  690. ``custom_ids`` is the caller's already-loaded set of configured ``custom:<name>`` ids (default:
  691. read from config) so one decision never consults two config sources."""
  692. stripped = raw.strip()
  693. colon = stripped.find(":")
  694. if colon > 0:
  695. provider_part = stripped[:colon].strip().lower()
  696. model_part = stripped[colon + 1:].strip()
  697. if provider_part and model_part and provider_part in _KNOWN_PROVIDER_NAMES:
  698. if provider_part == "custom":
  699. configured = _configured_custom_provider_ids() if custom_ids is None else custom_ids
  700. # Longest configured ``custom:<name>`` id that prefixes the input wins.
  701. lowered = stripped.lower()
  702. for custom_id in sorted(configured - {"custom"}, key=len, reverse=True):
  703. if lowered.startswith(f"{custom_id.lower()}:"):
  704. return custom_id, stripped[len(custom_id) + 1 :].strip()
  705. # ``custom:local:qwen`` → ("custom:local", "qwen") for a configured named provider;
  706. # single-colon ``custom:qwen`` → ("custom", "qwen") as before.
  707. if ":" in model_part:
  708. custom_name, actual_model = (part.strip() for part in model_part.split(":", 1))
  709. if custom_name and actual_model:
  710. if f"custom:{custom_name.lower()}" in configured:
  711. return (f"custom:{custom_name.lower()}", actual_model)
  712. return ("custom", model_part)
  713. return (normalize_provider(provider_part), model_part)
  714. return (current_provider, stripped)
  715. def _get_custom_base_url() -> str:
  716. """The custom endpoint ``model.base_url`` from config.yaml."""
  717. return str(_get_model_config_dict().get("base_url", "")).strip()
  718. def _get_provider_config_dict(provider: str) -> dict[str, Any]:
  719. """Return config.yaml providers.<provider>, or an empty dict."""
  720. key = str(provider or "").strip()
  721. if not key:
  722. return {}
  723. try:
  724. from hermes_cli.config import load_config
  725. providers_cfg = load_config().get("providers", {})
  726. if isinstance(providers_cfg, dict):
  727. entry = providers_cfg.get(key) or providers_cfg.get(key.lower())
  728. if isinstance(entry, dict):
  729. return entry
  730. except _CONFIG_ERRORS:
  731. pass
  732. return {}
  733. def _get_model_config_dict() -> dict[str, Any]:
  734. """Return the main model config mapping, or an empty dict."""
  735. try:
  736. from hermes_cli.config import load_config
  737. model_cfg = load_config().get("model", {})
  738. if isinstance(model_cfg, dict):
  739. return model_cfg
  740. except Exception:
  741. pass
  742. return {}
  743. def _base_url_looks_like_anthropic_messages(base_url: str) -> bool:
  744. normalized = str(base_url or "").strip().lower().rstrip("/")
  745. if not normalized:
  746. return False
  747. return urllib.parse.urlparse(normalized).path.rstrip("/").endswith(("/anthropic", "/anthropic/v1"))
  748. def _anthropic_models_url(base_url: Optional[str] = None, *, after_id: Optional[str] = None) -> str:
  749. """Anthropic ``/v1/models`` page URL. The endpoint is cursor-paginated with a default page of
  750. 20 (smaller than the live catalog), so every request asks for the maximum page size and
  751. ``after_id`` continues from a previous page's ``last_id``."""
  752. endpoint = str(base_url or "https://api.anthropic.com").strip().rstrip("/")
  753. url = endpoint + ("/models" if endpoint.endswith("/v1") else "/v1/models")
  754. params = {"limit": "1000"}
  755. if after_id:
  756. params["after_id"] = after_id
  757. return url + ("&" if "?" in url else "?") + urllib.parse.urlencode(params)
  758. _ANTHROPIC_MODELS_MAX_PAGES = 20
  759. def _anthropic_next_cursor(page: Any, seen_cursors: set[str]) -> Optional[str]:
  760. """``last_id`` to continue from, or None when the page is final or the server repeats a
  761. cursor (which would otherwise loop forever)."""
  762. if not isinstance(page, dict) or page.get("has_more") is not True:
  763. return None
  764. last_id = page.get("last_id")
  765. if not isinstance(last_id, str) or not last_id or last_id in seen_cursors:
  766. return None
  767. seen_cursors.add(last_id)
  768. return last_id
  769. def curated_models_for_provider(
  770. provider: Optional[str],
  771. *,
  772. force_refresh: bool = False,
  773. ) -> list[tuple[str, str]]:
  774. """Return ``(model_id, description)`` tuples for a provider's model list.
  775. Tries to fetch the live model list from the provider's API first,
  776. falling back to the static ``_PROVIDER_MODELS`` catalog if the API
  777. is unreachable.
  778. """
  779. normalized = normalize_provider(provider)
  780. if normalized == "openrouter":
  781. return fetch_openrouter_models(force_refresh=force_refresh)
  782. # Try live API first (Codex, Nous, etc. all support /models)
  783. live = provider_model_ids(normalized)
  784. if live:
  785. # StepFun's Step Plan /models merge now lives in its provider fetcher
  786. # (``_stepfun_catalog``) so every picker surface sees the same list.
  787. return [(m, "") for m in live]
  788. # Fallback to static catalog
  789. models = static_catalog(normalized)
  790. return [(m, "") for m in models]
  791. def _provider_keys(provider: str) -> set[str]:
  792. key = (provider or "").strip().lower()
  793. normalized = normalize_provider(provider)
  794. return {k for k in (key, normalized) if k}
  795. def _provider_catalog_names(provider: str) -> tuple[str, ...]:
  796. """Active picker models plus retired aliases recognized for detection."""
  797. return tuple(static_catalog(provider)) + _PROVIDER_RETIRED_ALIASES.get(provider, ())
  798. def _model_in_provider_catalog(name_lower: str, providers: set[str]) -> bool:
  799. return any(
  800. name_lower == model.lower()
  801. for provider in providers
  802. for model in _provider_catalog_names(provider))
  803. def _resolve_static_model_alias(
  804. name_lower: str, current_keys: set[str]) -> Optional[tuple[str, str]]:
  805. """Resolve short aliases (e.g. sonnet/opus) using static catalogs only."""
  806. try:
  807. from hermes_cli.model_switch import MODEL_ALIASES
  808. except Exception:
  809. return None
  810. identity = MODEL_ALIASES.get(name_lower)
  811. if identity is None:
  812. return None
  813. def _match(provider: str) -> Optional[str]:
  814. prefix = f"{identity.vendor}/{identity.family}" if provider in _AGGREGATOR_PROVIDERS else identity.family
  815. prefix = prefix.lower()
  816. return next((m for m in static_catalog(provider) if m.lower().startswith(prefix)), None)
  817. # Current provider first, then native vendors, then aggregators / borrow-list providers the user
  818. # is already on — so `sonnet` resolves to anthropic before any re-exposing provider.
  819. skip = current_keys | _AGGREGATOR_PROVIDERS | _BORROWED_MODEL_PROVIDERS
  820. candidates = [
  821. *current_keys, *(p for p in static_catalog_providers() if p not in skip),
  822. *(p for p in _AGGREGATOR_PROVIDERS if p in current_keys),
  823. *(p for p in _BORROWED_MODEL_PROVIDERS if p in current_keys)]
  824. for provider in candidates:
  825. if matched := _match(provider):
  826. return provider, matched
  827. return None
  828. def detect_static_provider_for_model(
  829. model_name: str, current_provider: str) -> Optional[tuple[str, str]]:
  830. """Auto-detect a provider from static catalogs only → ``(provider_id, model_name)`` (the name may
  831. be remapped by a static alias or a bare provider name), or ``None`` without a confident match."""
  832. name = (model_name or "").strip()
  833. if not name:
  834. return None
  835. name_lower = name.lower()
  836. current_keys = _provider_keys(current_provider)
  837. alias_match = _resolve_static_model_alias(name_lower, current_keys)
  838. if alias_match:
  839. return alias_match
  840. # Step 0: a bare provider name typed as the model (`/model nous`) is a provider switch to that
  841. # provider's default. Skip "custom" (no catalog) and "openrouter" (needs an explicit model).
  842. resolved_provider = _PROVIDER_ALIASES.get(name_lower, name_lower)
  843. if resolved_provider not in {"custom", "openrouter"}:
  844. default_models = static_catalog(resolved_provider)
  845. if resolved_provider in _PROVIDER_LABELS and default_models and resolved_provider not in current_keys:
  846. # Cost-safe default, not ``default_models[0]``: metered aggregators list most-capable-first,
  847. # so [0] would silently escalate `/model nous` to the priciest flagship.
  848. return (resolved_provider, get_default_model_for_provider(resolved_provider) or default_models[0])
  849. # A model in the current provider's own catalog never suggests switching.
  850. if _model_in_provider_catalog(name_lower, current_keys):
  851. return None
  852. return next(_static_catalog_matches(name, current_provider), None)
  853. def _static_catalog_matches(name: str, current_provider: str):
  854. """Yield every ``(provider_id, name)`` whose static catalog lists *name*, in ladder order.
  855. Several first-party providers list the same slug (``gpt-5.6-luna`` on ``openai-api`` AND
  856. ``openai-codex``); the first is only a guess, so callers that gate on credentials need the
  857. siblings too (#102775)."""
  858. name_lower = name.lower()
  859. current_keys = _provider_keys(current_provider)
  860. # Step 1: direct static-catalog match. Aggregators list other vendors' models — never
  861. # auto-switch TO them. A custom endpoint (custom / custom:*) is never auto-switched away
  862. # from: the user configured it deliberately and may serve the same model name there.
  863. if current_provider != "custom" and not current_provider.startswith("custom:"):
  864. for pid in static_catalog_providers():
  865. if pid in current_keys or pid in _AGGREGATOR_PROVIDERS or pid in _BORROWED_MODEL_PROVIDERS:
  866. continue
  867. if _model_in_provider_catalog(name_lower, {pid}):
  868. yield (pid, name)
  869. # Borrow-list providers (re-expose other vendors' models) only after every native-vendor
  870. # catalog, and only when one is the current provider.
  871. for pid in _BORROWED_MODEL_PROVIDERS:
  872. if pid not in current_keys and _model_in_provider_catalog(name_lower, {pid}):
  873. yield (pid, name)
  874. def _configured_provider_ids() -> set[str]:
  875. """Provider ids (incl. ``custom:*``) from the user's ``providers:`` config block; empty when config
  876. is unreadable (callers fall through to built-in catalogs)."""
  877. try:
  878. from hermes_cli.config import load_config
  879. providers = (load_config() or {}).get("providers")
  880. if not isinstance(providers, dict):
  881. return set()
  882. return {key for pid in providers if (key := str(pid).strip().lower())}
  883. except Exception:
  884. return set()
  885. def _resolve_provider_prefix(model_name: str) -> Optional[tuple[str, str]]:
  886. """Route an explicit ``vendor/model`` prefix (``nous/deepseek-v4-pro``, ``ollama/qwen3.5:4b``) to
  887. a provider the user defined in ``providers:`` (by raw name or alias) instead of the default.
  888. ``nous/deepseek-v4-pro`` or ``ollama/qwen3.5:4b`` should route to the named provider instead of falling
  889. back to the configured default (which silently sends non-default models to the wrong endpoint, #87189).
  890. """
  891. if "/" not in model_name:
  892. return None
  893. vendor, model = model_name.split("/", 1)
  894. vendor, model = vendor.strip().lower(), model.strip()
  895. if not vendor or not model:
  896. return None
  897. configured = _configured_provider_ids()
  898. # An explicitly named provider block (``ollama:``) wins over the alias table, which may
  899. # canonicalize the same name elsewhere (``ollama`` → ``custom``).
  900. for candidate in (vendor, _PROVIDER_ALIASES.get(vendor, vendor)):
  901. if candidate in configured:
  902. return (candidate, model)
  903. return None
  904. def detect_provider_for_model(
  905. model_name: str, current_provider: str) -> Optional[tuple[str, str]]:
  906. """Auto-detect the best provider for a model name: the current provider's live catalog, static
  907. catalogs (bare provider name → its default; direct catalog match), then the OpenRouter catalog,
  908. then a configured ``vendor/`` prefix.
  909. Never hands back a provider the user holds no credentials for: an unauthenticated guess is
  910. skipped and the ladder continues (``None`` = stay on the current provider). Exceptions: the user
  911. NAMED the provider (``/model nous``), or there is no current provider yet (``auto``) — then the
  912. first guess is returned so the credential step fails loudly instead of silently ignoring input."""
  913. from hermes_cli.models_detect import (
  914. current_provider_catalog_match, current_provider_owns_vendor, provider_has_credentials)
  915. name = (model_name or "").strip()
  916. if not name:
  917. return None
  918. # The current provider's LIVE catalog outranks every static guess: a model it already serves
  919. # (Codex early-access ids, Portal-only slugs, Ollama Cloud models absent from _PROVIDER_MODELS)
  920. # must never re-route the session to another vendor or to metered OpenRouter.
  921. served = current_provider_catalog_match(name, current_provider)
  922. if served is not None:
  923. return (current_provider, served) if served != name else None
  924. # Live catalog unavailable or lagging: the vendor's own id on the vendor's first-party provider
  925. # is still a selection — an aggregator relisting it is not grounds to switch.
  926. if current_provider_owns_vendor(name, current_provider):
  927. return None
  928. no_selection = (current_provider or "").strip().lower() in {"", "auto"}
  929. first_guess = None
  930. for candidate in _detection_candidates(name, current_provider):
  931. if candidate is None:
  932. return None # the current catalog owns this name
  933. if candidate[0] == current_provider or provider_has_credentials(candidate[0]):
  934. return candidate
  935. if _PROVIDER_ALIASES.get(name.lower(), name.lower()) == candidate[0]:
  936. return candidate # explicitly named provider: let the credential step report it
  937. first_guess = first_guess or candidate
  938. logger.debug("Skipping auto-switch of '%s' to %s: no credentials configured", name, candidate[0])
  939. if no_selection and first_guess:
  940. return first_guess # nothing usable anywhere: fail loudly on the first guess
  941. # A ``vendor/model`` prefix naming a provider the user DECLARED in ``providers:`` is a selection,
  942. # not a guess — hand it back even before its key is wired up.
  943. return _resolve_provider_prefix(name)
  944. def _detection_candidates(name: str, current_provider: str):
  945. """Yield ``(provider, model)`` guesses in ladder order; ``None`` means the current provider's own
  946. catalog owns the name (stop, stay)."""
  947. static_match = detect_static_provider_for_model(name, current_provider)
  948. if static_match:
  949. yield static_match
  950. # Sibling catalogs listing the same slug (openai-api / openai-codex share the gpt-5.6
  951. # family): the credential gate downstream takes the first one the user can actually use.
  952. for sibling in _static_catalog_matches(name, current_provider):
  953. if sibling != static_match:
  954. yield sibling
  955. if _model_in_provider_catalog(name.lower(), _provider_keys(current_provider)):
  956. yield None
  957. return
  958. # OpenRouter catalog (exact slug, then bare model part).
  959. or_slug = _find_openrouter_slug(name)
  960. if or_slug:
  961. if current_provider == "openrouter" and or_slug == name:
  962. yield None # already on openrouter with matching name
  963. return
  964. yield ("openrouter", or_slug)
  965. # Explicit ``vendor/model`` prefix naming a configured provider — AFTER the OpenRouter lookup so
  966. # aggregator-native slugs (``deepseek/deepseek-chat``) keep their routing.
  967. prefixed = _resolve_provider_prefix(name)
  968. if prefixed:
  969. yield prefixed
  970. def _find_openrouter_slug(model_name: str) -> Optional[str]:
  971. """Full OpenRouter slug for a bare or partial model name (exact slug first, then bare part)."""
  972. name_lower = model_name.strip().lower()
  973. if not name_lower:
  974. return None
  975. ids = model_ids()
  976. return (
  977. next((mid for mid in ids if name_lower == mid.lower()), None)
  978. or next((mid for mid in ids if "/" in mid and name_lower == mid.split("/", 1)[1].lower()), None)
  979. )
  980. def normalize_provider(provider: Optional[str]) -> str:
  981. """Normalize provider aliases to canonical ids. ``"auto"`` passes through — use
  982. ``hermes_cli.auth.resolve_provider()`` to resolve it from credentials."""
  983. normalized = (provider or "openrouter").strip().lower()
  984. return _PROVIDER_ALIASES.get(normalized, normalized)
  985. def provider_label(provider: Optional[str]) -> str:
  986. """Return a human-friendly label for a provider id or alias."""
  987. original = (provider or "openrouter").strip()
  988. normalized = original.lower()
  989. if normalized == "auto":
  990. return "Auto"
  991. normalized = normalize_provider(normalized)
  992. return _PROVIDER_LABELS.get(normalized, original or "OpenRouter")
  993. def _is_openai_fast_model(model_id: Optional[str]) -> bool:
  994. """OpenAI flagship eligible for Priority Processing. Codex-series excluded — the Codex Responses
  995. API doesn't accept ``service_tier``."""
  996. base = _strip_vendor_prefix(str(model_id or "")).split(":")[0]
  997. return bool(base) and "codex" not in base and base.startswith(tuple(_OPENAI_FAST_MODE_PREFIXES))
  998. def _strip_vendor_prefix(model_id: str) -> str:
  999. """Lowercase and strip a ``vendor/`` prefix (``anthropic/claude-opus-4-6`` → ``claude-opus-4-6``)."""
  1000. raw = str(model_id or "").strip().lower()
  1001. return raw.split("/", 1)[1] if "/" in raw else raw
  1002. def model_supports_fast_mode(model_id: Optional[str]) -> bool:
  1003. """Return whether Hermes should expose the /fast toggle for this model."""
  1004. from agent.model_metadata import is_grok_46_family
  1005. return (
  1006. _is_anthropic_fast_model(model_id)
  1007. or _is_openai_fast_model(model_id)
  1008. or is_grok_46_family(str(model_id or "")))
  1009. def _is_anthropic_fast_model(model_id: Optional[str]) -> bool:
  1010. """Accepts the Anthropic Fast Mode ``speed`` param (Opus 4.8 / Opus 5 / Opus 5.5 only) —
  1011. deliberately NOT a general "fast model" check. The list lives in ``agent.model_metadata``."""
  1012. from agent.model_metadata import is_anthropic_fast_mode_model
  1013. return is_anthropic_fast_mode_model(model_id)
  1014. def _fast_mode_route_supported(
  1015. model_id: Optional[str], provider: Optional[str], base_url: Optional[str]) -> bool:
  1016. """Only the first-party endpoint that bills for fast mode may receive its params."""
  1017. from urllib.parse import urlparse
  1018. from agent.model_metadata import is_grok_46_family
  1019. if _is_anthropic_fast_model(model_id):
  1020. allowed = {"anthropic": "api.anthropic.com"}
  1021. elif is_grok_46_family(str(model_id or "")):
  1022. allowed = {"xai": "api.x.ai"}
  1023. else:
  1024. allowed = {
  1025. "openai": "api.openai.com",
  1026. "openai-api": "api.openai.com",
  1027. "openai-codex": "chatgpt.com",
  1028. }
  1029. if provider and normalize_provider(provider) not in allowed:
  1030. return False
  1031. host = (urlparse(str(base_url or "")).hostname or "").lower()
  1032. return not host or host in allowed.values()
  1033. def model_supports_ultrafast(model_id: Optional[str]) -> bool:
  1034. """OpenAI Ultrafast (``service_tier: "ultrafast"``) is published per model, not per family."""
  1035. from agent.model_metadata import strip_codex_context_variant_suffix
  1036. base = _strip_vendor_prefix(strip_codex_context_variant_suffix(str(model_id or ""))).split(":")[0]
  1037. return base in _OPENAI_ULTRAFAST_MODELS
  1038. def resolve_fast_mode_overrides(
  1039. model_id: Optional[str], *, provider: Optional[str] = None, base_url: Optional[str] = None,
  1040. tier: Optional[str] = None,
  1041. ) -> dict[str, Any] | None:
  1042. """Fast/priority request_overrides — ``{"speed": "fast"}`` (Anthropic Fast Mode) or
  1043. ``{"service_tier": "priority"}`` (OpenAI / xAI Priority Processing) — or None if unsupported.
  1044. ``tier="ultrafast"`` asks for OpenAI Ultrafast instead: ``{"service_tier": "ultrafast"}`` on an
  1045. Ultrafast model, None elsewhere (never a silent downgrade to a different paid tier).
  1046. With ``provider``/``base_url`` the route is gated too (``_fast_mode_route_supported``) so proxies
  1047. never see the params. Single fast-mode gate for ``/fast`` and ``agent.fast_mode`` windows."""
  1048. if not model_supports_fast_mode(model_id):
  1049. return None
  1050. if (provider or base_url) and not _fast_mode_route_supported(model_id, provider, base_url):
  1051. return None
  1052. if tier == "ultrafast":
  1053. return {"service_tier": "ultrafast"} if model_supports_ultrafast(model_id) else None
  1054. return {"speed": "fast"} if _is_anthropic_fast_model(model_id) else {"service_tier": "priority"}
  1055. def _model_dedup_key(model_id: str) -> str:
  1056. """Case-insensitive dedup key folded through the picker-search alias table, so a bare live wire
  1057. id and its curated public slug (Kimi ``k3`` / ``kimi-k3``) don't both survive a merge."""
  1058. key = str(model_id).strip().lower()
  1059. try:
  1060. from hermes_cli.model_search import model_alias_canonical
  1061. return model_alias_canonical(key)
  1062. except Exception:
  1063. return key
  1064. def _merge_with_models_dev(provider: str, curated: list[str]) -> list[str]:
  1065. """models.dev entries first (their order), then curated-only extras, case-insensitively deduped
  1066. while preserving curated casing. Curated unchanged when models.dev is unreachable/empty."""
  1067. try:
  1068. from agent.models_dev import list_agentic_models
  1069. mdev = list_agentic_models(provider)
  1070. except Exception:
  1071. mdev = []
  1072. if not mdev:
  1073. return list(curated)
  1074. return _merge_unique(_merge_unique([], mdev), curated)
  1075. def _openai_discovery_base_url(provider: str) -> str:
  1076. """OpenAI endpoint for model discovery, mirroring runtime precedence so discovery probes the SAME
  1077. endpoint inference uses: ``$OPENAI_BASE_URL`` → config ``model.base_url`` (when the configured
  1078. provider matches) → the canonical default."""
  1079. env_raw = os.getenv("OPENAI_BASE_URL", "").strip().rstrip("/")
  1080. if env_raw:
  1081. return env_raw
  1082. try:
  1083. model_cfg = _get_model_config_dict()
  1084. cfg_provider = str(model_cfg.get("provider") or "").strip().lower()
  1085. same_provider = normalize_provider(provider) == normalize_provider(cfg_provider)
  1086. if cfg_provider in ("openai", "openai-api") and same_provider:
  1087. cfg_url = str(model_cfg.get("base_url") or "").strip().rstrip("/")
  1088. if cfg_url:
  1089. return cfg_url
  1090. except Exception:
  1091. pass
  1092. return "https://api.openai.com/v1"
  1093. def _codex_catalog(normalized: str, force_refresh: bool) -> list[str]:
  1094. from hermes_cli.codex_models import get_codex_model_ids
  1095. # Live OAuth token so the picker matches what ChatGPT lists for this account; hardcoded
  1096. # catalog without a token / when unreachable. Read-only (#68004): a picker never imports,
  1097. # refreshes or persists a credential, so an expired stored token means the hardcoded catalog
  1098. # until the runtime lease refreshes it.
  1099. # The token and the host it is routed to come from the same resolution (#121486): a pooled
  1100. # gateway key is only ever sent to that gateway, never to the chatgpt.com default.
  1101. base_url = None
  1102. try:
  1103. from hermes_cli.auth import _codex_access_token_is_expiring, resolve_codex_runtime_credentials
  1104. creds = resolve_codex_runtime_credentials(read_only=True)
  1105. access_token, base_url = creds.get("api_key"), creds.get("base_url")
  1106. if _codex_access_token_is_expiring(access_token, 0):
  1107. access_token = None
  1108. except Exception:
  1109. access_token = None
  1110. return get_codex_model_ids(access_token=access_token, base_url=base_url)
  1111. def _nous_catalog(normalized: str, force_refresh: bool) -> Optional[list[str]]:
  1112. try:
  1113. from hermes_cli.anon_challenge import background_caller
  1114. from hermes_cli.auth import fetch_nous_models, resolve_nous_runtime_credentials
  1115. with background_caller(): # never waits on or opens a challenge
  1116. creds = resolve_nous_runtime_credentials()
  1117. if creds:
  1118. live = fetch_nous_models(api_key=creds.get("api_key", ""), inference_base_url=creds.get("base_url", ""))
  1119. if live:
  1120. return live
  1121. except Exception:
  1122. pass
  1123. # Live failed / no creds: the docs-hosted manifest, so new Portal models surface without a release.
  1124. return get_curated_nous_model_ids() or None
  1125. def _api_key_credentials(normalized: str) -> tuple[str, str]:
  1126. """``(api_key, base_url)`` from ``resolve_api_key_provider_credentials``; empty strings on any miss."""
  1127. try:
  1128. from hermes_cli.auth import resolve_api_key_provider_credentials
  1129. creds = resolve_api_key_provider_credentials(normalized)
  1130. return str(creds.get("api_key") or "").strip(), str(creds.get("base_url") or "").strip()
  1131. except Exception:
  1132. return "", ""
  1133. def _api_key_provider_live(normalized: str, force_refresh: bool) -> Optional[list[str]]:
  1134. """Live /v1/models for a simple api-key provider (stepfun, gmi); None on any miss."""
  1135. api_key, base_url = _api_key_credentials(normalized)
  1136. if not (api_key and base_url):
  1137. return None
  1138. try:
  1139. return fetch_api_models(api_key, base_url) or None
  1140. except Exception:
  1141. return None
  1142. def _stepfun_catalog(normalized: str, force_refresh: bool) -> Optional[list[str]]:
  1143. """Step Plan live list merged with the curated catalog (the ``_anthropic_catalog`` pattern).
  1144. The StepFun inference endpoint is the Step Plan API, whose ``/models`` returns a subset of
  1145. the full catalog: it omits models served by the Standard API (e.g. ``step-3.7-flash``),
  1146. so a healthy live response would shadow curated-only models from every picker surface
  1147. (#41147). Live rows first, then curated-only additions — and when the probe declines
  1148. (no credentials / failure) ``None`` falls through to the generic profile path, whose
  1149. ``merge_profile_catalog`` already serves the curated floor as a placeholder.
  1150. """
  1151. live = _api_key_provider_live(normalized, force_refresh)
  1152. if not live:
  1153. return live
  1154. curated = list(static_catalog(normalized))
  1155. return _merge_unique(live, curated, key=_model_dedup_key) if curated else live
  1156. def _anthropic_catalog(normalized: str, force_refresh: bool) -> list[str]:
  1157. model_cfg = _get_model_config_dict()
  1158. cfg_base_url = cfg_api_key = ""
  1159. if normalize_provider(str(model_cfg.get("provider", "") or "")) == "anthropic":
  1160. cfg_base_url = str(model_cfg.get("base_url", "") or "").strip()
  1161. cfg_api_key = str(model_cfg.get("api_key", "") or "").strip()
  1162. live = _fetch_anthropic_models(base_url=cfg_base_url or None, api_key=cfg_api_key or None)
  1163. curated = list(_PROVIDER_MODELS.get("anthropic", []))
  1164. if not live:
  1165. # A placeholder for the outage, not this account/proxy's catalog: the disk cache must
  1166. # never pin it over a same-credentials live row (#107391).
  1167. return CuratedFallbackModels(curated)
  1168. # The live /v1/models dump lags newly-routed curated aliases (reachable before enumerated):
  1169. # curated first, then live-only extras, so a fresh curated model never disappears.
  1170. return live if cfg_base_url else _merge_unique(curated, live)
  1171. def _openai_catalog(normalized: str, force_refresh: bool) -> Optional[list[str]]:
  1172. api_key = os.getenv("OPENAI_API_KEY", "").strip()
  1173. if not api_key:
  1174. return None
  1175. base = _openai_discovery_base_url(normalized)
  1176. # Custom OpenAI-compatible endpoints serve a small curated catalog — use it verbatim. Official
  1177. # OpenAI hosts (canonical and data-residency regional) return 120+ embeddings/whisper/tts/…
  1178. # entries, so intersect with the curated agentic catalog so ``/model`` matches ``hermes model``.
  1179. # Model not in live /v1/models — check the curated catalog before rejecting. Providers may omit models
  1180. # from their live listing that are still valid (stale cache, partial rollout, gated previews). Use the
  1181. # pure-catalog helper (no extra live fetch) so we only accept models Hermes actually ships. (#46850)
  1182. # Their /v1/models listing is access-scoped and authoritative — a model absent from it is one this key
  1183. # CANNOT serve, so the curated soft-accept would manufacture a selection that 400s at first use. Custom
  1184. # OpenAI-compatible proxies keep the fallback (incomplete listings are common there).
  1185. from hermes_cli.providers import is_official_openai_host
  1186. try:
  1187. live = fetch_api_models(api_key, base)
  1188. except Exception:
  1189. live = None
  1190. if not live:
  1191. return None
  1192. if not is_official_openai_host(base):
  1193. return live
  1194. live_lower = {m.lower() for m in live}
  1195. curated = list(static_catalog(normalized))
  1196. # Curated order, only models the account has access to; an account serving none of them (rare)
  1197. # falls back to curated so the picker still offers sane defaults.
  1198. discovered = [m for m in curated if m.lower() in live_lower]
  1199. # Astra is intentionally absent from offline/static catalogs: the official API's
  1200. # account-scoped /models response is the only source that may advertise it.
  1201. discovered.extend(m for m in live if is_astra_model(m))
  1202. return discovered or curated or live
  1203. def _custom_catalog(normalized: str, force_refresh: bool) -> Optional[list[str]]:
  1204. base_url = _get_custom_base_url()
  1205. if not base_url:
  1206. return None
  1207. model_cfg = _get_model_config_dict()
  1208. # Try common API key env vars for custom endpoints.
  1209. api_key = (
  1210. str(model_cfg.get("api_key", "") or "").strip()
  1211. or os.getenv("CUSTOM_API_KEY", "")
  1212. or os.getenv("OPENAI_API_KEY", "")
  1213. or os.getenv("OPENROUTER_API_KEY", ""))
  1214. api_mode = "anthropic_messages" if _base_url_looks_like_anthropic_messages(base_url) else None
  1215. return fetch_api_models(api_key, base_url, api_mode=api_mode) or None
  1216. def _bedrock_catalog(normalized: str, force_refresh: bool) -> Optional[list[str]]:
  1217. # Live discovery keyed by the resolved AWS region so EU/AP users see eu.*/ap.* ids.
  1218. try:
  1219. from agent.bedrock_adapter import bedrock_model_ids_or_none
  1220. return bedrock_model_ids_or_none()
  1221. except Exception:
  1222. return None
  1223. def _azure_foundry_catalog(normalized: str, force_refresh: bool) -> Optional[list[str]]:
  1224. """Live ``GET <base>/models`` of the configured Azure Foundry resource (#27989).
  1225. Deployments are per-resource, so the static catalog is intentionally empty and the plugin
  1226. profile ships ``base_url=""`` — which is why the generic profile fetch never fires. Resolve
  1227. through the runtime resolver so the picker targets the same resource inference hits
  1228. (``model.base_url`` / ``AZURE_FOUNDRY_BASE_URL``) with the same credential: an API key string,
  1229. or the Entra ID token-provider callable that ``azure_detect`` already accepts. Anthropic-style
  1230. ``/anthropic`` routes serve no ``/models``; the probe never raises, so any miss keeps ``[]``.
  1231. """
  1232. try:
  1233. from hermes_cli.azure_detect import _probe_openai_models
  1234. from hermes_cli.runtime_provider import _resolve_azure_foundry_runtime
  1235. runtime = _resolve_azure_foundry_runtime(requested_provider=normalized, model_cfg=_get_model_config_dict())
  1236. base_url = str(runtime.get("base_url") or "").strip().rstrip("/")
  1237. credential = runtime.get("api_key")
  1238. if not (base_url and credential):
  1239. return None
  1240. ok, ids = _probe_openai_models(base_url, credential)
  1241. return ids if ok and ids else None
  1242. except Exception:
  1243. return None
  1244. # Per-provider catalog sources tried before the generic profile fetch (a profile's ``picker_catalog``
  1245. # hook fills the same slot, see ``_catalog_fetcher``). A fetcher returning None falls through to the
  1246. # profile/curated path; a list is returned as-is (even empty).
  1247. _PROVIDER_CATALOG_FETCHERS: dict[str, Any] = {
  1248. "openrouter": lambda normalized, force_refresh: model_ids(force_refresh=force_refresh),
  1249. "openai-codex": _codex_catalog,
  1250. "nous": _nous_catalog,
  1251. "stepfun": _stepfun_catalog,
  1252. "gmi": _api_key_provider_live,
  1253. "anthropic": _anthropic_catalog,
  1254. "ai-gateway": lambda normalized, force_refresh: _fetch_ai_gateway_models() or None,
  1255. # DeepInfra's generic /models mixes chat, image, video, speech and embedding models; the tagged
  1256. # catalog helper is the only safe source for the chat picker, including its empty/failure result.
  1257. "deepinfra": lambda normalized, force_refresh: _fetch_deepinfra_models(force_refresh=force_refresh) or [],
  1258. "ollama-cloud": lambda normalized, force_refresh: fetch_ollama_cloud_models(force_refresh=force_refresh) or None,
  1259. "openai": _openai_catalog,
  1260. "openai-api": _openai_catalog,
  1261. "custom": _custom_catalog,
  1262. "bedrock": _bedrock_catalog,
  1263. "azure-foundry": _azure_foundry_catalog}
  1264. # ``-free`` slugs the relay still LISTS but no longer serves: the Go-only twin (``ox-alpha-free``)
  1265. # and the promo it delisted without removing from ``/models`` (``deepseek-v4-flash-free``). The
  1266. # live-first keyed Zen/Go pickers filter through this so a stale live listing can never route
  1267. # into a 400/403 (#111749).
  1268. _OPENCODE_FREE_EXCLUDED_MODELS = frozenset(
  1269. {"ox-alpha-free", "deepseek-v4-flash-free", "x-preview-f-free"}
  1270. )
  1271. def _catalog_fetcher(normalized: str):
  1272. """The built-in fetcher for *normalized*, else its profile's ``picker_catalog`` hook, else None."""
  1273. fetcher = _PROVIDER_CATALOG_FETCHERS.get(normalized)
  1274. if fetcher is not None:
  1275. return fetcher
  1276. from providers import get_provider_profile
  1277. from providers.base import ProviderProfile
  1278. profile = get_provider_profile(normalized)
  1279. hook = profile.picker_catalog if isinstance(profile, ProviderProfile) else None
  1280. return (lambda _normalized, force_refresh: hook(force_refresh)) if hook is not None else None
  1281. def _profile_live_catalog(normalized: str) -> Optional[list[str]]:
  1282. """Generic live fetch for any provider registered in providers/ with ``auth_type="api_key"``.
  1283. Live results are merged with the curated list so models the live endpoint omits still appear:
  1284. curated-first by default so the newest curated models lead when the live API lags;
  1285. ``_LIVE_FIRST_PICKER_PROVIDERS`` (OpenCode Zen/Go, authoritative live API) live-first so stale
  1286. curated entries stop polluting the top. Plugin providers without a static entry use the
  1287. profile's ``fallback_models`` as the curated list (Fireworks lists an image model first).
  1288. """
  1289. from providers import get_provider_profile
  1290. profile = get_provider_profile(normalized)
  1291. if not profile:
  1292. return None
  1293. # external_process providers (ACP agent CLIs) have no api_key/base_url credentials: the
  1294. # profile's fetch_models drives its own subprocess (kwargs are ignored per the base contract).
  1295. # Every non-api-key profile falls back to its own fallback_models (OAuth plugins have no
  1296. # static _PROVIDER_MODELS row), exactly as api_key plugins do below.
  1297. if profile.auth_type == "external_process":
  1298. try:
  1299. live = profile.fetch_models()
  1300. except Exception as exc: # a failed subprocess launch degrades to the curated list, like api_key below
  1301. logger.debug("external_process catalog fetch failed for %s: %s", normalized, exc)
  1302. live = None
  1303. # Same merge as setup (`_model_flow_plugin_provider`) so /model, the Desktop picker and
  1304. # `hermes model` offer one list: live ids plus any pinned id the probe omitted.
  1305. return merge_profile_catalog(normalized, profile, list(live) if live else None)
  1306. if not (profile.auth_type == "api_key" and profile.base_url):
  1307. return list(profile.fallback_models) or None
  1308. api_key, base_url = _api_key_credentials(normalized)
  1309. return probe_profile_catalog(normalized, profile, api_key, base_url or profile.base_url or None)
  1310. def probe_profile_catalog(normalized: str, profile, api_key: Optional[str], base_url: Optional[str]) -> Optional[list[str]]:
  1311. """``profile.fetch_models`` gated on a key (no key → no doomed probe) and merged with the curated
  1312. list; a raising catalog override degrades like a None return — fallback_models, not an empty picker."""
  1313. live = None
  1314. if api_key:
  1315. try:
  1316. live = profile.fetch_models(api_key=api_key, base_url=base_url)
  1317. except Exception:
  1318. live = None
  1319. return merge_profile_catalog(normalized, profile, live)
  1320. def merge_profile_catalog(normalized: str, profile, live: Optional[list[str]]) -> Optional[list[str]]:
  1321. """Combine a profile's live catalog with its curated list the way the ``/model`` picker does, so
  1322. first-time setup (``model_setup_flows._api_key_provider_model_list``) offers the same rows the
  1323. picker will later show. Empty live → ``fallback_models`` (None when the profile has none)."""
  1324. if not live:
  1325. rows = CuratedFallbackModels(profile.fallback_models) if profile.fallback_models else None
  1326. else:
  1327. curated = list(static_catalog(normalized)) or list(profile.fallback_models or ())
  1328. if not curated:
  1329. rows = live
  1330. else:
  1331. primary, secondary = (live, curated) if normalized in _LIVE_FIRST_PICKER_PROVIDERS else (curated, live)
  1332. rows = _merge_unique(primary, secondary, key=_model_dedup_key)
  1333. return _drop_delisted_opencode_models(normalized, rows)
  1334. def _drop_delisted_opencode_models(normalized: str, rows: Optional[list[str]]) -> Optional[list[str]]:
  1335. """The relay still LISTS delisted ids it no longer serves, and the curated floor (merged back in
  1336. as the secondary half, or served alone when there is no key) carries retired ids too. Filter the
  1337. FINAL rows for the live-first Zen/Go pickers so no path can offer a slug that 401s (#111749,
  1338. #115496)."""
  1339. if rows and normalized in _LIVE_FIRST_PICKER_PROVIDERS:
  1340. return type(rows)(m for m in rows if str(m).lower() not in _OPENCODE_FREE_EXCLUDED_MODELS)
  1341. return rows
  1342. def _chat_catalog_rows(models):
  1343. """Drop generation ids from a chat-catalog list, keeping its list subclass."""
  1344. from hermes_cli.chat_catalog import without_generation_models
  1345. return without_generation_models(models)
  1346. def _configured_relay_base_url(provider: str) -> str:
  1347. """``model.base_url`` when it points the *configured* provider at a relay/proxy, else "".
  1348. Discovery must probe the same endpoint inference uses (#121387): when ``model.base_url``
  1349. differs from the provider's own endpoint, the vendor's canonical host is NOT the catalog to list.
  1350. Mirrors the ``$OPENAI_BASE_URL`` -> ``model.base_url`` -> canonical precedence of
  1351. ``_openai_discovery_base_url`` for every built-in provider, not just OpenAI.
  1352. """
  1353. try:
  1354. model_cfg = _get_model_config_dict()
  1355. except Exception:
  1356. return ""
  1357. cfg_provider = str(model_cfg.get("provider") or "").strip().lower()
  1358. if not cfg_provider or not provider:
  1359. return ""
  1360. try:
  1361. normalized = normalize_provider(provider)
  1362. if normalized != normalize_provider(cfg_provider):
  1363. return ""
  1364. except Exception:
  1365. return ""
  1366. base_url = str(model_cfg.get("base_url") or "").strip().rstrip("/")
  1367. if not base_url:
  1368. return ""
  1369. # A base_url equal to the provider's own endpoint (the profile's or the registry row's: TokenHub's
  1370. # profile leaves it empty; OpenRouter has no registry row) is not a relay: setup persists
  1371. # canonical URLs, and OAuth providers (Codex) need native discovery.
  1372. try:
  1373. from hermes_cli.auth import PROVIDER_REGISTRY
  1374. from providers import get_provider_profile
  1375. profile_url = getattr(get_provider_profile(normalized), "base_url", "")
  1376. registry_url = getattr(PROVIDER_REGISTRY.get(normalized), "inference_base_url", "")
  1377. canonical = {normalize_route_base_url(u) for u in (profile_url, registry_url) if u}
  1378. except Exception:
  1379. return base_url # lookup failed: stay a relay, never widening where credentials go
  1380. return "" if normalize_route_base_url(base_url) in canonical else base_url
  1381. def _relay_model_catalog(normalized: str, relay: str) -> Optional[list[str]]:
  1382. """Live catalog probed at a configured ``model.base_url`` relay, or None to fall through.
  1383. Returns only the relay's live ids (no curated merge): a relay user must see the relay's
  1384. catalog, and a failed/empty probe degrades to the canonical fetchers untouched.
  1385. """
  1386. try:
  1387. from providers import get_provider_profile
  1388. profile = get_provider_profile(normalized)
  1389. if profile is None or getattr(profile, "auth_type", "") != "api_key":
  1390. return None
  1391. api_key, _ = _api_key_credentials(normalized)
  1392. live = profile.fetch_models(api_key=api_key, base_url=relay)
  1393. return [str(m) for m in (live or []) if m] or None
  1394. except Exception:
  1395. return None
  1396. # Canonical fetchers that already resolve `model.base_url` themselves for the configured
  1397. # provider AND degrade to their curated list when that relay fails — `_anthropic_catalog`,
  1398. # `_custom_catalog`, `_openai_catalog` (via `_openai_discovery_base_url`) and the simple
  1399. # api-key fetchers (via `resolve_api_key_provider_credentials`). They already satisfy the
  1400. # "no vendor egress when a relay is configured" invariant, so intercepting them would only
  1401. # override correct, better-merged behaviour. Everything else is vendor-pinned (#121387).
  1402. _RELAY_AWARE_CATALOG_FETCHERS = frozenset(
  1403. {"anthropic", "custom", "openai", "openai-api", "stepfun", "gmi"}
  1404. )
  1405. def _static_catalog(normalized: str, fetcher: Any) -> list[str]:
  1406. """The local, no-egress catalog tail: curated static list (+ models.dev merge where preferred).
  1407. Shared by the normal path's final fallback and by the configured-relay degrade path, which
  1408. must never reach a live vendor fetcher (#121387).
  1409. """
  1410. # Merge static curated list with live API results so models that the live endpoint omits (stale cache,
  1411. # partial rollout) still appear in the picker. Single providers (kimi, zai) use curated-first (commit
  1412. # 658ac1d86) to surface newest models even when live API lags (#46309). OpenCode Zen / Go are different:
  1413. # their live API is the authoritative catalog, so they merge live-first — live entries lead and stale
  1414. # curated entries no longer pollute the top of the picker. (#49129) Plugin providers with no static
  1415. # _PROVIDER_MODELS entry fall back to the profile's curated fallback_models so their agentic picks lead
  1416. # the picker instead of whatever the live catalog happens to return first (e.g. Fireworks lists an image
  1417. # model, flux-*, ahead of its chat models).
  1418. # A provider with a live fetcher that declined is serving a placeholder; one without any live
  1419. # source is serving its authoritative catalog.
  1420. curated_static = (CuratedFallbackModels if fetcher is not None else list)(static_catalog(normalized))
  1421. if normalized not in _MODELS_DEV_PREFERRED:
  1422. return _chat_catalog_rows(_drop_delisted_opencode_models(normalized, curated_static))
  1423. # models.dev keeps listing retired Zen ids too: filter after the merge, not before.
  1424. merged = _drop_delisted_opencode_models(normalized, _merge_with_models_dev(normalized, curated_static))
  1425. return _chat_catalog_rows(_xai_finalize_catalog(merged) if normalized in {"xai", "xai-oauth"} else merged)
  1426. def provider_model_ids(provider: Optional[str], *, force_refresh: bool = False) -> list[str]:
  1427. """Best known model catalog for a provider: per-provider live fetchers, then the generic profile
  1428. fetch, then the static list (merged with models.dev for ``_MODELS_DEV_PREFERRED`` providers)."""
  1429. requested = str(provider or "").strip().lower()
  1430. if requested == "ollama":
  1431. return _ollama_local_catalog(force_refresh)
  1432. normalized = normalize_provider(provider)
  1433. # A configured `model.base_url` relay is TERMINAL for live catalog egress: the picker must
  1434. # list what the configured endpoint serves and must never touch the vendor host (#121387).
  1435. # A failed or empty probe degrades to the local curated list — falling through to the
  1436. # canonical fetchers would send the provider credential to exactly the host the user
  1437. # deliberately routed away from, recreating the bug on the failure path.
  1438. relay = _configured_relay_base_url(provider or "")
  1439. if relay and normalized not in _RELAY_AWARE_CATALOG_FETCHERS:
  1440. relayed = _relay_model_catalog(normalized, relay)
  1441. if relayed:
  1442. return _chat_catalog_rows(relayed)
  1443. return _static_catalog(normalized, _catalog_fetcher(normalized))
  1444. fetcher = _catalog_fetcher(normalized)
  1445. if fetcher is not None:
  1446. models = fetcher(normalized, force_refresh)
  1447. if models is not None:
  1448. return _chat_catalog_rows(models)
  1449. try:
  1450. models = _profile_live_catalog(normalized)
  1451. except Exception:
  1452. models = None
  1453. if models is not None:
  1454. return _chat_catalog_rows(models)
  1455. return _static_catalog(normalized, fetcher)
  1456. # ---------------------------------------------------------------------------
  1457. # Disk cache for provider_model_ids() — keeps /model picker fast (otherwise every open re-fetches
  1458. # every authed provider's /v1/models). One JSON file at $HERMES_HOME/provider_models_cache.json;
  1459. # entries keyed by credential fingerprint (rotate OPENAI_API_KEY → entry invalidates); 1h TTL;
  1460. # only NON-EMPTY results are cached so a transient failure is never pinned; any read/write error
  1461. # degrades silently to a live fetch.
  1462. # ---------------------------------------------------------------------------
  1463. _PROVIDER_MODELS_CACHE_TTL = 3600 # 1h
  1464. # Stale-while-revalidate window: an expired same-credentials entry is served IMMEDIATELY while a
  1465. # daemon thread refreshes the disk cache; beyond this bound the caller blocks on a live fetch.
  1466. # Catalogs change on release timescales, so hour-old data beats stalling every picker surface.
  1467. _PROVIDER_MODELS_STALE_SERVE_MAX = 7 * 24 * 3600 # 7d
  1468. # A curated fallback row is a placeholder for an outage, not a catalog: re-probe soon and never
  1469. # serve it through the stale window.
  1470. _PROVIDER_MODELS_FALLBACK_TTL = 60
  1471. # Cache keys with a background SWR refresh in flight — dedupes concurrent refreshes.
  1472. _swr_refresh_inflight: set = set()
  1473. _swr_refresh_lock = threading.Lock()
  1474. def _cache_entry(fp: str, models: list[str], at: Optional[float] = None) -> dict:
  1475. """One provider row of the disk cache: credential fingerprint, write time, model ids."""
  1476. return {"fp": fp, "at": time.time() if at is None else at, "models": list(models)}
  1477. def _live_result_entry(fp: str, live: list[str], existing: Any, at: Optional[float] = None) -> Optional[dict]:
  1478. """Row to store for a ``provider_model_ids`` result, or ``None`` to keep *existing*: a curated
  1479. fallback never replaces the account's real catalog for the same credentials, and when it is
  1480. stored it is flagged so it expires on the short fallback TTL."""
  1481. if not isinstance(live, CuratedFallbackModels):
  1482. return _cache_entry(fp, live, at)
  1483. if _cache_entry_valid(existing, fp) and not existing.get("fallback"):
  1484. return None
  1485. return {**_cache_entry(fp, live, at), "fallback": True}
  1486. def _ollama_native_probe_reachable() -> bool:
  1487. """Whether the configured local Ollama root answered the native ``/api/tags`` probe (an empty
  1488. catalog from a reachable server is authoritative; a failed probe is not)."""
  1489. base_url = _get_ollama_base_url()
  1490. headers = _get_ollama_native_headers(base_url) or None
  1491. probe_key = _ollama_probe_cache_key(_root_for_ollama_native_api(base_url), headers)
  1492. return _OLLAMA_LOCAL_PROBE_REACHABLE.get(probe_key) is True
  1493. def _spawn_swr_refresh(cache_key: str, refresh_fn=None) -> None:
  1494. """Fire-and-forget daemon refresh of *cache_key*'s cache entry, at most one in flight per key.
  1495. Failures are swallowed — the stale entry stays served until a later refresh succeeds.
  1496. ``refresh_fn`` (no-args → fresh entry dict or None) lets ``custom:<base_url>`` keys from
  1497. :func:`cached_fetch_api_models` reuse the same inflight-dedupe scaffolding."""
  1498. # Under a routed profile the inflight key includes the home: the same provider slug names a
  1499. # different disk cache and credential set per profile, so one profile's refresh must not
  1500. # suppress another's. Unscoped keeps the bare key (tests inspect the set by slug).
  1501. from hermes_constants import get_hermes_home_override, hermes_home_key
  1502. inflight_key = cache_key if get_hermes_home_override() is None else (hermes_home_key(), cache_key)
  1503. with _swr_refresh_lock:
  1504. if inflight_key in _swr_refresh_inflight:
  1505. return
  1506. _swr_refresh_inflight.add(inflight_key)
  1507. def _default_refresh():
  1508. live = provider_model_ids(cache_key, force_refresh=True)
  1509. if live or (cache_key == "ollama" and _ollama_native_probe_reachable()):
  1510. fp = _credential_fingerprint(cache_key)
  1511. return _live_result_entry(fp, live or [], _load_provider_models_cache().get(cache_key))
  1512. return None
  1513. def _refresh() -> None:
  1514. try:
  1515. entry = (refresh_fn or _default_refresh)()
  1516. if entry:
  1517. # _store_cache_entry re-reads under the write lock: the GUI read path spawns one of these
  1518. # per stale provider, so a plain load-modify-save would let concurrent warms drop rows.
  1519. _store_cache_entry(cache_key, entry)
  1520. except Exception:
  1521. logger.debug("SWR refresh failed for %s", cache_key, exc_info=True)
  1522. finally:
  1523. with _swr_refresh_lock:
  1524. _swr_refresh_inflight.discard(inflight_key)
  1525. # copy_context: the refresh must read the calling profile's credentials and write ITS disk cache.
  1526. ctx = contextvars.copy_context()
  1527. threading.Thread(target=lambda: ctx.run(_refresh), daemon=True, name=f"model-cache-swr-{cache_key}").start()
  1528. def _provider_models_cache_path() -> Path:
  1529. from hermes_constants import get_hermes_home
  1530. return get_hermes_home() / "provider_models_cache.json"
  1531. def _credential_fingerprint(provider: str) -> str:
  1532. """Short hash of the credentials ``provider_model_ids(provider)`` would see right now.
  1533. API-key providers include their configured values and credential-file mtimes. Codex uses the
  1534. stable principal selected by its read-only resolver: routine token and pool-state writes must
  1535. not discard an account-scoped catalog, while a real account switch must invalidate it.
  1536. """
  1537. import hashlib
  1538. parts: list[str] = []
  1539. try:
  1540. from hermes_cli.auth import PROVIDER_REGISTRY
  1541. pcfg = PROVIDER_REGISTRY.get(provider)
  1542. if pcfg is not None:
  1543. for ev in getattr(pcfg, "api_key_env_vars", ()) or ():
  1544. parts.append(f"{ev}={os.environ.get(ev, '')}")
  1545. bev = getattr(pcfg, "base_url_env_var", "") or ""
  1546. if bev:
  1547. parts.append(f"{bev}={os.environ.get(bev, '')}")
  1548. except Exception:
  1549. pass
  1550. # External-process providers discover models through the launched program, so the command /
  1551. # argv env overrides identify the catalog the way an API key identifies an HTTP catalog.
  1552. try:
  1553. from providers import get_provider_profile
  1554. profile = get_provider_profile(provider)
  1555. if profile is not None and profile.auth_type == "external_process":
  1556. for ev in (*profile.process_command_env_vars, profile.process_args_env_var):
  1557. if ev:
  1558. parts.append(f"{ev}={os.environ.get(ev, '')}")
  1559. except Exception:
  1560. pass
  1561. # config.yaml's model.base_url changes the endpoint discovery probes (data-residency hosts)
  1562. # without touching any env var, so it must change the fingerprint too.
  1563. if provider in ("openai", "openai-api"):
  1564. try:
  1565. parts.append(f"effective_base={_openai_discovery_base_url(provider)}")
  1566. except Exception:
  1567. pass
  1568. # Azure Foundry deployments are per-resource and the wizard writes only model.base_url, so a
  1569. # resource switch under the same key must not serve the previous resource's catalog (#27989).
  1570. if provider == "azure-foundry":
  1571. try:
  1572. from hermes_cli.runtime_provider import _config_base_url_for_provider
  1573. parts.append(f"effective_base={_config_base_url_for_provider(_get_model_config_dict(), 'azure-foundry')}")
  1574. except Exception:
  1575. pass
  1576. if provider == "ollama":
  1577. provider_cfg = _get_provider_config_dict("ollama")
  1578. key_env = provider_cfg.get("key_env") or provider_cfg.get("api_key_env") or ""
  1579. model_cfg = _get_model_config_dict()
  1580. parts += [
  1581. f"OLLAMA_HOST={os.environ.get('OLLAMA_HOST', '')}",
  1582. "providers.ollama.base_url="
  1583. f"{provider_cfg.get('base_url', '') or provider_cfg.get('api', '') or provider_cfg.get('url', '')}",
  1584. f"providers.ollama.api_key={provider_cfg.get('api_key', '')}",
  1585. f"providers.ollama.key_env={key_env}",
  1586. ]
  1587. if key_env:
  1588. parts.append(f"{key_env}={os.environ.get(str(key_env), '')}")
  1589. parts += [
  1590. f"model.provider={model_cfg.get('provider', '')}|model.base_url={model_cfg.get('base_url', '')}",
  1591. "providers.ollama.extra_headers="
  1592. + json.dumps(provider_cfg.get("extra_headers", {}), sort_keys=True, default=str),
  1593. ]
  1594. def _mtime_part(label: str, path) -> None:
  1595. from utils import file_cache_version # hashed every time: keys a disk cache later processes read
  1596. try:
  1597. parts.append(f"{label}@{file_cache_version(path, always_digest=True)}")
  1598. except FileNotFoundError:
  1599. parts.append(f"{label}@missing")
  1600. except Exception:
  1601. pass
  1602. if provider == "openai-codex":
  1603. from hermes_cli.codex_models import codex_catalog_credential_identity
  1604. parts.append(f"codex_identity={codex_catalog_credential_identity()}")
  1605. else:
  1606. try:
  1607. from hermes_constants import get_hermes_home
  1608. for rel in ("auth.json", "credentials.json"):
  1609. _mtime_part(rel, get_hermes_home() / rel)
  1610. except Exception:
  1611. pass
  1612. from providers import list_providers
  1613. profile_files = [rel for profile in list_providers() for rel in profile.catalog_credential_files]
  1614. for rel in ("~/.codex/auth.json", "~/.claude/.credentials.json", *profile_files, "~/.minimax/credentials.json"):
  1615. path = os.path.expanduser(rel)
  1616. _mtime_part(path, path)
  1617. blob = "|".join(parts).encode("utf-8", errors="replace")
  1618. # blake2b, not sha256: fingerprint only (collisions = a harmless cache miss), and CodeQL's
  1619. # weak-sensitive-data-hashing rule flags sha256 over env vars named *API_KEY*/*TOKEN*.
  1620. return hashlib.blake2b(blob, digest_size=8).hexdigest()
  1621. def _load_provider_models_cache() -> dict:
  1622. """Return the full cache dict, or {} on any error."""
  1623. try:
  1624. return _read_json_cache(_provider_models_cache_path()) or {}
  1625. except Exception:
  1626. return {}
  1627. def _save_provider_models_cache(data: dict) -> None:
  1628. """Persist the cache dict. Best-effort — silent on any error."""
  1629. try:
  1630. _write_json_cache(_provider_models_cache_path(), data, indent=None)
  1631. except Exception:
  1632. pass
  1633. def _store_cache_entry(cache_key: str, entry: dict) -> None:
  1634. """Write one row into the disk cache, re-reading it under the thread + cross-process locks: a slow
  1635. fetch worker or another process must never write back the snapshot it loaded before fetching."""
  1636. from hermes_cli.models_cache_lock import write_under_cache_lock
  1637. def write_row() -> None:
  1638. cache = _load_provider_models_cache()
  1639. cache[cache_key] = entry
  1640. _save_provider_models_cache(cache)
  1641. write_under_cache_lock(_provider_models_cache_path(), write_row)
  1642. def _normalized_cache_slug(provider: Optional[str]) -> str:
  1643. """``ollama`` stays a raw slug (its alias would canonicalize to ``custom``); everything else normalizes."""
  1644. requested = str(provider or "").strip().lower()
  1645. return requested if requested == "ollama" else (normalize_provider(provider) or (provider or ""))
  1646. def _model_requires_account_discovery(provider: Optional[str], model: str) -> bool:
  1647. """Astra names cannot confer API/OAuth entitlement through picker state."""
  1648. return _normalized_cache_slug(provider) in {"openai", "openai-api", "openai-codex"} and is_astra_model(model)
  1649. def cached_provider_model_ids(
  1650. provider: Optional[str], *, force_refresh: bool = False,
  1651. ttl_seconds: int = _PROVIDER_MODELS_CACHE_TTL, non_blocking: bool = False) -> list[str]:
  1652. """Disk-cached :func:`provider_model_ids`: fresh cache hit, else live fetch persisting a non-empty
  1653. result. Always returns a list.
  1654. ``non_blocking`` marks the GUI read path (``model.options``): it NEVER waits on a provider probe.
  1655. A same-credentials row of any age is served as-is and a daemon thread warms the next open; a
  1656. cold/mismatched row returns ``[]`` so the caller keeps its curated list. One degraded provider
  1657. (hanging or timing-out ``/v1/models``) therefore delays nothing but itself (#114215)."""
  1658. normalized = _normalized_cache_slug(provider)
  1659. if not normalized:
  1660. return []
  1661. is_ollama = normalized == "ollama"
  1662. cache = _load_provider_models_cache()
  1663. fp = _credential_fingerprint(normalized)
  1664. entry = cache.get(normalized)
  1665. now = time.time()
  1666. if not force_refresh:
  1667. tier = _disk_serve_tier(entry, fp, now, is_ollama=is_ollama, ttl_seconds=ttl_seconds)
  1668. if tier is not None:
  1669. if tier == "stale":
  1670. _spawn_swr_refresh(normalized)
  1671. return _chat_catalog_rows(list(entry["models"]))
  1672. if non_blocking and not force_refresh:
  1673. # Read path: never touch the network in the caller's thread. A same-credentials row past the
  1674. # SWR window is still served (hour-old catalog beats an empty picker) while a daemon thread
  1675. # warms the next open; a cold row returns [] and the caller falls back to its curated list.
  1676. _spawn_swr_refresh(normalized)
  1677. if _cache_entry_valid(entry, fp, allow_empty=is_ollama):
  1678. return _chat_catalog_rows([
  1679. model for model in entry["models"]
  1680. if not _model_requires_account_discovery(normalized, model)])
  1681. return []
  1682. live = provider_model_ids(normalized, force_refresh=force_refresh)
  1683. if live:
  1684. fresh = _live_result_entry(fp, live, entry, now)
  1685. if fresh is None:
  1686. # The live fetch degraded to the curated list; the account's real catalog is on disk.
  1687. return _chat_catalog_rows([model for model in entry["models"] if not _model_requires_account_discovery(normalized, model)])
  1688. _store_cache_entry(normalized, fresh)
  1689. return _chat_catalog_rows(list(live))
  1690. if is_ollama:
  1691. if _ollama_native_probe_reachable():
  1692. # A reachable empty native catalog is authoritative; do not resurrect a stale disk catalog.
  1693. _store_cache_entry(normalized, _cache_entry(fp, [], now))
  1694. return []
  1695. # A failed/non-native probe is not authoritative: keep a stale catalog rather than blanking
  1696. # the picker during a transient outage.
  1697. same_creds = isinstance(entry, dict) and entry.get("fp") == fp
  1698. if same_creds and isinstance(entry.get("models"), list) and entry["models"]:
  1699. return _chat_catalog_rows(list(entry["models"]))
  1700. return []
  1701. # Live returned nothing: a stale same-fingerprint entry beats an empty result — minus account-gated
  1702. # models, which only a successful discovery may advertise (the entry itself is untouched, so the
  1703. # next successful fetch restores them).
  1704. if _cache_entry_valid(entry, fp):
  1705. return _chat_catalog_rows([model for model in entry["models"] if not _model_requires_account_discovery(normalized, model)])
  1706. return []
  1707. def clear_provider_models_cache(provider: Optional[str] = None) -> None:
  1708. """Drop one provider's cache entry, or wipe the whole cache (``provider=None``). Used by
  1709. ``/model --refresh`` and ``hermes model --refresh``."""
  1710. try:
  1711. from hermes_cli.model_catalog import clear_fetch_backoff
  1712. clear_fetch_backoff() # a recovered catalog is fetched now, not after the offline backoff
  1713. # Native Ollama tags are keyed by root URL, not provider slug: clear them on every refresh.
  1714. _OLLAMA_LOCAL_MODELS_CACHE.clear()
  1715. _OLLAMA_LOCAL_PROBE_FAILURE_CACHE.clear()
  1716. _OLLAMA_LOCAL_PROBE_REACHABLE.clear()
  1717. # Provider-owned in-process memos (e.g. an external CLI's session catalog) must re-probe so a
  1718. # fresh login shows on the next switch.
  1719. from providers import list_providers
  1720. for profile in list_providers():
  1721. profile.invalidate_catalog_cache()
  1722. from hermes_cli.models_cache_lock import write_under_cache_lock
  1723. path = _provider_models_cache_path()
  1724. # Under the cache lock like every other writer: a locked writer that loaded the cache
  1725. # before this clear would otherwise save its snapshot after it, bringing the row back.
  1726. def clear_file() -> None:
  1727. if provider is None:
  1728. if path.exists():
  1729. path.unlink()
  1730. return
  1731. cache = _load_provider_models_cache()
  1732. normalized = _normalized_cache_slug(provider)
  1733. if normalized in cache:
  1734. del cache[normalized]
  1735. _save_provider_models_cache(cache)
  1736. write_under_cache_lock(path, clear_file)
  1737. except Exception:
  1738. pass
  1739. def _resolve_anthropic_pool_catalog_credentials() -> tuple[str, str]:
  1740. """Read-only API-key pool credential for model discovery (``resolve_anthropic_token()`` ignores
  1741. ``api_key`` pool entries — its runtime contract is OAuth-oriented)."""
  1742. try:
  1743. from agent.credential_pool import AUTH_TYPE_API_KEY
  1744. from hermes_cli.auth import read_credential_pool
  1745. for entry in read_credential_pool("anthropic"):
  1746. if not isinstance(entry, dict) or entry.get("auth_type") != AUTH_TYPE_API_KEY:
  1747. continue
  1748. token = str(entry.get("access_token") or "").strip()
  1749. if token:
  1750. return token, str(entry.get("base_url") or entry.get("inference_base_url") or "").strip()
  1751. except Exception:
  1752. pass
  1753. return "", ""
  1754. def _fetch_anthropic_models(
  1755. timeout: float = 5.0, *, base_url: Optional[str] = None, api_key: Optional[str] = None
  1756. ) -> Optional[list[str]]:
  1757. """Sorted model ids from the Anthropic /v1/models endpoint, or None. Credentials: explicit
  1758. ``api_key``, else ``resolve_anthropic_token()`` (env / OAuth / Claude Code), else a read-only
  1759. API-key credential_pool entry."""
  1760. try:
  1761. from agent.anthropic_credentials import resolve_anthropic_token, _is_oauth_token
  1762. except ImportError:
  1763. return None
  1764. resolved_base_url = base_url
  1765. token = (api_key or "").strip() or resolve_anthropic_token()
  1766. if not token:
  1767. # A pool credential and its endpoint are one security boundary — never pair the pool key
  1768. # with a caller-provided endpoint.
  1769. token, resolved_base_url = _resolve_anthropic_pool_catalog_credentials()
  1770. if not token:
  1771. return None
  1772. headers: dict[str, str] = {"anthropic-version": "2023-06-01"}
  1773. is_oauth = _is_oauth_token(token)
  1774. if is_oauth:
  1775. headers["Authorization"] = f"Bearer {token}"
  1776. from agent.anthropic_adapter import _COMMON_BETAS, _OAUTH_ONLY_BETAS, _CONTEXT_1M_BETA
  1777. headers["anthropic-beta"] = ",".join(_COMMON_BETAS + _OAUTH_ONLY_BETAS)
  1778. else:
  1779. headers["x-api-key"] = token
  1780. url = _anthropic_models_url(resolved_base_url)
  1781. try:
  1782. try:
  1783. data = _get_json(url, timeout=timeout, headers=headers)
  1784. except urllib.error.HTTPError as http_err:
  1785. # OAuth subscriptions that 400 the 1M context beta ("long context beta is not yet
  1786. # available for this subscription"): retry once without it; re-raise anything else.
  1787. if not (is_oauth and http_err.code == 400):
  1788. raise
  1789. try:
  1790. body_text = http_err.read().decode(errors="ignore").lower()
  1791. except Exception:
  1792. body_text = ""
  1793. if not ("long context beta" in body_text and "not yet available" in body_text):
  1794. raise
  1795. headers["anthropic-beta"] = ",".join(
  1796. [b for b in _COMMON_BETAS if b != _CONTEXT_1M_BETA] + list(_OAUTH_ONLY_BETAS)
  1797. )
  1798. data = _get_json(url, timeout=timeout, headers=headers)
  1799. models = [m["id"] for m in data.get("data", []) if m.get("id")]
  1800. seen_cursors: set[str] = set()
  1801. for _page in range(_ANTHROPIC_MODELS_MAX_PAGES):
  1802. cursor = _anthropic_next_cursor(data, seen_cursors)
  1803. if cursor is None:
  1804. break
  1805. data = _get_json(_anthropic_models_url(resolved_base_url, after_id=cursor), timeout=timeout, headers=headers)
  1806. models.extend(m["id"] for m in data.get("data", []) if m.get("id"))
  1807. models = list(dict.fromkeys(models))
  1808. # opus, then sonnet, then haiku; alphabetical within tier.
  1809. return sorted(models, key=lambda m: ("opus" not in m, "sonnet" not in m, "haiku" not in m, m))
  1810. except Exception as e:
  1811. logger.debug("Failed to fetch Anthropic models: %s", e)
  1812. return None
  1813. def azure_foundry_model_api_mode(model_name: Optional[str]) -> Optional[str]:
  1814. """``"codex_responses"`` for families that only accept the Responses API on Azure Foundry (GPT-5.x
  1815. incl. gpt-5-mini, codex, o1/o3/o4), else None. Any ``vendor/`` prefix is stripped first."""
  1816. raw = str(model_name or "").strip().lower().rsplit("/", 1)[-1]
  1817. return "codex_responses" if raw and raw.startswith(tuple(_AZURE_FOUNDRY_RESPONSES_PREFIXES)) else None
  1818. _OPENCODE_FAMILIES = ("opencode-go", "opencode-zen")
  1819. def opencode_provider_family(provider_id: Optional[str]) -> Optional[str]:
  1820. """Resolve a provider id (canonical or prefixed) to its OpenCode family, or None.
  1821. Returns ``"opencode-zen"`` or ``"opencode-go"`` for the built-in providers AND for custom providers
  1822. whose name extends a family slug (e.g. ``opencode-go-bridge`` pointing at
  1823. ``https://opencode.ai/zen/go/v1``, issue #85589). Matching is case-insensitive. Custom family providers
  1824. need the same per-model api_mode routing and /v1 base-url normalization as the built-ins — this
  1825. predicate is the single owner of that family-membership question; do not re-implement it inline.
  1826. """
  1827. raw = str(provider_id or "").strip().lower()
  1828. if not raw:
  1829. return None
  1830. canonical = normalize_provider(provider_id)
  1831. if canonical in _OPENCODE_FAMILIES:
  1832. return canonical
  1833. return next((f for f in _OPENCODE_FAMILIES if raw.startswith(f)), None)
  1834. def normalize_opencode_model_id(provider_id: Optional[str], model_id: Optional[str]) -> str:
  1835. """Normalize OpenCode config IDs to the bare model slug used in API requests."""
  1836. family = opencode_provider_family(provider_id)
  1837. current = str(model_id or "").strip()
  1838. if not current or family is None:
  1839. return current
  1840. for prefix in (f"{provider_id or family}/", f"{family}/"):
  1841. if current.lower().startswith(prefix.lower()):
  1842. return current[len(prefix):]
  1843. return current
  1844. # Per-family (model-id prefix → api_mode) routing from OpenCode's published Zen/Go endpoint
  1845. # tables, checked in order. GPT/Codex/Grok and Muse Spark use /v1/responses (Muse Spark 503s on
  1846. # chat/completions); Claude, MiniMax (Go), Union Alpha, and Qwen use /v1/messages;
  1847. # everything else falls through to /v1/chat/completions.
  1848. _OPENCODE_API_MODE_PREFIXES: dict[str, tuple[tuple[tuple[str, ...], str], ...]] = {
  1849. "opencode-go": (
  1850. (("gpt-", "grok-", "muse-spark"), "codex_responses"),
  1851. (("claude-", "minimax-", "qwen", "union-alpha"), "anthropic_messages")),
  1852. "opencode-zen": (
  1853. (("claude-", "union-alpha"), "anthropic_messages"), (("gpt-", "grok-", "muse-spark"), "codex_responses"),
  1854. (("qwen",), "anthropic_messages"))}
  1855. def opencode_model_api_mode(provider_id: Optional[str], model_id: Optional[str]) -> str:
  1856. """Determine the API mode for an OpenCode Zen / Go model (see ``_OPENCODE_API_MODE_PREFIXES``)."""
  1857. family = opencode_provider_family(provider_id)
  1858. normalized = normalize_opencode_model_id(provider_id, model_id).lower()
  1859. if normalized:
  1860. for prefixes, mode in _OPENCODE_API_MODE_PREFIXES.get(family or "", ()):
  1861. if normalized.startswith(prefixes):
  1862. return mode
  1863. return "chat_completions"
  1864. # Relay path per OpenCode family on opencode.ai hosts.
  1865. _OPENCODE_FAMILY_PATHS = {"opencode-zen": "/zen", "opencode-go": "/zen/go"}
  1866. def normalize_opencode_base_url(
  1867. provider_id: Optional[str], api_mode: Optional[str], base_url: Optional[str]) -> str:
  1868. """Normalize an OpenCode Zen / Go base URL for the API mode. Must be SYMMETRIC: the anthropic-
  1869. stripped URL gets persisted to ``model.base_url`` after switching into an anthropic-routed model,
  1870. and chat/codex modes heal it by re-adding ``/v1`` — but only on opencode.ai hosts, so custom
  1871. ``OPENCODE_*_BASE_URL`` proxies are left alone. On those hosts the relay path segment follows
  1872. the resolved family too (``/zen`` vs ``/zen/go``): the two relays serve different model sets,
  1873. so a ``model.base_url`` carried over from the other family 401s ("Model ... is not supported").
  1874. The family heal applies to the BUILT-IN providers only: a custom provider merely named after a
  1875. family (``opencode-go-bridge``) declared its relay path explicitly in ``providers:`` and keeps it.
  1876. Only the path is edited, so a port, userinfo, query or fragment round-trips untouched."""
  1877. url = str(base_url or "").strip().rstrip("/")
  1878. family = opencode_provider_family(provider_id)
  1879. if not url or family is None:
  1880. return url
  1881. parsed = urllib.parse.urlparse(url)
  1882. host = (parsed.hostname or "").lower()
  1883. official = host == "opencode.ai" or host.endswith(".opencode.ai")
  1884. path = parsed.path.rstrip("/")
  1885. if official and normalize_provider(provider_id) in _OPENCODE_FAMILIES and re.fullmatch(r"/zen(/go)?(/v1)?", path):
  1886. path = _OPENCODE_FAMILY_PATHS[family] + ("/v1" if path.endswith("/v1") else "")
  1887. if api_mode == "anthropic_messages":
  1888. path = re.sub(r"/v1$", "", path)
  1889. elif official and not path.endswith("/v1"):
  1890. path += "/v1"
  1891. return urllib.parse.urlunparse(parsed._replace(path=path))
  1892. # Negative cache: monotonic timestamp of the last timed-out probe, keyed
  1893. # by ``host:port`` so both URL candidates (``/v1`` + root) share one entry.
  1894. # Without this, an unreachable endpoint (TCP blackhole — SYN draws no reply,
  1895. # so every attempt burns its full connect timeout) makes every picker open /
  1896. # chat turn re-pay the timeout per candidate, and the sequential stalls stack
  1897. # past 10s while the Desktop sits on a spinner with no error (#81123). Short
  1898. # TTL collapses the burst but still picks up recovery without a restart.
  1899. # Mirrors _deepinfra_catalog_neg_cache.
  1900. _probe_neg_cache: dict[str, float] = {}
  1901. _PROBE_NEG_TTL = 60.0 # seconds
  1902. def _probe_neg_key(base_url: str) -> Optional[str]:
  1903. """``host:port`` for *base_url* (both URL candidates share one entry), or None without a host."""
  1904. from utils import base_url_origin
  1905. _, host, port = base_url_origin(base_url)
  1906. return f"{host}:{port}" if host else None
  1907. def _probe_result(
  1908. models, probed_url, resolved_base_url, suggested_base_url=None, used_fallback=False
  1909. ) -> dict[str, Any]:
  1910. return {
  1911. "models": models,
  1912. "probed_url": probed_url,
  1913. "resolved_base_url": resolved_base_url,
  1914. "suggested_base_url": suggested_base_url,
  1915. "used_fallback": used_fallback}
  1916. def probe_api_models(
  1917. api_key: Optional[str], base_url: Optional[str], timeout: float = 5.0,
  1918. api_mode: Optional[str] = None, request_headers: Optional[dict[str, str]] = None,
  1919. ) -> dict[str, Any]:
  1920. """Probe a ``/models`` endpoint with light URL heuristics (``base`` then ``base±/v1``).
  1921. ``anthropic_messages`` mode sends ``x-api-key`` + ``anthropic-version`` instead of a bearer; the
  1922. ``data[].id`` response shape is identical. ``models`` is None when no candidate answered."""
  1923. normalized = (base_url or "").strip().rstrip("/")
  1924. if not normalized:
  1925. return _probe_result(None, None, "")
  1926. from providers import profile_for_host
  1927. owner = profile_for_host(normalized, metadata=True)
  1928. owned = owner.probe_models(base_url=normalized, api_key=api_key, timeout=timeout) if owner else None
  1929. if owned is not None:
  1930. return _probe_result(*owned)
  1931. alternate_base = normalized[:-3].rstrip("/") if normalized.endswith("/v1") else normalized + "/v1"
  1932. candidates: list[tuple[str, bool]] = [(normalized, False)]
  1933. if alternate_base and alternate_base != normalized:
  1934. candidates.append((alternate_base, True))
  1935. tried: list[str] = []
  1936. _neg_key = _probe_neg_key(normalized)
  1937. if _neg_key is not None:
  1938. _neg_seen = _probe_neg_cache.get(_neg_key)
  1939. if _neg_seen is not None and (time.monotonic() - _neg_seen) < _PROBE_NEG_TTL:
  1940. return _probe_result(
  1941. None, normalized.rstrip("/") + "/models", normalized,
  1942. alternate_base if alternate_base != normalized else None)
  1943. headers: dict[str, str] = {"User-Agent": hermes_user_agent()}
  1944. if urllib.parse.urlparse(normalized).hostname == "generativelanguage.googleapis.com":
  1945. headers["X-Goog-Api-Client"] = hermes_user_agent("hermes-agent")
  1946. if api_key and api_mode == "anthropic_messages":
  1947. headers["x-api-key"] = api_key
  1948. headers["anthropic-version"] = "2023-06-01"
  1949. elif api_key:
  1950. headers["Authorization"] = f"Bearer {api_key}"
  1951. if isinstance(request_headers, dict):
  1952. # Per-provider custom headers can contain secrets: merge last so endpoint config wins; never log.
  1953. from hermes_cli.config import normalize_extra_headers
  1954. headers.update(normalize_extra_headers(request_headers))
  1955. # Only thread ssl_context when a per-provider TLS override applies; public endpoints keep the
  1956. # original 2-arg call so existing call-seam mocks stay valid.
  1957. _open_kwargs: dict[str, Any] = {}
  1958. _ssl_context = _custom_provider_ssl_context(normalized)
  1959. if _ssl_context is not None:
  1960. _open_kwargs["ssl_context"] = _ssl_context
  1961. all_timed_out = True
  1962. for candidate_base, is_fallback in candidates:
  1963. url = candidate_base.rstrip("/") + "/models"
  1964. tried.append(url)
  1965. try:
  1966. data = _get_json(url, timeout=timeout, headers=headers, **_open_kwargs)
  1967. except Exception as exc:
  1968. # TLS, authentication and parsing failures must not hide corrected settings.
  1969. cause = exc.reason if isinstance(exc, urllib.error.URLError) else exc
  1970. all_timed_out = all_timed_out and isinstance(cause, TimeoutError)
  1971. continue
  1972. if _neg_key is not None:
  1973. _probe_neg_cache.pop(_neg_key, None)
  1974. from hermes_cli.chat_catalog import note_catalog_item
  1975. probed = []
  1976. for item in data.get("data", []):
  1977. if isinstance(item, dict) and note_catalog_item(item):
  1978. continue
  1979. probed.append(item.get("id", ""))
  1980. return _probe_result(
  1981. probed, url, candidate_base.rstrip("/"),
  1982. alternate_base if alternate_base != candidate_base else normalized, is_fallback)
  1983. if _neg_key is not None and all_timed_out:
  1984. _probe_neg_cache[_neg_key] = time.monotonic()
  1985. return _probe_result(
  1986. None, tried[0] if tried else normalized.rstrip("/") + "/models", normalized,
  1987. alternate_base if alternate_base != normalized else None)
  1988. # Legacy id-regex filter for items with no surface tag; unreachable (deletable) once every catalog
  1989. # entry carries an explicit ``chat``/``embed``/``image-gen``/``tts``/``stt`` tag.
  1990. _DEEPINFRA_EXCLUDE_RE = re.compile(
  1991. r"(?i)(embed|rerank|whisper|stable-diffusion|flux|sdxl|"
  1992. r"tts|bark|speech|image-gen|clip|vit-|dpt-)")
  1993. # Surface tags say *what kind of model* this is. Absent all of them, the tags array only carries
  1994. # capability tags (``reasoning``, ``vision``, …) and the chat surface falls back to id-regex inference.
  1995. _DEEPINFRA_SURFACE_TAGS: frozenset[str] = frozenset({
  1996. "chat", "embed", "image-gen", "tts", "stt", "video-gen"})
  1997. _DEEPINFRA_DEFAULT_BASE_URL = "https://api.deepinfra.com/v1/openai"
  1998. _DEEPINFRA_MODELS_QUERY = "filter=true&sort_by=hermes"
  1999. # Full tagged catalog keyed by base URL; every surface filter reads it so one round-trip serves all.
  2000. _deepinfra_catalog_cache: dict[str, list[dict]] = {}
  2001. # Negative cache (monotonic time of the last failed fetch per base URL) so an unreachable catalog
  2002. # doesn't make every surface helper eat the full timeout in turn. Short TTL so connectivity recovers.
  2003. _deepinfra_catalog_neg_cache: dict[str, float] = {}
  2004. _DEEPINFRA_CATALOG_NEG_TTL = 60.0 # seconds
  2005. def _deepinfra_env(key: str) -> str:
  2006. """Profile-scoped ``.env``/environ read: under a multiplexed turn the launch env is not this profile's."""
  2007. from hermes_cli.config import get_env_value_prefer_dotenv
  2008. return (get_env_value_prefer_dotenv(key) or "").strip()
  2009. def _deepinfra_catalog_url() -> tuple[str, str]:
  2010. """Return ``(cache_key, full_url)`` for the DeepInfra catalog endpoint. The key carries the
  2011. api-key fingerprint: the catalog is user-scoped (private fine-tunes), so two profiles with
  2012. different keys must not share an entry."""
  2013. base = (_deepinfra_env("DEEPINFRA_BASE_URL") or _DEEPINFRA_DEFAULT_BASE_URL).rstrip("/")
  2014. from agent.credential_persistence import fingerprint_secret_value
  2015. fp = fingerprint_secret_value(_deepinfra_env("DEEPINFRA_API_KEY")) or "anon"
  2016. return f"{base}#{fp}", f"{base}/models?{_DEEPINFRA_MODELS_QUERY}"
  2017. def _fetch_deepinfra_catalog(
  2018. *, timeout: float = 5.0, force_refresh: bool = False) -> Optional[list[dict]]:
  2019. """Raw DeepInfra catalog list (chat, embed, image-gen, TTS, STT in one response), cached per base
  2020. URL. A Bearer token is attached when available so user-scoped catalogs (private fine-tunes) show."""
  2021. cache_key, url = _deepinfra_catalog_url()
  2022. if not force_refresh:
  2023. if cache_key in _deepinfra_catalog_cache:
  2024. return _deepinfra_catalog_cache[cache_key]
  2025. last_fail = _deepinfra_catalog_neg_cache.get(cache_key)
  2026. if last_fail is not None and (time.monotonic() - last_fail) < _DEEPINFRA_CATALOG_NEG_TTL:
  2027. return None
  2028. headers: dict[str, str] = {"User-Agent": hermes_user_agent()}
  2029. api_key = _deepinfra_env("DEEPINFRA_API_KEY")
  2030. if api_key:
  2031. headers["Authorization"] = f"Bearer {api_key}"
  2032. try:
  2033. payload = _get_json(url, timeout=timeout, headers=headers)
  2034. except Exception:
  2035. _deepinfra_catalog_neg_cache[cache_key] = time.monotonic()
  2036. return None
  2037. data = payload.get("data")
  2038. if not isinstance(data, list):
  2039. _deepinfra_catalog_neg_cache[cache_key] = time.monotonic()
  2040. return None
  2041. _deepinfra_catalog_cache[cache_key] = data
  2042. _deepinfra_catalog_neg_cache.pop(cache_key, None)
  2043. return data
  2044. def _fetch_deepinfra_models_by_tag(
  2045. tag: str, *, timeout: float = 5.0, force_refresh: bool = False) -> Optional[list[dict]]:
  2046. """DeepInfra ``{"id", "metadata"}`` items whose ``metadata.tags`` includes *tag*. Items with no
  2047. surface tag fall through to the legacy id-regex exclusion (chat surface only — embed/image-gen/
  2048. tts/stt cannot be inferred from an id). ``None`` on network failure."""
  2049. data = _fetch_deepinfra_catalog(timeout=timeout, force_refresh=force_refresh)
  2050. if data is None:
  2051. return None
  2052. matched: list[dict] = []
  2053. for item in data:
  2054. mid = item.get("id")
  2055. raw_metadata = item.get("metadata")
  2056. if not mid or raw_metadata is None: # metadata None = listed-but-not-served stub
  2057. continue
  2058. metadata = raw_metadata if isinstance(raw_metadata, dict) else {}
  2059. raw_tags = metadata.get("tags")
  2060. tags = raw_tags if isinstance(raw_tags, list) else []
  2061. if any(t in _DEEPINFRA_SURFACE_TAGS for t in tags):
  2062. hit = tag in tags
  2063. else:
  2064. hit = tag == "chat" and not _DEEPINFRA_EXCLUDE_RE.search(mid)
  2065. if hit:
  2066. matched.append({"id": mid, "metadata": metadata})
  2067. return matched
  2068. def _fetch_deepinfra_models(
  2069. timeout: float = 5.0, *, force_refresh: bool = False) -> Optional[list[str]]:
  2070. """DeepInfra chat-model ids (string-list contract for :func:`provider_model_ids`); ``None`` on
  2071. network failure or when no chat-tagged id exists."""
  2072. items = _fetch_deepinfra_models_by_tag("chat", timeout=timeout, force_refresh=force_refresh)
  2073. return ([item["id"] for item in items] or None) if items is not None else None
  2074. def deepinfra_model_ids(tag: str, *, force_refresh: bool = False) -> list[str]:
  2075. """Return DeepInfra model ids carrying surface *tag* (``[]`` on failure)."""
  2076. items = _fetch_deepinfra_models_by_tag(tag, force_refresh=force_refresh)
  2077. return [item["id"] for item in items] if items else []
  2078. def deepinfra_base_url(section: Optional[dict] = None) -> str:
  2079. """DeepInfra base URL: config-section ``base_url`` → ``DEEPINFRA_BASE_URL`` env → default; stripped."""
  2080. candidate = section.get("base_url") if isinstance(section, dict) else None
  2081. value = candidate or _deepinfra_env("DEEPINFRA_BASE_URL") or _DEEPINFRA_DEFAULT_BASE_URL
  2082. return str(value).strip().rstrip("/")
  2083. def _fetch_ai_gateway_models(timeout: float = 5.0) -> Optional[list[str]]:
  2084. """Fetch available language models with tool-use from AI Gateway."""
  2085. api_key = os.getenv("AI_GATEWAY_API_KEY", "").strip()
  2086. if not api_key:
  2087. return None
  2088. base_url = os.getenv("AI_GATEWAY_BASE_URL", "").strip()
  2089. if not base_url:
  2090. from hermes_constants import AI_GATEWAY_BASE_URL
  2091. base_url = AI_GATEWAY_BASE_URL
  2092. headers = {"Authorization": f"Bearer {api_key}", "User-Agent": hermes_user_agent()}
  2093. try:
  2094. url = base_url.rstrip("/") + "/models"
  2095. data = _get_json(url, timeout=timeout, headers=headers)
  2096. return [
  2097. m["id"] for m in data.get("data", [])
  2098. if m.get("id") and m.get("type") == "language" and "tool-use" in (m.get("tags") or [])]
  2099. except Exception:
  2100. return None
  2101. def fetch_api_models(
  2102. api_key: Optional[str], base_url: Optional[str], timeout: float = 5.0,
  2103. api_mode: Optional[str] = None, headers: Optional[dict[str, str]] = None,
  2104. ) -> Optional[list[str]]:
  2105. """Fetch the list of available model IDs from the provider's ``/models`` endpoint."""
  2106. result = probe_api_models(api_key, base_url, timeout=timeout, api_mode=api_mode, request_headers=headers)
  2107. return result.get("models")
  2108. def _custom_endpoint_fingerprint(
  2109. api_key: Any, api_mode: Optional[str], headers: Optional[dict[str, str]]) -> str:
  2110. """Custom endpoints have no ``PROVIDER_REGISTRY`` slug, so hash exactly what callers pass to
  2111. :func:`fetch_api_models`: a rotated ``api_key``, changed ``api_mode`` or edited ``extra_headers``
  2112. each bust the cache entry. blake2b for the same CodeQL rationale as ``_credential_fingerprint``."""
  2113. import hashlib
  2114. from agent.command_token_source import CommandTokenSource
  2115. identity = api_key.cache_identity if isinstance(api_key, CommandTokenSource) else api_key
  2116. blob = "|".join((identity or "", api_mode or "", json.dumps(headers or {}, sort_keys=True)))
  2117. return hashlib.blake2b(blob.encode("utf-8", errors="replace"), digest_size=8).hexdigest()
  2118. def _cache_entry_valid(
  2119. entry: Any, fp: str, *, allow_empty: bool = False) -> TypeGuard[dict[str, Any]]:
  2120. """Well-formed cache row for fingerprint *fp*. Requires a numeric ``at`` so corrupt disk state
  2121. degrades to a cache miss instead of raising; empty model lists are valid only when the caller
  2122. opts into an authoritative empty catalog."""
  2123. return (
  2124. isinstance(entry, dict)
  2125. and entry.get("fp") == fp
  2126. and isinstance(entry.get("models"), list)
  2127. and (allow_empty or bool(entry["models"]))
  2128. and isinstance(entry.get("at"), (int, float))
  2129. and not isinstance(entry.get("at"), bool))
  2130. def _disk_serve_tier(entry: Any, fp: str, now: float, *, is_ollama: bool,
  2131. ttl_seconds: int = _PROVIDER_MODELS_CACHE_TTL) -> Optional[str]:
  2132. """How :func:`cached_provider_model_ids` serves *entry* without the network.
  2133. ``"fresh"`` inside the row's TTL (a curated fallback row only for
  2134. ``_PROVIDER_MODELS_FALLBACK_TTL``), ``"stale"`` for a non-empty, non-fallback row inside
  2135. ``_PROVIDER_MODELS_STALE_SERVE_MAX`` (served while an SWR thread revalidates), else ``None``:
  2136. the call would block on a live fetch. Empty native catalogs are authoritative only inside the
  2137. short native TTL, never through the stale window."""
  2138. if is_ollama:
  2139. ttl_seconds = min(ttl_seconds, _OLLAMA_LOCAL_MODELS_CACHE_TTL)
  2140. if not _cache_entry_valid(entry, fp, allow_empty=is_ollama):
  2141. return None
  2142. age = now - entry["at"]
  2143. if age < (_PROVIDER_MODELS_FALLBACK_TTL if entry.get("fallback") else ttl_seconds):
  2144. return "fresh"
  2145. if entry["models"] and not entry.get("fallback") and age < _PROVIDER_MODELS_STALE_SERVE_MAX:
  2146. return "stale"
  2147. return None
  2148. def cached_fetch_api_models(
  2149. api_key: Any, base_url: Optional[str], *, timeout: float = 5.0,
  2150. api_mode: Optional[str] = None, headers: Optional[dict[str, str]] = None,
  2151. force_refresh: bool = False, cache_only: bool = False,
  2152. fetch_models=None,
  2153. ttl_seconds: int = _PROVIDER_MODELS_CACHE_TTL) -> Optional[list[str]]:
  2154. """Disk-cached :func:`fetch_api_models` for custom endpoints. ``cache_only`` callers (GUI picker
  2155. opens that must not block on a stopped local endpoint) still get a warm catalog instead of
  2156. collapsing to the config-declared subset. ``fetch_models`` supplies native-aware discovery
  2157. without minting a command token before cache admission."""
  2158. from hermes_cli.model_switch_providers import _NativePickerModelList
  2159. def _catalog(entry):
  2160. rows = (_NativePickerModelList if entry.get("native_catalog") else list)(entry["models"])
  2161. return _chat_catalog_rows(rows)
  2162. def _entry(live, at=None):
  2163. return {**_cache_entry(fp, live, at), "native_catalog": isinstance(live, _NativePickerModelList)}
  2164. def _live():
  2165. if fetch_models is not None:
  2166. return fetch_models()
  2167. from agent.command_token_source import materialize_probe_api_key
  2168. return fetch_api_models(materialize_probe_api_key(api_key), base_url, timeout=timeout, api_mode=api_mode, headers=headers)
  2169. normalized_url = str(base_url or "").strip().rstrip("/").lower()
  2170. if not normalized_url: # nothing to key the cache on
  2171. return None if cache_only else _chat_catalog_rows(_live())
  2172. # Key on URL AND credential fingerprint: N ``custom_providers`` rows can share one proxy URL
  2173. # with distinct keys (#106184). A URL-only key let the last probe overwrite its siblings'
  2174. # slot, so every other same-URL row failed the fingerprint check, got an empty catalog and
  2175. # vanished from the no-probe pickers.
  2176. fp = _custom_endpoint_fingerprint(api_key, api_mode, headers)
  2177. cache_key = f"custom:{normalized_url}#{fp}"
  2178. cache = _load_provider_models_cache()
  2179. entry = cache.get(cache_key)
  2180. now = time.time()
  2181. native_row = isinstance(entry, dict) and entry.get("native_catalog") is True
  2182. valid = not force_refresh and _cache_entry_valid(entry, fp, allow_empty=native_row)
  2183. if valid:
  2184. age = now - entry["at"]
  2185. if age < ttl_seconds:
  2186. return _catalog(entry)
  2187. # An empty native catalog is authoritative only inside the TTL (as in
  2188. # cached_provider_model_ids): never stale-serve it, or an Ollama that was model-less at
  2189. # first open keeps an empty row for the whole stale window after models are pulled.
  2190. if entry["models"] and age < _PROVIDER_MODELS_STALE_SERVE_MAX:
  2191. # Stale-while-revalidate: serve now, refresh off-thread for the next open. cache_only
  2192. # opens (GUI pickers that must not block on a stopped local server) take the same
  2193. # non-blocking refresh: without it a locally loaded model stayed invisible for the
  2194. # whole 7-day stale window unless the user found "Refresh Models" (#71169 class).
  2195. def _refresh_custom():
  2196. live = _live()
  2197. return _entry(live) if live or isinstance(live, _NativePickerModelList) else None
  2198. _spawn_swr_refresh(cache_key, _refresh_custom)
  2199. return _catalog(entry)
  2200. if cache_only:
  2201. return None
  2202. live = _live()
  2203. if live or isinstance(live, _NativePickerModelList):
  2204. stored = _entry(live, now)
  2205. _store_cache_entry(cache_key, stored)
  2206. return _catalog(stored)
  2207. # Live returned nothing (offline, timeout, auth hiccup): a stale same-fingerprint entry beats it
  2208. # (non-empty only: an empty native row is not worth resurrecting over the generic fallback).
  2209. if _cache_entry_valid(entry, fp):
  2210. return _catalog(entry)
  2211. return _chat_catalog_rows(live)