Skip to content

feat(models): remote model catalog manifest for OpenRouter + Nous Portal#16033

Merged
teknium1 merged 1 commit into
mainfrom
hermes/hermes-54bb6792
Apr 26, 2026
Merged

feat(models): remote model catalog manifest for OpenRouter + Nous Portal#16033
teknium1 merged 1 commit into
mainfrom
hermes/hermes-54bb6792

Conversation

@teknium1

@teknium1 teknium1 commented Apr 26, 2026

Copy link
Copy Markdown
Contributor

Summary

Curated model picker lists for OpenRouter and Nous Portal now resolve via a JSON manifest served by the docs site, falling back to the in-repo snapshot on network failure. We can update model lists without shipping a hermes-agent release.

Live URL: https://hermes-agent.nousresearch.com/docs/api/model-catalog.json (source at website/static/api/model-catalog.json, auto-deploys via the existing deploy-site.yml pipeline on every merge to main).

Schema (v1)

  • id + optional description per model
  • Free-form metadata dict at manifest / provider / model levels — add tags, tiers, notes later without a version bump
  • Pricing and context length stay live-fetched (/v1/models endpoints, models.dev) — not in the manifest

Config

model_catalog:
  enabled: true
  url: https://hermes-agent.nousresearch.com/docs/api/model-catalog.json
  ttl_hours: 24
  providers: {}   # optional per-provider override URLs (same schema)

Fetch pipeline

in-process cache → disk cache (fresh < TTL) → HTTP fetch → disk-cache fallback on failure → in-repo snapshot as last resort. Never raises; at worst returns the bundled list.

Changes

File What
website/static/api/model-catalog.json new — initial manifest (35 OpenRouter + 31 Nous)
scripts/build_model_catalog.py new — regenerator from in-repo lists
hermes_cli/model_catalog.py new — fetch + validate + cache module
hermes_cli/models.py fetch_openrouter_models() prefers manifest; new get_curated_nous_model_ids() helper
hermes_cli/main.py, hermes_cli/auth.py Nous flows call the helper
hermes_cli/config.py model_catalog section defaults
website/docs/reference/model-catalog.md + sidebars.ts docs page
tests/hermes_cli/test_model_catalog.py new — 21 tests

Validation

Result
test_model_catalog.py (new) 21/21 passed
test_models.py + test_models_dev_preferred_merge.py 69/69 passed
test_config.py + test_config_validation.py 67/67 passed
E2E (local HTTP server serving the real manifest) fetch → disk cache → in-process cache → network-failure-falls-back-to-cache → empty-cache-plus-network-down-returns-empty → integration fallback to hardcoded list all verified

Not in this PR

  • HuggingFace / Kilocode / Opencode-Zen / Bedrock — next pass (group 2 and 3 extension)
  • Context-length / pricing in the manifest — stays live-fetched
  • hermes models refresh subcommand — cache auto-refreshes past TTL on next /model; can add explicitly later if needed

@teknium1
feat(models): remote model catalog manifest for OpenRouter + Nous Portal
9134cae 
OpenRouter and Nous Portal curated picker lists now resolve via a JSON
manifest served by the docs site, falling back to the in-repo snapshot
when unreachable. Lets us update model lists without shipping a release.

Live URL: https://hermes-agent.nousresearch.com/docs/api/model-catalog.json
(source at website/static/api/model-catalog.json; auto-deploys via the
existing deploy-site.yml GitHub Pages pipeline on every merge to main).

Schema (v1) carries id + optional description + free-form metadata at
manifest, provider, and model levels. Pricing and context length stay
live-fetched via existing machinery (/v1/models endpoints, models.dev).

Config (new model_catalog section, default enabled):
  model_catalog.url       master manifest URL
  model_catalog.ttl_hours disk cache TTL (default 24h)
  model_catalog.providers.<name>.url   optional per-provider override

Fetch pipeline: in-process cache -> disk cache (fresh < TTL) -> HTTP
fetch -> disk-cache-on-failure fallback -> in-repo snapshot as last
resort. Never raises to callers; at worst returns the bundled list.

Changes:
- website/static/api/model-catalog.json    initial manifest (35 OR + 31 Nous)
- scripts/build_model_catalog.py           regenerator from in-repo lists
- hermes_cli/model_catalog.py              fetch + validate + cache module
- hermes_cli/models.py                     fetch_openrouter_models() +
                                           new get_curated_nous_model_ids()
- hermes_cli/main.py, hermes_cli/auth.py   Nous flows use the helper
- hermes_cli/config.py                     model_catalog defaults
- website/docs/reference/model-catalog.md  + sidebars.ts
- tests/hermes_cli/test_model_catalog.py   21 tests (validation, fetch
                                           success/failure, accessors,
                                           disabled, overrides, integration)
@teknium1 teknium1 merged commit 8553669 into main Apr 26, 2026
12 of 13 checks passed
@teknium1 teknium1 deleted the hermes/hermes-54bb6792 branch April 26, 2026 12:46
@alt-glitch alt-glitch added type/feature New feature or request P2 Medium — degraded but workaround exists comp/cli CLI entry point, hermes_cli/, setup wizard provider/openrouter OpenRouter aggregator provider/nous Nous Research API (OAuth) labels Apr 26, 2026
@ether-btc

ether-btc commented Apr 26, 2026

Copy link
Copy Markdown
Contributor

Excellence Contribution — Remote Model Catalog Manifest

What it does
Model picker lists for OpenRouter and Nous Portal are now served from a JSON manifest at hermes-agent.nousresearch.com/docs/api/model-catalog.json, fetched at runtime with a 24-hour TTL. The manifest is updated by scripts/build_model_catalog.py and deployed via the existing deploy-site.yml pipeline on every merge to main. Network failures fall back through: in-process cache → disk cache → HTTP fetch → disk fallback → in-repo snapshot.

Why it matters
Previously, adding a new model meant a code change, PR, review, merge, and release. With the remote manifest, model lists update without any code change or release cycle. The team adds new OpenRouter or Nous Portal models by updating a JSON file and merging to main. Users see new models within 24 hours (TTL), or immediately via /model refresh.

Schema design
Pricing and context length are intentionally excluded — live-fetched from /v1/models endpoints and models.dev respectively, keeping the manifest lightweight and version-independent. The manifest schema supports free-form metadata at manifest, provider, and model levels for extensibility.

Implications

  • Model support ships without releases — the gap between model availability and Hermes support shrinks from weeks to days
  • hermes models refresh is the user-facing control point for immediate manifest refresh
  • The manifest is extensible: metadata fields (tier, regional availability) can be added without a version bump
  • Phase 2 (HuggingFace, Kilocode, Opencode-Zen, Bedrock) can be added to the manifest without code changes

@michaelfeil

michaelfeil commented Apr 27, 2026

Copy link
Copy Markdown

You could also use this: https://github.com/anomalyco/models.dev

ulasbilgen pushed a commit to ulasbilgen/hermes-adhd-agent that referenced this pull request May 1, 2026
@teknium1
feat(models): remote model catalog manifest for OpenRouter + Nous Por…
a277097 
…tal (NousResearch#16033)

OpenRouter and Nous Portal curated picker lists now resolve via a JSON
manifest served by the docs site, falling back to the in-repo snapshot
when unreachable. Lets us update model lists without shipping a release.

Live URL: https://hermes-agent.nousresearch.com/docs/api/model-catalog.json
(source at website/static/api/model-catalog.json; auto-deploys via the
existing deploy-site.yml GitHub Pages pipeline on every merge to main).

Schema (v1) carries id + optional description + free-form metadata at
manifest, provider, and model levels. Pricing and context length stay
live-fetched via existing machinery (/v1/models endpoints, models.dev).

Config (new model_catalog section, default enabled):
  model_catalog.url       master manifest URL
  model_catalog.ttl_hours disk cache TTL (default 24h)
  model_catalog.providers.<name>.url   optional per-provider override

Fetch pipeline: in-process cache -> disk cache (fresh < TTL) -> HTTP
fetch -> disk-cache-on-failure fallback -> in-repo snapshot as last
resort. Never raises to callers; at worst returns the bundled list.

Changes:
- website/static/api/model-catalog.json    initial manifest (35 OR + 31 Nous)
- scripts/build_model_catalog.py           regenerator from in-repo lists
- hermes_cli/model_catalog.py              fetch + validate + cache module
- hermes_cli/models.py                     fetch_openrouter_models() +
                                           new get_curated_nous_model_ids()
- hermes_cli/main.py, hermes_cli/auth.py   Nous flows use the helper
- hermes_cli/config.py                     model_catalog defaults
- website/docs/reference/model-catalog.md  + sidebars.ts
- tests/hermes_cli/test_model_catalog.py   21 tests (validation, fetch
                                           success/failure, accessors,
                                           disabled, overrides, integration)
@github-actions github-actions Bot mentioned this pull request May 1, 2026
Merged
donald131 pushed a commit to donald131/hermes-agent that referenced this pull request May 2, 2026
@teknium1
feat(models): remote model catalog manifest for OpenRouter + Nous Por…
a8a8d9e 
…tal (NousResearch#16033)

OpenRouter and Nous Portal curated picker lists now resolve via a JSON
manifest served by the docs site, falling back to the in-repo snapshot
when unreachable. Lets us update model lists without shipping a release.

Live URL: https://hermes-agent.nousresearch.com/docs/api/model-catalog.json
(source at website/static/api/model-catalog.json; auto-deploys via the
existing deploy-site.yml GitHub Pages pipeline on every merge to main).

Schema (v1) carries id + optional description + free-form metadata at
manifest, provider, and model levels. Pricing and context length stay
live-fetched via existing machinery (/v1/models endpoints, models.dev).

Config (new model_catalog section, default enabled):
  model_catalog.url       master manifest URL
  model_catalog.ttl_hours disk cache TTL (default 24h)
  model_catalog.providers.<name>.url   optional per-provider override

Fetch pipeline: in-process cache -> disk cache (fresh < TTL) -> HTTP
fetch -> disk-cache-on-failure fallback -> in-repo snapshot as last
resort. Never raises to callers; at worst returns the bundled list.

Changes:
- website/static/api/model-catalog.json    initial manifest (35 OR + 31 Nous)
- scripts/build_model_catalog.py           regenerator from in-repo lists
- hermes_cli/model_catalog.py              fetch + validate + cache module
- hermes_cli/models.py                     fetch_openrouter_models() +
                                           new get_curated_nous_model_ids()
- hermes_cli/main.py, hermes_cli/auth.py   Nous flows use the helper
- hermes_cli/config.py                     model_catalog defaults
- website/docs/reference/model-catalog.md  + sidebars.ts
- tests/hermes_cli/test_model_catalog.py   21 tests (validation, fetch
                                           success/failure, accessors,
                                           disabled, overrides, integration)
02356abc pushed a commit to 02356abc/hermes-agent that referenced this pull request May 14, 2026
@teknium1
feat(models): remote model catalog manifest for OpenRouter + Nous Por…
47d323d 
…tal (NousResearch#16033)

OpenRouter and Nous Portal curated picker lists now resolve via a JSON
manifest served by the docs site, falling back to the in-repo snapshot
when unreachable. Lets us update model lists without shipping a release.

Live URL: https://hermes-agent.nousresearch.com/docs/api/model-catalog.json
(source at website/static/api/model-catalog.json; auto-deploys via the
existing deploy-site.yml GitHub Pages pipeline on every merge to main).

Schema (v1) carries id + optional description + free-form metadata at
manifest, provider, and model levels. Pricing and context length stay
live-fetched via existing machinery (/v1/models endpoints, models.dev).

Config (new model_catalog section, default enabled):
  model_catalog.url       master manifest URL
  model_catalog.ttl_hours disk cache TTL (default 24h)
  model_catalog.providers.<name>.url   optional per-provider override

Fetch pipeline: in-process cache -> disk cache (fresh < TTL) -> HTTP
fetch -> disk-cache-on-failure fallback -> in-repo snapshot as last
resort. Never raises to callers; at worst returns the bundled list.

Changes:
- website/static/api/model-catalog.json    initial manifest (35 OR + 31 Nous)
- scripts/build_model_catalog.py           regenerator from in-repo lists
- hermes_cli/model_catalog.py              fetch + validate + cache module
- hermes_cli/models.py                     fetch_openrouter_models() +
                                           new get_curated_nous_model_ids()
- hermes_cli/main.py, hermes_cli/auth.py   Nous flows use the helper
- hermes_cli/config.py                     model_catalog defaults
- website/docs/reference/model-catalog.md  + sidebars.ts
- tests/hermes_cli/test_model_catalog.py   21 tests (validation, fetch
                                           success/failure, accessors,
                                           disabled, overrides, integration)
dannyJ848 pushed a commit to dannyJ848/hermes-agent that referenced this pull request May 17, 2026
@teknium1
feat(models): remote model catalog manifest for OpenRouter + Nous Por…
9c4c24e 
…tal (NousResearch#16033)

OpenRouter and Nous Portal curated picker lists now resolve via a JSON
manifest served by the docs site, falling back to the in-repo snapshot
when unreachable. Lets us update model lists without shipping a release.

Live URL: https://hermes-agent.nousresearch.com/docs/api/model-catalog.json
(source at website/static/api/model-catalog.json; auto-deploys via the
existing deploy-site.yml GitHub Pages pipeline on every merge to main).

Schema (v1) carries id + optional description + free-form metadata at
manifest, provider, and model levels. Pricing and context length stay
live-fetched via existing machinery (/v1/models endpoints, models.dev).

Config (new model_catalog section, default enabled):
  model_catalog.url       master manifest URL
  model_catalog.ttl_hours disk cache TTL (default 24h)
  model_catalog.providers.<name>.url   optional per-provider override

Fetch pipeline: in-process cache -> disk cache (fresh < TTL) -> HTTP
fetch -> disk-cache-on-failure fallback -> in-repo snapshot as last
resort. Never raises to callers; at worst returns the bundled list.

Changes:
- website/static/api/model-catalog.json    initial manifest (35 OR + 31 Nous)
- scripts/build_model_catalog.py           regenerator from in-repo lists
- hermes_cli/model_catalog.py              fetch + validate + cache module
- hermes_cli/models.py                     fetch_openrouter_models() +
                                           new get_curated_nous_model_ids()
- hermes_cli/main.py, hermes_cli/auth.py   Nous flows use the helper
- hermes_cli/config.py                     model_catalog defaults
- website/docs/reference/model-catalog.md  + sidebars.ts
- tests/hermes_cli/test_model_catalog.py   21 tests (validation, fetch
                                           success/failure, accessors,
                                           disabled, overrides, integration)
@teknium1 teknium1 mentioned this pull request May 24, 2026
Closed
gweeteve pushed a commit to gweeteve/hermes-agent that referenced this pull request Jun 2, 2026
@teknium1
feat(models): remote model catalog manifest for OpenRouter + Nous Por…
6eb530e 
…tal (NousResearch#16033)

OpenRouter and Nous Portal curated picker lists now resolve via a JSON
manifest served by the docs site, falling back to the in-repo snapshot
when unreachable. Lets us update model lists without shipping a release.

Live URL: https://hermes-agent.nousresearch.com/docs/api/model-catalog.json
(source at website/static/api/model-catalog.json; auto-deploys via the
existing deploy-site.yml GitHub Pages pipeline on every merge to main).

Schema (v1) carries id + optional description + free-form metadata at
manifest, provider, and model levels. Pricing and context length stay
live-fetched via existing machinery (/v1/models endpoints, models.dev).

Config (new model_catalog section, default enabled):
  model_catalog.url       master manifest URL
  model_catalog.ttl_hours disk cache TTL (default 24h)
  model_catalog.providers.<name>.url   optional per-provider override

Fetch pipeline: in-process cache -> disk cache (fresh < TTL) -> HTTP
fetch -> disk-cache-on-failure fallback -> in-repo snapshot as last
resort. Never raises to callers; at worst returns the bundled list.

Changes:
- website/static/api/model-catalog.json    initial manifest (35 OR + 31 Nous)
- scripts/build_model_catalog.py           regenerator from in-repo lists
- hermes_cli/model_catalog.py              fetch + validate + cache module
- hermes_cli/models.py                     fetch_openrouter_models() +
                                           new get_curated_nous_model_ids()
- hermes_cli/main.py, hermes_cli/auth.py   Nous flows use the helper
- hermes_cli/config.py                     model_catalog defaults
- website/docs/reference/model-catalog.md  + sidebars.ts
- tests/hermes_cli/test_model_catalog.py   21 tests (validation, fetch
                                           success/failure, accessors,
                                           disabled, overrides, integration)
Egavasyug pushed a commit to Egavasyug/hermes-agent that referenced this pull request Jun 10, 2026
@teknium1
feat(models): remote model catalog manifest for OpenRouter + Nous Por…
18779bb 
…tal (NousResearch#16033)

OpenRouter and Nous Portal curated picker lists now resolve via a JSON
manifest served by the docs site, falling back to the in-repo snapshot
when unreachable. Lets us update model lists without shipping a release.

Live URL: https://hermes-agent.nousresearch.com/docs/api/model-catalog.json
(source at website/static/api/model-catalog.json; auto-deploys via the
existing deploy-site.yml GitHub Pages pipeline on every merge to main).

Schema (v1) carries id + optional description + free-form metadata at
manifest, provider, and model levels. Pricing and context length stay
live-fetched via existing machinery (/v1/models endpoints, models.dev).

Config (new model_catalog section, default enabled):
  model_catalog.url       master manifest URL
  model_catalog.ttl_hours disk cache TTL (default 24h)
  model_catalog.providers.<name>.url   optional per-provider override

Fetch pipeline: in-process cache -> disk cache (fresh < TTL) -> HTTP
fetch -> disk-cache-on-failure fallback -> in-repo snapshot as last
resort. Never raises to callers; at worst returns the bundled list.

Changes:
- website/static/api/model-catalog.json    initial manifest (35 OR + 31 Nous)
- scripts/build_model_catalog.py           regenerator from in-repo lists
- hermes_cli/model_catalog.py              fetch + validate + cache module
- hermes_cli/models.py                     fetch_openrouter_models() +
                                           new get_curated_nous_model_ids()
- hermes_cli/main.py, hermes_cli/auth.py   Nous flows use the helper
- hermes_cli/config.py                     model_catalog defaults
- website/docs/reference/model-catalog.md  + sidebars.ts
- tests/hermes_cli/test_model_catalog.py   21 tests (validation, fetch
                                           success/failure, accessors,
                                           disabled, overrides, integration)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

comp/cli CLI entry point, hermes_cli/, setup wizard P2 Medium — degraded but workaround exists provider/nous Nous Research API (OAuth) provider/openrouter OpenRouter aggregator type/feature New feature or request

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@teknium1 @ether-btc @michaelfeil @alt-glitch