Python
"""Reasoning-effort levels and their per-provider translation (OPE-176).
One setting, `reasoning_effort`, five levels mirroring Anthropic's: low, medium, high,
xhigh, max. Unset means "send nothing" — every provider's request stays byte-identical to
before the setting existed (Anthropic's API default is `high`; Together's default for
Kimi K3 is `max`). Each provider client translates a level into the parameter its wire
accepts, records what it actually sent, and falls back (once, per model, per run) when
the endpoint rejects the parameter.
Level names a model does not accept map to the NEAREST accepted level by rank, ties going
UP (xhigh on Kimi K3 → max; medium on Kimi K3 → high). The mapping is recorded on every
reply as `{requested, effective, param, note}` so a run record states its effort.
Sources (read 2026-09-08): platform.claude.com/docs/en/build-with-claude/effort (supported
models per level; `high` == omitted; hold the level constant within a conversation or
the prompt cache restarts); Moonshot/Together Kimi K3 docs (`reasoning_effort` low/high/max,
default max).
"""
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any, Optional, Sequence
from ..config import EFFORT_LEVELS
_RANK = {level: i for i, level in enumerate(EFFORT_LEVELS)}
# "No thinking, just answer." The auto-title request sends this so a reasoning model does
# not spend its 64-token cap on hidden reasoning. It is not one of the five user-selectable
# levels and never goes through the rank table: Anthropic has no such value (the effort
# field is omitted), and OpenAI-vocabulary endpoints accept it on the wire (#676, #702).
NO_EFFORT = "none"
@dataclass(frozen=True)
class EffortPlan:
requested: str
# The level/value actually sent; None when nothing was sent (unsupported, rejected).
effective: Optional[str]
# Provider request parameters to merge (empty when nothing is sent).
params: dict[str, Any] = field(default_factory=dict)
note: str = ""
def record(self) -> dict[str, Any]:
"""The sidecar persisted on the assistant message / run record."""
out: dict[str, Any] = {"requested": self.requested, "effective": self.effective}
if self.params:
out["param"] = self.params
if self.note:
out["note"] = self.note
return out
def without_param(self, note: str) -> "EffortPlan":
"""The plan after the endpoint rejected the parameter and it was dropped."""
return EffortPlan(self.requested, None, {}, note)
def validate_level(value: Any, source: str = "reasoning_effort") -> Optional[str]:
"""Normalise a configured value to one of EFFORT_LEVELS (case-insensitive) or raise."""
if value is None:
return None
text = str(value).strip().lower()
if not text:
return None
if text not in _RANK:
raise ValueError(
f"{source} must be one of {', '.join(EFFORT_LEVELS)}; got {value!r}"
)
return text
def nearest_supported(level: str, supported: Sequence[str]) -> Optional[str]:
"""The accepted level closest in rank to `level`; ties resolve to the higher one.
Levels outside `_RANK` (e.g. "none", an effort value OpenAI-compatible endpoints
accept but which is not a ranking level) return None — the caller omits the
parameter instead of crashing, since absence of the parameter is valid for
OpenAI-compatible endpoints."""
if not supported:
return None
if level in supported:
return level
if level not in _RANK:
return None
target = _RANK[level]
return min(supported, key=lambda s: (abs(_RANK[s] - target), -_RANK[s]))
# -- Anthropic -----------------------------------------------------------------------
_ALL = tuple(EFFORT_LEVELS)
_NO_XHIGH = ("low", "medium", "high", "max")
# Longest prefix wins. Per the effort doc's "Supported models" + per-level availability.
_ANTHROPIC_EFFORT: tuple[tuple[str, tuple[str, ...]], ...] = (
("claude-fable-5-1", _ALL),
("claude-mythos-5-1", _ALL),
("claude-fable-5", _ALL),
("claude-mythos-5", _ALL),
("claude-mythos-preview", _NO_XHIGH),
("claude-opus-5", _ALL),
("claude-opus-4-8", _ALL),
("claude-opus-4-7", _ALL),
("claude-opus-4-6", _NO_XHIGH),
("claude-opus-4-5", ("low", "medium", "high")),
("claude-sonnet-5", _ALL),
("claude-sonnet-4-6", _NO_XHIGH),
)
# Budget-thinking models (older Claude): the level becomes a thinking budget. Anthropic
# requires budget_tokens >= 1,024 and < max_tokens; the provider floors max_tokens.
BUDGET_TOKENS_BY_LEVEL = {
"low": 2_048,
"medium": 8_192,
"high": 16_000,
"xhigh": 24_000,
"max": 32_000,
}
def _anthropic_supported(model: str) -> Optional[tuple[str, ...]]:
best: Optional[tuple[str, ...]] = None
best_len = -1
for prefix, levels in _ANTHROPIC_EFFORT:
if model.startswith(prefix) and len(prefix) > best_len:
best, best_len = levels, len(prefix)
return best
def anthropic_effort(model: str, level: str, *, budget_mode: bool) -> EffortPlan:
"""`output_config.effort` on adaptive-thinking models; `thinking.budget_tokens` on
budget-mode models. Unknown adaptive models get the level as-is (the 400 fallback
covers a wrong guess); the mapping is recorded either way. `"none"` has no Anthropic
equivalent, so nothing is sent and the API default applies."""
if level == NO_EFFORT:
return unsupported(level, "Anthropic has no effort value 'none'; no effort parameter sent")
if budget_mode:
budget = BUDGET_TOKENS_BY_LEVEL[level]
return EffortPlan(
level,
level,
{"thinking": {"type": "enabled", "budget_tokens": budget}},
f"budget-thinking model: {level} -> budget_tokens {budget}",
)
supported = _anthropic_supported(model)
if supported is None:
return EffortPlan(
level,
level,
{"output_config": {"effort": level}},
"model not in the documented effort table; sent unverified",
)
effective = nearest_supported(level, supported)
assert effective is not None
note = "" if effective == level else f"{level} not accepted by {model}; sent {effective}"
return EffortPlan(level, effective, {"output_config": {"effort": effective}}, note)
# -- OpenAI-compatible endpoints (Together, Moonshot, DeepSeek, …) -------------------
# Bare model id (as the OpenAI-compatible client receives it) → accepted values.
# Only rows with a verified source; everything else gets the OpenAI vocabulary.
_OPENAI_COMPAT: dict[str, tuple[str, ...]] = {
# Kimi K3: Moonshot and Together document reasoning_effort low / high / max.
"moonshotai/Kimi-K3": ("low", "high", "max"),
"moonshotai/kimi-k3": ("low", "high", "max"), # OpenRouter's lowercase slug
"kimi-k3": ("low", "high", "max"),
}
_OPENAI_DEFAULT = ("low", "medium", "high")
def openai_compat_effort(model: str, level: str) -> EffortPlan:
supported = _OPENAI_COMPAT.get(model) or _OPENAI_COMPAT.get(model.lower()) or _OPENAI_DEFAULT
verified = model in _OPENAI_COMPAT or model.lower() in _OPENAI_COMPAT
if level == NO_EFFORT:
# Send it as-is where the OpenAI vocabulary is assumed (it includes "none"). A
# verified row that documents no such value gets its lowest level instead — "none"
# ranks below "low", so that is the nearest accepted one, per this module's rule.
# A rejection is dropped by the provider's param-fix retry like any other.
if verified and NO_EFFORT not in supported:
lowest = min(supported, key=_RANK.__getitem__)
return EffortPlan(level, lowest, {"reasoning_effort": lowest}, f"{model} has no 'none'; sent its lowest level {lowest}")
return EffortPlan(level, level, {"reasoning_effort": level}, "no-thinking request; OpenAI vocabulary assumed")
effective = nearest_supported(level, supported)
if effective is None:
return unsupported(level, f"effort level {level!r} unknown for {model}; no effort parameter sent")
note = ""
if effective != level:
note = f"{level} not accepted by {model}; sent {effective}"
elif not verified:
note = "model not in the verified table; OpenAI vocabulary assumed"
return EffortPlan(level, effective, {"reasoning_effort": effective}, note)
def unsupported(level: str, why: str) -> EffortPlan:
return EffortPlan(level, None, {}, why)
def mentions_effort(exc: BaseException) -> bool:
"""Does an endpoint error name the effort parameter (so dropping it is the fix)?"""
msg = str(exc).lower()
return "effort" in msg or "output_config" in msg