Catálogo de modelos

O Hermes busca listas curadas de modelos do OpenRouter e do Nous Portal num manifesto JSON hospedado junto do site de documentação. Isso deixa quem mantém o projeto atualizar as listas do seletor sem publicar uma versão nova do hermes-agent.

Quando o manifesto está inalcançável (sem rede, rede bloqueada, falha de hospedagem), o Hermes cai em silêncio no retrato que veio dentro do próprio pacote. O manifesto nunca quebra o seletor — na pior das hipóteses, você vê a lista que veio com a sua versão instalada.

URL do manifesto ao vivo

https://hermes-agent.nousresearch.com/docs/api/model-catalog.json

Publicado a cada merge na main, pelo mesmo pipeline deploy-site.yml do GitHub Pages. A fonte da verdade fica no repositório, em website/static/api/model-catalog.json.

Esquema

{
  "version": 1,
  "updated_at": "2026-04-25T22:00:00Z",
  "metadata": {},
  "providers": {
    "openrouter": {
      "metadata": {},
      "models": [
        {"id": "z-ai/glm-5.2",         "description": "default", "default": true},
        {"id": "moonshotai/kimi-k3",   "description": "recommended", "metadata": {}},
        {"id": "openai/gpt-5.4",       "description": ""}
      ]
    },
    "nous": {
      "metadata": {},
      "models": [
        {"id": "z-ai/glm-5.2", "default": true},
        {"id": "anthropic/claude-opus-4.7"},
        {"id": "moonshotai/kimi-k3"}
      ]
    }
  }
}

Sobre os campos:

• version — versão inteira do esquema. Esquemas futuros aumentam esse número; o Hermes recusa manifestos com versões que não entende e cai no retrato interno.
• metadata — dicionário livre, no nível do manifesto, do provedor e do modelo. Qualquer chave. O Hermes ignora campos desconhecidos, então dá para anotar entradas ("tier": "paid", "tags": [...]) sem combinar mudança de esquema.
• description — só do OpenRouter. Define o texto do selo no seletor ("recommended", "free", "default", ou vazio). O Nous Portal não usa isso — o controle da camada gratuita vem ao vivo do endpoint de preços do Portal.
• default — exatamente uma entrada por provedor pode ter "default": true. Esse é o padrão silencioso: onde o Hermes cai quando o usuário nunca escolheu um modelo (cartão de confirmação da abertura na interface gráfica, provider configurado sem model, model.default vazio). É lido só do cache em tempo de execução (get_default_model_from_cache), para os caminhos quentes nunca tocarem a rede; sem manifesto em cache, o Hermes usa a constante PREFERRED_SILENT_DEFAULT_MODEL do repositório, que precisa bater com a entrada marcada. Isso deixa quem mantém trocar o padrão silencioso sem publicar versão nova. É, de propósito, um modelo capaz e de custo baixo, nunca o carro-chefe mais caro.
• Preço e tamanho de contexto NÃO estão no manifesto. Isso vem das APIs ao vivo dos provedores (endpoints /v1/models, models.dev) na hora da busca.

Comportamento da busca

Quando	O que acontece
/model ou hermes model	Busca se o cache em disco está velho; senão, usa o cache
Cache em disco novo (dentro do tempo de vida)	Nenhum acesso à rede
Falha de rede, com cache	Cai no cache em silêncio, com uma linha de log
Falha de rede, sem cache	Cai no retrato do repositório, em silêncio
Manifesto reprova na validação	Tratado como inalcançável

Local do cache: ~/.hermes/cache/model_catalog.json.

Configuração

model_catalog:
  enabled: true
  url: https://hermes-agent.nousresearch.com/docs/api/model-catalog.json
  ttl_hours: 1
  providers: {}

Coloque enabled: false para desligar a busca remota de vez e sempre usar o retrato interno.

URLs próprias por provedor

Terceiros podem hospedar a própria lista curada, com o mesmo esquema. Aponte um provedor para uma URL sua:

model_catalog:
  providers:
    openrouter:
      url: https://exemplo.com/minha-curadoria-openrouter.json

O manifesto que sobrescreve só precisa preencher os blocos de provedor que interessam. Os outros continuam resolvendo pela URL principal.

Esconder provedores do seletor

O excluded_providers esconde provedores específicos do seletor /model, mesmo havendo credencial válida. Útil quando existem credenciais de provedores antigos ou de teste, que não deveriam aparecer no uso normal (um token velho do Copilot ou do OpenRouter ainda em cache no auth.json, ou descoberto pela CLI gh).

model_catalog:
  excluded_providers:
    - copilot
    - openrouter
    - openai

A exclusão é comparada sem diferenciar maiúsculas contra todas as chaves pelas quais um provedor pode aparecer — o identificador do Hermes e o do models.dev, o identificador da camada de sobreposição e o do Hermes resolvido, e o identificador canônico — então uma entrada só, como copilot, esconde o provedor venha de onde vier. Todas as superfícies do seletor /model respeitam: os seletores interativo e de texto do gateway, o da TUI e o do hermes model na linha de comando. Uma lista vazia (ou a ausência da chave) não tem efeito.

Atualizar o manifesto

Para quem mantém o projeto:

# Regenera a partir das listas fixas no repositório (mantém o manifesto em sincronia
# depois de editar OPENROUTER_MODELS ou _PROVIDER_MODELS["nous"] em hermes_cli/models.py).
python scripts/build_model_catalog.py

Depois, abra um pull request com a mudança em website/static/api/model-catalog.json para a main. O site publica sozinho no merge, e o manifesto novo está no ar em alguns minutos.

Também dá para editar o JSON à mão, para mudanças finas de metadados que não pertencem ao retrato interno — o script gerador é conveniência, não a única fonte da verdade.