CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
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.pyindex 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.pyindex 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 = (capabilityif 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.pyindex 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.reasoningif 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 warningsdiff --git a/cubepi/providers/openai.py b/cubepi/providers/openai.pyindex 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.pyindex 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.pyindex 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) -> CapabilityDif 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.pyindex ff62eb8..a9376b4 100644--- a/tests/checkpointer/test_postgres_schema.py+++ b/tests/checkpointer/test_postgres_schema.py@@ -1,6 +1,7 @@import asyncpgimport pytest+from cubepi.checkpointer.postgres.checkpointer import _schema_mismatch_hintfrom 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.asyncioasync 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.pyindex 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.asyncioasync 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.pyindex 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.mdindex 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` viathe final message directly; `BaseProvider` implements it for anyprovider 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-sidediff --git a/website/docs/guides/agents/first-agent.md b/website/docs/guides/agents/first-agent.mdindex 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 fieldsand tag responses. Building a `Model` by hand and passing both`provider=` and `model=` to `Agent` is the 0.6 idiom and no longer worksin 0.7.diff --git a/website/docs/guides/middleware/compaction.md b/website/docs/guides/middleware/compaction.mdindex 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 thecontent 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.mdindex 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 subagentsdiff --git a/website/docs/guides/providers/anthropic.md b/website/docs/guides/providers/anthropic.mdindex 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 — keepit stable across your codebase, and set it when you want tracing anderror 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, ReasoningCapabilityfrom cubepi.providers.anthropic import AnthropicProviderprovider = 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 theAnthropic API rejects non-default temperatures alongside extendedthinking ([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 reasoningis 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 thetool list invalidates from the tools onward. Make those two stablediff --git a/website/docs/guides/providers/custom.md b/website/docs/guides/providers/custom.mdindex 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. Theinherited `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.mdindex 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 mappingmax_tokens=8192,context_window=128_000,)```-### Thinking on Chat Completions+### Reasoning on Chat CompletionsOpenAI exposes reasoning content through `delta.reasoning_content` ono-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 differentfields. CubePi understands three in priority order:diff --git a/website/docs/guides/providers/overview.md b/website/docs/guides/providers/overview.mdindex 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 aall models served by that provider:```python-from cubepi import CapabilityDescriptor+from cubepi import CapabilityDescriptor, ReasoningCapabilityfrom cubepi.providers.openai import OpenAIProviderprovider = 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, ReasoningCapabilityfrom cubepi.providers.openai import OpenAIProviderprovider = 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:```pythonimport os-from cubepi import CapabilityDescriptor+from cubepi import CapabilityDescriptor, ReasoningCapabilityfrom cubepi.providers.openai import OpenAIProviderprovider = 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 backendsthat 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 Agentprovider = 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).