fix: gate reasoning fields on model.reasoning inside apply_reasoning_control

Consolidates the model.reasoning check that each provider re-implemented
inconsistently into apply_reasoning_control itself:

- Anthropic no longer sends thinking:enabled to non-reasoning models (the
  deleted clamp_thinking_level used to guarantee this; nothing replaced it).
- Hybrid/off-mode payloads (e.g. Qwen's enable_thinking:false) now apply
  regardless of model.reasoning, restoring the pre-refactor behavior.
- Chat Completions no longer injects a default temperature for reasoning
  models (o-series/gpt-5 reject non-default temperature), matching the
  guard already present in the Responses provider.
- Anthropic's built-in profile now has budgets for effort="minimal"/"max"
  so requesting them doesn't produce thinking:enabled with no budget_tokens.
- OpenAI's effort="max" now maps to the real "xhigh" tier instead of the
  invalid literal "max".
- get_capability_profile() drops unreachable fallback branches and the
  magic "anthropic.messages.legacy_budget" string in favor of a small
  alias table and a direct ("anthropic", "messages") call.
- The postgres schema-mismatch hint now names the actual upgrade_vN_to_vM_op
  helper(s) needed instead of hardcoding the v3->v4 helper.
- Docs updated for the ReasoningControl/ReasoningCapability rename.

Author: claude

cubepi/checkpointer/postgres/checkpointer.py

@@ -44,6 +44,25 @@ def _run_key(run_id: str | None) -> str:
     return run_id or ""
 
 
+def _schema_mismatch_hint(actual: int, expected: int) -> str:
+    """Build the operator-facing hint for a schema-version mismatch.
+
+    Names the actual upgrade_vN_to_vM_op() helper(s) needed to close the gap
+    between ``actual`` and ``expected``, rather than hardcoding one version
+    transition, so the hint stays correct as EXPECTED_SCHEMA_VERSION grows.
+    """
+    steps = ", ".join(
+        f"upgrade_v{v}_to_v{v + 1}_op()" for v in range(actual, expected)
+    )
+    return (
+        "cubepi was upgraded but host alembic is behind. "
+        f"Generate a new alembic revision that calls {steps} + "
+        "write_schema_version_op() (see "
+        "cubepi.checkpointer.postgres.alembic_helpers) and run "
+        "`alembic upgrade head` against this database."
+    )
+
+
 def _serialize_structured_value(value: StructuredValue) -> str:
     return _STRUCTURED_VALUE_ADAPTER.dump_json(value).decode("utf-8")
 
@@ -131,13 +150,7 @@ async def _verify_schema(self) -> None:
                 raise CubepiSchemaMismatch(
                     expected=EXPECTED_SCHEMA_VERSION,
                     actual=row["version"],
-                    hint=(
-                        "cubepi was upgraded but host alembic is behind. "
-                        "Generate a new alembic revision that calls "
-                        "add_run_id_column_op() + write_schema_version_op() "
-                        "(see cubepi.checkpointer.postgres.alembic_helpers) "
-                        "and run `alembic upgrade head` against this database."
-                    ),
+                    hint=_schema_mismatch_hint(row["version"], EXPECTED_SCHEMA_VERSION),
                 )
 
     async def load(self, thread_id: str) -> CheckpointData | None:

cubepi/providers/anthropic.py

@@ -91,11 +91,12 @@ def __init__(
             cache_policy or DefaultCacheMarkerPolicy()
         )
         # Anthropic always runs the capability path; capability=None falls back
-        # to _ANTHROPIC_DEFAULT_CAPABILITY which mirrors legacy wire bytes.
+        # to the built-in Anthropic Messages profile, which mirrors legacy
+        # wire bytes.
         self._capability: CapabilityDescriptor = (
             capability
             if capability is not None
-            else get_capability_profile("anthropic.messages.legacy_budget")
+            else get_capability_profile("anthropic", "messages")
         )
         self._model_overrides: dict[str, CapabilityDescriptor] = (
             model_capability_overrides or {}

cubepi/providers/capability.py

@@ -135,9 +135,17 @@ def apply_reasoning_control(
     *,
     model: Model | None = None,
 ) -> list[CapabilityWarning]:
-    """Apply provider-independent reasoning controls to a provider payload."""
-    del model
-
+    """Apply provider-independent reasoning controls to a provider payload.
+
+    When ``model.reasoning`` is False, any requested mode other than "off" is
+    treated as "off" — the model can't reason, so no effort/summary/include
+    fields are written and only the "off" mode payload (if any) applies. This
+    is what lets a hybrid model's off-payload (e.g. Qwen's
+    ``enable_thinking: false``) keep firing regardless of ``model.reasoning``,
+    while never sending enable/effort/summary fields to a model that can't use
+    them. Callers should invoke this unconditionally rather than re-deriving
+    their own ``model.reasoning`` gate.
+    """
     reasoning = (
         capability.reasoning
         if isinstance(capability, CapabilityDescriptor)
@@ -146,35 +154,44 @@ def apply_reasoning_control(
     if reasoning is None:
         return []
 
+    model_supports_reasoning = model is None or model.reasoning
+    effective_mode = control.mode if model_supports_reasoning else "off"
+
     warnings: list[CapabilityWarning] = []
-    mode_payload = reasoning.mode_payloads.get(control.mode)
+    mode_payload = reasoning.mode_payloads.get(effective_mode)
     if mode_payload is not None:
         merge_capability_payload(kwargs, mode_payload)
     else:
-        _handle_unsupported_mode(reasoning, control.mode, warnings)
+        _handle_unsupported_mode(reasoning, effective_mode, warnings)
 
     if (
-        reasoning.effort_path is not None
-        and (control.mode != "off" or reasoning.apply_effort_when_off)
+        model_supports_reasoning
+        and reasoning.effort_path is not None
+        and (effective_mode != "off" or reasoning.apply_effort_when_off)
     ):
         effort = reasoning.effort_values.get(control.effort)
         if effort is not None:
             _write_dotted_path(kwargs, reasoning.effort_path, effort)
 
-    if reasoning.summary_path is not None:
+    if (
+        model_supports_reasoning
+        and reasoning.summary_path is not None
+        and effective_mode != "off"
+    ):
         summary = reasoning.summary_values.get(control.summary)
         if summary is not None:
             _write_dotted_path(kwargs, reasoning.summary_path, summary)
 
-    for key in (
-        "always",
-        f"mode:{control.mode}",
-        f"effort:{control.effort}",
-        f"summary:{control.summary}",
-    ):
-        patch = reasoning.include_payloads.get(key)
-        if patch is not None:
-            merge_capability_payload(kwargs, patch)
+    if model_supports_reasoning:
+        for key in (
+            "always",
+            f"mode:{effective_mode}",
+            f"effort:{control.effort}",
+            f"summary:{control.summary}",
+        ):
+            patch = reasoning.include_payloads.get(key)
+            if patch is not None:
+                merge_capability_payload(kwargs, patch)
 
     return warnings
 

cubepi/providers/openai.py

@@ -151,7 +151,10 @@ async def _produce() -> None:
                 # temperature or max_tokens. Spec §3.5.
                 cap = self._resolve_capability(model.id)
                 if self._cap_active or model.reasoning:
-                    kwargs.setdefault("temperature", model.temperature)
+                    # Reasoning models reject a non-default temperature, so
+                    # only setdefault it for models that don't reason.
+                    if not model.reasoning:
+                        kwargs.setdefault("temperature", model.temperature)
                     # Don't inject a default max_tokens when the caller already
                     # set the renamed target field (e.g. max_completion_tokens
                     # via on_payload).
@@ -160,8 +163,7 @@ async def _produce() -> None:
                     apply_temperature(kwargs, cap.temperature)
                     if cap.max_tokens_field != "max_tokens" and "max_tokens" in kwargs:
                         kwargs[cap.max_tokens_field] = kwargs.pop("max_tokens")
-                    if model.reasoning:
-                        apply_reasoning_control(kwargs, cap, opts.reasoning, model=model)
+                    apply_reasoning_control(kwargs, cap, opts.reasoning, model=model)
 
                 # Fire request listeners AFTER all kwargs mutations so observers
                 # see the final wire payload (including extra_body merges,

cubepi/providers/openai_responses.py

@@ -149,8 +149,7 @@ async def _produce() -> None:
                         kwargs.setdefault("max_output_tokens", model.max_tokens)
                     cap = self._resolve_capability(model.id)
                     apply_temperature(kwargs, cap.temperature)
-                    if model.reasoning:
-                        apply_reasoning_control(kwargs, cap, opts.reasoning, model=model)
+                    apply_reasoning_control(kwargs, cap, opts.reasoning, model=model)
                 else:
                     if model.max_tokens:
                         kwargs.setdefault("max_output_tokens", model.max_tokens)

cubepi/providers/reasoning_profiles.py

@@ -11,7 +11,9 @@
     "low": "low",
     "medium": "medium",
     "high": "high",
-    "max": "max",
+    # OpenAI has no "max" effort value; "xhigh" is its highest tier (mirrors
+    # the legacy _THINKING_TO_EFFORT mapping's "xhigh" -> "xhigh").
+    "max": "xhigh",
 }
 
 _OPENAI_SUMMARY_VALUES: dict[ReasoningSummary, Any] = {
@@ -22,6 +24,11 @@
 }
 
 
+_API_ALIASES: dict[tuple[str, str], tuple[str, str]] = {
+    ("openai", "openai-completions"): ("openai", "chat_completions"),
+}
+
+
 def get_capability_profile(provider: str, api: str | None = None) -> CapabilityDescriptor:
     """Return the built-in capability profile for a provider/API pair."""
 
@@ -31,17 +38,10 @@ def get_capability_profile(provider: str, api: str | None = None) -> CapabilityD
     if api is None:
         return CapabilityDescriptor()
 
-    key = (provider_key, api)
+    key = _API_ALIASES.get((provider_key, api), (provider_key, api))
     profile = _PROFILES.get(key)
     if profile is not None:
         return profile.model_copy(deep=True)
-
-    if provider_key == "openai" and api in {"chat_completions", "openai-completions"}:
-        return _PROFILES[("openai", "chat_completions")].model_copy(deep=True)
-    if provider_key == "openai" and api == "responses":
-        return _PROFILES[("openai", "responses")].model_copy(deep=True)
-    if provider_key == "anthropic":
-        return _PROFILES[("anthropic", "messages")].model_copy(deep=True)
     return CapabilityDescriptor()
 
 
@@ -80,9 +80,15 @@ def get_capability_profile(provider: str, api: str | None = None) -> CapabilityD
             },
             effort_path="thinking.budget_tokens",
             effort_values={
+                # Anthropic requires budget_tokens >= 1024 for extended
+                # thinking; "minimal" uses that floor.
+                "minimal": 1024,
                 "low": 2048,
                 "medium": 8192,
                 "high": 16384,
+                # No tier above "high" in the legacy budget scale (the old
+                # ThinkingLevel="xhigh" clamped down to "high"'s budget).
+                "max": 16384,
             },
             apply_effort_when_off=False,
             unsupported_mode_policy="skip",

tests/checkpointer/test_postgres_schema.py

@@ -1,13 +1,26 @@
 import asyncpg
 import pytest
 
+from cubepi.checkpointer.postgres.checkpointer import _schema_mismatch_hint
 from cubepi.checkpointer.postgres.models import EXPECTED_SCHEMA_VERSION
 
 
 def test_expected_schema_version_is_5():
     assert EXPECTED_SCHEMA_VERSION == 5
 
 
+def test_schema_mismatch_hint_names_the_v4_to_v5_helper():
+    hint = _schema_mismatch_hint(actual=4, expected=5)
+    assert "upgrade_v4_to_v5_op()" in hint
+    assert "add_run_id_column_op" not in hint
+
+
+def test_schema_mismatch_hint_names_every_step_across_multiple_versions():
+    hint = _schema_mismatch_hint(actual=3, expected=5)
+    assert "upgrade_v3_to_v4_op()" in hint
+    assert "upgrade_v4_to_v5_op()" in hint
+
+
 @pytest.mark.asyncio
 async def test_cubepi_runs_table_present(pg_v4_dsn):
     conn = await asyncpg.connect(pg_v4_dsn)

tests/providers/test_openai_capability.py

@@ -171,6 +171,18 @@ async def test_openai_chat_off_writes_minimal_effort() -> None:
     assert payload["reasoning_effort"] == "minimal"
 
 
+@pytest.mark.asyncio
+async def test_openai_chat_reasoning_model_does_not_get_default_temperature() -> None:
+    """Reasoning models on chat completions reject a non-default temperature;
+    a legacy caller with no explicit capability must not have one injected."""
+    payload = await _capture_payload_openai(
+        OpenAIProvider(api_key="x", base_url="http://example"),
+        _model(reasoning=True, temperature=0.7),
+    )
+
+    assert "temperature" not in payload
+
+
 @pytest.mark.asyncio
 async def test_temperature_ignored_strips_field():
     cap = CapabilityDescriptor(temperature=TemperatureSpec(mode="ignored"))

tests/providers/test_reasoning_capability.py

@@ -92,3 +92,104 @@ def test_lint_warns_for_top_level_thinking_on_openai_chat():
     assert isinstance(warnings[0], CapabilityWarning)
     assert warnings[0].code == "openai_chat_top_level_thinking"
     assert "extra_body.thinking" in warnings[0].message
+
+
+def test_apply_reasoning_clamps_mode_to_off_for_non_reasoning_model():
+    """A non-reasoning model must never receive an enabled mode payload,
+    mirroring the clamping the deleted clamp_thinking_level used to do."""
+    cap = get_capability_profile("anthropic", "messages")
+    payload: dict = {}
+
+    apply_reasoning_control(
+        payload,
+        cap,
+        ReasoningControl(mode="on", effort="medium"),
+        model=Model(id="claude-haiku", provider_id="anthropic", reasoning=False),
+    )
+
+    assert payload == {"thinking": {"type": "disabled"}}
+
+
+def test_apply_reasoning_off_payload_applies_regardless_of_model_reasoning():
+    """Hybrid models (e.g. Qwen) must still get their off-mode payload even
+    when registered with reasoning=False."""
+    cap = CapabilityDescriptor(
+        reasoning=ReasoningCapability(
+            mode_payloads={
+                "off": {"extra_body": {"enable_thinking": False}},
+                "on": {"extra_body": {"enable_thinking": True}},
+            }
+        )
+    )
+    payload: dict = {}
+
+    apply_reasoning_control(
+        payload,
+        cap,
+        ReasoningControl(mode="off"),
+        model=Model(id="qwen", provider_id="test", reasoning=False),
+    )
+
+    assert payload == {"extra_body": {"enable_thinking": False}}
+
+
+def test_apply_reasoning_skips_effort_for_non_reasoning_model_even_with_apply_when_off():
+    """model.reasoning=False must suppress effort writes entirely, even when
+    the capability sets apply_effort_when_off=True."""
+    cap = CapabilityDescriptor(
+        reasoning=ReasoningCapability(
+            mode_payloads={"on": {"reasoning": {"effort": "low"}}},
+            effort_path="reasoning.effort",
+            effort_values={"medium": "medium"},
+        )
+    )
+    payload: dict = {}
+
+    apply_reasoning_control(
+        payload,
+        cap,
+        ReasoningControl(mode="on", effort="medium"),
+        model=Model(id="gpt-4o", provider_id="test", reasoning=False),
+    )
+
+    assert payload == {}
+
+
+def test_anthropic_profile_has_budgets_for_minimal_and_max_effort():
+    cap = get_capability_profile("anthropic", "messages")
+    payload: dict = {}
+
+    apply_reasoning_control(
+        payload,
+        cap,
+        ReasoningControl(mode="on", effort="max"),
+        model=Model(id="claude-opus", provider_id="anthropic", reasoning=True),
+    )
+
+    assert payload["thinking"]["type"] == "enabled"
+    assert payload["thinking"]["budget_tokens"] > 0
+
+
+def test_openai_effort_max_maps_to_xhigh_not_invalid_max_value():
+    cap = get_capability_profile("openai", "responses")
+    payload: dict = {}
+
+    apply_reasoning_control(
+        payload,
+        cap,
+        ReasoningControl(mode="on", effort="max"),
+        model=Model(id="gpt-5", provider_id="openai", reasoning=True),
+    )
+
+    assert payload["reasoning"]["effort"] == "xhigh"
+
+
+def test_get_capability_profile_resolves_openai_completions_alias():
+    direct = get_capability_profile("openai", "chat_completions")
+    aliased = get_capability_profile("openai", "openai-completions")
+    assert aliased == direct
+
+
+def test_get_capability_profile_unknown_pair_returns_empty_descriptor():
+    cap = get_capability_profile("some-vendor", "some-api")
+    assert cap == CapabilityDescriptor()

website/docs/getting-started/core-concepts.md

@@ -81,8 +81,7 @@ class Provider(Protocol):
         options: StreamOptions | None = None,
         max_output_tokens: int | None = None,
         temperature: float | None = None,
-        thinking: ThinkingLevel | None = None,
-        thinking_budgets: ThinkingBudgets | None = None,
+        reasoning: ReasoningControl | None = None,
     ) -> AssistantMessage: ...
 ```
 
@@ -92,7 +91,7 @@ yields `StreamEvent`s and exposes the final `AssistantMessage` via
 the final message directly; `BaseProvider` implements it for any
 provider that implements `stream()`. Built-in providers:
 
-- `AnthropicProvider` — Claude (Messages API, with thinking, caching,
+- `AnthropicProvider` — Claude (Messages API, with reasoning, caching,
   tool use).
 - `OpenAIProvider` — GPT family (Chat Completions API).
 - `OpenAIResponsesProvider` — GPT family (Responses API, server-side