Coerce reasoning effort to model/provider-supported levels

[franksong2702]

Thinking Path

• Hermes WebUI aims for near 1:1 parity with the Hermes CLI in the browser, including the reasoning-effort control for thinking-capable models.
• A configured effort (agent.reasoning_effort) is the same across a session, but different models/providers accept different effort levels — e.g. openai-codex gpt-5 rejects max, and o1/o3/o4 only accept low/medium/high.
• Previously the configured effort was handed to the provider as-is, so an unsupported value could be rejected downstream or silently misbehave.
• This PR clamps the configured effort to the closest level the target model/provider actually supports, before the turn runs.
• The benefit is that switching models no longer requires re-picking an effort level, and an effort the model can't honor degrades predictably instead of failing.

What Changed

• api/config.py
  • _filter_reasoning_efforts_for_provider() applies per-provider quirks to an otherwise-valid effort list: strips max for openai-codex gpt-5, restricts o1/o3/o4 to low/medium/high. It is threaded through all four resolution paths (heuristic, models.dev, copilot, lmstudio).
  • coerce_reasoning_effort_for_model() resolves the supported levels for the target model and returns the configured effort if supported, otherwise degrades to the closest lower supported level (e.g. max → xhigh → high, xhigh → high). It never escalates, and returns "" only when no lower level exists.
  • resolve_model_reasoning_efforts() no longer double-applies the provider filter to the already-filtered _models_dev_reasoning_efforts() result.
• api/streaming.py
  • _run_agent_streaming routes the configured effort through coerce_reasoning_effort_for_model() before parse_reasoning_effort(), so the agent receives a model-appropriate value.

This is one logical change (reasoning-effort coercion). It was split out of #3401 so it can be reviewed on its own.

Why It Matters

Without coercion, a configured effort that a model cannot honor is either rejected by the provider or silently disabled. In particular, a user with reasoning_effort: xhigh who switched to a model capped at high previously got reasoning turned off entirely. Clamping down to the nearest supported level keeps reasoning on at the best level the model allows, and removes a class of "why did reasoning stop working when I changed models" confusion.

Verification

python -m pytest -q tests/test_reasoning_effort_model_capabilities.py tests/test_models_dev_reasoning.py tests/test_reasoning_show_hide.py
# 47 passed
python3 -m py_compile api/config.py api/streaming.py   # ok

Tests cover: gpt-5 max → xhigh clamp, xhigh → high / max → high degrade on o1/o3/o4, the no-escalation invariant (a supported lower effort is returned verbatim), and the streaming wiring contract. CI runs the full suite on Python 3.11/3.12/3.13.

No user-visible UI change (this is backend effort resolution), so no screenshots apply.

Risks / Follow-ups

• Behavioral surface is narrow: only the effort value passed to the agent changes, and only when the configured level is unsupported by the target model.
• The provider quirks (gpt-5 no-max, o* capped at high) are encoded as small explicit rules; new provider quirks would extend _filter_reasoning_efforts_for_provider().
• Not a contract-affecting change: no public contract doc or RFC describes reasoning-effort selection, so no Contract Routing / Contract Change section is required.

Model Used

AI-assisted.

• Provider: Anthropic
• Model: Claude Opus 4.8
• Mode/tools: Claude Code agentic session (repo edits, local pytest/py_compile verification)

[greptile-apps]

Greptile Summary

This PR introduces coerce_reasoning_effort_for_model() and _filter_reasoning_efforts_for_provider() in api/config.py to map a configured reasoning effort to the closest level a target model/provider actually supports before each streaming turn, replacing the previous pass-through of the raw config value.

• Adds _filter_reasoning_efforts_for_provider() that enforces provider/model quirks (drops max for gpt-5 on openai-codex; restricts o1/o3/o4 to low/medium/high) and threads this filter through all resolution paths (heuristic, models.dev, copilot, lmstudio).
• Adds coerce_reasoning_effort_for_model() with a downgrade ladder so that an unsupported effort (e.g. max on openai-codex gpt-5) falls back to the highest supported level below it rather than silently disabling reasoning.
• Wires coerce_reasoning_effort_for_model() + parse_reasoning_effort() into _run_agent_streaming in api/streaming.py, replacing the previous direct parse_reasoning_effort call.

Confidence Score: 5/5

Safe to merge — the coerce logic is correct, all resolution paths are covered, and the downgrade ladder handles edge cases that were flagged in prior review rounds.

The downgrade chain in coerce_reasoning_effort_for_model is correct for all effort levels including xhigh (previously flagged as missing a fallback). The filter is threaded consistently through heuristic, models.dev, copilot, and lmstudio paths. Tests cover max-to-xhigh clamping, xhigh-to-high degradation, and non-escalation. The streaming integration correctly preserves the existing try/except guard.

No files require special attention.

Important Files Changed

Filename	Overview
api/config.py	Adds _filter_reasoning_efforts_for_provider and coerce_reasoning_effort_for_model; threads the filter through all resolve paths; downgrade ladder logic is correct and covered by tests.
api/streaming.py	Replaces direct parse_reasoning_effort call with coerce_reasoning_effort_for_model + parse_reasoning_effort in _run_agent_streaming; existing try/except guard is preserved.
tests/test_reasoning_effort_model_capabilities.py	Adds tests for max-clamping to xhigh (gpt-5.5), xhigh/max degradation to high (o3-mini), and non-escalation invariant; all cover the critical coerce paths.
tests/test_models_dev_reasoning.py	Updates existing gpt-5.5/openai-codex test to assert max is excluded and xhigh is present, consistent with new filter behavior.
tests/test_reasoning_show_hide.py	Adds import-presence assertion for coerce_reasoning_effort_for_model in streaming.py; lightweight structural test.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["coerce_reasoning_effort_for_model(effort, model_id, provider_id, base_url)"] --> B{raw empty?}
    B -- yes --> C["return ''"]
    B -- no --> D{raw == 'none'?}
    D -- yes --> E["return 'none'"]
    D -- no --> F{raw in VALID_REASONING_EFFORTS?}
    F -- no --> G["return ''"]
    F -- yes --> H["resolve_model_reasoning_efforts(model_id, provider_id, base_url)"]
    H --> I["_filter_reasoning_efforts_for_provider(efforts, model, provider)"]
    I --> J{provider == openai-codex?}
    J -- o1/o3/o4 --> K["keep only low/medium/high"]
    J -- gpt-5 --> L["drop max"]
    J -- other --> M["return normalized as-is"]
    K --> N["supported list"]
    L --> N
    M --> N
    N --> O{raw in supported?}
    O -- yes --> P["return raw"]
    O -- no --> Q["walk ladder downward from raw"]
    Q --> R{any lower level supported?}
    R -- yes --> S["return highest supported level below raw"]
    R -- no --> T["return ''"]

Loading

_{Reviews (2): Last reviewed commit: "Address review: generalize effort clamp,..." | Re-trigger Greptile}

[nesquena-hermes]

Shipped in v0.51.247 (Release HO) — thank you @franksong2702! 🙏 Reasoning effort is now coerced to the level the active model/provider actually supports (gpt-5/codex max→xhigh, o1/o3/o4→high), only ever stepping down. One adjustment on the way in: the first cut dropped a configured effort for unrecognized models (capability detection returns [] for both known-unsupported AND simply-unknown models); we changed it to preserve the configured effort on an empty/unknown capability set so custom/aggregator models keep their effort (the provider stays the final authority), while the known-bad clamps still degrade. The chip-visibility gate is untouched. + regression test. Closing as merged-via-release-stage.