hermes-skills/skills/devops/model-failover-and-credit-tracking/references/model-routing-policy-2026-07-14.md

Model Routing Policy — 2026-07-14

User-confirmed routing shape

Production model routing must follow this provider order:

Primary     → admin-ai
Fallback 1  → admin-ai
Fallback 2  → OpenRouter direct
Fallback 3  → independent direct frontier-capable provider

At Fallback 3, the priority is uptime/access to Sho'Nuff and model competence, not cost optimization. The model must be capable enough for serious ops/debugging/infrastructure work, not merely available.

Concrete target route from this session

Primary:
  deepseek-v4-pro via admin-ai

Fallback 1:
  deepseek-chat via admin-ai

Fallback 2:
  openrouter/qwen/qwen3.6-plus via OpenRouter direct

Fallback 3:
  xai/grok-4.3 via xAI direct

This satisfies:

• admin-ai primary control and LiteLLM logging
• same-router model fallback
• independent OpenRouter fallback
• independent direct frontier-capable fallback
• no Ollama/Gemini in normal text routing

Fallback 3 provider pool

Germaine stated keys are available for:

• OpenAI
• Perplexity
• Groq
• OpenRouter
• DeepSeek
• xAI
• Mistral
• Fireworks AI
• Anthropic
• Gemini
• Cohere
• AI21
• Deepgram

For Fallback 3:

• Exclude OpenRouter because it is already Fallback 2.
• Exclude Deepgram from LLM routing; it is speech/audio, not a general chat brain.
• Exclude Gemini from normal text routing unless Germaine explicitly re-approves it.
• Prefer frontier-capable direct providers over cheap/fast small models.

Recommended direct-provider selection order, subject to live completion and quota tests:

1. OpenAI direct GPT-5.5/GPT-5-class, if quota/billing healthy
2. Anthropic direct Claude Opus/Sonnet-class, if usage limit healthy
3. xAI direct high-end Grok
4. Mistral direct top model, if configured and tested
5. Fireworks AI high-end hosted model, if selected and tested
6. Groq direct only if the selected model is good enough for Sho'Nuff ops
7. DeepSeek direct only if frontier providers are unavailable and uptime is at risk
8. Cohere / AI21 only after explicit quality testing

Direct-vs-aggregator distinction

Model IDs prefixed with openrouter/ are OpenRouter routes even if the model family is OpenAI, Anthropic, Qwen, etc. Examples:

openrouter/openai/gpt-5.2-pro         → OpenRouter route
openrouter/anthropic/claude-opus-4.7  → OpenRouter route
openrouter/qwen/qwen3.6-plus          → OpenRouter route

A true direct provider fallback should use that provider's direct route, e.g. xai/grok-4.3 for xAI direct.

Verified candidates from this session

Working via current app1 admin-ai endpoint:

deepseek-v4-pro                      OK
deepseek-chat                        OK
xai/grok-4.3                         OK
xai/grok-4-1-fast                    OK
openrouter/qwen/qwen3.6-plus         OK via OpenRouter route
openrouter/openai/gpt-5.2-pro        OK via OpenRouter route
openrouter/anthropic/claude-opus-4.7 OK via OpenRouter route

Failing/limited during this session:

gpt-5.5 direct/admin-ai              OpenAI insufficient_quota
claude-opus/sonnet direct            Anthropic usage limit until 2026-08-01
mistral direct names tested          no healthy LiteLLM deployment configured
qwen/qwen3-32b direct name           no healthy LiteLLM deployment configured

Explicit exclusions from automatic routing

• Ollama / llama3.2:3b: too weak for Sho'Nuff operations; do not use as automatic fallback or LLM cron model.
• Gemini: removed from normal model-routing plan; do not reintroduce as normal fallback just because it tests cleanly. It may remain available for vision/manual use if approved.
• GPT/Claude: escalation/frontier candidates only when quotas allow; do not make them hidden uptime dependencies while quota-limited.

Health check requirements

Do not trust /v1/models alone. A route is healthy only if a real /v1/chat/completions call returns usable content.

Check each production tier separately:

• admin-ai primary model completion
• admin-ai fallback model completion
• OpenRouter direct fallback completion
• selected Fallback 3 direct-provider completion

Use enough max_tokens for reasoning models; too-small budgets can produce blank/length-limited responses and false negatives.

GPT/Claude quota failures should be reported as escalation-model unavailable, not as total admin-ai failure.

Background jobs

• Script-only jobs should stay no_agent=true where possible.
• No cron/background job should be pinned to Ollama.
• Jobs using admin-ai must use admin-ai model IDs, e.g. deepseek-chat, not OpenRouter model IDs like deepseek/deepseek-chat.
• Pinned cron jobs do not inherit the conversation fallback chain; audit and pin them explicitly.