{
  "id": "page:docs-hermes-research-raw-provider-runtime",
  "_kind": "Page",
  "_file": "wiki/docs/hermes-research/raw/provider-runtime.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/hermes-research/raw/provider-runtime.md",
    "sourceKind": "repo-docs",
    "title": "Provider Runtime Resolution",
    "displayName": "Provider Runtime Resolution",
    "slug": "docs/hermes-research/raw/provider-runtime",
    "articlePath": "wiki/docs/hermes-research/raw/provider-runtime.md",
    "article": "\n# Provider Runtime Resolution\n\n> Source: https://hermes-agent.nousresearch.com/docs/developer-guide/provider-runtime\n\n## Overview\n\nHermes implements a shared provider runtime resolver used across CLI, gateway, cron jobs, ACP, and auxiliary model calls. The primary implementation files include `hermes_cli/runtime_provider.py`, `hermes_cli/auth.py`, and `hermes_cli/model_switch.py`.\n\n## Core Architecture\n\nThe resolver uses a plugin-based system where providers are declared in `plugins/model-providers/<name>/` and register themselves via `register_provider()`. Each plugin specifies:\n\n- `api_mode`\n- `base_url`\n- `env_vars`\n- `fallback_models`\n\nThe `get_provider_profile()` function returns canonical configuration for any provider, eliminating duplication across the codebase.\n\n## Resolution Precedence\n\nProvider selection follows this hierarchy:\n\n1. Explicit CLI/runtime request\n2. `config.yaml` model/provider configuration\n3. Environment variables\n4. Provider-specific defaults or auto-resolution\n\nThis ordering ensures saved model choices take priority, preventing stale shell exports from overriding user selections.\n\n## Supported Provider Families\n\nThe system includes 30+ provider integrations including:\n\n- OpenRouter, Nous Portal, OpenAI Codex\n- Anthropic (native), Google Gemini, DeepSeek\n- AWS Bedrock, Azure Foundry, NVIDIA NIM\n- Ollama Cloud, LM Studio\n- Custom OpenAI-compatible endpoints\n\n## Resolution Output\n\nThe resolver returns:\n\n- Provider identifier\n- API mode specification\n- Base URL\n- API key with source tracking\n- Provider-specific metadata (expiry/refresh info)\n\n## Key Implementation Details\n\n**OpenAI-Compatible Endpoints**: The system prevents API key leakage by scoping credentials to specific base URLs. OpenAI keys work for custom endpoints as fallback.\n\n**Native Anthropic Path**: When anthropic is selected, the system uses `api_mode = anthropic_messages` and native Messages API via `agent/anthropic_adapter.py`.\n\n**Auxiliary Model Routing**: Tasks like vision, summarization, and memory operations can route to independent providers using the same runtime resolution path.\n\n## Fallback Models\n\nHermes supports configured fallback provider chains -- ordered lists of `(provider, model)` pairs tried sequentially on errors.\n\n**Activation Triggers**:\n- Invalid API responses after max retries\n- Non-retryable client errors (401, 403, 404)\n- Transient errors (429, 500, 502, 503) after retry exhaustion\n\n**Activation Process**: The system calls `_try_activate_fallback()` to rebuild the client with proper authentication, swap model/provider configuration in-place, and reset the retry counter.\n\n**Limitations**: Subagent delegation inherits parent provider settings but not fallback configuration. Auxiliary tasks use independent auto-detection chains.\n\n## Related Documentation\n\n- Agent Loop Internals\n- ACP Internals\n- Context Compression & Prompt Caching\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-hermes-research",
      "to": "page:docs-hermes-research-raw-provider-runtime",
      "kind": "contains_page"
    }
  ]
}