| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032 |
- """Models.dev registry integration — primary database for providers and models.
- Resolution: in-memory cache (fresh, or stale served while one background daemon
- thread refreshes) → disk cache (~/.hermes/models_dev_cache.json, any age) →
- network only when no cache exists. Failed refreshes back off 5 min process-wide.
- Refreshes use ETag conditional GET when a servable registry is held. Hot paths
- pass ``allow_network=False`` and never do I/O. A corrupt/empty disk cache is
- quarantined, never served as ``{}``. ``models_dev.url`` in config.yaml = mirror."""
- import contextlib
- import json
- import logging
- import re
- import threading
- import time
- from dataclasses import dataclass
- from pathlib import Path
- from typing import Any, Dict, List, Optional, Tuple
- from utils import atomic_json_write, atomic_write_text
- from hermes_constants import openrouter_variant_base
- import requests
- logger = logging.getLogger(__name__)
- MODELS_DEV_URL = "https://models.dev/api.json"
- _MODELS_DEV_CACHE_TTL = 4 * 3600 # 4 hours — ETag conditional GET makes refresh cheap
- _MODELS_DEV_RETRY_DELAY = 300 # 5 minutes after a failed refresh
- _MODELS_DEV_FETCH_DEADLINE = 15.0 # whole download; ~600 KB gzipped fits at ~40 KB/s
- # In-memory cache
- _models_dev_cache: dict[str, Any] = {}
- _models_dev_cache_time: float = 0
- _models_dev_retry_after: float = 0
- _models_dev_fetch_lock = threading.Lock()
- _models_dev_refresh_lock = threading.Lock()
- _models_dev_refresh_in_flight = False
- _models_dev_download_slot = threading.Lock() # held by the one live download, abandoned or not
- @dataclass
- class ModelInfo:
- """Full metadata for a single model from models.dev."""
- id: str
- name: str
- family: str
- provider_id: str # models.dev provider ID (e.g. "anthropic")
- # Capabilities
- reasoning: bool = False
- tool_call: bool = False
- attachment: bool = False # supports image/file attachments (vision)
- temperature: bool = False
- structured_output: bool = False
- open_weights: bool = False
- # Modalities
- input_modalities: tuple[str, ...] = () # ("text", "image", "pdf", ...)
- output_modalities: tuple[str, ...] = ()
- # Limits
- context_window: int = 0
- max_output: int = 0
- max_input: Optional[int] = None
- # Cost (per million tokens, USD)
- cost_input: float = 0.0
- cost_output: float = 0.0
- cost_cache_read: Optional[float] = None
- cost_cache_write: Optional[float] = None
- # Metadata
- knowledge_cutoff: str = ""
- release_date: str = ""
- status: str = "" # "alpha", "beta", "deprecated", or ""
- interleaved: Any = False # True or {"field": "reasoning_content"}
- def has_cost_data(self) -> bool:
- return self.cost_input > 0 or self.cost_output > 0
- def supports_vision(self) -> bool:
- return self.attachment or "image" in self.input_modalities
- def supports_pdf(self) -> bool:
- return "pdf" in self.input_modalities
- def supports_audio_input(self) -> bool:
- return "audio" in self.input_modalities
- def format_capabilities(self) -> str:
- """Human-readable capabilities, e.g. 'reasoning, tools, vision, PDF'."""
- flags = (
- (self.reasoning, "reasoning"), (self.tool_call, "tools"), (self.supports_vision(), "vision"), (self.supports_pdf(), "PDF"),
- (self.supports_audio_input(), "audio"), (self.structured_output, "structured output"), (self.open_weights, "open weights"),
- )
- return ", ".join(label for on, label in flags if on) or "basic"
- @dataclass
- class ProviderInfo:
- """Full metadata for a provider from models.dev."""
- id: str # models.dev provider ID
- name: str # display name
- env: tuple[str, ...] # env var names for API key
- api: str # base URL
- doc: str = "" # documentation URL
- model_count: int = 0
- @dataclass
- class ModelCapabilities:
- """Structured capability metadata for a model from models.dev."""
- supports_tools: bool = True
- supports_vision: Optional[bool] = None
- supports_reasoning: Optional[bool] = None
- context_window: int = 200000
- max_output_tokens: Optional[int] = None
- model_family: str = ""
- # Hermes provider names → models.dev provider IDs
- PROVIDER_TO_MODELS_DEV: dict[str, str] = {
- "openrouter": "openrouter", "novita": "novita-ai", "anthropic": "anthropic",
- "openai": "openai", "openai-api": "openai", "openai-codex": "openai", "zai": "zai",
- "kimi": "kimi-for-coding", "kimi-coding": "kimi-for-coding",
- "moonshot": "kimi-for-coding", "stepfun": "stepfun",
- "kimi-coding-cn": "kimi-for-coding", "minimax": "minimax",
- "minimax-oauth": "minimax", "minimax-cn": "minimax-cn", "deepseek": "deepseek",
- "alibaba": "alibaba", "qwen-oauth": "alibaba",
- "ai-gateway": "vercel", "opencode-zen": "opencode",
- "opencode-go": "opencode-go",
- "kilocode": "kilo", "fireworks": "fireworks-ai",
- "huggingface": "huggingface", "gemini": "google", "google": "google",
- "xai": "xai",
- "xai-oauth": "xai", # OAuth is a transport path for the same xAI catalog
- "xiaomi": "xiaomi", "nvidia": "nvidia",
- # Meta Model API (Muse Spark, api.meta.ai): models.dev keys it "meta", the
- # Hermes provider is "meta-ai"; both aliases are needed or muse-spark-*
- # falls back to the generic 256K default instead of its true 1M window.
- "meta-ai": "meta", "meta": "meta", "groq": "groq", "mistral": "mistral",
- "togetherai": "togetherai", "perplexity": "perplexity", "cohere": "cohere",
- "ollama-cloud": "ollama-cloud",
- }
- # Reverse mapping: models.dev id → Hermes ids (built lazily; many-to-one).
- _MODELS_DEV_TO_PROVIDER: Optional[dict[str, list[str]]] = None
- def _profile_models_dev_ids() -> dict[str, str]:
- """``{name: models_dev_id}`` declared by registered provider profiles the static map lacks.
- Read at lookup time (never merged into ``PROVIDER_TO_MODELS_DEV``)."""
- from providers import list_providers
- return {p.name: p.models_dev_id for p in list_providers()
- if p.models_dev_id and p.name not in PROVIDER_TO_MODELS_DEV}
- def models_dev_provider_map() -> dict[str, str]:
- """Hermes provider id → models.dev id: ``PROVIDER_TO_MODELS_DEV``, then profile ``models_dev_id``s."""
- return {**PROVIDER_TO_MODELS_DEV, **_profile_models_dev_ids()}
- def models_dev_id_for(provider: str) -> Optional[str]:
- """models.dev id for an exact Hermes provider id (static map first, then its profile), or None."""
- key = (provider or "").strip()
- if not key or key in PROVIDER_TO_MODELS_DEV:
- return PROVIDER_TO_MODELS_DEV.get(key)
- return _profile_models_dev_ids().get(key)
- def _models_dev_to_hermes_ids(mdev_id: str) -> list[str]:
- """Return the Hermes provider ids that map to *mdev_id* (may be [])."""
- global _MODELS_DEV_TO_PROVIDER
- if _MODELS_DEV_TO_PROVIDER is None:
- _MODELS_DEV_TO_PROVIDER = {}
- for hermes_id, mapped in PROVIDER_TO_MODELS_DEV.items():
- _MODELS_DEV_TO_PROVIDER.setdefault(mapped, []).append(hermes_id)
- profile_ids = [name for name, mapped in _profile_models_dev_ids().items() if mapped == mdev_id]
- return [*_MODELS_DEV_TO_PROVIDER.get(mdev_id, []), *profile_ids]
- def _dict_or_empty(value: Any) -> dict[str, Any]:
- return value if isinstance(value, dict) else {}
- def _configured_catalog_provider(
- provider: str, *, config: Optional[dict[str, Any]] = None,
- ) -> Optional[str]:
- """``catalog_provider`` declared on a custom provider's ``providers.<name>`` row (or legacy
- ``custom_providers[]`` entry): the catalogued vendor whose models it resells. None when unset."""
- name = (provider or "").strip()
- if name.lower().startswith("custom:"):
- name = name[len("custom:"):]
- if not name or models_dev_id_for(name) is not None:
- return None
- provider_config = (
- _cfg_get("providers", name, default=None, config=config)
- if config is not None
- else _cfg_get("providers", name, default=None)
- )
- alias = _dict_or_empty(provider_config).get("catalog_provider")
- if not alias:
- legacy = (
- _cfg_get("custom_providers", default=None, config=config)
- if config is not None
- else _cfg_get("custom_providers", default=None)
- )
- alias = next((e.get("catalog_provider") for e in (legacy if isinstance(legacy, list) else [])
- if isinstance(e, dict) and str(e.get("name") or "").strip() == name), None)
- alias = str(alias or "").strip()
- return alias or None
- def _models_dev_id(
- provider: str, *, config: Optional[dict[str, Any]] = None,
- ) -> Optional[str]:
- """models.dev provider id for a Hermes provider id, or None. A custom provider reaches the
- catalog only through its configured ``catalog_provider`` alias (#112649)."""
- key = (provider or "").strip()
- mdev_id = models_dev_id_for(key)
- if mdev_id is None:
- alias = _configured_catalog_provider(key, config=config)
- mdev_id = (models_dev_id_for(alias) or alias) if alias else None
- if mdev_id is not None and mdev_id not in models_dev_provider_map().values() \
- and mdev_id not in fetch_models_dev(allow_network=False):
- # A mistyped alias must not leak into ModelInfo.provider_id; the row stays on its own slug.
- if (key, alias) not in _UNKNOWN_CATALOG_PROVIDER_WARNED:
- _UNKNOWN_CATALOG_PROVIDER_WARNED.add((key, alias))
- logger.warning("providers.%s: catalog_provider %r is neither a Hermes provider id nor a "
- "models.dev id; ignoring", key, alias)
- mdev_id = None
- return mdev_id
- _UNKNOWN_CATALOG_PROVIDER_WARNED: set = set() # (provider, alias) warned once per process
- def _cfg_get(*keys: str, default: Any, config: Optional[dict[str, Any]] = None) -> Any:
- """``cfg_get`` over the read-only config; *default* on any failure."""
- try:
- from hermes_cli.config import cfg_get, load_config_readonly
- return cfg_get(config if config is not None else load_config_readonly(), *keys, default=default)
- except Exception:
- return default
- def _hermes_path(name: str) -> Path:
- from hermes_constants import get_hermes_home
- return get_hermes_home() / name
- def _get_cache_path() -> Path:
- return _hermes_path("models_dev_cache.json")
- def _get_etag_path() -> Path:
- return _hermes_path("models_dev_cache.etag")
- def _quietly(what: str, fn, default=None):
- """Run *fn*; on any exception log ``"Failed to <what>: %s"`` at debug and return *default*."""
- try:
- return fn()
- except Exception as e:
- logger.debug("Failed to %s: %s", what, e)
- return default
- def _load_etag() -> str:
- """Last-known ETag from disk, or "" if missing."""
- return _quietly("load models.dev ETag", lambda: _get_etag_path().read_text(encoding="utf-8-sig").strip() if _get_etag_path().exists() else "", "")
- def _save_etag(etag: str) -> None:
- def write() -> None:
- etag_path = _get_etag_path()
- from hermes_constants import mkdir_under_hermes_home
- mkdir_under_hermes_home(etag_path.parent)
- atomic_write_text(etag_path, etag)
- _quietly("save models.dev ETag", write)
- def _clear_etag() -> None:
- """Delete the ETag sidecar so the next fetch is unconditional: an If-None-Match without a
- servable cache invites a 304 that leaves the process with no data at all."""
- _quietly("clear models.dev ETag", lambda: _get_etag_path().unlink(missing_ok=True))
- def _get_models_dev_url() -> str:
- """The models.dev API URL, honoring the ``models_dev.url`` config override."""
- url = _cfg_get("models_dev", "url", default="")
- # Module global (not a captured constant) so patching MODELS_DEV_URL works.
- return url.strip() if isinstance(url, str) and url.strip() else MODELS_DEV_URL
- def _validate_registry(data: Any) -> bool:
- """True if *data* is a non-empty dict suitable for serving."""
- return isinstance(data, dict) and len(data) > 0
- def _load_disk_cache() -> dict[str, Any]:
- """Load the disk cache; a corrupt/empty one is quarantined with a warning so it never
- masquerades as ``{}`` and breaks provider/model resolution."""
- try:
- cache_path = _get_cache_path()
- if cache_path.exists():
- with open(cache_path, encoding="utf-8-sig") as f:
- data = json.load(f)
- if _validate_registry(data):
- return data
- logger.warning("models.dev disk cache is corrupt or empty; quarantining (will refetch from network)")
- _quarantine_corrupt_cache(cache_path)
- except Exception as e:
- logger.warning("Failed to load models.dev disk cache; quarantining: %s", e)
- with contextlib.suppress(Exception):
- _quarantine_corrupt_cache(_get_cache_path())
- return {}
- def _quarantine_corrupt_cache(cache_path: Path) -> None:
- """Rename a rejected cache aside and drop its ETag sidecar. Renaming makes the rejection a
- one-time event — otherwise every hot-path call that finds the in-memory cache empty re-parses
- and re-warns until a network fetch succeeds. The sidecar vouches for a registry we no longer hold."""
- try:
- cache_path.rename(cache_path.with_suffix(".json.corrupt"))
- except Exception as e:
- logger.debug("Could not quarantine corrupt models.dev cache: %s", e)
- _clear_etag()
- def _disk_cache_age_seconds() -> Optional[float]:
- """Age of the disk cache file in seconds, or None if missing/unreadable. An mtime in the future
- (clock skew) is also None — unknown freshness — so callers fall through to the network."""
- def stat() -> Optional[float]:
- cache_path = _get_cache_path()
- age = time.time() - cache_path.stat().st_mtime if cache_path.exists() else -1
- return age if age >= 0 else None
- return _quietly("stat models.dev disk cache", stat)
- def _save_disk_cache(data: dict[str, Any], etag: str = "") -> None:
- """Save the registry atomically, plus the ETag sidecar when non-empty."""
- _quietly("save models.dev disk cache", lambda: atomic_json_write(_get_cache_path(), data, indent=None, separators=(",", ":")))
- if etag:
- _save_etag(etag)
- # Network refresh: all state mutation happens under _models_dev_fetch_lock.
- class _NotModified(Exception):
- """Server returned 304 Not Modified — existing cache is still valid."""
- def _fetch_models_dev_from_network(*, conditional: bool = False) -> tuple[dict[str, Any], str]:
- """Fetch the live registry; returns ``(registry, etag)`` (etag "" if none). Raises on network
- errors and on an empty/invalid payload. ``conditional`` sends ``If-None-Match`` with the sidecar's
- ETag and raises ``_NotModified`` on 304 — pass True ONLY while holding ``_models_dev_fetch_lock``
- AND a servable registry, or a 304 leaves the process with no data."""
- from agent.deadline import DeadlineExpired, run_bounded_sync
- headers: dict[str, str] = {}
- if conditional and (etag := _load_etag()):
- headers["If-None-Match"] = etag
- url = _get_models_dev_url()
- # A download abandoned at the deadline keeps its thread and socket until the server stops; it
- # owns this slot until then, so a later attempt (force_refresh skips the backoff) fails fast
- # instead of stacking a second transfer on the same slow link.
- if not _models_dev_download_slot.acquire(blocking=False):
- raise RuntimeError("an abandoned models.dev download is still running")
- started = threading.Event()
- def download() -> tuple[int, Any, str]:
- started.set()
- try:
- # (connect, read) bounds each socket op, not the download: a trickling body never trips it.
- response = requests.get(url, headers=headers, timeout=(5, 10))
- if response.status_code == 304:
- return 304, None, ""
- response.raise_for_status()
- return response.status_code, response.json(), response.headers.get("ETag", "")
- finally:
- _models_dev_download_slot.release()
- # The cold-cache fetch runs inside a caller's request (a fresh home's first session.create
- # reaches it through tool availability), so the whole exchange, DNS included, gets one
- # wall-clock cap; on expiry the caller falls back to the stale/empty cache and the backoff.
- try:
- bounded = run_bounded_sync(download, _MODELS_DEV_FETCH_DEADLINE, label="models.dev fetch")
- except BaseException:
- if not started.is_set(): # the worker never ran (thread start failed), so the slot is ours
- _models_dev_download_slot.release()
- raise
- if bounded.timed_out:
- raise DeadlineExpired("models.dev fetch", _MODELS_DEV_FETCH_DEADLINE)
- status, data, etag = bounded.value
- if status == 304:
- raise _NotModified()
- if not _validate_registry(data):
- raise ValueError("models.dev returned an empty or invalid registry")
- return data, etag
- def _mark_stale_cache_grace() -> None:
- """Give stale cache data a 5-minute in-memory grace before retrying refresh. Only ever moves the
- timestamp forward, so a background refresh that completed meanwhile keeps its fresh stamp."""
- global _models_dev_cache_time
- _models_dev_cache_time = max(_models_dev_cache_time, time.time() - _MODELS_DEV_CACHE_TTL + _MODELS_DEV_RETRY_DELAY)
- def _serve_stale(msg: str, *args: Any) -> dict[str, Any]:
- """Arm the grace window, kick off a background refresh, return the held cache."""
- _mark_stale_cache_grace()
- _start_background_refresh_models_dev()
- logger.debug(msg, *args)
- return _models_dev_cache
- def _commit_registry(data: dict[str, Any], *, etag: str = "", where: str) -> None:
- """Persist a fetched registry: disk + in-mem + clear backoff. Callers hold ``_models_dev_fetch_lock``
- so a failing refresh on one path can never stomp state a succeeding refresh just committed."""
- global _models_dev_cache, _models_dev_cache_time, _models_dev_retry_after
- _save_disk_cache(data, etag)
- _models_dev_cache = data
- _models_dev_cache_time = time.time()
- _models_dev_retry_after = 0
- logger.debug(
- "Refreshed models.dev registry (%s): %d providers, %d total models", where, len(data),
- sum(len(p.get("models", {})) for p in data.values() if isinstance(p, dict)),
- )
- def _confirm_cache_not_modified(*, where: str) -> None:
- """After a 304: clear backoff and re-mark the held cache fresh (disk is untouched — only the
- freshness marker advances). Caller holds the lock."""
- global _models_dev_cache_time, _models_dev_retry_after
- if not _models_dev_cache:
- # Should be unreachable (conditional GETs require a servable cache) but previously caused a
- # permanent empty-registry loop: drop the sidecar and arm the backoff rather than marking {} "fresh".
- _clear_etag()
- _models_dev_retry_after = time.time() + _MODELS_DEV_RETRY_DELAY
- logger.warning("models.dev returned 304 but no cached registry is held (%s); "
- "cleared ETag sidecar, will refetch unconditionally", where)
- return
- _models_dev_cache_time = time.time()
- _models_dev_retry_after = 0
- logger.debug("models.dev registry unchanged (304 Not Modified, %s); cache re-confirmed fresh", where)
- def _note_refresh_failure(exc: Exception, *, where: str) -> None:
- """Arm the process-wide 5-minute backoff. Caller holds the lock."""
- global _models_dev_retry_after
- _models_dev_retry_after = time.time() + _MODELS_DEV_RETRY_DELAY
- logger.debug("models.dev refresh failed (%s); retry suppressed for %ds: %s", where, _MODELS_DEV_RETRY_DELAY, exc)
- def _refresh_locked(where: str) -> Optional[dict[str, Any]]:
- """One conditional fetch + state update; caller holds ``_models_dev_fetch_lock``. Returns the
- registry to serve, or None when the fetch failed (backoff armed)."""
- try:
- data, etag = _fetch_models_dev_from_network(conditional=bool(_models_dev_cache))
- _commit_registry(data, etag=etag, where=where)
- return data
- except _NotModified:
- _confirm_cache_not_modified(where=where)
- return _models_dev_cache
- except Exception as e:
- _note_refresh_failure(e, where=where)
- return None
- def _background_refresh_models_dev() -> None:
- """Best-effort refresh after serving stale cache data."""
- global _models_dev_refresh_in_flight
- try:
- # Fetch INSIDE the lock, symmetric with the foreground path: the conditional-GET inputs (memory
- # cache + sidecar) can't be mutated mid-fetch by a concurrent force_refresh and the two paths
- # can't double-download. Hot-path callers never touch this lock.
- with _models_dev_fetch_lock:
- _refresh_locked("background")
- finally:
- with _models_dev_refresh_lock:
- _models_dev_refresh_in_flight = False
- def _start_background_refresh_models_dev() -> None:
- """Start one daemon refresh worker if none is running and the failure backoff has elapsed."""
- global _models_dev_refresh_in_flight
- if time.time() < _models_dev_retry_after:
- return
- with _models_dev_refresh_lock:
- if _models_dev_refresh_in_flight:
- return
- _models_dev_refresh_in_flight = True
- thread = threading.Thread(target=_background_refresh_models_dev, name="models-dev-refresh", daemon=True)
- try:
- thread.start()
- except Exception as e:
- # Thread/fd exhaustion: clear the flag so refresh isn't disabled for the rest of the process.
- with _models_dev_refresh_lock:
- _models_dev_refresh_in_flight = False
- logger.debug("Failed to start models.dev refresh thread: %s", e)
- def fetch_models_dev(force_refresh: bool = False, *, allow_network: bool = True) -> dict[str, Any]:
- """Fetch the models.dev registry (dict keyed by provider ID; {} on failure). Cache hierarchy:
- fresh in-memory → stale in-memory (served now, refreshed in one background daemon thread — stale
- beats a foreground timeout) → disk of any age (stale triggers the same background refresh) →
- singleflight foreground fetch. A failed refresh suppresses automatic refreshes for 5 minutes.
- ``force_refresh=True`` bypasses the cache fast paths and the backoff, falling back to cached data
- only if the call fails. ``allow_network=False`` returns any memory/disk cache and never makes a request."""
- global _models_dev_cache, _models_dev_cache_time, _models_dev_retry_after
- if not allow_network:
- if not _models_dev_cache and (disk_data := _load_disk_cache()):
- _models_dev_cache = disk_data
- disk_age = _disk_cache_age_seconds()
- _models_dev_cache_time = time.time() - disk_age if disk_age is not None else 0
- return _models_dev_cache
- if not force_refresh:
- # Stage 1: fresh in-memory cache — the hot path, no I/O.
- if _models_dev_cache and (time.time() - _models_dev_cache_time) < _MODELS_DEV_CACHE_TTL:
- return _models_dev_cache
- # Stage 2: stale in-memory cache beats blocking on the network.
- if _models_dev_cache:
- return _serve_stale("Using stale in-memory models.dev cache; refreshing in background")
- # Stage 3: disk cache (cold-start only). A stale disk cache is deliberately usable so
- # resolution doesn't hang when models.dev is unreachable.
- disk_age = _disk_cache_age_seconds()
- if disk_age is not None and (disk_data := _load_disk_cache()):
- _models_dev_cache = disk_data
- if disk_age >= _MODELS_DEV_CACHE_TTL:
- return _serve_stale("Using stale models.dev disk cache (age=%.0fs); refreshing in background", disk_age)
- # Anchor the in-mem TTL to the file's age so an aging cache isn't extended by another full TTL.
- _models_dev_cache_time = time.time() - disk_age
- logger.debug("Loaded models.dev from fresh disk cache (%d providers, age=%.0fs)", len(disk_data), disk_age)
- return _models_dev_cache
- # Process-wide backoff: don't make every caller retry an unreachable endpoint while no usable cache exists.
- if time.time() < _models_dev_retry_after:
- return _models_dev_cache
- # Stage 4: singleflight foreground fetch. Recheck state under the lock — another caller may
- # have refreshed or armed the backoff while we waited.
- with _models_dev_fetch_lock:
- if not force_refresh and (_models_dev_cache or time.time() < _models_dev_retry_after):
- return _models_dev_cache
- # Cold force_refresh: stages 1-3 were skipped, so hydrate memory from disk first so the
- # conditional GET fires and a 304 can re-confirm it.
- if force_refresh and not _models_dev_cache and (disk := _load_disk_cache()):
- _models_dev_cache = disk
- _models_dev_cache_time = 0 # servable but not fresh
- served = _refresh_locked("foreground")
- if served is not None:
- return served
- # Stage 5: network failed — serve any stale memory/disk cache. Freshness stays expired;
- # the retry-after timestamp gates the next attempt.
- if not _models_dev_cache:
- _models_dev_cache = _load_disk_cache()
- _models_dev_cache_time = 0
- if _models_dev_cache:
- logger.debug("Loaded stale models.dev disk cache (%d providers)", len(_models_dev_cache))
- return _models_dev_cache
- def _registry_provider(mdev_id: str, allow_network: bool) -> Optional[dict[str, Any]]:
- """The raw models.dev provider entry, or None."""
- # Keep the zero-argument call on the allow_network path: dozens of test sites monkeypatch fetch_models_dev with zero-arg lambdas.
- registry = fetch_models_dev() if allow_network else fetch_models_dev(allow_network=False)
- provider_data = registry.get(mdev_id)
- return provider_data if isinstance(provider_data, dict) else None
- def _registry_models(mdev_id: str, *, allow_network: bool) -> Optional[dict[str, Any]]:
- """The ``models`` dict of a models.dev provider entry, or None."""
- provider_data = _registry_provider(mdev_id, allow_network)
- models = provider_data.get("models", {}) if provider_data is not None else None
- return models if isinstance(models, dict) else None
- def _get_provider_models(
- provider: str, *, allow_network: bool = False, config: Optional[dict[str, Any]] = None,
- ) -> Optional[dict[str, Any]]:
- """Resolve a Hermes provider ID to its models dict, or None if unknown.
- ``allow_network`` defaults to False — hot-path callers must never block."""
- mdev_id = _models_dev_id(provider, config=config)
- return _registry_models(mdev_id, allow_network=allow_network) if mdev_id else None
- _OPENROUTER_CATALOG_PROVIDERS = frozenset({"openrouter"})
- def _openrouter_catalog_lookup_base(provider: str, model: str) -> Optional[str]:
- """Return the base id to retry a catalog lookup with, or ``None``.
- OpenRouter's ``:nitro`` / ``:floor`` / ``:exacto`` / ``:online`` are
- request-time routing modifiers: they change which endpoint serves the
- request, never which model runs. ``/models`` and models.dev list only the
- base id, so a routed id must resolve to the base model's metadata.
- Scoped to OpenRouter so a genuine ``model:tag`` on another provider (an
- Ollama tag, a ``:cloud`` catalog key) is never rewritten.
- Deliberately excludes ``:free``, ``:batch``, ``:extended``, and
- ``:thinking``: those are REAL catalog SKUs with their own entries and
- their own — sometimes different — context windows. Stripping them would
- report a window LARGER than the model actually has. Their real entries
- are found by the exact/case-insensitive passes above, and a genuinely
- absent SKU must miss so ``model_overrides`` ``_default`` fill-gap
- semantics still apply.
- """
- if provider not in _OPENROUTER_CATALOG_PROVIDERS:
- return None
- return openrouter_variant_base(model)
- def _iter_model_entries(
- models: dict[str, Any], model: str, *, suffix_fallback: bool = True, provider: str = ""
- ):
- """Yield ``(model_id, entry)`` candidates: exact, case-insensitive, then (optionally)
- ``:cloud``/``-cloud`` suffixed forms. Suffix fallback: some providers (ollama-cloud) store
- ``kimi-k2.6:cloud`` while the live API returns the bare name; without it context lookup falls to
- stale OpenRouter metadata and trips the 64k minimum-context guard. Every consumer shares this
- order so a suffix-keyed catalog model counts as KNOWN for ``model_overrides`` fill-gap ``_default``.
- ``provider`` enables the OpenRouter routing-variant fallback as a LAST
- resort — after exact, case-insensitive, and ``:cloud`` matching — so a
- real catalog SKU always wins over its base.
- """
- for name in ([model] + [model + suffix for suffix in (":cloud", "-cloud")] if suffix_fallback else [model]):
- entry = models.get(name)
- if isinstance(entry, dict):
- yield name, entry
- name_lower = name.lower()
- for mid, mdata in models.items():
- if mid.lower() == name_lower and isinstance(mdata, dict):
- yield mid, mdata
- routed_base = _openrouter_catalog_lookup_base(provider, model)
- if routed_base is not None:
- # Recursion is bounded: the base never carries a recognized variant suffix,
- # and provider is cleared so the retry cannot loop.
- yield from _iter_model_entries(
- models, routed_base, suffix_fallback=suffix_fallback, provider=""
- )
- def _find_model_entry(
- models: dict[str, Any], model: str, provider: str = ""
- ) -> Optional[dict[str, Any]]:
- """First catalog entry for *model* (exact, case-insensitive, suffix), or None."""
- return next((entry for _mid, entry in _iter_model_entries(models, model, provider=provider)), None)
- def _extract_limit(entry: Any, key: str) -> Optional[int]:
- """Positive int ``entry.limit[key]`` or None (audio/image models have context=0)."""
- value = _dict_or_empty(_dict_or_empty(entry).get("limit")).get(key)
- return int(value) if isinstance(value, (int, float)) and value > 0 else None
- def _extract_context(entry: dict[str, Any]) -> Optional[int]:
- """Context length from a models.dev model entry, or None if invalid/zero."""
- return _extract_limit(entry, "context")
- def lookup_models_dev_context(provider: str, model: str, *, allow_network: bool = False) -> Optional[int]:
- """Context window in tokens for provider+model, or None if not found. An EXPLICIT ``model_overrides``
- entry wins over the catalog; ``_default`` fills the gap only when the catalog has no answer (the
- self-unblock path for wrong/missing context in models.dev). Catalog entries with context=0 are
- skipped in favour of later candidates. ``allow_network`` defaults to False — runs every turn.
- See #84482.
- """
- override_ctx = _override_context_window(provider, model)
- if override_ctx is not None:
- return override_ctx
- declared_ctx = _override_int(_provider_model_capabilities(provider, model), "context_window")
- if declared_ctx is not None:
- return declared_ctx
- models = _get_provider_models(provider, allow_network=allow_network)
- catalog_ctx = next((ctx for _mid, entry in _iter_model_entries(models, model, provider=provider) if (ctx := _extract_context(entry))), None) if models is not None else None
- return catalog_ctx if catalog_ctx is not None else _default_override_context(provider)
- # Per-model overrides (config.yaml → model_overrides). Canonical schema (the ONLY key space consumers
- # accept): context_window, supports_tools, supports_vision, supports_reasoning,
- # model_family. ``<provider>.<model_id>`` is an explicit partial patch that always wins over the
- # catalog. ``<provider>._default`` / top-level ``_default`` are FILL-GAP defaults: they apply ONLY to
- # models the catalog does not know and never displace catalog data. Provider keys accept the Hermes
- # or models.dev id; model ids match exactly, then case-insensitively (mirroring catalog lookup).
- # Resolution semantics: 1. 2. See #84482, #8731.
- _OVERRIDE_WARNED_KEYS: set = set()
- # Safe defaults for models absent from the catalog (tools on, 200K context). Capability fields and the
- # output limit stay absent so consumers see them as unknown instead of a synthesized value.
- _UNKNOWN_MODEL_BASE: dict[str, Any] = {"limit": {"context": 200000}, "tool_call": True}
- # Account-gated models may be usable before models.dev has indexed them. Keep
- # their capabilities available for an explicitly selected/discovered model
- # without adding them to any picker catalog.
- _DEEPSEEK_FLASH_VISION: dict[str, Any] = {
- "limit": {"context": 1_000_000, "output": 384_000},
- "modalities": {"input": ["text", "image"], "output": ["text"]},
- "tool_call": True,
- "reasoning": True,
- "family": "deepseek-flash",
- }
- _BUILTIN_MODEL_METADATA: dict[tuple[str, str], dict[str, Any]] = {
- ("openai", "gpt-6-astra"): {
- "limit": {"context": 1_050_000, "output": 128_000},
- "modalities": {"input": ["text", "image"], "output": ["text"]},
- "tool_call": True,
- "reasoning": True,
- "family": "gpt-6",
- },
- # Native DeepSeek V4.1-Flash is multimodal (https://api-docs.deepseek.com/guides/vision).
- # models.dev lagged the 2026-09-10 rename; without this, a cold/empty cache treats
- # ``deepseek-flash`` as unknown → image_input_mode falls through to lossy text.
- # ``deepseek-v4-pro`` stays catalog-only: vendor docs still mark it text-only.
- ("deepseek", "deepseek-flash"): _DEEPSEEK_FLASH_VISION,
- ("deepseek", "deepseek-v4-flash"): _DEEPSEEK_FLASH_VISION,
- ("deepseek", "deepseek-v4.1-flash"): _DEEPSEEK_FLASH_VISION,
- ("deepseek", "deepseek-v4-flash-vision-exp"): _DEEPSEEK_FLASH_VISION,
- }
- def _load_model_overrides(*, config: Optional[dict[str, Any]] = None) -> dict[str, Any]:
- """The ``model_overrides`` config section ({} on any failure). Deliberately not memoized:
- ``load_config_readonly()`` is already (mtime, size)-cached upstream, and an ``id(cfg)``-keyed
- layer can serve stale overrides after a reload when CPython reuses the dict address."""
- overrides = (
- _cfg_get("model_overrides", default={}, config=config)
- if config is not None
- else _cfg_get("model_overrides", default={})
- )
- return _dict_or_empty(overrides)
- def _provider_override_section(provider: str, *, config: Optional[dict[str, Any]] = None) -> Optional[dict[str, Any]]:
- """Override section for *provider* (keyed by Hermes OR models.dev id), or None."""
- overrides = (
- _load_model_overrides(config=config)
- if config is not None
- else _load_model_overrides()
- )
- provider_key = (provider or "").strip()
- if not overrides or not provider_key:
- return None
- # Forward (Hermes → models.dev id) and reverse (caller passed a models.dev id, config keyed by Hermes id) aliases.
- candidates = [provider_key, models_dev_id_for(provider_key), *_models_dev_to_hermes_ids(provider_key)]
- return next((section for section in (overrides.get(key) if key else None for key in candidates) if isinstance(section, dict)), None)
- def _explicit_model_override(provider: str, model: str, *, config: Optional[dict[str, Any]] = None) -> Optional[dict[str, Any]]:
- """Explicit per-provider+model override dict (exact, then case-insensitive skipping the ``_default`` sentinel), or None."""
- model_key = (model or "").strip()
- section = _provider_override_section(provider, config=config) if model_key else None
- if section is None:
- return None
- entry = section.get(model_key)
- if isinstance(entry, dict):
- return entry
- model_lower = model_key.lower()
- return next((mdata for mid, mdata in section.items() if mid != "_default" and mid.lower() == model_lower and isinstance(mdata, dict)), None)
- def _default_model_override(provider: str, *, config: Optional[dict[str, Any]] = None) -> Optional[dict[str, Any]]:
- """Fill-gap ``_default`` override: per-provider first, then global; or None."""
- section = _provider_override_section(provider, config=config)
- if section is not None and isinstance(section.get("_default"), dict):
- return section["_default"]
- overrides = (
- _load_model_overrides(config=config)
- if config is not None
- else _load_model_overrides()
- )
- global_default = overrides.get("_default")
- return global_default if isinstance(global_default, dict) else None
- def _override_for(
- provider: str, model: str, *, catalog_hit: bool, config: Optional[dict[str, Any]] = None,
- ) -> Optional[dict[str, Any]]:
- """Explicit override if any; else the ``_default`` only on a catalog miss."""
- explicit = _explicit_model_override(provider, model, config=config)
- return explicit if explicit is not None or catalog_hit else _default_model_override(provider, config=config)
- def _override_int(override: dict[str, Any], key: str) -> Optional[int]:
- """Coerce an override field to a positive int, warning once on garbage."""
- raw = override.get(key)
- if raw is None:
- return None
- with contextlib.suppress(TypeError, ValueError):
- value = int(raw)
- if value > 0:
- return value
- warn_key = (key, repr(raw))
- if warn_key not in _OVERRIDE_WARNED_KEYS:
- _OVERRIDE_WARNED_KEYS.add(warn_key)
- logger.warning("model_overrides: ignoring invalid %s value %r (expected a positive integer)", key, raw)
- return None
- def _override_context_window(provider: str, model: str) -> Optional[int]:
- """EXPLICITLY overridden context_window, or None. Explicit-only on purpose: this runs early in the
- resolution chain (agent/model_metadata.py, before custom_providers and live probes) where a
- ``_default`` must not preempt more specific sources; fill-gap defaults apply in ``lookup_models_dev_context``."""
- ov = _explicit_model_override(provider, model)
- return _override_int(ov, "context_window") if ov is not None else None
- # Catalog miss — a _default override may fill the gap (#84482).
- def _default_override_context(provider: str) -> Optional[int]:
- """Fill-gap context from a ``_default`` override, for catalog misses."""
- default = _default_model_override(provider)
- return _override_int(default, "context_window") if default is not None else None
- def _override_to_catalog_shape(override: dict[str, Any]) -> tuple[dict[str, Any], Optional[bool]]:
- """Translate canonical override keys into a models.dev-shaped patch. Returns ``(patch, vision)`` —
- vision is out-of-band because it maps onto the ``modalities.input`` list rather than a scalar field."""
- patch: dict[str, Any] = {}
- limit = {
- catalog_key: value for catalog_key, override_key in (("context", "context_window"),)
- if (value := _override_int(override, override_key)) is not None
- }
- if limit:
- patch["limit"] = limit
- for override_key, catalog_key in (("supports_tools", "tool_call"), ("supports_reasoning", "reasoning")):
- if override_key in override:
- patch[catalog_key] = bool(override[override_key])
- vision: Optional[bool] = None
- if "supports_vision" in override:
- vision = patch["attachment"] = bool(override["supports_vision"])
- if "model_family" in override:
- patch["family"] = str(override["model_family"] or "")
- return patch, vision
- def _merge_catalog_entry_with_override(raw: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
- """Patch a catalog entry with a canonical-schema override. Sub-dicts (``limit``, ``modalities``) are
- merged, not clobbered — setting only ``context_window`` must not wipe the catalog's ``limit.output``."""
- shaped, vision_override = _override_to_catalog_shape(override)
- merged = dict(raw)
- limit_patch = shaped.pop("limit", None)
- if limit_patch:
- merged["limit"] = {**_dict_or_empty(raw.get("limit")), **limit_patch}
- if vision_override is not None:
- base_mods = dict(_dict_or_empty(raw.get("modalities")))
- input_mods = base_mods.get("input")
- input_mods = list(input_mods) if isinstance(input_mods, list) else []
- if vision_override and "image" not in input_mods:
- input_mods.append("image")
- elif not vision_override and "image" in input_mods:
- input_mods.remove("image")
- base_mods["input"] = input_mods
- merged["modalities"] = base_mods
- merged.update(shaped)
- return merged
- def _builtin_model_metadata(
- provider: str, model: str, *, config: Optional[dict[str, Any]] = None,
- ) -> Optional[dict[str, Any]]:
- """Built-in metadata for a provider/model pair, if Hermes has a vendor-specific entry."""
- provider_key = _models_dev_id(provider, config=config) or (provider or "").strip()
- return _BUILTIN_MODEL_METADATA.get((provider_key, (model or "").strip().lower()))
- def _relay_vision_marker_metadata(provider: str, model: str) -> Optional[dict[str, Any]]:
- """Fill-gap base for an OpenCode Zen/Go ``*-vision*`` model id the catalog does not know. The relays
- resell vendor previews (``deepseek-v4-flash-vision-exp``) before models.dev indexes them, and the id's
- ``-vision`` token is the vendor's own capability marker; without it ``image_input_mode: auto`` treats
- the model as text-only and detours images through the lossy describe path (#96066). Every other field
- keeps the unknown-model defaults, so only vision is claimed."""
- from hermes_cli.models import opencode_provider_family
- if "-vision" not in (model or "").strip().lower() or opencode_provider_family(provider) is None:
- return None
- return {**_UNKNOWN_MODEL_BASE, "modalities": {"input": ["text", "image"], "output": ["text"]}}
- def _provider_model_capabilities(provider: str, model: str) -> dict[str, Any]:
- """Exact-model declaration from the registered ``ProviderProfile.model_capabilities`` (canonical
- ``model_overrides`` schema). The ONE plugin seam: every consumer that reads models.dev through this
- module (picker badges, image routing, ``/api/model/info``, context lookup) sees it (#102115)."""
- from providers import get_provider_profile
- profile = get_provider_profile(provider)
- return profile.model_capabilities.get(model, {}) if profile is not None else {}
- def _apply_overrides(
- provider: str, model: str, entry: Optional[dict[str, Any]], *, config: Optional[dict[str, Any]] = None,
- ) -> Optional[dict[str, Any]]:
- """Catalog/builtin metadata, patched by the plugin's declaration, then by the explicit user override.
- ``_UNKNOWN_MODEL_BASE`` is the base on a catalog miss; a fill-gap ``_default`` applies only when no
- source knows the model. None when nothing knows it."""
- builtin = _builtin_model_metadata(provider, model, config=config)
- base = entry if entry is not None else builtin
- declared = _provider_model_capabilities(provider, model)
- if declared:
- base = _merge_catalog_entry_with_override(base if base is not None else _UNKNOWN_MODEL_BASE, declared)
- override = _override_for(provider, model, catalog_hit=base is not None, config=config)
- if base is None:
- base = _relay_vision_marker_metadata(provider, model)
- return base if override is None else _merge_catalog_entry_with_override(base if base is not None else _UNKNOWN_MODEL_BASE, override)
- def _entry_supports_vision(entry: dict[str, Any]) -> bool:
- """Prefer explicit ``modalities.input`` (the older ``attachment`` flag can be stale or too broad
- for image routing); fall back to it only when the input modalities are absent/invalid."""
- input_mods = _dict_or_empty(entry.get("modalities", {})).get("input")
- return "image" in input_mods if isinstance(input_mods, list) else bool(entry.get("attachment", False))
- def get_model_capabilities(
- provider: str, model: str, *, allow_network: bool = False, config: Optional[dict[str, Any]] = None,
- ) -> Optional[ModelCapabilities]:
- """Capability metadata from the models.dev cache, or None if unresolvable. EXPLICIT ``model_overrides``
- patch catalog fields; ``_default`` fills the gap only for models the catalog does not know. Unspecified
- fields fall through to the catalog, or to safe defaults. ``allow_network`` defaults to False (hot path).
- EXPLICIT ``model_overrides`` entries (per-provider+model) win over catalog values for the fields they
- set. ``_default`` entries fill the gap only for models the catalog does not know — the supported
- self-unblock path for custom/local models (#8731) and for models with wrong metadata in models.dev
- (#84482).
- """
- models = _get_provider_models(provider, allow_network=allow_network, config=config)
- entry = _find_model_entry(models, model, provider) if models is not None else None
- unknown_base = (
- entry is None
- and _builtin_model_metadata(provider, model, config=config) is None
- )
- raw = _apply_overrides(provider, model, entry, config=config)
- if raw is None:
- return None
- return ModelCapabilities(
- supports_tools=bool(raw.get("tool_call", False)),
- supports_vision=(
- None
- if unknown_base and "attachment" not in raw and "modalities" not in raw
- else _entry_supports_vision(raw)
- ),
- supports_reasoning=None if unknown_base and "reasoning" not in raw else bool(raw.get("reasoning", False)),
- context_window=_extract_limit(raw, "context") or 200000,
- max_output_tokens=_extract_limit(raw, "output"),
- model_family=raw.get("family", "") or "",
- )
- def list_provider_models(provider: str, *, allow_network: bool = True) -> list[str]:
- """All model IDs for a provider ([] if unknown). ``allow_network`` defaults to True: the model
- picker is interactive and a fresh catalog is worth a short wait."""
- from hermes_cli.models import normalize_provider
- provider = normalize_provider(provider) or provider
- models = _get_provider_models(provider, allow_network=allow_network)
- return [mid for mid in models if not _should_hide_from_provider_catalog(provider, mid)] if models is not None else []
- # Non-agentic or noise models (TTS, embedding, dated preview snapshots, live/streaming-only, image-only).
- _NOISE_PATTERNS: re.Pattern = re.compile(
- r"-tts\b|embedding|live-|-(preview|exp)-\d{2,4}[-_]|" r"-image\b|-image-preview\b|-customtools\b", re.IGNORECASE)
- # Hidden from the Gemini catalogs surfaced in setup/model selection (capability metadata stays available for direct use).
- _GOOGLE_HIDDEN_MODELS = frozenset({
- # Low-TPM Gemma models that trip Google input-token quota walls under agent-style traffic.
- "gemma-4-31b-it", "gemma-4-26b-it", "gemma-4-26b-a4b-it",
- "gemma-3-1b", "gemma-3-1b-it", "gemma-3-2b", "gemma-3-2b-it",
- "gemma-3-4b", "gemma-3-4b-it", "gemma-3-12b", "gemma-3-12b-it",
- "gemma-3-27b", "gemma-3-27b-it",
- # Stale/retired Google slugs that 404 on the current endpoints.
- "gemini-1.5-flash", "gemini-1.5-pro", "gemini-1.5-flash-8b",
- "gemini-2.0-flash", "gemini-2.0-flash-lite",
- })
- def _should_hide_from_provider_catalog(provider: str, model_id: str) -> bool:
- return (provider or "").strip().lower() in {"gemini", "google"} and (model_id or "").strip().lower() in _GOOGLE_HIDDEN_MODELS
- def list_agentic_models(provider: str, *, allow_network: bool = True) -> list[str]:
- """Model IDs suitable for agentic use: tool_call=True, minus hidden and noise models. [] on any
- failure. ``allow_network`` defaults to True (called from interactive model selection)."""
- models = _get_provider_models(provider, allow_network=allow_network)
- return [
- mid for mid, entry in models.items()
- if isinstance(entry, dict) and not _should_hide_from_provider_catalog(provider, mid) and entry.get("tool_call", False) and not _NOISE_PATTERNS.search(mid)
- ] if models is not None else []
- def _parse_model_info(model_id: str, raw: dict[str, Any], provider_id: str) -> ModelInfo:
- """Convert a raw models.dev model entry dict into a ModelInfo dataclass."""
- cost = _dict_or_empty(raw.get("cost"))
- modalities = _dict_or_empty(raw.get("modalities"))
- def _mods(key: str) -> tuple[str, ...]:
- mods = modalities.get(key) or []
- return tuple(mods) if isinstance(mods, list) else ()
- def _cost(key: str) -> Optional[float]:
- return float(cost[key]) if cost.get(key) is not None else None
- return ModelInfo(
- id=model_id, name=raw.get("name", "") or model_id, family=raw.get("family", "") or "", provider_id=provider_id,
- **{k: bool(raw.get(k, False)) for k in ("reasoning", "tool_call", "attachment", "temperature", "structured_output", "open_weights")},
- input_modalities=_mods("input"), output_modalities=_mods("output"),
- context_window=_extract_limit(raw, "context") or 0, max_output=_extract_limit(raw, "output") or 0, max_input=_extract_limit(raw, "input"),
- cost_input=float(cost.get("input", 0) or 0), cost_output=float(cost.get("output", 0) or 0),
- cost_cache_read=_cost("cache_read"), cost_cache_write=_cost("cache_write"),
- knowledge_cutoff=raw.get("knowledge", "") or "", release_date=raw.get("release_date", "") or "",
- status=raw.get("status", "") or "", interleaved=raw.get("interleaved", False),
- )
- def _parse_provider_info(provider_id: str, raw: dict[str, Any]) -> ProviderInfo:
- """Convert a raw models.dev provider entry dict into a ProviderInfo."""
- env = raw.get("env") or []
- models = raw.get("models") or {}
- return ProviderInfo(
- id=provider_id, name=raw.get("name", "") or provider_id, env=tuple(env) if isinstance(env, list) else (),
- api=raw.get("api", "") or "", doc=raw.get("doc", "") or "", model_count=len(models) if isinstance(models, dict) else 0,
- )
- def get_provider_info(
- provider_id: str, *, allow_network: bool = True, config: Optional[dict[str, Any]] = None,
- ) -> Optional[ProviderInfo]:
- """Provider metadata by Hermes or models.dev ID, or None if not cataloged. ``allow_network`` defaults to True (interactive setup)."""
- mdev_id = _models_dev_id(provider_id, config=config) or provider_id
- raw = _registry_provider(mdev_id, allow_network)
- return _parse_provider_info(mdev_id, raw) if raw is not None else None
- def get_model_info(
- provider_id: str, model_id: str, *, allow_network: bool = False, config: Optional[dict[str, Any]] = None,
- ) -> Optional[ModelInfo]:
- """Full model metadata by Hermes or models.dev provider ID (exact match, then case-insensitive), or
- None if not found. EXPLICIT ``model_overrides`` patch known catalog models; ``_default`` fills the gap
- only for unknown ones. ``allow_network`` defaults to False — cost guard and inventory are hot paths.
- ``model_overrides`` entries use the SAME canonical schema as every other consumer (``context_window``,
- ``supports_*``, ``model_family``) — they are translated into the catalog shape at
- this boundary, and sub-dicts (``limit``, ``modalities``) are merged rather than clobbered. See #84482,
- #8731.
- """
- mdev_id = _models_dev_id(provider_id, config=config) or provider_id
- models = _registry_models(mdev_id, allow_network=allow_network)
- mid, entry = next(_iter_model_entries(models, model_id, suffix_fallback=False, provider=provider_id), (model_id, None)) if models is not None else (model_id, None)
- # Not in catalog — an override (explicit or _default) may still provide it.
- raw = _apply_overrides(provider_id, model_id, entry, config=config)
- return _parse_model_info(mid, raw, mdev_id) if raw is not None else None
|