i+,UdZddlmZddlZddlZddlZddlZddlZddl m Z ddl m Z ddl mZddlmZejeZdZd Zd Zd Zd eZdad ed<daded<d/dZd0dZd1dZd2dZ d3d Z!d4d"Z"d#d$d5d&Z#d6d(Z$d6d)Z%d7d+Z&d8d-Z'd9d.Z(dS):u 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.jsong @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_URLr DEFAULT_TTL_HOURS)rcfgraws =/home/ubuntu/.hermes/hermes-agent/hermes_cli/model_catalog.py_load_catalog_configr$Us 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*is-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_manifestrEtsn$$ ,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++ D8DDrCrrct|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)rCrGrpnamepblockrHms r#r@r@sZ 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]cbt} |j}n#ttf$rYdSwxYw t |5}t j|}dddn #1swxYwYn#tt jf$rYdSwxYwt|sdS||fS)z@Return ``(data_or_none, mtime)``. mtime is 0 if file is missing.)Nr N) r*statst_mtimer=FileNotFoundErroropenr5loadr<r@)pathmtimefhrCs r#_read_disk_cacher\s ==D $ & '{{ $ZZ !29R==D ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! T) *{{ d # #{ %=sB*??A?A3' A?3A77A?:A7;A??BBNonect} |jdd||jdz}t |d5}t j||d|ddddn #1swxYwYt||dS#t$r&}t d|Yd}~dSd}~wwxYw) NT)parentsexist_okz.tmpw)indent z$model catalog cache write failed: %s) r*parentmkdir with_suffixsuffixrWr5dumpwriterr=r>r?)rCrYtmpr[rDs r#_write_disk_cacherls. ==DA $666t{V344 #s^^ r IdBq ) ) ) ) HHTNNN                sD!!!!! AAA :C@@@@@@@@@As<A B/-B B/BB/BB// C9CCF) force_refreshrmct}|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$maxr\timer rrEDEFAULT_FETCH_TIMEOUTrl) rmr! ttl_seconds disk_data disk_mtimenow disk_freshfetched new_disk_data new_mtimes r# get_catalogrzsC  C y> c3{+f455K,..Iz )++C$&KC*,< +KJ   &  ! 5 5 5  6 ZI,A"&0#c%j*?@@G'"""#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$rrrrrNrErq)r{r! provider_cfg override_urls r#_fetch_provider_overriders  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)rrrrrz)r{overrideblockcatalogs r#_get_provider_blockrs'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. openrouterNrHrI descriptionrrrrNappend)routrQmiddescs r#get_curated_openrouter_modelsr"s - -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. nousNrHrIrr)rrrQrs r#get_curated_nous_modelsr5s  ' 'E tC YYx $ $!%%++#$$**,,   JJsOOO ;$r+cdadadS)zIClear the in-process cache. Used by tests and ``hermes model --refresh``.Nr )r rr+r# reset_cacherEsN"%r+)rr)rr)rrr,r rr )rCrrr)rrR)rCrrr])rmrrr)r{rrr )rr)rr)rr]))__doc__ __future__rr5loggingrp urllib.errorr0urllib.requestpathlibrtypingr hermes_clir_HERMES_VERSIONutilsr getLogger__name__r>rr rqrKr3r __annotations__rr$r*rEr@r\rlrzrrrrrrr+r#rs***X#"""""  555555  8 $ $H4?44 )-,,,,%((((((>>>>44" A A A A$*/444444nHHHH" 6 6 6 6&     &&&&&&r+