Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

fix: gate reasoning fields on model.reasoning inside apply_reasoning_control

Claude Code992734406918
diff --git a/cubepi/checkpointer/postgres/checkpointer.py b/cubepi/checkpointer/postgres/checkpointer.py
index 2bdbf21..b7b2f55 100644
--- a/cubepi/checkpointer/postgres/checkpointer.py
+++ b/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 @@ class PostgresCheckpointer:
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:
diff --git a/cubepi/providers/anthropic.py b/cubepi/providers/anthropic.py
index 6f334b4..8b841c7 100644
--- a/cubepi/providers/anthropic.py
+++ b/cubepi/providers/anthropic.py
@@ -91,11 +91,12 @@ class AnthropicProvider(BaseProvider):
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 {}
diff --git a/cubepi/providers/capability.py b/cubepi/providers/capability.py
index 2860e5d..f127035 100644
--- a/cubepi/providers/capability.py
+++ b/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
diff --git a/cubepi/providers/openai.py b/cubepi/providers/openai.py
index 9bdc20c..e10e717 100644
--- a/cubepi/providers/openai.py
+++ b/cubepi/providers/openai.py
@@ -151,7 +151,10 @@ class OpenAIProvider(BaseProvider):
# 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 @@ class OpenAIProvider(BaseProvider):
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,
diff --git a/cubepi/providers/openai_responses.py b/cubepi/providers/openai_responses.py
index ab10204..911e994 100644
--- a/cubepi/providers/openai_responses.py
+++ b/cubepi/providers/openai_responses.py
@@ -149,8 +149,7 @@ class OpenAIResponsesProvider(BaseProvider):
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)
diff --git a/cubepi/providers/reasoning_profiles.py b/cubepi/providers/reasoning_profiles.py
index 87b6aad..8d99590 100644
--- a/cubepi/providers/reasoning_profiles.py
+++ b/cubepi/providers/reasoning_profiles.py
@@ -11,7 +11,9 @@ _OPENAI_EFFORT_VALUES: dict[ReasoningEffort, str] = {
"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 @@ _OPENAI_SUMMARY_VALUES: dict[ReasoningSummary, Any] = {
}
+_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 @@ _PROFILES: dict[tuple[str, str], CapabilityDescriptor] = {
},
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",
diff --git a/tests/checkpointer/test_postgres_schema.py b/tests/checkpointer/test_postgres_schema.py
index ff62eb8..a9376b4 100644
--- a/tests/checkpointer/test_postgres_schema.py
+++ b/tests/checkpointer/test_postgres_schema.py
@@ -1,6 +1,7 @@
import asyncpg
import pytest
+from cubepi.checkpointer.postgres.checkpointer import _schema_mismatch_hint
from cubepi.checkpointer.postgres.models import EXPECTED_SCHEMA_VERSION
@@ -8,6 +9,18 @@ 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)
diff --git a/tests/providers/test_openai_capability.py b/tests/providers/test_openai_capability.py
index a94a457..751feea 100644
--- a/tests/providers/test_openai_capability.py
+++ b/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"
+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"))
diff --git a/tests/providers/test_reasoning_capability.py b/tests/providers/test_reasoning_capability.py
index f7996c2..1b6e4cd 100644
--- a/tests/providers/test_reasoning_capability.py
+++ b/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()
diff --git a/website/docs/getting-started/core-concepts.md b/website/docs/getting-started/core-concepts.md
index dfb8083..a98ffca 100644
--- a/website/docs/getting-started/core-concepts.md
+++ b/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
diff --git a/website/docs/guides/agents/first-agent.md b/website/docs/guides/agents/first-agent.md
index bea2b7e..30c0ced 100644
--- a/website/docs/guides/agents/first-agent.md
+++ b/website/docs/guides/agents/first-agent.md
@@ -29,7 +29,7 @@ model = provider.model(
```
`provider_id` lives on the provider constructor and is propagated into the
-bound model automatically — used by the framework to clamp thinking levels
+bound model automatically — used by the framework to gate reasoning fields
and tag responses. Building a `Model` by hand and passing both
`provider=` and `model=` to `Agent` is the 0.6 idiom and no longer works
in 0.7.
diff --git a/website/docs/guides/middleware/compaction.md b/website/docs/guides/middleware/compaction.md
index 3bb54b4..5602395 100644
--- a/website/docs/guides/middleware/compaction.md
+++ b/website/docs/guides/middleware/compaction.md
@@ -37,7 +37,7 @@ agent = Agent(
```
The summary call uses `Provider.generate(...)` with `temperature=0.0` and
-`thinking="off"`. `max_output_tokens` is computed dynamically from the
+`reasoning=ReasoningControl(mode="off")`. `max_output_tokens` is computed dynamically from the
content size (floor 1024, ceiling 4096) when `max_summary_tokens` is `None`,
or passed verbatim otherwise.
diff --git a/website/docs/guides/middleware/examples.md b/website/docs/guides/middleware/examples.md
index cdcdbac..8b15b9b 100644
--- a/website/docs/guides/middleware/examples.md
+++ b/website/docs/guides/middleware/examples.md
@@ -196,8 +196,8 @@ agent = Agent(
```
The summary call uses `Provider.generate(...)` with
-`temperature=0.0`, `thinking="off"`, and `max_output_tokens` set from
-`max_summary_tokens`.
+`temperature=0.0`, `reasoning=ReasoningControl(mode="off")`, and
+`max_output_tokens` set from `max_summary_tokens`.
## Built-in subagents
diff --git a/website/docs/guides/providers/anthropic.md b/website/docs/guides/providers/anthropic.md
index cbf5878..669c48d 100644
--- a/website/docs/guides/providers/anthropic.md
+++ b/website/docs/guides/providers/anthropic.md
@@ -42,58 +42,70 @@ SDK. `provider_id` is a free-form label used by CubePi internals — keep
it stable across your codebase, and set it when you want tracing and
error messages to show a specific source label.
-## Extended thinking
+## Extended thinking (reasoning)
-CubePi maps a `ThinkingLevel` enum onto Anthropic's `budget_tokens`:
+CubePi exposes a provider-independent `ReasoningControl(mode, effort,
+summary)` and maps it onto Anthropic's `thinking` + `budget_tokens`:
-| Level | Default budget |
+| `effort` | Budget |
|---|---|
-| `"off"` | thinking disabled |
+| `"minimal"` | 1024 |
| `"low"` | 2048 |
| `"medium"` | 8192 |
| `"high"` | 16384 |
-| `"xhigh"` | clamped to `"high"` |
+| `"max"` | 16384 (Anthropic has no tier above `"high"`) |
-Set it per-agent:
+`mode="off"` disables thinking; `mode="on"` (or `"auto"`) enables it at
+the given `effort`. Set it per-agent:
```python
-agent = Agent(model=model, thinking="medium")
+from cubepi import ReasoningControl
+
+agent = Agent(
+ model=model,
+ reasoning=ReasoningControl(mode="on", effort="medium"),
+)
```
-To change the per-level budgets, supply a
-[`CapabilityDescriptor`](./overview) with a
-`reasoning_level` of `kind="int_budget"` at construction — its
-`level_budgets` map is the single source of truth for budget values.
+A non-reasoning model (`Model(reasoning=False)`) never receives an
+enabled `thinking` payload, regardless of the requested `mode` — CubePi
+clamps it to `"off"` for you.
+
+To change the per-effort budgets, supply a
+[`CapabilityDescriptor`](./overview) with a `ReasoningCapability` whose
+`effort_values` map is the single source of truth for budget values:
```python
-from cubepi import CapabilityDescriptor, ReasoningLevelSpec
+from cubepi import CapabilityDescriptor, ReasoningCapability
from cubepi.providers.anthropic import AnthropicProvider
provider = AnthropicProvider(
api_key="sk-ant-…",
capability=CapabilityDescriptor(
- reasoning_off_payload={"thinking": {"type": "disabled"}},
- reasoning_on_payload={"thinking": {"type": "enabled"}},
- reasoning_level=ReasoningLevelSpec(
- path="thinking.budget_tokens",
- kind="int_budget",
- level_budgets={"off": 0, "low": 4096,
- "medium": 12288, "high": 16384, "xhigh": 16384},
+ reasoning=ReasoningCapability(
+ mode_payloads={
+ "off": {"thinking": {"type": "disabled"}},
+ "on": {"thinking": {"type": "enabled"}},
+ },
+ effort_path="thinking.budget_tokens",
+ effort_values={
+ "low": 4096, "medium": 12288, "high": 16384, "max": 16384,
+ },
),
),
)
```
-:::note Changed in 0.5
-`AnthropicProvider` no longer honors
-`StreamOptions(thinking_budgets=…)` — the capability descriptor's
-`level_budgets` is now the only way to override budgets.
+:::note Changed in 0.13
+The `thinking` / `ThinkingLevel` / `ThinkingBudgets` API (and
+`StreamOptions(thinking_budgets=…)`) is replaced by `ReasoningControl` +
+`ReasoningCapability`. `Agent(thinking=…)` is now `Agent(reasoning=…)`.
:::
-When thinking is on, CubePi **omits `temperature`** because the
+When reasoning is on, CubePi **omits `temperature`** because the
Anthropic API rejects non-default temperatures alongside extended
thinking ([feature compatibility](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#feature-compatibility)).
-Set `Model.temperature` to the value you want when thinking is off;
+Set `Model.temperature` to the value you want when reasoning is off;
CubePi handles the rest.
Thinking content streams as `thinking_start` / `thinking_delta` /
@@ -177,11 +189,11 @@ and inject it via a [custom provider](./custom).
## Common pitfalls
-- **`temperature` ignored** — Expected. CubePi drops it when thinking
+- **`temperature` ignored** — Expected. CubePi drops it when reasoning
is on; that's an API constraint, not a bug.
-- **`xhigh` looks the same as `high`** — Anthropic doesn't expose a
- budget tier above `high`, so CubePi clamps `xhigh` down. The token
- budget is the same.
+- **`effort="max"` looks the same as `"high"`** — Anthropic doesn't
+ expose a budget tier above `high`, so the built-in profile maps both
+ to the same token budget.
- **Cache misses you didn't expect** — Caches are keyed by content +
ttl. Changing the system prompt invalidates everything; changing the
tool list invalidates from the tools onward. Make those two stable
diff --git a/website/docs/guides/providers/custom.md b/website/docs/guides/providers/custom.md
index cb8ec82..06f3600 100644
--- a/website/docs/guides/providers/custom.md
+++ b/website/docs/guides/providers/custom.md
@@ -25,7 +25,7 @@ class Provider(Protocol):
That is the only method custom providers usually implement. The
inherited `generate()` consumes `stream()` and returns the final
`AssistantMessage`, with per-call overrides for `max_output_tokens`,
-`temperature`, `thinking`, and `thinking_budgets`.
+`temperature`, and `reasoning` (a `ReasoningControl`).
This page covers two scenarios:
diff --git a/website/docs/guides/providers/openai.md b/website/docs/guides/providers/openai.md
index 71661f3..03e805d 100644
--- a/website/docs/guides/providers/openai.md
+++ b/website/docs/guides/providers/openai.md
@@ -32,18 +32,32 @@ provider = OpenAIProvider(
model = provider.model(
"gpt-5",
- reasoning=True, # enables thinking level mapping
+ reasoning=True, # enables reasoning-effort mapping
max_tokens=8192,
context_window=128_000,
)
```
-### Thinking on Chat Completions
+### Reasoning on Chat Completions
OpenAI exposes reasoning content through `delta.reasoning_content` on
o-series and gpt-5 models. CubePi captures it as `ThinkingContent` and
-emits `thinking_*` events identically to Anthropic. The same
-`ThinkingLevel` enum (`"off"` → `"high"`) works.
+emits `thinking_*` events identically to Anthropic. Control it with
+`ReasoningControl`:
+
+```python
+from cubepi import ReasoningControl
+
+agent = Agent(
+ model=model,
+ reasoning=ReasoningControl(mode="on", effort="high"),
+)
+```
+
+`effort` accepts `"minimal" | "low" | "medium" | "high" | "max"` and is
+written to `reasoning_effort` on the wire (`"max"` maps to OpenAI's
+`"xhigh"` tier). A model bound with `reasoning=False` never receives a
+`reasoning_effort` field, regardless of the requested mode.
Many OpenAI-compatible OSS backends emit reasoning under different
fields. CubePi understands three in priority order:
diff --git a/website/docs/guides/providers/overview.md b/website/docs/guides/providers/overview.md
index 920f96b..81317b0 100644
--- a/website/docs/guides/providers/overview.md
+++ b/website/docs/guides/providers/overview.md
@@ -26,13 +26,13 @@ Use `provider.model(model_id, ...)` to create a bound model for an agent.
arguments:
- `api: str` — alternate API name/route tag for downstream integrations.
-- `reasoning: bool` — enable reasoning mode and thinking-level negotiation.
+- `reasoning: bool` — enable reasoning for this model. A model bound with
+ `reasoning=False` never receives reasoning fields on the wire, regardless
+ of the agent's `ReasoningControl`.
- `context_window: int` — context-capacity hint used for validation and prompt planning.
- `max_tokens: int` — default max generation cap for this model.
- `temperature: float` — default sampling temperature for this model.
- `cost: ModelCost | None` — optional cost metadata object.
-- `thinking_level_map: dict[str, str | None] | None` — optional map for level
- overrides and unsupported levels (`None` disables a level).
### Calling a bound model directly
@@ -66,15 +66,19 @@ for utilities (summarizers, classifiers) where you already hold a
all models served by that provider:
```python
-from cubepi import CapabilityDescriptor
+from cubepi import CapabilityDescriptor, ReasoningCapability
from cubepi.providers.openai import OpenAIProvider
provider = OpenAIProvider(
api_key="...",
base_url="https://api.deepseek.com",
capability=CapabilityDescriptor(
- reasoning_on_payload={"extra_body": {"thinking": True}},
- reasoning_off_payload={"extra_body": {"thinking": False}},
+ reasoning=ReasoningCapability(
+ mode_payloads={
+ "on": {"extra_body": {"thinking": True}},
+ "off": {"extra_body": {"thinking": False}},
+ },
+ ),
max_tokens_field="max_completion_tokens",
),
)
@@ -84,18 +88,22 @@ If only one model needs an override, use
`model_capability_overrides`:
```python
-from cubepi import CapabilityDescriptor
+from cubepi import CapabilityDescriptor, ReasoningCapability
from cubepi.providers.openai import OpenAIProvider
provider = OpenAIProvider(
api_key="...",
base_url="https://openrouter.ai/api/v1",
capability=CapabilityDescriptor(
- reasoning_on_payload={"extra_body": {"thinking": True}},
+ reasoning=ReasoningCapability(
+ mode_payloads={"on": {"extra_body": {"thinking": True}}},
+ ),
),
model_capability_overrides={
"deepseek-r1": CapabilityDescriptor(
- reasoning_on_payload={"extra_body": {"thinking": "enabled"}},
+ reasoning=ReasoningCapability(
+ mode_payloads={"on": {"extra_body": {"thinking": "enabled"}}},
+ ),
),
},
)
@@ -105,10 +113,8 @@ provider = OpenAIProvider(
`CapabilityDescriptor` supports these fields:
-- `reasoning_on_payload / reasoning_off_payload` — payload merged when
- reasoning is on/off.
-- `reasoning_level` (`ReasoningLevelSpec`) — map `off`/`low`/... to backend
- payload paths.
+- `reasoning` (`ReasoningCapability | None`) — maps `ReasoningControl`
+ (mode/effort/summary) onto this endpoint's wire payload.
- `temperature` (`TemperatureSpec`) — clip, force, or strip temperature.
- `max_tokens_field` — pick `max_tokens` or `max_completion_tokens`.
- `supports_tools` / `supports_images` / `supports_streaming` — metadata consumed
@@ -155,15 +161,19 @@ endpoint's wire shape:
```python
import os
-from cubepi import CapabilityDescriptor
+from cubepi import CapabilityDescriptor, ReasoningCapability
from cubepi.providers.openai import OpenAIProvider
provider = OpenAIProvider(
api_key=os.environ["DEEPSEEK_API_KEY"],
base_url="https://api.deepseek.com",
capability=CapabilityDescriptor(
- reasoning_off_payload={"extra_body": {"reasoning": {"exclude": True}}},
- reasoning_on_payload={"extra_body": {"reasoning": {"exclude": False}}},
+ reasoning=ReasoningCapability(
+ mode_payloads={
+ "off": {"extra_body": {"reasoning": {"exclude": True}}},
+ "on": {"extra_body": {"reasoning": {"exclude": False}}},
+ },
+ ),
),
)
```
@@ -206,87 +216,103 @@ TemperatureSpec(mode="ignored") # drop the key
- **`ignored`** — the key is stripped entirely. **Effect:** for backends
that 400 on any `temperature` while reasoning.
-### Reasoning toggle: `reasoning_off_payload` / `reasoning_on_payload`
+### Reasoning: `ReasoningCapability`
-When thinking is off, `reasoning_off_payload` is deep-merged into the
-request; when it's on, `reasoning_on_payload` is. **Effect:** this is how
-"turn reasoning on/off" becomes whatever field the vendor expects:
+`ReasoningCapability` maps the provider-independent `ReasoningControl`
+(`mode`, `effort`, `summary`) onto whatever fields the vendor expects.
+`mode_payloads` is the on/off toggle — the payload for the request's
+`ReasoningControl.mode` is deep-merged into the request:
```python
+from cubepi import CapabilityDescriptor, ReasoningCapability
+
CapabilityDescriptor(
- reasoning_off_payload={"extra_body": {"enable_thinking": False}},
- reasoning_on_payload={"extra_body": {"enable_thinking": True}},
+ reasoning=ReasoningCapability(
+ mode_payloads={
+ "off": {"extra_body": {"enable_thinking": False}},
+ "on": {"extra_body": {"enable_thinking": True}},
+ },
+ ),
)
```
The merge recurses into nested dicts; arrays are atomic; on a collision
-the capability value wins.
-
-### Reasoning level: `reasoning_level` (three shapes)
-
-Beyond on/off, CubePi maps a `ThinkingLevel`
-(`off`/`low`/`medium`/`high`/`xhigh`) onto a concrete wire value
-written at a dotted `path`. `kind` picks the shape:
-
-`ReasoningLevelSpec` only changes how that level is serialized. You still need
-two call-site controls:
+the capability value wins. `mode_payloads["off"]` is applied even for a
+model bound with `reasoning=False` (so a hybrid model's "disable
+thinking" quirk always fires); anything else in `ReasoningCapability`
+(effort, summary, `mode_payloads` for any mode other than `"off"`) is
+skipped entirely for such a model.
+
+Beyond on/off, `effort_path` + `effort_values` map a `ReasoningEffort`
+(`minimal`/`low`/`medium`/`high`/`max`) onto a concrete wire value
+written at a dotted path — a token budget, an effort string, or a
+vendor-specific enum, depending on what you put in `effort_values`.
+`summary_path` + `summary_values` do the same for `ReasoningSummary`.
+You still need two call-site controls:
- set `reasoning=True` when binding the model (enable reasoning for that model)
-- set the Agent's `thinking` argument to one of `off|low|medium|high|xhigh`
- (defaults to `off`).
+- set the agent's `reasoning` argument to a `ReasoningControl(mode=..., effort=...)`
+ (defaults to `mode="off"`).
```python
-from cubepi import CapabilityDescriptor, ReasoningLevelSpec
+from cubepi import (
+ Agent,
+ CapabilityDescriptor,
+ ReasoningCapability,
+ ReasoningControl,
+)
from cubepi.providers.openai import OpenAIProvider
-from cubepi import Agent
provider = OpenAIProvider(
api_key="...",
capability=CapabilityDescriptor(
- reasoning_on_payload={"extra_body": {"reasoning": {"enabled": True}}},
- reasoning_level=ReasoningLevelSpec(
- path="reasoning.effort",
- kind="effort",
- level_to_effort={
- "off": "low",
+ reasoning=ReasoningCapability(
+ mode_payloads={"on": {"extra_body": {"reasoning": {"enabled": True}}}},
+ effort_path="reasoning.effort",
+ effort_values={
"low": "low",
"medium": "medium",
"high": "high",
- "xhigh": "high",
+ "max": "high",
},
),
),
)
-agent = Agent(model=provider.model("deepseek-r1", reasoning=True), thinking="high")
+agent = Agent(
+ model=provider.model("deepseek-r1", reasoning=True),
+ reasoning=ReasoningControl(mode="on", effort="high"),
+)
```
```python
-from cubepi import ReasoningLevelSpec
+from cubepi import ReasoningCapability
-# int_budget — a token budget (Anthropic).
-ReasoningLevelSpec(
- path="thinking.budget_tokens", kind="int_budget",
- level_budgets={"off": 0, "low": 2048,
- "medium": 8192, "high": 16384, "xhigh": 16384},
+# A token budget (Anthropic).
+ReasoningCapability(
+ effort_path="thinking.budget_tokens",
+ effort_values={"minimal": 1024, "low": 2048,
+ "medium": 8192, "high": 16384, "max": 16384},
)
-# effort — an effort string (OpenAI Responses).
-ReasoningLevelSpec(
- path="reasoning.effort", kind="effort",
- level_to_effort={"low": "low", "medium": "medium",
- "high": "high", "xhigh": "high"},
+# An effort string (OpenAI Responses).
+ReasoningCapability(
+ effort_path="reasoning.effort",
+ effort_values={"low": "low", "medium": "medium",
+ "high": "high", "max": "xhigh"},
)
-# enum — a vendor-specific state (Doubao's 3-state thinking).
-ReasoningLevelSpec(
- path="thinking.type", kind="enum",
- level_to_enum={"off": "disabled", "low": "enabled", "high": "enabled"},
+# A vendor-specific enum (Doubao's 3-state thinking) via mode_payloads.
+ReasoningCapability(
+ mode_payloads={
+ "off": {"thinking": {"type": "disabled"}},
+ "on": {"thinking": {"type": "enabled"}},
+ },
)
```
-**Effect:** a level missing from the map is simply not written, so the
-endpoint keeps its own default for that level.
+**Effect:** an effort/summary value missing from the map is simply not
+written, so the endpoint keeps its own default for that value.
### `supports_tools` / `supports_images` / `supports_streaming`
@@ -347,7 +373,7 @@ full guide.
## See also
- [OpenAI Provider](./openai) — concrete OpenAI / OpenAI-compatible setup.
-- [Anthropic Provider](./anthropic) — the `int_budget` reasoning shape in practice.
+- [Anthropic Provider](./anthropic) — the token-budget reasoning shape in practice.
- [Writing a Custom Provider](./custom) — when the endpoint isn't even OpenAI/Anthropic-shaped.
- [Multi-Provider Failover](../../recipes/multi-provider-failover) — `FallbackBoundModel` in action.
- [API Reference → `cubepi.providers`](../../api/cubepi-providers).