)j7NUdZddlmZddlZddlZddlZddlZddlZddl m Z ddl m Z ddl mZddlmZejeZdZd Zd ed <d Zd Zd ZdeZdaded<daded<d7dZd8dZd9dZ efd:dZ!d;d#Z"dd+Z%d?d-Z&d?d.Z'd@d0Z(dAd2Z)dBd5Z*dCd6Z+dS)Du Remote model catalog fetcher. The Hermes docs site hosts a JSON manifest of curated models for providers we want to update without shipping a release (currently OpenRouter and Nous Portal). This module fetches, validates, and caches that manifest, falling back to the in-repo hardcoded lists when the network is unavailable. Pipeline -------- 1. ``get_catalog()`` — returns a parsed manifest dict. - Checks in-process cache (invalidated by TTL). - Reads disk cache at ``~/.hermes/cache/model_catalog.json``. - Fetches the master URL if disk cache is stale or missing. - On any fetch failure, keeps using the stale cache (or empty dict). 2. ``get_curated_openrouter_models()`` / ``get_curated_nous_models()`` — thin accessors returning the shapes existing callers expect. Each falls back to the in-repo hardcoded list on any lookup failure. Schema (version 1) ------------------ :: { "version": 1, "updated_at": "2026-04-25T22:00:00Z", "metadata": {...}, # free-form "providers": { "openrouter": { "metadata": {...}, # free-form "models": [ {"id": "vendor/model", "description": "recommended", "metadata": {...}} # free-form, model-level ] }, "nous": {...} } } Unknown fields are ignored — extra metadata can be added at either level without bumping ``version``. ``version`` bumps are reserved for breaking changes (renaming ``providers``, changing ``models`` shape). ) annotationsN)Path)Any) __version__)atomic_replacezAhttps://hermes-agent.nousresearch.com/docs/api/model-catalog.json)zfhttps://raw.githubusercontent.com/NousResearch/hermes-agent/main/website/static/api/model-catalog.jsontuple[str, ...]DEFAULT_CATALOG_FALLBACK_URLSg @z hermes-cli/dict[str, Any] | None_catalog_cachefloat_catalog_cache_source_mtimereturndict[str, Any]c  ddlm}|pi}n#t$ri}YnwxYw|d}t |t si}t |ddt|dptt|dptt |dt r|dnid S) z@Load the ``model_catalog`` config block with defaults filled in.r) load_config model_catalogenabledTurl ttl_hours providers)rrrr) hermes_cli.configr Exceptionget isinstancedictboolstrDEFAULT_CATALOG_URLrDEFAULT_TTL_HOURS)rcfgraws =/home/ubuntu/.hermes/hermes-agent/hermes_cli/model_catalog.py_load_catalog_configr%^s 111111kmm!r  ''/ " "C c4  400113775>>8%899377;//D3DEE-7 8L8Ld-S-S[SWW[)))Y[   s  $$rc.ddlm}|dz dz S)zHReturn the disk cache path. Import lazily so tests can monkeypatch home.rget_hermes_homecachezmodel_catalog.json)hermes_constantsr(r's r$ _cache_pathr+rs-000000 ?  w &)= ==rrtimeoutc tj|dtd}tj||5}t j|}dddn #1swxYwYn#tj j tt j tf$r'}td||Yd}~dSd}~wt $r'}td||Yd}~dSd}~wwxYwt#|std|dS|S) zGHTTP GET the manifest URL and return a parsed dict, or None on failure.zapplication/json)Acceptz User-Agent)headers)r-Nz#model catalog fetch failed (%s): %sz$model catalog fetch errored (%s): %sz,model catalog at %s failed schema validation)urllibrequestRequest_HERMES_USER_AGENTurlopenjsonloadsreaddecodeerrorURLError TimeoutErrorJSONDecodeErrorOSErrorloggerinfor_validate_manifest)rr-reqrespdataexcs r$_fetch_manifestrF}sn$$ ,0%  ^ # #C # 9 9 4T:diikk002233D 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 L !<1Ew O 93DDDttttt  :CEEEttttt d # # BCHHHt KsHA B 9B BBBBB,D C++ D8DD primary_url fallback_urlsct||}||S|D]<}|r||kr t||}|td||cS=dS)a3Try ``primary_url`` first, then walk ``fallback_urls``. Returns the first manifest that fetches and validates, or None when every URL fails. Skips fallback URLs identical to the primary so an operator who configured the catalog URL to point at the raw GitHub copy doesn't double-fetch. Nz3model catalog primary URL failed; using fallback %s)rFr?r@)rGr-rHrDrs r$_fetch_manifest_with_fallbackrJs ; 0 0D   c[(( sG,,   KKMs S S SKKK  4r,rDrrct|tsdS|d}t|tr |tkrdS|d}t|tsdS|D]\}}t|t rt|tsdS|d}t|tsdS|D]a}t|tsdSt|dt r|dsdSbdS)z=Return True when ``data`` matches the minimum manifest shape.FversionrmodelsidT) rrrintSUPPORTED_SCHEMA_VERSIONitemsrliststrip)rDrLrpnamepblockrMms r$rArAsZ dD ! !uhhy!!G gs # #w1I'I'Iu%%I i & &u"**   v%%% Z-E-E 55H%%&$'' 55  Aa&& uuuaeeDkk3// qw}} uuu   4r,#tuple[dict[str, Any] | None, float]cft} |j}n#ttf$rYdSwxYw t |d5}t j|}dddn #1swxYwYn#tt jf$rYdSwxYwt|sdS||fS)z@Return ``(data_or_none, mtime)``. mtime is 0 if file is missing.)Nr utf-8encodingN) r+statst_mtimer>FileNotFoundErroropenr6loadr=rA)pathmtimefhrDs r$_read_disk_cacherds  ==D $ & '{{ $ ) ) ) !R9R==D ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! T) *{{ d # #{ %=sB*??BA5) B5A99B<A9=BBBNonect} |jdd||jdz}t |dd5}t j||d|d dddn #1swxYwYt||dS#t$r&}t d |Yd}~dSd}~wwxYw) NT)parentsexist_okz.tmpwrYrZ)indent z$model catalog cache write failed: %s) r+parentmkdir with_suffixsuffixr_r6dumpwriterr>r?r@)rDratmprcrEs r$_write_disk_cacherts5 ==DA $666t{V344 #sW - - -  IdBq ) ) ) ) HHTNNN                sD!!!!! AAA :C@@@@@@@@@As<A B1-B B1BB1BB11 C!;CC!F) force_refreshruct}|dsiStd|ddz}t\}}tj}|duo||z |k}|st||t kr |rtS|s |r||a|a|St |dt}|.t|t\}} ||a| a|S|a|a|S||a|a|SiS)uReturn the parsed model catalog manifest, or an empty dict on failure. Callers should treat a missing provider/model as "use the in-repo fallback" — never raise from this function so the CLI keeps working offline. rr rg @Nr) r%maxrdtimer rrJDEFAULT_FETCH_TIMEOUTrt) rur" ttl_seconds disk_data disk_mtimenow disk_freshfetched new_disk_data new_mtimes r$ get_catalogrsC  C y> c3{+f455K,..Iz )++C$&KC*,< +KJ   &  ! 5 5 5  6 ZI,A"&0#,CJ8MNNG'"""#3#5#5 y  $*N*3 '  &)#"&0# Ir,providercdt}|dsdS|d|}t|tsdS|d}t|tr|sdSt |tS)zEIf ``model_catalog.providers..url`` is set, fetch that instead.rNrr)r%rrrrrSrFry)rr" provider_cfg override_urls r$_fetch_provider_overrider$s  C y>t{#''11L lD ) )t##E**L lC ( ( 0B0B0D0Dt <--//1F G GGr,cLt|}|@|di|}t|tr|St }|sdS|di|}t|tr|ndS)zHReturn the provider's manifest block, respecting per-provider overrides.Nr)rrrrr)roverrideblockcatalogs r$_get_provider_blockr5s'11H ["--11(;; eT " " LmmG t KK R ( ( , ,X 6 6Eud++ 5555r,list[tuple[str, str]] | NonecNtd}|sdSg}|dgD]v}t|dpd}|s;t|dpd}|||fw|pdS)zReturn OpenRouter's curated ``[(id, description), ...]`` from the manifest. Returns ``None`` when the manifest is unavailable, so callers can fall back to their hardcoded list. openrouterNrMrN descriptionrrrrSappend)routrVmiddescs r$get_curated_openrouter_modelsrDs - -E t!#C YYx $ $  !%%++#$$**,,  155''-2.. C; ;$r,list[str] | Nonectd}|sdSg}|dgD]O}t|dpd}|r||P|pdS)z~Return Nous Portal's curated list of model ids from the manifest. Returns ``None`` when the manifest is unavailable. nousNrMrNrr)rrrVrs r$get_curated_nous_modelsrWs  ' 'E tC YYx $ $!%%++#$$**,,   JJsOOO ;$r, project_root 'Path | str'ct|dz dz dz dz } t|d5}tj|}dddn #1swxYwYn@#ttjf$r'}t d||Yd}~d Sd}~wwxYwt|st d |d St|td S) uOverwrite the disk cache with the catalog shipped in a local checkout. ``hermes update`` pulls the latest repo, so the freshly-pulled ``website/static/api/model-catalog.json`` IS the newest catalog — no network round-trip needed. Copying it straight over the disk cache keeps the model picker current even when the remote manifest fetch is bot-gated or the Portal hiccups. Reads the shipped manifest, validates it against the schema, and writes it to ``~/.hermes/cache/model_catalog.json`` via the same atomic writer the network path uses. Returns ``True`` on success, ``False`` if the file is missing, malformed, or fails validation (caller should treat a ``False`` as non-fatal — the network fetch path still applies on the next picker open). websitestaticapizmodel-catalog.jsonrYrZNz1model catalog seed from checkout skipped (%s): %sFz@model catalog seed from checkout skipped: invalid manifest at %sT) rr_r6r`r>r=r?debugrArt reset_cache)rsrcrcrDrEs r$seed_cache_from_checkoutrgs2 |  y (8 3e ;>R RC # ( ( ( !B9R==D ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! T) * H#sSSSuuuuu d # # WY\]]]udMMM 4s:AA AAAAAB1BBcdadadS)zIClear the in-process cache. Used by tests and ``hermes model --refresh``.Nr )r rr,r$rrsN"%r,)rr)rr)rrr-rrr )rGrr-rrHrrr )rDrrr)rrW)rDrrre)rurrr)rrrr )rr)rr)rrrr)rre),__doc__ __future__rr6loggingrx urllib.errorr1urllib.requestpathlibrtypingr hermes_clir_HERMES_VERSIONutilsr getLogger__name__r?r r __annotations__r!ryrPr4r rr%r+rFrJrArdrtrrrrrrrrr,r$rsi***X#"""""  555555  8 $ $H24?44 )-,,,,%((((((>>>>:&C24" A A A A$*/444444nHHHH" 6 6 6 6&     >&&&&&&r,