mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-07-20 15:33:54 +00:00

ScotterMonk d9cdb81923 feat(config): support per-model reasoning_effort overrides

Add agent.reasoning_overrides dict to config.yaml. Users can now set
a reasoning_effort per model, overriding the global agent.reasoning_effort.

Example:
  agent:
    reasoning_effort: "medium"       # global default
    reasoning_overrides:
      "openrouter/anthropic/claude-opus-4.5": "xhigh"
      "openai/gpt-5": "low"
      "claude-sonnet-4.6": "high"    # bare model name also works

The helper is spelling-tolerant: override keys match regardless of
provider prefix or dots-vs-dashes normalization, so users can write
keys in any sensible form and they'll match.

Resolution priority:
1. Session-scoped /reasoning --session override (gateway only; unchanged)
2. Per-model override from agent.reasoning_overrides (spelling-tolerant)
3. Global agent.reasoning_effort (existing)
4. Provider default (unchanged)

Wired into:
- CLI startup (cli.py)
- Messaging gateway agent construction (gateway/run.py)
- Desktop/TUI _load_reasoning_config (tui_gateway/server.py)
- Cron job scheduler (cron/scheduler.py)
- /model mid-session switch (agent/agent_runtime_helpers.py)
  + _primary_runtime now tracks reasoning_config for correct fallback recovery
- Fallback activation (agent/chat_completion_helpers.py::try_activate_fallback)
  + Re-resolves reasoning_config for the fallback model (best-effort)

Closes #21256 (per-model reasoning_effort defaults).

Note: no hermes config set agent.reasoning_overrides.<model> support;
users edit the YAML directly. _set_nested splits on "." and would
corrupt model keys containing version dots.

2026-07-14 11:46:40 -07:00

3.1 KiB

Raw Blame History

Hermes Agent Configuration Guide

Per-Model Reasoning Effort Overrides

You can configure different reasoning effort levels for different models. This allows you to set high effort for complex reasoning models like claude-opus-4.5 while keeping medium for faster models like gemini-flash.

Configuration

Edit your config.yaml (typically at ~/.hermes/config.yaml):

agent:
  reasoning_overrides:
    claude-opus-4.5: high
    gemini-flash: medium
    gpt-4.5: high

Key Matching

The model name matching is spelling-tolerant. All of these variations will match:

claude-opus-4.5, claude-opus-4-5, claude-opus.4.5
anthropic/claude-opus-4.5, openrouter/anthropic/claude-opus-4.5
With or without provider prefixes

Exact matches take precedence over variants.

Resolution Order

When determining reasoning effort for a model, Hermes checks in this order:

Session override: /reasoning high (current session only)
Per-model override: agent.reasoning_overrides.<model> from config.yaml
Global default: agent.reasoning_effort from config.yaml

How It Works

The override applies automatically in these scenarios:

CLI startup: Uses the override for the configured default model
Gateway messaging: Each gateway session uses the override for its model
Desktop/TUI: Uses the override for the configured model
Model switching: When you switch models, the reasoning effort updates to the new model's override
Fallback activation: When the primary model fails and Hermes falls back to a secondary model, it uses that fallback model's override
Reasoning recovery: When the primary model recovers after a fallback, the original model's override is restored

Examples

Example 1: High effort for Opus, medium for others

agent:
  reasoning_overrides:
    claude-opus-4.5: high

Example 2: Different efforts per model

agent:
  reasoning_overrides:
    claude-opus-4.5: high
    gemini-2.0-flash: low
    gpt-4.5: high
    o3-mini: medium

Example 3: With provider prefixes

agent:
  reasoning_overrides:
    anthropic/claude-opus-4.5: high
    google/gemini-2.0-flash: low

All of these are equivalent — the provider prefix is optional.

Disabling Reasoning for Specific Models

Set the override to none to disable reasoning for a specific model:

agent:
  reasoning_overrides:
    gemini-flash: none

Troubleshooting

Override not taking effect?

Check the exact model name in your config with /model
Verify the override is under agent.reasoning_overrides (not agent.reasoning_effort)
Restart the gateway or CLI session after editing config.yaml
Check logs for parsing errors

Override applies but reasoning doesn't work?

Not all models support reasoning (e.g., gemini-flash has limited support)
Check the model's documentation for reasoning capability
Use a model that explicitly supports extended thinking

Session override not respecting per-model override?

Session overrides take precedence (by design)
Clear the session override with /reasoning default to return to the per-model override

3.1 KiB Raw Blame History