This page covers the model selection and validation system, including the model catalog system, provider-specific normalization, and the dynamic context length discovery mechanism.
Hermes maintains a multi-tier model discovery system that combines the models.dev community registry, live API discovery, and curated fallback snapshots.
The primary database for model metadata is models.dev. This registry tracks thousands of models across numerous providers agent/models_dev.py1-9
~/.hermes/models_dev_cache.json), and periodic network fetches from https://models.dev/api.json agent/models_dev.py11-15ModelInfo object contains critical fields for agent operations: context_window, tool_call capability, reasoning flags, and cost_input/cost_output for token budgeting agent/models_dev.py46-82While models.dev provides the raw data, Hermes uses specialized logic to curate these lists for different providers:
OPENROUTER_MODELS_URL agent/model_metadata.py24 and filtered. Models whose supported_parameters omit tools are dropped to prevent runtime failures tests/hermes_cli/test_models.py93-119config.yaml under the providers: or custom_providers: sections hermes_cli/providers.py14-15 The system ensures these are properly enumerated in the model picker tests/hermes_cli/test_user_providers_model_switch.py90-110/v1/models endpoint, persisting discovered models to config.yaml to avoid stale lists hermes_cli/model_switch.py104-158Model Resolution Hierarchy
Sources: hermes_cli/model_switch.py176-218 agent/models_dev.py11-19 agent/model_metadata.py24 hermes_cli/model_switch.py104-158 tests/hermes_cli/test_user_providers_model_switch.py90-110
LLM providers vary in their naming conventions. The normalize_model_for_provider function ensures the correct string reaches the API hermes_cli/model_normalize.py25-27
| Provider Type | Logic | Example |
|---|---|---|
| Aggregators | Requires vendor/model prefix hermes_cli/model_normalize.py67-71 | anthropic/claude-sonnet-5 |
| Anthropic | Native transport expects dots replaced by hyphens hermes_cli/model_normalize.py74-76 | claude-3-5-sonnet-20241022 |
| Copilot | Preserves dots in bare names hermes_cli/model_normalize.py79-83 | claude-sonnet-4.6 |
| DeepSeek | Maps aliases (r1, think) to canonical deepseek-reasoner hermes_cli/model_normalize.py148-180 | deepseek-reasoner |
| Xiaomi | Requires lowercase model IDs hermes_cli/model_normalize.py114-116 | mimo-v2.5-pro |
Sources: hermes_cli/model_normalize.py1-180 hermes_cli/model_switch.py37-39 hermes_cli/providers.py38-44
The /model command and CLI flags trigger a shared pipeline in hermes_cli/model_switch.py:
resolve_provider_full hermes_cli/providers.py35 This includes resolving named custom providers defined in custom_providers tests/hermes_cli/test_model_switch_custom_providers.py123-142normalize_model_for_provider hermes_cli/model_normalize.py25-27Model Switching Data Flow
Sources: hermes_cli/model_switch.py1-19 hermes_cli/providers.py35 tests/hermes_cli/test_model_switch_custom_providers.py123-142 hermes_cli/model_switch.py181-201
Hermes dynamically discovers model context lengths to inform the ContextCompressor and prevent overflow errors.
The get_model_context_length() function in agent/model_metadata.py follows this priority:
DEFAULT_CONTEXT_LENGTHS agent/model_metadata.py191-220/api/show, vLLM /v1/models/{model}) for runtime limits agent/model_metadata.py113-125CONTEXT_PROBE_TIERS (256k, 128k, 64k, 32k, 16k, 8k) to step down until a request succeeds agent/model_metadata.py181-188Hermes uses a rough estimation of 4 characters per token for text agent/model_metadata.py236-242 For multimodal content, it applies a flat cost of ~1500 tokens per image to avoid exploding token counts from base64 strings tests/agent/test_model_metadata.py96-121 It also implements a bounded cache for tool schema token estimation to avoid repeated serialization overhead agent/model_metadata.py149-170
Sources: agent/model_metadata.py181-220 agent/model_metadata.py236-242 tests/agent/test_model_metadata.py96-121 agent/model_metadata.py149-170
The hermes_cli/inventory.py module provides a unified substrate for model and provider data used by the CLI, TUI, and Web Dashboard hermes_cli/inventory.py1-4
The ConfigContext class captures the disk-config snapshot, including current_provider, current_model, and configured user_providers or custom_providers hermes_cli/inventory.py43-55
The build_models_payload function centralizes the logic for generating model options, applying flags for pricing, capabilities, and picker-specific hints hermes_cli/inventory.py114-129 It delegates curation to list_authenticated_providers to ensure only tool-capable models are surfaced hermes_cli/inventory.py26-32
Inventory Data Flow
Sources: hermes_cli/inventory.py80-108 hermes_cli/inventory.py114-129 hermes_cli/inventory.py26-32
Hermes utilizes an "Auxiliary" LLM client for non-core tasks such as vision analysis and context compression.
The system decides how to handle images based on the active model's capabilities:
image_url parts if the model supports vision agent/models_dev.py87-88native if the main model is vision-capable, otherwise falls back to text.Sources: agent/models_dev.py87-88 agent/model_metadata.py103-107
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.