Skip to content

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

feat: add reasoning capability primitives

xf gong1519702bdae3
diff --git a/cubepi/__init__.py b/cubepi/__init__.py
index 33de20f..7aab8e5 100644
--- a/cubepi/__init__.py
+++ b/cubepi/__init__.py
@@ -28,6 +28,10 @@ from cubepi.providers import (
MessageStream,
Model,
Provider,
+ ReasoningControl,
+ ReasoningEffort,
+ ReasoningMode,
+ ReasoningSummary,
StreamEvent,
StreamOptions,
TextContent,
@@ -51,8 +55,14 @@ from cubepi.errors import (
)
from cubepi.providers.capability import (
CapabilityDescriptor,
+ CapabilityWarning,
+ PayloadPreview,
+ ReasoningCapability,
ReasoningLevelSpec,
TemperatureSpec,
+ apply_reasoning_control,
+ lint_capability,
+ preview_payload,
)
from cubepi.providers.images import (
AssistantImages,
@@ -102,7 +112,12 @@ __all__ = [
"ProviderError",
"ProviderUnavailable",
"RateLimited",
+ "ReasoningCapability",
+ "ReasoningControl",
+ "ReasoningEffort",
"ReasoningLevelSpec",
+ "ReasoningMode",
+ "ReasoningSummary",
"SizeSpec",
"StreamEvent",
"StreamOptions",
@@ -116,7 +131,12 @@ __all__ = [
"ToolDefinition",
"ToolResultMessage",
"UserMessage",
+ "CapabilityWarning",
+ "PayloadPreview",
+ "apply_reasoning_control",
"is_synthetic_message",
+ "lint_capability",
+ "preview_payload",
"synthetic_user_message",
"adjust_max_tokens_for_thinking",
"compose_middleware",
diff --git a/cubepi/providers/__init__.py b/cubepi/providers/__init__.py
index eac4a81..400740d 100644
--- a/cubepi/providers/__init__.py
+++ b/cubepi/providers/__init__.py
@@ -15,6 +15,10 @@ from cubepi.providers.base import (
OnResponseCallback,
Provider,
ProviderResponse,
+ ReasoningControl,
+ ReasoningEffort,
+ ReasoningMode,
+ ReasoningSummary,
StreamEvent,
StreamOptions,
TextContent,
@@ -32,6 +36,17 @@ from cubepi.providers.base import (
chain_providers,
collect_agent_providers,
)
+from cubepi.providers.capability import (
+ CapabilityDescriptor,
+ CapabilityWarning,
+ PayloadPreview,
+ ReasoningCapability,
+ ReasoningLevelSpec,
+ TemperatureSpec,
+ apply_reasoning_control,
+ lint_capability,
+ preview_payload,
+)
from cubepi.providers.faux import (
FauxProvider,
faux_assistant_message,
@@ -49,6 +64,7 @@ from cubepi.providers.models import (
get_supported_thinking_levels,
models_are_equal,
)
+from cubepi.providers.reasoning_profiles import get_capability_profile
# Lazy imports for optional providers
@@ -90,6 +106,12 @@ __all__ = [
"OnResponseCallback",
"Provider",
"ProviderResponse",
+ "ReasoningCapability",
+ "ReasoningControl",
+ "ReasoningEffort",
+ "ReasoningLevelSpec",
+ "ReasoningMode",
+ "ReasoningSummary",
"StreamEvent",
"StreamOptions",
"TextContent",
@@ -101,6 +123,7 @@ __all__ = [
"ToolResultMessage",
"Usage",
"UserMessage",
+ "apply_reasoning_control",
"is_synthetic_message",
"synthetic_user_message",
"adjust_max_tokens_for_thinking",
@@ -112,6 +135,13 @@ __all__ = [
"faux_thinking",
"faux_tool_call",
"get_supported_thinking_levels",
+ "get_capability_profile",
+ "lint_capability",
"models_are_equal",
+ "preview_payload",
+ "CapabilityDescriptor",
+ "CapabilityWarning",
+ "PayloadPreview",
+ "TemperatureSpec",
"THINKING_LEVELS",
]
diff --git a/cubepi/providers/base.py b/cubepi/providers/base.py
index 9c27a65..009d507 100644
--- a/cubepi/providers/base.py
+++ b/cubepi/providers/base.py
@@ -23,10 +23,21 @@ from cubepi.types import JsonObject, StructuredValue
BaseModelT = TypeVar("BaseModelT", bound=BaseModel)
ThinkingLevel = Literal["off", "low", "medium", "high", "xhigh"]
+ReasoningMode = Literal["off", "auto", "on"]
+ReasoningEffort = Literal["minimal", "low", "medium", "high", "max"]
+ReasoningSummary = Literal["none", "auto", "detailed", "summarized"]
ToolChoice = Literal["auto", "required", "none"] | str
+class ReasoningControl(BaseModel):
+ """Provider-independent reasoning controls."""
+
+ mode: ReasoningMode = "off"
+ effort: ReasoningEffort = "medium"
+ summary: ReasoningSummary = "none"
+
+
class ThinkingBudgets(BaseModel):
"""Token budgets for each thinking level."""
@@ -625,6 +636,7 @@ class StreamOptions(BaseModel):
model_config = ConfigDict(arbitrary_types_allowed=True)
+ reasoning: ReasoningControl = Field(default_factory=ReasoningControl)
thinking: ThinkingLevel = "off"
thinking_budgets: ThinkingBudgets | None = None
signal: asyncio.Event | None = None
@@ -683,6 +695,7 @@ class Provider(Protocol):
options: StreamOptions | None = None,
max_output_tokens: int | None = None,
temperature: float | None = None,
+ reasoning: ReasoningControl | None = None,
thinking: ThinkingLevel | None = None,
thinking_budgets: ThinkingBudgets | None = None,
) -> AssistantMessage: ...
@@ -764,6 +777,7 @@ class BaseProvider:
options: StreamOptions | None = None,
max_output_tokens: int | None = None,
temperature: float | None = None,
+ reasoning: ReasoningControl | None = None,
thinking: ThinkingLevel | None = None,
thinking_budgets: ThinkingBudgets | None = None,
) -> AssistantMessage:
@@ -776,7 +790,9 @@ class BaseProvider:
if model_updates:
model = model.model_copy(update=model_updates)
- option_updates: dict[str, ThinkingLevel | ThinkingBudgets] = {}
+ option_updates: dict[str, ReasoningControl | ThinkingLevel | ThinkingBudgets] = {}
+ if reasoning is not None:
+ option_updates["reasoning"] = reasoning
if thinking is not None:
option_updates["thinking"] = thinking
if thinking_budgets is not None:
@@ -895,6 +911,7 @@ class BoundModel:
options: StreamOptions | None = None,
max_output_tokens: int | None = None,
temperature: float | None = None,
+ reasoning: ReasoningControl | None = None,
thinking: ThinkingLevel | None = None,
thinking_budgets: ThinkingBudgets | None = None,
) -> AssistantMessage:
@@ -908,6 +925,7 @@ class BoundModel:
options=options,
max_output_tokens=max_output_tokens,
temperature=temperature,
+ reasoning=reasoning,
thinking=thinking,
thinking_budgets=thinking_budgets,
)
diff --git a/cubepi/providers/capability.py b/cubepi/providers/capability.py
index 2b1e50c..77316da 100644
--- a/cubepi/providers/capability.py
+++ b/cubepi/providers/capability.py
@@ -5,11 +5,19 @@ See docs/dev/specs/2026-05-19-llm-provider-platform-design.md §3.1.
from __future__ import annotations
+import copy
from typing import Any, Literal
from pydantic import BaseModel, Field, model_validator
-from cubepi.providers.base import ThinkingLevel
+from cubepi.providers.base import (
+ Model,
+ ReasoningControl,
+ ReasoningEffort,
+ ReasoningMode,
+ ReasoningSummary,
+ ThinkingLevel,
+)
class TemperatureSpec(BaseModel):
@@ -50,9 +58,36 @@ class ReasoningLevelSpec(BaseModel):
return self
+UnsupportedModePolicy = Literal["skip", "warn", "error"]
+
+
+class ReasoningCapability(BaseModel):
+ """How one endpoint maps standard reasoning controls onto its wire payload."""
+
+ mode_payloads: dict[ReasoningMode, dict[str, Any]] = Field(default_factory=dict)
+ effort_path: str | None = None
+ effort_values: dict[ReasoningEffort, Any] = Field(default_factory=dict)
+ summary_path: str | None = None
+ summary_values: dict[ReasoningSummary, Any] = Field(default_factory=dict)
+ include_payloads: dict[str, dict[str, Any]] = Field(default_factory=dict)
+ apply_effort_when_off: bool = True
+ unsupported_mode_policy: UnsupportedModePolicy = "warn"
+
+
+class CapabilityWarning(BaseModel):
+ code: str
+ message: str
+
+
+class PayloadPreview(BaseModel):
+ payload: dict[str, Any]
+ warnings: list[CapabilityWarning] = Field(default_factory=list)
+
+
class CapabilityDescriptor(BaseModel):
"""Vendor quirks for one endpoint. Empty default = legacy no-op."""
+ reasoning: ReasoningCapability | None = None
reasoning_off_payload: dict[str, Any] = Field(default_factory=dict)
reasoning_on_payload: dict[str, Any] = Field(default_factory=dict)
reasoning_level: ReasoningLevelSpec | None = None
@@ -117,6 +152,97 @@ def apply_temperature(kwargs: dict[str, Any], spec: TemperatureSpec) -> None:
kwargs["temperature"] = max(spec.min, min(spec.max, value))
+def apply_reasoning_control(
+ kwargs: dict[str, Any],
+ capability: CapabilityDescriptor | ReasoningCapability,
+ control: ReasoningControl,
+) -> list[CapabilityWarning]:
+ """Apply provider-independent reasoning controls to a provider payload."""
+
+ reasoning = (
+ capability.reasoning
+ if isinstance(capability, CapabilityDescriptor)
+ else capability
+ )
+ if reasoning is None:
+ return []
+
+ warnings: list[CapabilityWarning] = []
+ mode_payload = reasoning.mode_payloads.get(control.mode)
+ if mode_payload is not None:
+ merge_capability_payload(kwargs, mode_payload)
+ else:
+ _handle_unsupported_mode(reasoning, control.mode, warnings)
+
+ if (
+ reasoning.effort_path is not None
+ and (control.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:
+ 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)
+
+ return warnings
+
+
+def preview_payload(
+ model: Model,
+ capability: CapabilityDescriptor,
+ control: ReasoningControl,
+ base_payload: dict[str, Any] | None = None,
+) -> PayloadPreview:
+ """Return the payload fragment produced by applying reasoning controls."""
+
+ payload = copy.deepcopy(base_payload) if base_payload is not None else {}
+ before = copy.deepcopy(payload)
+ warnings = apply_reasoning_control(payload, capability, control)
+ warnings.extend(lint_capability(model, capability))
+ return PayloadPreview(payload=_payload_delta(before, payload), warnings=warnings)
+
+
+def lint_capability(
+ model: Model,
+ capability: CapabilityDescriptor,
+) -> list[CapabilityWarning]:
+ """Detect capability mappings that are known to be invalid for an API shape."""
+
+ reasoning = capability.reasoning
+ if reasoning is None:
+ return []
+
+ warnings: list[CapabilityWarning] = []
+ if model.api in {"openai-completions", "chat_completions"}:
+ for payload in reasoning.mode_payloads.values():
+ if "thinking" in payload:
+ warnings.append(
+ CapabilityWarning(
+ code="openai_chat_top_level_thinking",
+ message=(
+ "OpenAI-compatible Chat Completions payloads must put "
+ "provider-specific thinking controls under "
+ "extra_body.thinking, not top-level thinking."
+ ),
+ )
+ )
+ break
+ return warnings
+
+
def _resolve_level_value(spec: ReasoningLevelSpec, level: ThinkingLevel) -> Any | None:
"""Return the wire value for ``level`` per ``spec``, or None to skip writing."""
if spec.kind == "int_budget":
@@ -143,6 +269,27 @@ def _resolve_level_value(spec: ReasoningLevelSpec, level: ThinkingLevel) -> Any
return None
+def _handle_unsupported_mode(
+ reasoning: ReasoningCapability,
+ mode: ReasoningMode,
+ warnings: list[CapabilityWarning],
+) -> None:
+ if reasoning.unsupported_mode_policy == "skip":
+ return
+ message = f"Reasoning mode '{mode}' is not supported by this capability."
+ if reasoning.unsupported_mode_policy == "error":
+ raise ValueError(message)
+ warnings.append(CapabilityWarning(code="unsupported_reasoning_mode", message=message))
+
+
+def _payload_delta(before: dict[str, Any], after: dict[str, Any]) -> dict[str, Any]:
+ delta: dict[str, Any] = {}
+ for key, value in after.items():
+ if key not in before or before[key] != value:
+ delta[key] = value
+ return delta
+
+
def _write_dotted_path(target: dict[str, Any], path: str, value: Any) -> None:
"""Walk a dotted path into ``target``, creating dicts as needed; set the leaf.
diff --git a/cubepi/providers/reasoning_profiles.py b/cubepi/providers/reasoning_profiles.py
new file mode 100644
index 0000000..b891f4b
--- /dev/null
+++ b/cubepi/providers/reasoning_profiles.py
@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import Any
+
+from cubepi.providers.base import ReasoningEffort, ReasoningSummary
+from cubepi.providers.capability import CapabilityDescriptor, ReasoningCapability
+
+
+_OPENAI_EFFORT_VALUES: dict[ReasoningEffort, str] = {
+ "minimal": "minimal",
+ "low": "low",
+ "medium": "medium",
+ "high": "high",
+ "max": "max",
+}
+
+_OPENAI_SUMMARY_VALUES: dict[ReasoningSummary, Any] = {
+ "none": None,
+ "auto": "auto",
+ "detailed": "detailed",
+ "summarized": "summarized",
+}
+
+
+def get_capability_profile(provider: str, api: str) -> CapabilityDescriptor:
+ """Return the built-in capability profile for a provider/API pair."""
+
+ key = (provider.lower(), api)
+ profile = _PROFILES.get(key)
+ if profile is not None:
+ return profile.model_copy(deep=True)
+
+ if provider.lower() == "openai" and api in {"chat_completions", "openai-completions"}:
+ return _PROFILES[("openai", "chat_completions")].model_copy(deep=True)
+ if provider.lower() == "openai" and api == "responses":
+ return _PROFILES[("openai", "responses")].model_copy(deep=True)
+ if provider.lower() == "anthropic":
+ return _PROFILES[("anthropic", "messages")].model_copy(deep=True)
+ return CapabilityDescriptor()
+
+
+_PROFILES: dict[tuple[str, str], CapabilityDescriptor] = {
+ ("openai", "chat_completions"): CapabilityDescriptor(
+ reasoning=ReasoningCapability(
+ effort_path="reasoning_effort",
+ effort_values=_OPENAI_EFFORT_VALUES,
+ apply_effort_when_off=True,
+ unsupported_mode_policy="skip",
+ )
+ ),
+ ("openai", "responses"): CapabilityDescriptor(
+ reasoning=ReasoningCapability(
+ effort_path="reasoning.effort",
+ effort_values=_OPENAI_EFFORT_VALUES,
+ summary_path="reasoning.summary",
+ summary_values=_OPENAI_SUMMARY_VALUES,
+ include_payloads={
+ "summary:auto": {"include": ["reasoning.encrypted_content"]},
+ "summary:detailed": {"include": ["reasoning.encrypted_content"]},
+ "summary:summarized": {"include": ["reasoning.encrypted_content"]},
+ },
+ apply_effort_when_off=True,
+ unsupported_mode_policy="skip",
+ )
+ ),
+ ("anthropic", "messages"): CapabilityDescriptor(
+ reasoning=ReasoningCapability(
+ mode_payloads={"off": {"thinking": {"type": "disabled"}}},
+ effort_path="thinking.budget_tokens",
+ effort_values={
+ "low": 2048,
+ "medium": 8192,
+ "high": 16384,
+ },
+ apply_effort_when_off=False,
+ unsupported_mode_policy="skip",
+ )
+ ),
+}
diff --git a/tests/providers/test_base.py b/tests/providers/test_base.py
index 957887e..844d4d9 100644
--- a/tests/providers/test_base.py
+++ b/tests/providers/test_base.py
@@ -11,9 +11,9 @@ from cubepi.providers.base import (
MessageStream,
Model,
ModelCost,
+ ReasoningControl,
StreamEvent,
TextContent,
- ThinkingBudgets,
ThinkingContent,
ToolCall,
ToolDefinition,
@@ -256,8 +256,8 @@ class TestBaseProviderGenerate:
async def test_generate_applies_common_per_call_overrides(self):
provider = _RecordingProvider(AssistantMessage(content=[]))
base_model = Model(id="gpt-4o", provider_id="openai", max_tokens=128)
- base_options = StreamOptions(thinking="low")
- budgets = ThinkingBudgets(low=4096)
+ base_options = StreamOptions(reasoning=ReasoningControl(mode="auto"))
+ reasoning = ReasoningControl(mode="on", effort="high")
await provider.generate(
base_model,
@@ -265,8 +265,7 @@ class TestBaseProviderGenerate:
options=base_options,
max_output_tokens=512,
temperature=0.0,
- thinking="high",
- thinking_budgets=budgets,
+ reasoning=reasoning,
)
assert provider.seen_model is not None
@@ -274,9 +273,8 @@ class TestBaseProviderGenerate:
assert provider.seen_model.temperature == 0.0
assert base_model.max_tokens == 128
assert provider.seen_options is not None
- assert provider.seen_options.thinking == "high"
- assert provider.seen_options.thinking_budgets is budgets
- assert base_options.thinking == "low"
+ assert provider.seen_options.reasoning == reasoning
+ assert base_options.reasoning == ReasoningControl(mode="auto")
class TestAssistantMessageMetadata:
diff --git a/tests/providers/test_reasoning_capability.py b/tests/providers/test_reasoning_capability.py
new file mode 100644
index 0000000..f7996c2
--- /dev/null
+++ b/tests/providers/test_reasoning_capability.py
@@ -0,0 +1,94 @@
+from cubepi.providers.base import Model, ReasoningControl, StreamOptions
+from cubepi.providers.capability import (
+ CapabilityDescriptor,
+ CapabilityWarning,
+ PayloadPreview,
+ ReasoningCapability,
+ apply_reasoning_control,
+ lint_capability,
+ preview_payload,
+)
+from cubepi.providers.reasoning_profiles import get_capability_profile
+
+
+def test_stream_options_default_reasoning_is_off_medium_none():
+ opts = StreamOptions()
+
+ assert opts.reasoning == ReasoningControl(
+ mode="off",
+ effort="medium",
+ summary="none",
+ )
+
+
+def test_apply_reasoning_writes_effort_when_off_for_chat_profile():
+ cap = get_capability_profile("openai", "chat_completions")
+ payload: dict = {}
+
+ apply_reasoning_control(
+ payload,
+ cap,
+ ReasoningControl(mode="off", effort="minimal"),
+ )
+
+ assert payload == {"reasoning_effort": "minimal"}
+
+
+def test_apply_reasoning_writes_nested_summary_and_include_payload():
+ cap = get_capability_profile("openai", "responses")
+ payload: dict = {}
+
+ apply_reasoning_control(
+ payload,
+ cap,
+ ReasoningControl(mode="auto", effort="high", summary="auto"),
+ )
+
+ assert payload == {
+ "reasoning": {"effort": "high", "summary": "auto"},
+ "include": ["reasoning.encrypted_content"],
+ }
+
+
+def test_preview_payload_returns_reasoning_diff():
+ cap = CapabilityDescriptor(
+ reasoning=ReasoningCapability(
+ mode_payloads={
+ "off": {"extra_body": {"thinking": {"type": "disabled"}}},
+ },
+ effort_path="reasoning_effort",
+ effort_values={"low": "low"},
+ )
+ )
+
+ preview = preview_payload(
+ Model(id="glm-5.2", provider_id="volcengine", api="openai-completions"),
+ cap,
+ ReasoningControl(mode="off", effort="low"),
+ )
+
+ assert preview == PayloadPreview(
+ payload={
+ "extra_body": {"thinking": {"type": "disabled"}},
+ "reasoning_effort": "low",
+ },
+ warnings=[],
+ )
+
+
+def test_lint_warns_for_top_level_thinking_on_openai_chat():
+ cap = CapabilityDescriptor(
+ reasoning=ReasoningCapability(
+ mode_payloads={"off": {"thinking": {"type": "disabled"}}},
+ )
+ )
+
+ warnings = lint_capability(
+ Model(id="glm-5.2", provider_id="volcengine", api="openai-completions"),
+ cap,
+ )
+
+ assert warnings
+ assert isinstance(warnings[0], CapabilityWarning)
+ assert warnings[0].code == "openai_chat_top_level_thinking"
+ assert "extra_body.thinking" in warnings[0].message