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
feat: add reasoning capability primitives
xf gong1519702bdae3
diff --git a/cubepi/__init__.py b/cubepi/__init__.pyindex 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__.pyindex 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.pyindex 9c27a65..009d507 100644--- a/cubepi/providers/base.py+++ b/cubepi/providers/base.py@@ -23,10 +23,21 @@ from cubepi.types import JsonObject, StructuredValueBaseModelT = 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 = Nonesignal: 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"] = reasoningif thinking is not None:option_updates["thinking"] = thinkingif 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.pyindex 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 copyfrom typing import Any, Literalfrom 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 = Nonereasoning_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) -> Anyreturn 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.pynew file mode 100644index 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.pyindex 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.0assert base_model.max_tokens == 128assert 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.pynew file mode 100644index 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