Skip to content

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

feat: render reasoning controls in providers

xf gongeb64bcff645b
diff --git a/cubepi/__init__.py b/cubepi/__init__.py
index 7aab8e5..976a9ff 100644
--- a/cubepi/__init__.py
+++ b/cubepi/__init__.py
@@ -35,15 +35,12 @@ from cubepi.providers import (
StreamEvent,
StreamOptions,
TextContent,
- ThinkingBudgets,
- ThinkingLevel,
ToolCall,
ToolDefinition,
ToolResultMessage,
UserMessage,
is_synthetic_message,
synthetic_user_message,
- adjust_max_tokens_for_thinking,
)
from cubepi.errors import (
ContextLengthExceeded,
@@ -58,7 +55,6 @@ from cubepi.providers.capability import (
CapabilityWarning,
PayloadPreview,
ReasoningCapability,
- ReasoningLevelSpec,
TemperatureSpec,
apply_reasoning_control,
lint_capability,
@@ -115,7 +111,6 @@ __all__ = [
"ReasoningCapability",
"ReasoningControl",
"ReasoningEffort",
- "ReasoningLevelSpec",
"ReasoningMode",
"ReasoningSummary",
"SizeSpec",
@@ -125,8 +120,6 @@ __all__ = [
"StructuredValue",
"TemperatureSpec",
"TextContent",
- "ThinkingBudgets",
- "ThinkingLevel",
"ToolCall",
"ToolDefinition",
"ToolResultMessage",
@@ -138,7 +131,6 @@ __all__ = [
"lint_capability",
"preview_payload",
"synthetic_user_message",
- "adjust_max_tokens_for_thinking",
"compose_middleware",
"run_agent_loop",
"run_agent_loop_continue",
diff --git a/cubepi/agent/agent.py b/cubepi/agent/agent.py
index f6d24f3..b8ac744 100644
--- a/cubepi/agent/agent.py
+++ b/cubepi/agent/agent.py
@@ -38,9 +38,9 @@ from cubepi.providers.base import (
Model,
OnPayloadCallback,
OnResponseCallback,
+ ReasoningControl,
StreamOptions,
TextContent,
- ThinkingLevel,
ToolCall,
ToolResultMessage,
Usage,
@@ -129,7 +129,7 @@ class AgentState:
model: Model = field(
default_factory=lambda: Model(id="unknown", provider_id="unknown")
)
- thinking: ThinkingLevel = "off"
+ reasoning: ReasoningControl = field(default_factory=ReasoningControl)
is_streaming: bool = False
streaming_message: Message | None = None
error_message: str | None = None
@@ -172,7 +172,7 @@ class Agent(Generic[TMessage]):
model: BoundModel | FallbackBoundModel,
system_prompt: str = "",
tools: list[AgentTool] | None = None,
- thinking: ThinkingLevel = "off",
+ reasoning: ReasoningControl | None = None,
convert_to_llm: Callable[..., list[Message]] | None = None,
transform_context: Callable | None = None,
transform_system_prompt: Callable | None = None,
@@ -199,7 +199,7 @@ class Agent(Generic[TMessage]):
self._state = AgentState(
system_prompt=system_prompt,
model=model.spec,
- thinking=thinking,
+ reasoning=reasoning or ReasoningControl(),
)
if messages is not None:
if thread_id is not None and checkpointer is not None:
@@ -588,7 +588,7 @@ class Agent(Generic[TMessage]):
)
# Build transient agent. Forward the parent's resolved execution
# options + middleware-composed hooks so the probe behaves like the
- # parent would (tool_execution, thinking, transform/response hooks,
+ # parent would (tool_execution, reasoning, transform/response hooks,
# on_payload/on_response, queue modes). Passing the resolved hooks
# as explicit args means we pass middleware=[] to avoid composing
# middleware twice — the parent's composed result already lives on
@@ -607,7 +607,7 @@ class Agent(Generic[TMessage]):
model=self._model,
system_prompt=self._state.system_prompt,
tools=fork_tools,
- thinking=self._state.thinking,
+ reasoning=self._state.reasoning,
convert_to_llm=self.convert_to_llm,
transform_context=self.transform_context,
transform_system_prompt=self.transform_system_prompt,
@@ -732,7 +732,7 @@ class Agent(Generic[TMessage]):
def _build_stream_options(self, signal: asyncio.Event) -> StreamOptions:
return StreamOptions(
- thinking=self._state.thinking,
+ reasoning=self._state.reasoning,
signal=signal,
on_payload=self.on_payload,
on_response=self.on_response,
diff --git a/cubepi/middleware/compaction/summarizer.py b/cubepi/middleware/compaction/summarizer.py
index 74fe7c4..7051475 100644
--- a/cubepi/middleware/compaction/summarizer.py
+++ b/cubepi/middleware/compaction/summarizer.py
@@ -9,6 +9,7 @@ from cubepi.providers.base import (
AssistantMessage,
BoundModel,
Message,
+ ReasoningControl,
StreamOptions,
TextContent,
ToolCall,
@@ -213,7 +214,7 @@ async def summarize(
options=StreamOptions(signal=abort_signal),
max_output_tokens=budget,
temperature=0.0,
- thinking="off",
+ reasoning=ReasoningControl(mode="off"),
)
text = "".join(
diff --git a/cubepi/providers/__init__.py b/cubepi/providers/__init__.py
index 400740d..c95595c 100644
--- a/cubepi/providers/__init__.py
+++ b/cubepi/providers/__init__.py
@@ -22,9 +22,7 @@ from cubepi.providers.base import (
StreamEvent,
StreamOptions,
TextContent,
- ThinkingBudgets,
ThinkingContent,
- ThinkingLevel,
ToolCall,
ToolDefinition,
ToolResultMessage,
@@ -32,7 +30,6 @@ from cubepi.providers.base import (
UserMessage,
is_synthetic_message,
synthetic_user_message,
- adjust_max_tokens_for_thinking,
chain_providers,
collect_agent_providers,
)
@@ -41,7 +38,6 @@ from cubepi.providers.capability import (
CapabilityWarning,
PayloadPreview,
ReasoningCapability,
- ReasoningLevelSpec,
TemperatureSpec,
apply_reasoning_control,
lint_capability,
@@ -58,12 +54,7 @@ from cubepi.providers.fallback import (
DEFAULT_TRIGGER_ERRORS,
FallbackBoundModel,
)
-from cubepi.providers.models import (
- THINKING_LEVELS,
- clamp_thinking_level,
- get_supported_thinking_levels,
- models_are_equal,
-)
+from cubepi.providers.models import models_are_equal
from cubepi.providers.reasoning_profiles import get_capability_profile
@@ -109,15 +100,12 @@ __all__ = [
"ReasoningCapability",
"ReasoningControl",
"ReasoningEffort",
- "ReasoningLevelSpec",
"ReasoningMode",
"ReasoningSummary",
"StreamEvent",
"StreamOptions",
"TextContent",
- "ThinkingBudgets",
"ThinkingContent",
- "ThinkingLevel",
"ToolCall",
"ToolDefinition",
"ToolResultMessage",
@@ -126,15 +114,12 @@ __all__ = [
"apply_reasoning_control",
"is_synthetic_message",
"synthetic_user_message",
- "adjust_max_tokens_for_thinking",
"chain_providers",
- "clamp_thinking_level",
"collect_agent_providers",
"faux_assistant_message",
"faux_text",
"faux_thinking",
"faux_tool_call",
- "get_supported_thinking_levels",
"get_capability_profile",
"lint_capability",
"models_are_equal",
@@ -143,5 +128,4 @@ __all__ = [
"CapabilityWarning",
"PayloadPreview",
"TemperatureSpec",
- "THINKING_LEVELS",
]
diff --git a/cubepi/providers/anthropic.py b/cubepi/providers/anthropic.py
index f5cb04f..6f334b4 100644
--- a/cubepi/providers/anthropic.py
+++ b/cubepi/providers/anthropic.py
@@ -31,51 +31,14 @@ from cubepi.providers.base import (
)
from cubepi.providers.capability import (
CapabilityDescriptor,
- ReasoningLevelSpec,
- TemperatureSpec,
+ apply_reasoning_control,
apply_temperature,
- merge_capability_payload,
- write_reasoning_level,
)
-from cubepi.providers.models import clamp_thinking_level
+from cubepi.providers.reasoning_profiles import get_capability_profile
CacheRetention = Literal["short", "long", "none"]
-# Default capability for Anthropic. Unlike OpenAI's empty default, Anthropic
-# always goes through the capability path — capability=None reproduces today's
-# wire bytes exactly because:
-# - reasoning_off_payload is empty: legacy omits the "thinking" key entirely
-# when thinking=off, so the default must too (no {"type": "disabled"}).
-# - reasoning_on_payload writes {"thinking": {"type": "enabled"}}, then
-# reasoning_level adds budget_tokens at thinking.budget_tokens.
-# - level_budgets mirrors cubepi.providers.base.ThinkingBudgets defaults
-# (low=2048, medium=8192, high=16384). xhigh clamps to high
-# to match adjust_max_tokens_for_thinking's "xhigh -> high" mapping.
-# "off" is included for completeness but reasoning_level is never written
-# on the off-branch.
-# - temperature mode="free" with min/max [0, 1] matches Anthropic's accepted
-# range; the stream() method itself decides whether to send temperature
-# (only when thinking is off — Anthropic rejects temperature with thinking
-# enabled).
-_ANTHROPIC_DEFAULT_CAPABILITY = CapabilityDescriptor(
- reasoning_off_payload={},
- reasoning_on_payload={"thinking": {"type": "enabled"}},
- reasoning_level=ReasoningLevelSpec(
- path="thinking.budget_tokens",
- kind="int_budget",
- level_budgets={
- "off": 0,
- "low": 2048,
- "medium": 8192,
- "high": 16384,
- "xhigh": 16384,
- },
- ),
- temperature=TemperatureSpec(mode="free", min=0.0, max=1.0, default=1.0),
-)
-
-
@runtime_checkable
class CacheMarkerPolicy(Protocol):
"""Policy controlling where Anthropic cache_control markers are inserted.
@@ -130,7 +93,9 @@ class AnthropicProvider(BaseProvider):
# Anthropic always runs the capability path; capability=None falls back
# to _ANTHROPIC_DEFAULT_CAPABILITY which mirrors legacy wire bytes.
self._capability: CapabilityDescriptor = (
- capability if capability is not None else _ANTHROPIC_DEFAULT_CAPABILITY
+ capability
+ if capability is not None
+ else get_capability_profile("anthropic.messages.legacy_budget")
)
self._model_overrides: dict[str, CapabilityDescriptor] = (
model_capability_overrides or {}
@@ -149,6 +114,25 @@ class AnthropicProvider(BaseProvider):
return None
return {"type": "tool", "name": choice}
+ @staticmethod
+ def _apply_anthropic_budget_guard(kwargs: dict[str, Any], model: Model) -> None:
+ budget = 0
+ thinking_block = kwargs.get("thinking")
+ if isinstance(thinking_block, dict):
+ budget = thinking_block.get("budget_tokens", 0) or 0
+ kwargs["max_tokens"] = min(model.max_tokens + budget, model.context_window)
+
+ min_output_tokens = 1024
+ if budget <= 0 or kwargs["max_tokens"] - budget >= min_output_tokens:
+ return
+
+ new_budget = max(0, kwargs["max_tokens"] - min_output_tokens)
+ if isinstance(thinking_block, dict):
+ if new_budget > 0:
+ thinking_block["budget_tokens"] = new_budget
+ else:
+ kwargs["thinking"] = {"type": "disabled"}
+
async def stream(
self,
model: Model,
@@ -161,7 +145,6 @@ class AnthropicProvider(BaseProvider):
) -> MessageStream:
opts = options or StreamOptions()
ms = MessageStream()
- thinking = clamp_thinking_level(model, opts.thinking)
cap = self._resolve_capability(model.id)
cache_control = self._get_cache_control()
@@ -203,62 +186,19 @@ class AnthropicProvider(BaseProvider):
if mapped is not None:
kwargs["tool_choice"] = mapped
- # Capability-driven thinking + temperature. The default capability
- # (capability=None) reproduces today's wire bytes:
- # - thinking off: reasoning_off_payload is empty, so no "thinking"
- # key is written; temperature is sent (legacy behavior).
- # - thinking on: reasoning_on_payload writes thinking.type=enabled,
- # reasoning_level writes thinking.budget_tokens; temperature is
- # stripped because Anthropic rejects custom temperature with
- # extended thinking enabled. See
- # https://platform.claude.com/docs/en/build-with-claude/extended-thinking#feature-compatibility
- #
- # max_tokens is computed AFTER the capability writes the budget so it
- # always accommodates whatever budget actually landed on the wire.
- # Anthropic rejects requests where budget_tokens >= max_tokens.
- if thinking == "off":
- merge_capability_payload(kwargs, cap.reasoning_off_payload)
+ apply_reasoning_control(kwargs, cap, opts.reasoning, model=model)
+ thinking_block = kwargs.get("thinking")
+ thinking_enabled = (
+ isinstance(thinking_block, dict)
+ and thinking_block.get("type") == "enabled"
+ )
+ if not thinking_enabled:
kwargs.setdefault("temperature", model.temperature)
apply_temperature(kwargs, cap.temperature)
kwargs["max_tokens"] = min(model.max_tokens, model.context_window)
else:
- merge_capability_payload(kwargs, cap.reasoning_on_payload)
- if cap.reasoning_level is not None:
- write_reasoning_level(kwargs, cap.reasoning_level, thinking)
kwargs.pop("temperature", None)
-
- # Per-request budget override via StreamOptions.thinking_budgets
- # takes precedence over the capability's level_budgets. Mirrors
- # the legacy adjust_max_tokens_for_thinking(custom_budgets=...)
- # parameter. ThinkingBudgets has no "xhigh" field, so xhigh maps
- # to "high" (matches legacy clamp behavior).
- if opts.thinking_budgets is not None and isinstance(
- kwargs.get("thinking"), dict
- ):
- level_for_lookup = "high" if thinking == "xhigh" else thinking
- custom_budget = getattr(opts.thinking_budgets, level_for_lookup, None)
- if custom_budget is not None:
- kwargs["thinking"]["budget_tokens"] = custom_budget
-
- budget = 0
- thinking_block = kwargs.get("thinking")
- if isinstance(thinking_block, dict):
- budget = thinking_block.get("budget_tokens", 0) or 0
- kwargs["max_tokens"] = min(model.max_tokens + budget, model.context_window)
-
- # If context_window clipped max_tokens such that the budget no
- # longer fits, reduce the budget in place. Anthropic rejects when
- # budget_tokens >= max_tokens; reserve at least 1024 output tokens
- # to mirror adjust_max_tokens_for_thinking's legacy policy.
- min_output_tokens = 1024
- if budget > 0 and kwargs["max_tokens"] - budget < min_output_tokens:
- new_budget = max(0, kwargs["max_tokens"] - min_output_tokens)
- if isinstance(thinking_block, dict):
- if new_budget > 0:
- thinking_block["budget_tokens"] = new_budget
- else:
- # Budget reduced to 0 — disable thinking entirely.
- kwargs["thinking"] = {"type": "disabled"}
+ self._apply_anthropic_budget_guard(kwargs, model)
async def _produce() -> None:
body: dict | None = None
diff --git a/cubepi/providers/base.py b/cubepi/providers/base.py
index 009d507..bb340ea 100644
--- a/cubepi/providers/base.py
+++ b/cubepi/providers/base.py
@@ -22,7 +22,6 @@ 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"]
@@ -38,48 +37,6 @@ class ReasoningControl(BaseModel):
summary: ReasoningSummary = "none"
-class ThinkingBudgets(BaseModel):
- """Token budgets for each thinking level."""
-
- low: int = 2048
- medium: int = 8192
- high: int = 16384
-
-
-def adjust_max_tokens_for_thinking(
- base_max_tokens: int,
- model_max_tokens: int,
- reasoning_level: ThinkingLevel,
- custom_budgets: ThinkingBudgets | None = None,
-) -> tuple[int, int]:
- """Adjust max_tokens to reserve space for a thinking budget.
-
- Given a base max_tokens (the desired output capacity), increases it to
- accommodate the thinking budget while respecting the model's hard cap.
- If the model cap is too small to fit both, the thinking budget is reduced
- to leave at least ``min_output_tokens`` (1024) for output.
-
- Returns:
- A ``(max_tokens, thinking_budget)`` tuple.
- """
- if reasoning_level == "off":
- return base_max_tokens, 0
-
- budgets = custom_budgets or ThinkingBudgets()
- min_output_tokens = 1024
-
- # Clamp "xhigh" down to "high"
- level = "high" if reasoning_level == "xhigh" else reasoning_level
- thinking_budget: int = getattr(budgets, level)
-
- max_tokens = min(base_max_tokens + thinking_budget, model_max_tokens)
-
- if max_tokens - thinking_budget < min_output_tokens:
- thinking_budget = max(0, max_tokens - min_output_tokens)
-
- return max_tokens, thinking_budget
-
-
class ModelCost(BaseModel):
input: float = 0
output: float = 0
@@ -103,7 +60,6 @@ class Model(BaseModel):
max_tokens: int = 8192
temperature: float = 0.7
cost: ModelCost | None = None
- thinking_level_map: dict[str, str | None] | None = None
class StructuredOutputError(Exception):
@@ -634,11 +590,9 @@ def _detach(listeners: list, cb: Callable) -> None:
class StreamOptions(BaseModel):
"""Options bag for Provider.stream(), transparent to the agent loop."""
- model_config = ConfigDict(arbitrary_types_allowed=True)
+ model_config = ConfigDict(arbitrary_types_allowed=True, extra="forbid")
reasoning: ReasoningControl = Field(default_factory=ReasoningControl)
- thinking: ThinkingLevel = "off"
- thinking_budgets: ThinkingBudgets | None = None
signal: asyncio.Event | None = None
on_payload: OnPayloadCallback | None = None
on_response: OnResponseCallback | None = None
@@ -696,8 +650,6 @@ class Provider(Protocol):
max_output_tokens: int | None = None,
temperature: float | None = None,
reasoning: ReasoningControl | None = None,
- thinking: ThinkingLevel | None = None,
- thinking_budgets: ThinkingBudgets | None = None,
) -> AssistantMessage: ...
@@ -737,7 +689,6 @@ class BaseProvider:
max_tokens: int = 8192,
temperature: float = 0.7,
cost: ModelCost | None = None,
- thinking_level_map: dict[str, str | None] | None = None,
) -> BoundModel:
return BoundModel(
provider=self,
@@ -750,7 +701,6 @@ class BaseProvider:
max_tokens=max_tokens,
temperature=temperature,
cost=cost,
- thinking_level_map=thinking_level_map,
),
)
@@ -778,8 +728,6 @@ class BaseProvider:
max_output_tokens: int | None = None,
temperature: float | None = None,
reasoning: ReasoningControl | None = None,
- thinking: ThinkingLevel | None = None,
- thinking_budgets: ThinkingBudgets | None = None,
) -> AssistantMessage:
"""Run a single provider call and return the final assistant message."""
model_updates: dict[str, int | float] = {}
@@ -790,13 +738,9 @@ class BaseProvider:
if model_updates:
model = model.model_copy(update=model_updates)
- option_updates: dict[str, ReasoningControl | ThinkingLevel | ThinkingBudgets] = {}
+ option_updates: dict[str, ReasoningControl] = {}
if reasoning is not None:
option_updates["reasoning"] = reasoning
- if thinking is not None:
- option_updates["thinking"] = thinking
- if thinking_budgets is not None:
- option_updates["thinking_budgets"] = thinking_budgets
if option_updates:
base_options = options or StreamOptions()
options = base_options.model_copy(update=option_updates)
@@ -912,8 +856,6 @@ class BoundModel:
max_output_tokens: int | None = None,
temperature: float | None = None,
reasoning: ReasoningControl | None = None,
- thinking: ThinkingLevel | None = None,
- thinking_budgets: ThinkingBudgets | None = None,
) -> AssistantMessage:
# Same positional-forwarding rationale as ``stream`` above.
return await self.provider.generate(
@@ -926,8 +868,6 @@ class BoundModel:
max_output_tokens=max_output_tokens,
temperature=temperature,
reasoning=reasoning,
- thinking=thinking,
- thinking_budgets=thinking_budgets,
)
async def generate_structured(
diff --git a/cubepi/providers/capability.py b/cubepi/providers/capability.py
index 77316da..2860e5d 100644
--- a/cubepi/providers/capability.py
+++ b/cubepi/providers/capability.py
@@ -16,7 +16,6 @@ from cubepi.providers.base import (
ReasoningEffort,
ReasoningMode,
ReasoningSummary,
- ThinkingLevel,
)
@@ -38,26 +37,6 @@ class TemperatureSpec(BaseModel):
return self
-class ReasoningLevelSpec(BaseModel):
- """How to express a fine-grain reasoning level on this endpoint."""
-
- path: str = Field(..., min_length=1)
- kind: Literal["int_budget", "effort", "enum"]
- level_budgets: dict[str, int] | None = None
- level_to_effort: dict[str, str] | None = None
- level_to_enum: dict[str, str] | None = None
-
- @model_validator(mode="after")
- def _validate_kind_map(self) -> ReasoningLevelSpec:
- if self.kind == "int_budget" and not self.level_budgets:
- raise ValueError("kind='int_budget' requires a non-empty level_budgets map")
- if self.kind == "effort" and not self.level_to_effort:
- raise ValueError("kind='effort' requires a non-empty level_to_effort map")
- if self.kind == "enum" and not self.level_to_enum:
- raise ValueError("kind='enum' requires a non-empty level_to_enum map")
- return self
-
-
UnsupportedModePolicy = Literal["skip", "warn", "error"]
@@ -88,9 +67,6 @@ 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
temperature: TemperatureSpec = Field(default_factory=TemperatureSpec)
@@ -156,8 +132,11 @@ def apply_reasoning_control(
kwargs: dict[str, Any],
capability: CapabilityDescriptor | ReasoningCapability,
control: ReasoningControl,
+ *,
+ model: Model | None = None,
) -> list[CapabilityWarning]:
"""Apply provider-independent reasoning controls to a provider payload."""
+ del model
reasoning = (
capability.reasoning
@@ -243,32 +222,6 @@ def lint_capability(
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":
- if spec.level_budgets is None:
- raise RuntimeError(
- "ReasoningLevelSpec(kind='int_budget') reached _resolve_level_value "
- "with no level_budgets — validator was bypassed"
- )
- return spec.level_budgets.get(level)
- if spec.kind == "effort":
- if spec.level_to_effort is None:
- raise RuntimeError(
- "ReasoningLevelSpec(kind='effort') reached _resolve_level_value "
- "with no level_to_effort — validator was bypassed"
- )
- return spec.level_to_effort.get(level)
- if spec.kind == "enum":
- if spec.level_to_enum is None:
- raise RuntimeError(
- "ReasoningLevelSpec(kind='enum') reached _resolve_level_value "
- "with no level_to_enum — validator was bypassed"
- )
- return spec.level_to_enum.get(level)
- return None
-
-
def _handle_unsupported_mode(
reasoning: ReasoningCapability,
mode: ReasoningMode,
@@ -306,17 +259,3 @@ def _write_dotted_path(target: dict[str, Any], path: str, value: Any) -> None:
cursor = cursor[part]
cursor[parts[-1]] = value
-
-def write_reasoning_level(
- kwargs: dict[str, Any],
- spec: ReasoningLevelSpec,
- level: ThinkingLevel,
-) -> None:
- """Write the resolved wire value for ``level`` at ``spec.path`` inside ``kwargs``.
-
- If the level is not in the spec's level map (i.e. unsupported), no write happens.
- """
- value = _resolve_level_value(spec, level)
- if value is None:
- return
- _write_dotted_path(kwargs, spec.path, value)
diff --git a/cubepi/providers/fallback.py b/cubepi/providers/fallback.py
index 76a6b71..6e15f5f 100644
--- a/cubepi/providers/fallback.py
+++ b/cubepi/providers/fallback.py
@@ -20,10 +20,9 @@ from cubepi.providers.base import (
MessageStream,
Model,
Provider,
+ ReasoningControl,
StreamEvent,
StreamOptions,
- ThinkingBudgets,
- ThinkingLevel,
ToolChoice,
ToolDefinition,
Usage,
@@ -203,8 +202,7 @@ class FallbackBoundModel:
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:
last_error: BaseException | str = "no providers in chain"
trigger = tuple(self.trigger_errors)
@@ -221,8 +219,7 @@ class FallbackBoundModel:
options=options,
max_output_tokens=max_output_tokens,
temperature=temperature,
- thinking=thinking,
- thinking_budgets=thinking_budgets,
+ reasoning=reasoning,
)
except trigger as exc:
last_error = exc
diff --git a/cubepi/providers/models.py b/cubepi/providers/models.py
index 3c4b562..01d7bca 100644
--- a/cubepi/providers/models.py
+++ b/cubepi/providers/models.py
@@ -1,94 +1,11 @@
-"""Thinking-level validation and model comparison utilities.
-
-Mirrors pi-agent-core's ``getSupportedThinkingLevels``, ``clampThinkingLevel``,
-and ``modelsAreEqual`` functions.
-"""
-
from __future__ import annotations
-from cubepi.providers.base import Model, ThinkingLevel
-
-# Ordered list of all thinking levels from lowest to highest.
-THINKING_LEVELS: list[ThinkingLevel] = [
- "off",
- "low",
- "medium",
- "high",
- "xhigh",
-]
-
-
-def get_supported_thinking_levels(model: Model) -> list[ThinkingLevel]:
- """Return the thinking levels supported by *model*.
-
- * Non-reasoning models only support ``["off"]``.
- * For reasoning models, levels are filtered through the model's
- ``thinking_level_map``. A level mapped to ``None`` is unsupported.
- ``"xhigh"`` is only included when it has an explicit (non-None) mapping.
- All other levels are included by default when the map omits them.
- """
- if not model.reasoning:
- return ["off"]
-
- tlm = model.thinking_level_map
-
- def _is_supported(level: ThinkingLevel) -> bool:
- if tlm is not None:
- mapped = tlm.get(level)
- if mapped is None and level in tlm:
- # Explicitly mapped to None -> unsupported
- return False
- # "xhigh" requires an explicit mapping to be available
- if level == "xhigh":
- return level in tlm and tlm[level] is not None
- else:
- # No map at all: xhigh is excluded by default
- if level == "xhigh":
- return False
- return True
-
- return [lvl for lvl in THINKING_LEVELS if _is_supported(lvl)]
-
-
-def clamp_thinking_level(model: Model, level: ThinkingLevel) -> ThinkingLevel:
- """Clamp *level* to the nearest supported level for *model*.
-
- If *level* is already supported, return it unchanged. Otherwise search
- upward first (higher intensity), then downward, through the ordered level
- list to find the closest available level.
- """
- available = get_supported_thinking_levels(model)
-
- if level in available:
- return level
-
- # Unknown level -> fall back to first available
- if level not in THINKING_LEVELS:
- return available[0] if available else "off"
-
- requested_idx = THINKING_LEVELS.index(level)
-
- # Search downward first (prefer cheaper/lower intensity)
- for i in range(requested_idx - 1, -1, -1):
- candidate = THINKING_LEVELS[i]
- if candidate in available:
- return candidate
-
- # Then upward
- for i in range(requested_idx + 1, len(THINKING_LEVELS)):
- candidate = THINKING_LEVELS[i]
- if candidate in available:
- return candidate
-
- return available[0] if available else "off"
+from cubepi.providers.base import Model
def models_are_equal(a: Model | None, b: Model | None) -> bool:
- """Return ``True`` if *a* and *b* refer to the same model.
+ """Return true when both model specs refer to the same provider/model id."""
- Comparison is by ``id`` and ``provider_id``. Returns ``False`` when either
- argument is ``None``.
- """
if a is None and b is None:
return True
if a is None or b is None:
diff --git a/cubepi/providers/openai.py b/cubepi/providers/openai.py
index 3c45eee..9bdc20c 100644
--- a/cubepi/providers/openai.py
+++ b/cubepi/providers/openai.py
@@ -9,9 +9,8 @@ from cubepi.utils.json_parse import parse_streaming_json
from cubepi.providers.capability import (
CapabilityDescriptor,
+ apply_reasoning_control,
apply_temperature,
- merge_capability_payload,
- write_reasoning_level,
)
from cubepi.providers.base import (
AssistantMessage,
@@ -37,6 +36,7 @@ from cubepi.providers.base import (
invoke_on_payload,
invoke_on_response,
)
+from cubepi.providers.reasoning_profiles import get_capability_profile
class OpenAIProvider(BaseProvider):
@@ -70,7 +70,9 @@ class OpenAIProvider(BaseProvider):
self._cap_active: bool = (
capability is not None or model_capability_overrides is not None
)
- self._capability: CapabilityDescriptor = capability or CapabilityDescriptor()
+ self._capability: CapabilityDescriptor = (
+ capability or get_capability_profile("openai.chat_completions")
+ )
self._model_overrides: dict[str, CapabilityDescriptor] = (
model_capability_overrides or {}
)
@@ -148,7 +150,7 @@ class OpenAIProvider(BaseProvider):
# exactly — the OpenAI path historically does not inject
# temperature or max_tokens. Spec §3.5.
cap = self._resolve_capability(model.id)
- if self._cap_active:
+ if self._cap_active or 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
@@ -158,14 +160,8 @@ 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 opts.thinking == "off":
- merge_capability_payload(kwargs, cap.reasoning_off_payload)
- else:
- merge_capability_payload(kwargs, cap.reasoning_on_payload)
- if cap.reasoning_level is not None:
- write_reasoning_level(
- kwargs, cap.reasoning_level, opts.thinking
- )
+ if model.reasoning:
+ 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 5aa5a8e..ab10204 100644
--- a/cubepi/providers/openai_responses.py
+++ b/cubepi/providers/openai_responses.py
@@ -17,7 +17,6 @@ from cubepi.providers.base import (
StreamOptions,
TextContent,
ThinkingContent,
- ThinkingLevel,
ToolCall,
ToolChoice,
ToolDefinition,
@@ -32,20 +31,10 @@ from cubepi.providers.base import (
)
from cubepi.providers.capability import (
CapabilityDescriptor,
+ apply_reasoning_control,
apply_temperature,
- merge_capability_payload,
- write_reasoning_level,
)
-
-# Map cubepi ThinkingLevel to OpenAI reasoning.effort values.
-# "off" means no reasoning parameter is sent.
-_THINKING_TO_EFFORT: dict[ThinkingLevel, str | None] = {
- "off": None,
- "low": "low",
- "medium": "medium",
- "high": "high",
- "xhigh": "xhigh",
-}
+from cubepi.providers.reasoning_profiles import get_capability_profile
class OpenAIResponsesProvider(BaseProvider):
@@ -80,7 +69,9 @@ class OpenAIResponsesProvider(BaseProvider):
self._cap_active: bool = (
capability is not None or model_capability_overrides is not None
)
- self._capability: CapabilityDescriptor = capability or CapabilityDescriptor()
+ self._capability: CapabilityDescriptor = (
+ capability or get_capability_profile("openai.responses")
+ )
self._model_overrides: dict[str, CapabilityDescriptor] = (
model_capability_overrides or {}
)
@@ -147,7 +138,7 @@ class OpenAIResponsesProvider(BaseProvider):
# Capability-driven payload mutations run AFTER on_payload so a
# caller's explicit values survive via setdefault. Mirrors the
# ordering used by OpenAIProvider. Spec §3.5.
- if self._cap_active:
+ if self._cap_active or model.reasoning:
# The max_tokens_field rename used by the chat-completions
# OpenAIProvider doesn't apply here — Responses always uses
# ``max_output_tokens`` natively, so we skip it. Reasoning
@@ -158,32 +149,9 @@ class OpenAIResponsesProvider(BaseProvider):
kwargs.setdefault("max_output_tokens", model.max_tokens)
cap = self._resolve_capability(model.id)
apply_temperature(kwargs, cap.temperature)
- if opts.thinking == "off":
- merge_capability_payload(kwargs, cap.reasoning_off_payload)
- elif model.reasoning:
- # Only write reasoning fields when the model actually
- # reasons. Non-reasoning Responses models reject
- # reasoning_effort and related fields.
- merge_capability_payload(kwargs, cap.reasoning_on_payload)
- if cap.reasoning_level is not None:
- write_reasoning_level(
- kwargs, cap.reasoning_level, opts.thinking
- )
+ if model.reasoning:
+ apply_reasoning_control(kwargs, cap, opts.reasoning, model=model)
else:
- # Legacy path: configure reasoning effort via the inline map.
- # Use setdefault to preserve on_payload-set fields, matching
- # the capability path's ordering semantics.
- effort = _THINKING_TO_EFFORT.get(opts.thinking)
- if model.reasoning and effort is not None:
- kwargs.setdefault(
- "reasoning",
- {
- "effort": effort,
- "summary": "auto",
- },
- )
- kwargs.setdefault("include", ["reasoning.encrypted_content"])
-
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 b891f4b..87b6aad 100644
--- a/cubepi/providers/reasoning_profiles.py
+++ b/cubepi/providers/reasoning_profiles.py
@@ -22,19 +22,25 @@ _OPENAI_SUMMARY_VALUES: dict[ReasoningSummary, Any] = {
}
-def get_capability_profile(provider: str, api: str) -> CapabilityDescriptor:
+def get_capability_profile(provider: str, api: str | None = None) -> CapabilityDescriptor:
"""Return the built-in capability profile for a provider/API pair."""
- key = (provider.lower(), api)
+ provider_key = provider.lower()
+ if api is None and "." in provider_key:
+ provider_key, api = provider_key.split(".", 1)
+ if api is None:
+ return CapabilityDescriptor()
+
+ key = (provider_key, 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"}:
+ if provider_key == "openai" and api in {"chat_completions", "openai-completions"}:
return _PROFILES[("openai", "chat_completions")].model_copy(deep=True)
- if provider.lower() == "openai" and api == "responses":
+ if provider_key == "openai" and api == "responses":
return _PROFILES[("openai", "responses")].model_copy(deep=True)
- if provider.lower() == "anthropic":
+ if provider_key == "anthropic":
return _PROFILES[("anthropic", "messages")].model_copy(deep=True)
return CapabilityDescriptor()
@@ -42,14 +48,16 @@ def get_capability_profile(provider: str, api: str) -> CapabilityDescriptor:
_PROFILES: dict[tuple[str, str], CapabilityDescriptor] = {
("openai", "chat_completions"): CapabilityDescriptor(
reasoning=ReasoningCapability(
+ mode_payloads={"off": {"reasoning_effort": "minimal"}},
effort_path="reasoning_effort",
effort_values=_OPENAI_EFFORT_VALUES,
- apply_effort_when_off=True,
+ apply_effort_when_off=False,
unsupported_mode_policy="skip",
)
),
("openai", "responses"): CapabilityDescriptor(
reasoning=ReasoningCapability(
+ mode_payloads={"off": {"reasoning": {"effort": "minimal"}}},
effort_path="reasoning.effort",
effort_values=_OPENAI_EFFORT_VALUES,
summary_path="reasoning.summary",
@@ -59,13 +67,17 @@ _PROFILES: dict[tuple[str, str], CapabilityDescriptor] = {
"summary:detailed": {"include": ["reasoning.encrypted_content"]},
"summary:summarized": {"include": ["reasoning.encrypted_content"]},
},
- apply_effort_when_off=True,
+ apply_effort_when_off=False,
unsupported_mode_policy="skip",
)
),
("anthropic", "messages"): CapabilityDescriptor(
reasoning=ReasoningCapability(
- mode_payloads={"off": {"thinking": {"type": "disabled"}}},
+ mode_payloads={
+ "off": {"thinking": {"type": "disabled"}},
+ "auto": {"thinking": {"type": "enabled"}},
+ "on": {"thinking": {"type": "enabled"}},
+ },
effort_path="thinking.budget_tokens",
effort_values={
"low": 2048,
diff --git a/tests/agent/test_agent.py b/tests/agent/test_agent.py
index f470077..cecec14 100644
--- a/tests/agent/test_agent.py
+++ b/tests/agent/test_agent.py
@@ -8,6 +8,7 @@ from cubepi.middleware.base import Middleware
from cubepi.providers.base import (
AssistantMessage,
Model,
+ ReasoningControl,
TextContent,
UserMessage,
)
@@ -34,7 +35,7 @@ class TestAgentInit:
agent = Agent(model=provider.model("faux-1"))
assert agent.state.system_prompt == ""
- assert agent.state.thinking == "off"
+ assert agent.state.reasoning == ReasoningControl()
assert agent.state.tools == []
assert agent.state.messages == []
assert agent.state.is_streaming is False
@@ -47,11 +48,11 @@ class TestAgentInit:
agent = Agent(
model=provider.model("faux-1"),
system_prompt="You are a helpful assistant.",
- thinking="low",
+ reasoning=ReasoningControl(mode="on", effort="low"),
)
assert agent.state.system_prompt == "You are a helpful assistant."
- assert agent.state.thinking == "low"
+ assert agent.state.reasoning == ReasoningControl(mode="on", effort="low")
def test_middleware_tools_are_registered_on_agent(self):
class Params(BaseModel):
diff --git a/tests/agent/test_agent_fork_once.py b/tests/agent/test_agent_fork_once.py
index 84e3374..c496e71 100644
--- a/tests/agent/test_agent_fork_once.py
+++ b/tests/agent/test_agent_fork_once.py
@@ -9,7 +9,7 @@ from cubepi.checkpointer.exceptions import CheckpointerError
from cubepi.checkpointer.memory import MemoryCheckpointer
from cubepi.hitl.binding import HitlBinding
from cubepi.middleware.base import Middleware
-from cubepi.providers.base import AssistantMessage, TextContent
+from cubepi.providers.base import AssistantMessage, ReasoningControl, TextContent
from cubepi.providers.faux import FauxProvider
@@ -242,7 +242,7 @@ async def test_fork_once_forwards_parent_execution_options():
checkpointer=cp,
thread_id="src",
tool_execution="sequential",
- thinking="medium",
+ reasoning=ReasoningControl(mode="on", effort="medium"),
after_model_response=_after_response,
)
await parent.fork_once("src", "probe", after_run_id="R1")
@@ -252,8 +252,8 @@ async def test_fork_once_forwards_parent_execution_options():
@pytest.mark.asyncio
-async def test_fork_once_forwards_tool_execution_and_thinking():
- """fork_once() child must inherit tool_execution and thinking settings."""
+async def test_fork_once_forwards_tool_execution_and_reasoning():
+ """fork_once() child must inherit tool_execution and reasoning settings."""
cp = MemoryCheckpointer()
captured: dict[str, object] = {}
@@ -263,14 +263,14 @@ async def test_fork_once_forwards_tool_execution_and_thinking():
def _spy_init(self, *args, **kwargs):
# Skip the parent constructor call: only capture the second Agent()
# (the child built by fork_once).
- captured.setdefault("calls", 0)
- captured["calls"] = captured["calls"] + 1 # type: ignore[operator]
- if captured["calls"] >= 3: # 1=seed, 2=parent, 3=child
- captured["thinking"] = kwargs.get("thinking")
+ calls = int(captured.get("calls", 0)) + 1
+ captured["calls"] = calls
+ if calls >= 3: # 1=seed, 2=parent, 3=child
+ captured["reasoning"] = kwargs.get("reasoning")
captured["tool_execution"] = kwargs.get("tool_execution")
return real_init(self, *args, **kwargs)
- Agent.__init__ = _spy_init # type: ignore[method-assign]
+ Agent.__init__ = _spy_init
try:
seed_agent = Agent(
model=_ok_faux().model("faux-model"),
@@ -283,11 +283,11 @@ async def test_fork_once_forwards_tool_execution_and_thinking():
checkpointer=cp,
thread_id="src",
tool_execution="sequential",
- thinking="medium",
+ reasoning=ReasoningControl(mode="on", effort="medium"),
)
await parent.fork_once("src", "probe", after_run_id="R1")
finally:
- Agent.__init__ = real_init # type: ignore[method-assign]
+ Agent.__init__ = real_init
- assert captured["thinking"] == "medium"
+ assert captured["reasoning"] == ReasoningControl(mode="on", effort="medium")
assert captured["tool_execution"] == "sequential"
diff --git a/tests/agent/test_e2e.py b/tests/agent/test_e2e.py
index da3d5db..1ccd70e 100644
--- a/tests/agent/test_e2e.py
+++ b/tests/agent/test_e2e.py
@@ -7,6 +7,7 @@ from cubepi.agent.types import AgentTool, AgentToolResult
from cubepi.providers.base import (
AssistantMessage,
Model,
+ ReasoningControl,
TextContent,
ToolCall,
ToolResultMessage,
@@ -182,7 +183,7 @@ class TestE2EBasic:
)
agent = Agent(
model=provider.model("faux-reasoning", reasoning=True),
- thinking="low",
+ reasoning=ReasoningControl(mode="on", effort="low"),
)
await agent.prompt("What is 2+2?")
diff --git a/tests/middleware/compaction/test_summarizer.py b/tests/middleware/compaction/test_summarizer.py
index ec2e841..9b9013a 100644
--- a/tests/middleware/compaction/test_summarizer.py
+++ b/tests/middleware/compaction/test_summarizer.py
@@ -13,6 +13,7 @@ from cubepi.providers.base import (
BoundModel,
Message,
Model,
+ ReasoningControl,
StreamOptions,
TextContent,
ToolCall,
@@ -37,8 +38,7 @@ class _FakeProvider:
options: StreamOptions | None = None,
max_output_tokens: int | None = None,
temperature: float | None = None,
- thinking=None,
- thinking_budgets=None,
+ reasoning: ReasoningControl | None = None,
) -> AssistantMessage:
self.calls.append(
{
@@ -49,8 +49,7 @@ class _FakeProvider:
"options": options,
"max_output_tokens": max_output_tokens,
"temperature": temperature,
- "thinking": thinking,
- "thinking_budgets": thinking_budgets,
+ "reasoning": reasoning,
}
)
return AssistantMessage(content=[TextContent(text=self.reply)])
@@ -77,7 +76,7 @@ async def test_summarize_uses_provider_generate_with_common_overrides() -> None:
assert len(result.summarized_message_refs) == 2
assert provider.calls[0]["max_output_tokens"] == 512
assert provider.calls[0]["temperature"] == 0.0
- assert provider.calls[0]["thinking"] == "off"
+ assert provider.calls[0]["reasoning"] == ReasoningControl(mode="off")
assert provider.calls[0]["options"].signal is signal
@@ -111,11 +110,10 @@ async def test_summarize_raises_on_provider_error_message() -> None:
options: StreamOptions | None = None,
max_output_tokens: int | None = None,
temperature: float | None = None,
- thinking=None,
- thinking_budgets=None,
+ reasoning: ReasoningControl | None = None,
) -> AssistantMessage:
del model, messages, system_prompt, tools, tool_choice, options
- del max_output_tokens, temperature, thinking, thinking_budgets
+ del max_output_tokens, temperature, reasoning
return AssistantMessage(
content=[],
stop_reason="error",
diff --git a/tests/middleware/test_compaction.py b/tests/middleware/test_compaction.py
index 67527b0..a5eb04e 100644
--- a/tests/middleware/test_compaction.py
+++ b/tests/middleware/test_compaction.py
@@ -16,6 +16,7 @@ from cubepi.providers.base import (
BoundModel,
Message,
Model,
+ ReasoningControl,
StreamOptions,
TextContent,
ToolDefinition,
@@ -51,8 +52,7 @@ class _FakeSummaryProvider:
options: StreamOptions | None = None,
max_output_tokens: int | None = None,
temperature: float | None = None,
- thinking=None,
- thinking_budgets=None,
+ reasoning: ReasoningControl | None = None,
) -> AssistantMessage:
self.calls.append(
{
@@ -63,8 +63,7 @@ class _FakeSummaryProvider:
"options": options,
"max_output_tokens": max_output_tokens,
"temperature": temperature,
- "thinking": thinking,
- "thinking_budgets": thinking_budgets,
+ "reasoning": reasoning,
}
)
if self.raises is not None:
diff --git a/tests/providers/test_anthropic.py b/tests/providers/test_anthropic.py
index decc280..694a8ec 100644
--- a/tests/providers/test_anthropic.py
+++ b/tests/providers/test_anthropic.py
@@ -10,6 +10,7 @@ from cubepi.providers.anthropic import AnthropicProvider, CacheRetention
from cubepi.providers.base import (
ImageContent,
Model,
+ ReasoningControl,
StreamOptions,
TextContent,
ThinkingContent,
@@ -521,7 +522,9 @@ class TestAnthropicStreamThinking:
ms = await provider.stream(
model,
[UserMessage(content=[TextContent(text="think about this")])],
- options=StreamOptions(thinking="medium"),
+ options=StreamOptions(
+ reasoning=ReasoningControl(mode="on", effort="medium")
+ ),
)
stream_events = []
@@ -836,7 +839,7 @@ class TestAnthropicStreamKwargsBuilding:
ms = await provider.stream(
model,
[UserMessage(content=[TextContent(text="think")])],
- options=StreamOptions(thinking="high"),
+ options=StreamOptions(reasoning=ReasoningControl(mode="on", effort="high")),
)
async for _ in ms:
pass
@@ -848,8 +851,8 @@ class TestAnthropicStreamKwargsBuilding:
assert call_kwargs["thinking"]["budget_tokens"] > 0
@pytest.mark.asyncio
- async def test_no_thinking_when_off(self):
- """When thinking is 'off', kwargs should not contain 'thinking'."""
+ async def test_thinking_disabled_when_off(self):
+ """When reasoning is off, Anthropic receives explicit disabled thinking."""
events = []
final = _make_final_message(content=[])
mock_stream = _MockAnthropicStream(events, final)
@@ -861,14 +864,14 @@ class TestAnthropicStreamKwargsBuilding:
ms = await provider.stream(
model,
[UserMessage(content=[TextContent(text="hi")])],
- options=StreamOptions(thinking="off"),
+ options=StreamOptions(reasoning=ReasoningControl(mode="off")),
)
async for _ in ms:
pass
await ms.result()
call_kwargs = mock_client.messages.stream.call_args[1]
- assert "thinking" not in call_kwargs
+ assert call_kwargs["thinking"] == {"type": "disabled"}
@pytest.mark.asyncio
async def test_on_response_callback_invoked(self):
diff --git a/tests/providers/test_anthropic_capability.py b/tests/providers/test_anthropic_capability.py
index 49966ea..32e14b0 100644
--- a/tests/providers/test_anthropic_capability.py
+++ b/tests/providers/test_anthropic_capability.py
@@ -15,13 +15,14 @@ import pytest
from cubepi.providers.anthropic import AnthropicProvider
from cubepi.providers.base import (
Model,
+ ReasoningControl,
StreamOptions,
TextContent,
UserMessage,
)
from cubepi.providers.capability import (
CapabilityDescriptor,
- ReasoningLevelSpec,
+ ReasoningCapability,
TemperatureSpec,
)
@@ -29,7 +30,7 @@ from cubepi.providers.capability import (
def _model() -> Model:
return Model(
id="claude-sonnet-test",
- provider="anthropic",
+ provider_id="anthropic",
context_window=200000,
max_tokens=8192,
reasoning=True,
@@ -80,7 +81,7 @@ async def _capture_anthropic(
def fake_stream(**kw: Any) -> _FakeStream:
return _FakeStream()
- p._client.messages.stream = fake_stream # type: ignore[attr-defined]
+ p._client.messages.stream = fake_stream # type: ignore[method-assign,assignment]
s = await p.stream(
model=_model(),
@@ -93,15 +94,27 @@ async def _capture_anthropic(
return captured
+async def test_anthropic_legacy_budget_profile_maps_effort_to_budget() -> None:
+ provider = AnthropicProvider(api_key="x")
+ payload = await _capture_anthropic(
+ provider,
+ StreamOptions(reasoning=ReasoningControl(mode="on", effort="medium")),
+ )
+
+ assert payload["thinking"]["type"] == "enabled"
+ assert payload["thinking"]["budget_tokens"] == 8192
+ assert payload["max_tokens"] > payload["thinking"]["budget_tokens"]
+
+
@pytest.mark.asyncio
async def test_default_capability_matches_legacy_thinking_off() -> None:
p = AnthropicProvider(api_key="x")
- payload = await _capture_anthropic(p, StreamOptions(thinking="off"))
- # Legacy behavior: no "thinking" key when thinking=off.
- # The default capability's reasoning_off_payload is empty, so the
- # absent-key case is what we get; tolerate {"type": "disabled"} for
- # callers who override the default capability.
- assert payload.get("thinking") == {"type": "disabled"} or "thinking" not in payload
+ payload = await _capture_anthropic(
+ p,
+ StreamOptions(reasoning=ReasoningControl(mode="off")),
+ )
+ assert payload["thinking"] == {"type": "disabled"}
# Temperature is allowed when thinking is off.
assert payload.get("temperature") == 1.0
@@ -109,9 +122,12 @@ async def test_default_capability_matches_legacy_thinking_off() -> None:
@pytest.mark.asyncio
async def test_default_capability_thinking_medium_writes_budget() -> None:
p = AnthropicProvider(api_key="x")
- payload = await _capture_anthropic(p, StreamOptions(thinking="medium"))
+ payload = await _capture_anthropic(
+ p,
+ StreamOptions(reasoning=ReasoningControl(mode="on", effort="medium")),
+ )
assert payload["thinking"]["type"] == "enabled"
- # Mirrors ThinkingBudgets.medium (8192) in cubepi/providers/base.py.
+ # Mirrors the built-in Anthropic legacy-budget profile.
assert payload["thinking"]["budget_tokens"] == 8192
# Anthropic rejects custom temperature with thinking on.
assert "temperature" not in payload
@@ -120,17 +136,21 @@ async def test_default_capability_thinking_medium_writes_budget() -> None:
@pytest.mark.asyncio
async def test_custom_capability_overrides_default() -> None:
custom = 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={"medium": 99999},
+ reasoning=ReasoningCapability(
+ mode_payloads={
+ "off": {"thinking": {"type": "disabled"}},
+ "on": {"thinking": {"type": "enabled"}},
+ },
+ effort_path="thinking.budget_tokens",
+ effort_values={"medium": 99999},
),
temperature=TemperatureSpec(mode="ignored"),
)
p = AnthropicProvider(api_key="x", capability=custom)
- payload = await _capture_anthropic(p, StreamOptions(thinking="medium"))
+ payload = await _capture_anthropic(
+ p,
+ StreamOptions(reasoning=ReasoningControl(mode="on", effort="medium")),
+ )
assert payload["thinking"]["budget_tokens"] == 99999
assert "temperature" not in payload
@@ -139,12 +159,10 @@ async def test_custom_capability_overrides_default() -> None:
async def test_model_capability_overrides_take_precedence() -> None:
"""Per-model override beats the instance-level capability."""
override = CapabilityDescriptor(
- reasoning_off_payload={},
- reasoning_on_payload={"thinking": {"type": "enabled"}},
- reasoning_level=ReasoningLevelSpec(
- path="thinking.budget_tokens",
- kind="int_budget",
- level_budgets={"medium": 4242},
+ reasoning=ReasoningCapability(
+ mode_payloads={"on": {"thinking": {"type": "enabled"}}},
+ effort_path="thinking.budget_tokens",
+ effort_values={"medium": 4242},
),
temperature=TemperatureSpec(mode="ignored"),
)
@@ -152,26 +170,31 @@ async def test_model_capability_overrides_take_precedence() -> None:
api_key="x",
model_capability_overrides={"claude-sonnet-test": override},
)
- payload = await _capture_anthropic(p, StreamOptions(thinking="medium"))
+ payload = await _capture_anthropic(
+ p,
+ StreamOptions(reasoning=ReasoningControl(mode="on", effort="medium")),
+ )
assert payload["thinking"]["budget_tokens"] == 4242
@pytest.mark.asyncio
async def test_custom_high_budget_capability_bumps_max_tokens():
"""Regression for max_tokens/budget_tokens desync: when custom level_budgets
- writes a budget larger than ThinkingBudgets defaults, max_tokens must be
+ writes a large budget, max_tokens must be
expanded to accommodate it (else Anthropic API rejects with
budget_tokens >= max_tokens)."""
custom = CapabilityDescriptor(
- reasoning_on_payload={"thinking": {"type": "enabled"}},
- reasoning_level=ReasoningLevelSpec(
- path="thinking.budget_tokens",
- kind="int_budget",
- level_budgets={"medium": 50000}, # WAY above ThinkingBudgets.medium=8192
+ reasoning=ReasoningCapability(
+ mode_payloads={"on": {"thinking": {"type": "enabled"}}},
+ effort_path="thinking.budget_tokens",
+ effort_values={"medium": 50000},
),
)
p = AnthropicProvider(api_key="x", capability=custom)
- payload = await _capture_anthropic(p, StreamOptions(thinking="medium"))
+ payload = await _capture_anthropic(
+ p,
+ StreamOptions(reasoning=ReasoningControl(mode="on", effort="medium")),
+ )
assert payload["thinking"]["budget_tokens"] == 50000
# max_tokens must be at least budget + something (model.max_tokens=8192,
# so min(8192+50000, 200000) = 58192). Anthropic rejects budget>=max_tokens.
@@ -183,18 +206,17 @@ async def test_capability_clamps_budget_when_context_too_small() -> None:
"""Regression: when context_window can't fit max_tokens + budget,
budget is reduced to fit. Anthropic rejects budget >= max_tokens."""
custom = CapabilityDescriptor(
- reasoning_on_payload={"thinking": {"type": "enabled"}},
- reasoning_level=ReasoningLevelSpec(
- path="thinking.budget_tokens",
- kind="int_budget",
- level_budgets={"high": 16384},
+ reasoning=ReasoningCapability(
+ mode_payloads={"on": {"thinking": {"type": "enabled"}}},
+ effort_path="thinking.budget_tokens",
+ effort_values={"high": 16384},
),
)
p = AnthropicProvider(api_key="x", capability=custom)
# Tight model: context_window only 10000, max_tokens 8192.
m = Model(
id="claude-tight-test",
- provider="anthropic",
+ provider_id="anthropic",
context_window=10000,
max_tokens=8192,
reasoning=True,
@@ -240,12 +262,12 @@ async def test_capability_clamps_budget_when_context_too_small() -> None:
def fake_stream(**kw: Any) -> _FakeStream:
return _FakeStream()
- p._client.messages.stream = fake_stream # type: ignore[attr-defined]
+ p._client.messages.stream = fake_stream # type: ignore[method-assign,assignment]
s = await p.stream(
model=m,
messages=[UserMessage(content=[TextContent(text="hi")])],
- options=StreamOptions(thinking="high"),
+ options=StreamOptions(reasoning=ReasoningControl(mode="on", effort="high")),
)
async for _ in s:
pass
@@ -258,16 +280,20 @@ async def test_capability_clamps_budget_when_context_too_small() -> None:
@pytest.mark.asyncio
-async def test_capability_honors_opts_thinking_budgets_override():
- """StreamOptions.thinking_budgets overrides capability's level_budgets per request."""
- from cubepi.providers.base import ThinkingBudgets
-
- # Default capability — level_budgets has medium=8192
- p = AnthropicProvider(api_key="x")
- custom_budgets = ThinkingBudgets(medium=12288)
+async def test_capability_effort_mapping_controls_budget() -> None:
+ cap = CapabilityDescriptor(
+ reasoning=ReasoningCapability(
+ mode_payloads={"on": {"thinking": {"type": "enabled"}}},
+ effort_path="thinking.budget_tokens",
+ effort_values={"medium": 12288},
+ )
+ )
+ p = AnthropicProvider(api_key="x", capability=cap)
payload = await _capture_anthropic(
- p, StreamOptions(thinking="medium", thinking_budgets=custom_budgets)
+ p,
+ StreamOptions(reasoning=ReasoningControl(mode="on", effort="medium")),
)
+
assert payload["thinking"]["type"] == "enabled"
assert payload["thinking"]["budget_tokens"] == 12288
# max_tokens must accommodate the new budget.
@@ -279,18 +305,17 @@ async def test_capability_disables_thinking_when_budget_reduced_to_zero() -> Non
"""When max_tokens floor is below min_output_tokens (1024), the clamp reduces
budget to 0 and the provider must fall back to thinking.type=disabled."""
custom = CapabilityDescriptor(
- reasoning_on_payload={"thinking": {"type": "enabled"}},
- reasoning_level=ReasoningLevelSpec(
- path="thinking.budget_tokens",
- kind="int_budget",
- level_budgets={"high": 16384},
+ reasoning=ReasoningCapability(
+ mode_payloads={"on": {"thinking": {"type": "enabled"}}},
+ effort_path="thinking.budget_tokens",
+ effort_values={"high": 16384},
),
)
p = AnthropicProvider(api_key="x", capability=custom)
# context_window=512 leaves no room for any budget at all.
m = Model(
id="claude-tiny-test",
- provider="anthropic",
+ provider_id="anthropic",
context_window=512,
max_tokens=512,
reasoning=True,
@@ -336,12 +361,12 @@ async def test_capability_disables_thinking_when_budget_reduced_to_zero() -> Non
def fake_stream(**kw: Any) -> _FakeStream:
return _FakeStream()
- p._client.messages.stream = fake_stream # type: ignore[attr-defined]
+ p._client.messages.stream = fake_stream # type: ignore[method-assign,assignment]
s = await p.stream(
model=m,
messages=[UserMessage(content=[TextContent(text="hi")])],
- options=StreamOptions(thinking="high"),
+ options=StreamOptions(reasoning=ReasoningControl(mode="on", effort="high")),
)
async for _ in s:
pass
diff --git a/tests/providers/test_bound_model_calls.py b/tests/providers/test_bound_model_calls.py
index 2c3524e..e43d989 100644
--- a/tests/providers/test_bound_model_calls.py
+++ b/tests/providers/test_bound_model_calls.py
@@ -9,6 +9,7 @@ from cubepi.providers.base import (
BaseProvider,
Message,
Model,
+ ReasoningControl,
StreamOptions,
TextContent,
ToolDefinition,
@@ -22,7 +23,7 @@ class _RecordingProvider(BaseProvider):
super().__init__(provider_id="rec")
self.generate_calls: list[dict[str, Any]] = []
- async def generate( # type: ignore[override]
+ async def generate(
self,
model: Model,
messages: list[Message],
@@ -33,8 +34,7 @@ class _RecordingProvider(BaseProvider):
options: StreamOptions | None = None,
max_output_tokens: int | None = None,
temperature: float | None = None,
- thinking: Any = None,
- thinking_budgets: Any = None,
+ reasoning: ReasoningControl | None = None,
) -> AssistantMessage:
self.generate_calls.append(
{
@@ -45,8 +45,7 @@ class _RecordingProvider(BaseProvider):
"options": options,
"max_output_tokens": max_output_tokens,
"temperature": temperature,
- "thinking": thinking,
- "thinking_budgets": thinking_budgets,
+ "reasoning": reasoning,
}
)
return AssistantMessage(
@@ -60,14 +59,14 @@ class _RecordingProvider(BaseProvider):
async def test_bound_model_generate_forwards_to_provider() -> None:
provider = _RecordingProvider()
bound = provider.model("model-x", temperature=0.5)
- messages = [UserMessage(content=[TextContent(text="hi")])]
+ messages: list[Message] = [UserMessage(content=[TextContent(text="hi")])]
response = await bound.generate(
messages=messages,
system_prompt="be brief",
max_output_tokens=64,
temperature=0.0,
- thinking="off",
+ reasoning=ReasoningControl(mode="off", effort="minimal"),
)
assert isinstance(response, AssistantMessage)
@@ -81,7 +80,7 @@ async def test_bound_model_generate_forwards_to_provider() -> None:
assert call["system_prompt"] == "be brief"
assert call["max_output_tokens"] == 64
assert call["temperature"] == 0.0
- assert call["thinking"] == "off"
+ assert call["reasoning"] == ReasoningControl(mode="off", effort="minimal")
@pytest.mark.asyncio
@@ -122,7 +121,7 @@ class _MangledNamesProvider(BaseProvider):
self.captured_model: Model | None = None
self.captured_messages: list[Message] | None = None
- async def generate( # type: ignore[override]
+ async def generate(
self,
spec_in, # NOT ``model=``
msg_in, # NOT ``messages=``
@@ -133,8 +132,7 @@ class _MangledNamesProvider(BaseProvider):
options: StreamOptions | None = None,
max_output_tokens: int | None = None,
temperature: float | None = None,
- thinking: Any = None,
- thinking_budgets: Any = None,
+ reasoning: ReasoningControl | None = None,
) -> AssistantMessage:
self.captured_model = spec_in
self.captured_messages = msg_in
@@ -151,7 +149,7 @@ async def test_bound_model_generate_forwards_positionally_for_mangled_provider()
):
provider = _MangledNamesProvider()
bound = provider.model("model-x")
- messages = [UserMessage(content=[TextContent(text="hi")])]
+ messages: list[Message] = [UserMessage(content=[TextContent(text="hi")])]
response = await bound.generate(messages=messages, system_prompt="x")
diff --git a/tests/providers/test_fallback.py b/tests/providers/test_fallback.py
index deaeef1..688d836 100644
--- a/tests/providers/test_fallback.py
+++ b/tests/providers/test_fallback.py
@@ -19,11 +19,10 @@ from cubepi.providers.base import (
Message,
MessageStream,
Model,
+ ReasoningControl,
StreamEvent,
StreamOptions,
TextContent,
- ThinkingBudgets,
- ThinkingLevel,
ToolDefinition,
UserMessage,
)
@@ -61,8 +60,7 @@ class _RaisingProvider(BaseProvider):
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:
raise self._error
diff --git a/tests/providers/test_models.py b/tests/providers/test_models.py
index 389d468..079b543 100644
--- a/tests/providers/test_models.py
+++ b/tests/providers/test_models.py
@@ -1,216 +1,15 @@
-"""Tests for thinking-level validation, clamping, and model comparison."""
-
from cubepi.providers.base import Model
-from cubepi.providers.models import (
- THINKING_LEVELS,
- clamp_thinking_level,
- get_supported_thinking_levels,
- models_are_equal,
-)
-
-
-# ---------------------------------------------------------------------------
-# Fixtures / helpers
-# ---------------------------------------------------------------------------
+from cubepi.providers.models import models_are_equal
-def _model(
- *,
- reasoning: bool = False,
- thinking_level_map: dict[str, str | None] | None = None,
- provider: str = "anthropic",
- model_id: str = "claude-sonnet-4-20250514",
-) -> Model:
- return Model(
- id=model_id,
- provider_id=provider,
- reasoning=reasoning,
- thinking_level_map=thinking_level_map,
+def test_models_are_equal_by_provider_and_model_id():
+ assert models_are_equal(
+ Model(id="gpt-4o", provider_id="openai"),
+ Model(id="gpt-4o", provider_id="openai"),
)
-
-
-# ---------------------------------------------------------------------------
-# get_supported_thinking_levels
-# ---------------------------------------------------------------------------
-
-
-class TestGetSupportedThinkingLevels:
- def test_non_reasoning_model_only_off(self):
- model = _model(reasoning=False)
- assert get_supported_thinking_levels(model) == ["off"]
-
- def test_reasoning_model_no_map_defaults(self):
- """Without a map, all levels except xhigh are available."""
- model = _model(reasoning=True)
- assert get_supported_thinking_levels(model) == [
- "off",
- "low",
- "medium",
- "high",
- ]
-
- def test_reasoning_model_with_xhigh_in_map(self):
- model = _model(
- reasoning=True,
- thinking_level_map={"xhigh": "max_tokens_16k"},
- )
- levels = get_supported_thinking_levels(model)
- assert "xhigh" in levels
- # All standard levels should still be present
- for lvl in ("off", "low", "medium", "high"):
- assert lvl in levels
-
- def test_xhigh_mapped_to_none_is_excluded(self):
- model = _model(
- reasoning=True,
- thinking_level_map={"xhigh": None},
- )
- assert "xhigh" not in get_supported_thinking_levels(model)
-
- def test_level_mapped_to_none_is_excluded(self):
- model = _model(
- reasoning=True,
- thinking_level_map={"low": None},
- )
- levels = get_supported_thinking_levels(model)
- assert "low" not in levels
- # Others remain
- assert "off" in levels
- assert "medium" in levels
- assert "high" in levels
-
- def test_empty_map_same_as_no_map(self):
- model = _model(reasoning=True, thinking_level_map={})
- levels = get_supported_thinking_levels(model)
- assert levels == ["off", "low", "medium", "high"]
-
- def test_all_levels_disabled_except_off(self):
- model = _model(
- reasoning=True,
- thinking_level_map={
- "low": None,
- "medium": None,
- "high": None,
- },
- )
- assert get_supported_thinking_levels(model) == ["off"]
-
-
-# ---------------------------------------------------------------------------
-# clamp_thinking_level
-# ---------------------------------------------------------------------------
-
-
-class TestClampThinkingLevel:
- def test_supported_level_passes_through(self):
- model = _model(reasoning=True)
- assert clamp_thinking_level(model, "medium") == "medium"
-
- def test_off_always_passes_for_non_reasoning(self):
- model = _model(reasoning=False)
- assert clamp_thinking_level(model, "off") == "off"
-
- def test_non_reasoning_clamps_to_off(self):
- model = _model(reasoning=False)
- assert clamp_thinking_level(model, "high") == "off"
-
- def test_clamp_xhigh_without_support_goes_down(self):
- """xhigh not in map -> clamp down to high."""
- model = _model(reasoning=True)
- assert clamp_thinking_level(model, "xhigh") == "high"
-
- def test_clamp_down_to_nearest(self):
- """When a level is disabled, search downward first (prefer cheaper)."""
- model = _model(
- reasoning=True,
- thinking_level_map={"medium": None},
- )
- # "medium" disabled -> next down is "low"
- assert clamp_thinking_level(model, "medium") == "low"
-
- def test_clamp_down_when_nothing_above(self):
- """When all higher levels are disabled, clamp down."""
- model = _model(
- reasoning=True,
- thinking_level_map={"high": None},
- )
- # "high" disabled, xhigh not in map -> search down -> "medium"
- assert clamp_thinking_level(model, "high") == "medium"
-
- def test_clamp_unknown_level_returns_first_available(self):
- model = _model(reasoning=True)
- # An invalid level should fall back to the first available
- result = clamp_thinking_level(model, "ultra") # type: ignore[arg-type]
- assert result == "off"
-
- def test_clamp_with_only_off_available(self):
- model = _model(
- reasoning=True,
- thinking_level_map={
- "low": None,
- "medium": None,
- "high": None,
- },
- )
- assert clamp_thinking_level(model, "medium") == "off"
-
- def test_clamp_preserves_exact_match_with_map(self):
- model = _model(
- reasoning=True,
- thinking_level_map={"medium": "budget_4096", "xhigh": "budget_max"},
- )
- assert clamp_thinking_level(model, "medium") == "medium"
- assert clamp_thinking_level(model, "xhigh") == "xhigh"
-
-
-# ---------------------------------------------------------------------------
-# models_are_equal
-# ---------------------------------------------------------------------------
-
-
-class TestModelsAreEqual:
- def test_equal_models(self):
- a = _model(model_id="claude-sonnet-4-20250514", provider="anthropic")
- b = _model(model_id="claude-sonnet-4-20250514", provider="anthropic")
- assert models_are_equal(a, b) is True
-
- def test_different_id(self):
- a = _model(model_id="claude-sonnet-4-20250514", provider="anthropic")
- b = _model(model_id="claude-opus-4-20250514", provider="anthropic")
- assert models_are_equal(a, b) is False
-
- def test_different_provider(self):
- a = _model(model_id="claude-sonnet-4-20250514", provider="anthropic")
- b = _model(model_id="claude-sonnet-4-20250514", provider="bedrock")
- assert models_are_equal(a, b) is False
-
- def test_none_a(self):
- b = _model()
- assert models_are_equal(None, b) is False
-
- def test_none_b(self):
- a = _model()
- assert models_are_equal(a, None) is False
-
- def test_both_none(self):
- assert models_are_equal(None, None) is True
-
-
-# ---------------------------------------------------------------------------
-# THINKING_LEVELS ordering
-# ---------------------------------------------------------------------------
-
-
-class TestThinkingLevelsOrdering:
- def test_correct_order(self):
- assert THINKING_LEVELS == [
- "off",
- "low",
- "medium",
- "high",
- "xhigh",
- ]
-
- def test_all_levels_present(self):
- expected = {"off", "low", "medium", "high", "xhigh"}
- assert set(THINKING_LEVELS) == expected
+ assert not models_are_equal(
+ Model(id="gpt-4o", provider_id="openai"),
+ Model(id="gpt-4o", provider_id="azure"),
+ )
+ assert not models_are_equal(Model(id="gpt-4o"), None)
+ assert models_are_equal(None, None)
diff --git a/tests/providers/test_openai_capability.py b/tests/providers/test_openai_capability.py
index 2702c68..a94a457 100644
--- a/tests/providers/test_openai_capability.py
+++ b/tests/providers/test_openai_capability.py
@@ -8,14 +8,14 @@ import pytest
from cubepi.providers.base import (
Model,
+ ReasoningControl,
StreamOptions,
TextContent,
- ThinkingLevel,
UserMessage,
)
from cubepi.providers.capability import (
CapabilityDescriptor,
- ReasoningLevelSpec,
+ ReasoningCapability,
TemperatureSpec,
)
from cubepi.providers.openai import OpenAIProvider
@@ -31,7 +31,7 @@ def test_provider_accepts_model_overrides():
cap = CapabilityDescriptor()
overrides = {
"deepseek-r1": CapabilityDescriptor(
- reasoning_off_payload={"reasoning": {"effort": "low"}}
+ reasoning=ReasoningCapability(effort_path="reasoning.effort")
)
}
p = OpenAIProvider(
@@ -46,7 +46,7 @@ def test_provider_accepts_model_overrides():
def test_resolve_capability_uses_override_when_present():
base = CapabilityDescriptor()
override = CapabilityDescriptor(
- reasoning_off_payload={"reasoning": {"effort": "low"}}
+ reasoning=ReasoningCapability(effort_path="reasoning.effort")
)
p = OpenAIProvider(
api_key="x",
@@ -60,9 +60,9 @@ def test_resolve_capability_uses_override_when_present():
def test_capability_default_when_kwarg_none():
p = OpenAIProvider(api_key="x", base_url="http://example")
- # No capability passed -> legacy no-op default, _cap_active=False
+ # No capability passed -> official OpenAI Chat profile, but _cap_active=False.
assert isinstance(p._capability, CapabilityDescriptor)
- assert p._capability.reasoning_off_payload == {}
+ assert p._capability.reasoning is not None
assert p._cap_active is False
@@ -89,7 +89,7 @@ def test_resolve_capability_returns_default_when_inactive():
p = OpenAIProvider(api_key="x", base_url="http://example")
result = p._resolve_capability("any-model")
assert isinstance(result, CapabilityDescriptor)
- assert result.reasoning_off_payload == {}
+ assert result.reasoning is not None
async def _capture_payload_openai(
@@ -97,12 +97,11 @@ async def _capture_payload_openai(
model: Model,
*,
on_payload=None,
- thinking: ThinkingLevel = "off",
+ reasoning: ReasoningControl | None = None,
) -> dict:
"""Run a stream with a fake openai client and return the kwargs sent.
on_payload: optional caller-side payload mutator passed via StreamOptions.
- thinking: ThinkingLevel value for StreamOptions; defaults to "off".
"""
captured: dict = {}
@@ -124,11 +123,14 @@ async def _capture_payload_openai(
async def fake_create(**kw):
return _FakeResponse()
- provider._client.chat.completions.create = fake_create # type: ignore[assignment]
+ provider._client.chat.completions.create = fake_create # type: ignore[method-assign]
stream = await provider.stream(
model=model,
messages=[UserMessage(content=[TextContent(text="hi")])],
- options=StreamOptions(thinking=thinking, on_payload=on_payload),
+ options=StreamOptions(
+ reasoning=reasoning or ReasoningControl(mode="off"),
+ on_payload=on_payload,
+ ),
)
async for _ in stream:
pass
@@ -138,13 +140,37 @@ async def _capture_payload_openai(
def _model(id: str = "test-model", **kw) -> Model:
return Model(
id=id,
- provider="test",
+ provider_id="test",
+ reasoning=kw.get("reasoning", False),
context_window=kw.get("context_window", 32000),
max_tokens=kw.get("max_tokens", 4096),
temperature=kw.get("temperature", 0.7),
)
+async def test_openai_chat_default_profile_writes_reasoning_effort() -> None:
+ payload = await _capture_payload_openai(
+ OpenAIProvider(api_key="x", base_url="http://example"),
+ _model(reasoning=True),
+ reasoning=ReasoningControl(mode="on", effort="high", summary="none"),
+ )
+
+ assert payload["reasoning_effort"] == "high"
+ assert "thinking" not in payload
+
+
+async def test_openai_chat_off_writes_minimal_effort() -> None:
+ payload = await _capture_payload_openai(
+ OpenAIProvider(api_key="x", base_url="http://example"),
+ _model(reasoning=True),
+ reasoning=ReasoningControl(mode="off", effort="minimal", summary="none"),
+ )
+
+ assert payload["reasoning_effort"] == "minimal"
+
+
@pytest.mark.asyncio
async def test_temperature_ignored_strips_field():
cap = CapabilityDescriptor(temperature=TemperatureSpec(mode="ignored"))
@@ -199,38 +225,53 @@ async def test_temperature_free_preserves_caller_value_via_on_payload():
@pytest.mark.asyncio
-async def test_reasoning_off_payload_merged_qwen():
+async def test_reasoning_mode_off_payload_merged_qwen():
cap = 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}},
+ }
+ )
)
p = OpenAIProvider(api_key="x", base_url="http://e", capability=cap)
- payload = await _capture_payload_openai(p, _model()) # default thinking="off"
+ payload = await _capture_payload_openai(p, _model(reasoning=True))
assert payload["extra_body"]["enable_thinking"] is False
@pytest.mark.asyncio
-async def test_reasoning_on_payload_merged_qwen():
+async def test_reasoning_mode_on_payload_merged_qwen():
cap = 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}},
+ }
+ )
)
p = OpenAIProvider(api_key="x", base_url="http://e", capability=cap)
- payload = await _capture_payload_openai(p, _model(), thinking="medium")
+ payload = await _capture_payload_openai(
+ p,
+ _model(reasoning=True),
+ reasoning=ReasoningControl(mode="on"),
+ )
assert payload["extra_body"]["enable_thinking"] is True
@pytest.mark.asyncio
-async def test_reasoning_level_effort_written():
+async def test_reasoning_effort_written():
cap = CapabilityDescriptor(
- reasoning_level=ReasoningLevelSpec(
- path="reasoning_effort",
- kind="effort",
- level_to_effort={"low": "low", "medium": "medium", "high": "high"},
- ),
+ reasoning=ReasoningCapability(
+ effort_path="reasoning_effort",
+ effort_values={"medium": "medium"},
+ )
)
p = OpenAIProvider(api_key="x", base_url="http://e", capability=cap)
- payload = await _capture_payload_openai(p, _model(), thinking="medium")
+ payload = await _capture_payload_openai(
+ p,
+ _model(reasoning=True),
+ reasoning=ReasoningControl(mode="on", effort="medium"),
+ )
assert payload["reasoning_effort"] == "medium"
@@ -238,7 +279,9 @@ async def test_reasoning_level_effort_written():
async def test_model_override_wins_for_reasoning():
base = CapabilityDescriptor()
override = CapabilityDescriptor(
- reasoning_on_payload={"reasoning": {"effort": "low"}},
+ reasoning=ReasoningCapability(
+ mode_payloads={"on": {"reasoning": {"effort": "low"}}},
+ )
)
p = OpenAIProvider(
api_key="x",
@@ -246,7 +289,11 @@ async def test_model_override_wins_for_reasoning():
capability=base,
model_capability_overrides={"deepseek-r1": override},
)
- payload = await _capture_payload_openai(p, _model("deepseek-r1"), thinking="medium")
+ payload = await _capture_payload_openai(
+ p,
+ _model("deepseek-r1", reasoning=True),
+ reasoning=ReasoningControl(mode="on"),
+ )
assert payload["reasoning"] == {"effort": "low"}
@@ -254,26 +301,29 @@ async def test_model_override_wins_for_reasoning():
async def test_legacy_no_capability_does_not_merge_reasoning_payload():
"""Regression: no capability -> no reasoning_off/on payload write."""
p = OpenAIProvider(api_key="x", base_url="http://e") # legacy
- payload = await _capture_payload_openai(p, _model(), thinking="off")
+ payload = await _capture_payload_openai(p, _model())
assert "extra_body" not in payload
assert "reasoning_effort" not in payload
@pytest.mark.asyncio
-async def test_reasoning_on_payload_and_level_both_applied():
+async def test_reasoning_mode_payload_and_effort_both_applied():
"""Anthropic-style combined case: on_payload writes the thinking block,
- then reasoning_level writes budget_tokens into the same dict. Order
+ then effort_path writes budget_tokens into the same dict. Order
matters — the merge must run before the level write so the dict exists."""
cap = CapabilityDescriptor(
- reasoning_on_payload={"thinking": {"type": "enabled"}},
- reasoning_level=ReasoningLevelSpec(
- path="thinking.budget_tokens",
- kind="int_budget",
- level_budgets={"medium": 8192},
- ),
+ reasoning=ReasoningCapability(
+ mode_payloads={"on": {"thinking": {"type": "enabled"}}},
+ effort_path="thinking.budget_tokens",
+ effort_values={"medium": 8192},
+ )
)
p = OpenAIProvider(api_key="x", base_url="http://e", capability=cap)
- payload = await _capture_payload_openai(p, _model(), thinking="medium")
+ payload = await _capture_payload_openai(
+ p,
+ _model(reasoning=True),
+ reasoning=ReasoningControl(mode="on", effort="medium"),
+ )
assert payload["thinking"] == {"type": "enabled", "budget_tokens": 8192}
diff --git a/tests/providers/test_openai_responses.py b/tests/providers/test_openai_responses.py
index f90286e..b1fbaa4 100644
--- a/tests/providers/test_openai_responses.py
+++ b/tests/providers/test_openai_responses.py
@@ -12,6 +12,7 @@ from cubepi.providers.base import (
AssistantMessage,
ImageContent,
Model,
+ ReasoningControl,
StreamOptions,
TextContent,
ThinkingContent,
@@ -31,7 +32,7 @@ from cubepi.providers.openai_responses import OpenAIResponsesProvider
def _model(*, reasoning: bool = False, max_tokens: int = 4096) -> Model:
return Model(
id="o3" if reasoning else "gpt-4.1",
- provider="openai",
+ provider_id="openai",
api="openai-responses",
reasoning=reasoning,
max_tokens=max_tokens,
@@ -373,7 +374,13 @@ class TestStreamThinking:
ms = await provider.stream(
model,
[UserMessage(content=[TextContent(text="think about this")])],
- options=StreamOptions(thinking="medium"),
+ options=StreamOptions(
+ reasoning=ReasoningControl(
+ mode="on",
+ effort="medium",
+ summary="auto",
+ )
+ ),
)
stream_events = []
@@ -742,9 +749,61 @@ class TestStreamError:
class TestReasoningParams:
"""Test that reasoning parameters are correctly configured."""
+ @pytest.mark.asyncio
+ async def test_responses_default_profile_writes_reasoning_object(self):
+ events = [
+ _make_event(
+ "response.completed",
+ response=SimpleNamespace(
+ id="resp_1",
+ status="completed",
+ usage=SimpleNamespace(
+ input_tokens=5,
+ output_tokens=5,
+ total_tokens=10,
+ input_tokens_details=SimpleNamespace(cached_tokens=0),
+ ),
+ service_tier=None,
+ ),
+ ),
+ ]
+
+ with patch("openai.AsyncOpenAI") as mock_openai:
+ mock_client = MagicMock()
+ mock_openai.return_value = mock_client
+ mock_client.responses = MagicMock()
+ mock_client.responses.create = AsyncMock(return_value=_async_iter(events))
+
+ provider = OpenAIResponsesProvider(api_key="test-key")
+ provider._client = mock_client
+
+ model = _model(reasoning=True)
+ ms = await provider.stream(
+ model,
+ [UserMessage(content=[TextContent(text="think")])],
+ options=StreamOptions(
+ reasoning=ReasoningControl(
+ mode="on",
+ effort="high",
+ summary="auto",
+ )
+ ),
+ )
+
+ async for _ in ms:
+ pass
+ await ms.result()
+
+ call_kwargs = mock_client.responses.create.call_args[1]
+ assert call_kwargs["reasoning"] == {
+ "effort": "high",
+ "summary": "auto",
+ }
+ assert call_kwargs["include"] == ["reasoning.encrypted_content"]
+
@pytest.mark.asyncio
async def test_reasoning_effort_sent(self):
- """When thinking is not 'off', reasoning params should be in the API call."""
+ """ReasoningControl writes Responses reasoning params."""
events = [
_make_event(
"response.completed",
@@ -775,7 +834,13 @@ class TestReasoningParams:
ms = await provider.stream(
model,
[UserMessage(content=[TextContent(text="think")])],
- options=StreamOptions(thinking="high"),
+ options=StreamOptions(
+ reasoning=ReasoningControl(
+ mode="on",
+ effort="high",
+ summary="auto",
+ )
+ ),
)
# Consume the stream to ensure the background task has run
@@ -789,7 +854,7 @@ class TestReasoningParams:
@pytest.mark.asyncio
async def test_no_reasoning_when_off(self):
- """When thinking is 'off', no reasoning params should be sent."""
+ """mode=off maps to minimal effort for reasoning-only Responses models."""
events = [
_make_event(
"response.completed",
@@ -820,14 +885,21 @@ class TestReasoningParams:
ms = await provider.stream(
model,
[UserMessage(content=[TextContent(text="hi")])],
- options=StreamOptions(thinking="off"),
+ options=StreamOptions(
+ reasoning=ReasoningControl(
+ mode="off",
+ effort="minimal",
+ summary="none",
+ )
+ ),
)
async for _ in ms:
pass
await ms.result()
call_kwargs = mock_client.responses.create.call_args[1]
- assert "reasoning" not in call_kwargs
+ assert call_kwargs["reasoning"] == {"effort": "minimal"}
+ assert "include" not in call_kwargs
@pytest.mark.asyncio
async def test_system_prompt_as_developer_for_reasoning(self):
diff --git a/tests/providers/test_openai_responses_capability.py b/tests/providers/test_openai_responses_capability.py
index 7fee844..b589afc 100644
--- a/tests/providers/test_openai_responses_capability.py
+++ b/tests/providers/test_openai_responses_capability.py
@@ -12,14 +12,14 @@ import pytest
from cubepi.providers.base import (
Model,
+ ReasoningControl,
StreamOptions,
TextContent,
- ThinkingLevel,
UserMessage,
)
from cubepi.providers.capability import (
CapabilityDescriptor,
- ReasoningLevelSpec,
+ ReasoningCapability,
TemperatureSpec,
)
from cubepi.providers.openai_responses import OpenAIResponsesProvider
@@ -28,7 +28,7 @@ from cubepi.providers.openai_responses import OpenAIResponsesProvider
def _model(id: str = "gpt-5-test", *, reasoning: bool = False, **kw) -> Model:
return Model(
id=id,
- provider="test",
+ provider_id="test",
api="openai-responses",
reasoning=reasoning,
context_window=kw.get("context_window", 200_000),
@@ -47,7 +47,7 @@ async def _capture_payload_responses(
model: Model,
*,
on_payload=None,
- thinking: ThinkingLevel = "off",
+ reasoning: ReasoningControl | None = None,
) -> dict:
"""Run stream and return final wire kwargs via request_listeners."""
captured: dict = {}
@@ -65,7 +65,10 @@ async def _capture_payload_responses(
stream = await provider.stream(
model=model,
messages=[UserMessage(content=[TextContent(text="hi")])],
- options=StreamOptions(thinking=thinking, on_payload=on_payload),
+ options=StreamOptions(
+ reasoning=reasoning or ReasoningControl(),
+ on_payload=on_payload,
+ ),
)
async for _ in stream:
pass
@@ -87,7 +90,7 @@ def test_provider_accepts_model_overrides():
cap = CapabilityDescriptor()
overrides = {
"gpt-5": CapabilityDescriptor(
- reasoning_off_payload={"reasoning": {"effort": "low"}}
+ reasoning=ReasoningCapability(effort_path="reasoning.effort")
)
}
p = OpenAIResponsesProvider(
@@ -101,7 +104,7 @@ def test_provider_accepts_model_overrides():
def test_resolve_capability_uses_override_when_present():
base = CapabilityDescriptor()
override = CapabilityDescriptor(
- reasoning_off_payload={"reasoning": {"effort": "low"}}
+ reasoning=ReasoningCapability(effort_path="reasoning.effort")
)
p = OpenAIResponsesProvider(
api_key="x",
@@ -115,7 +118,7 @@ def test_resolve_capability_uses_override_when_present():
def test_capability_default_when_kwarg_none():
p = OpenAIResponsesProvider(api_key="x")
assert isinstance(p._capability, CapabilityDescriptor)
- assert p._capability.reasoning_off_payload == {}
+ assert p._capability.reasoning is not None
assert p._cap_active is False
@@ -133,30 +136,31 @@ def test_cap_active_when_only_overrides_passed():
# ---------------------------------------------------------------------------
-# Legacy path (no capability) — _THINKING_TO_EFFORT still fires.
+# Default profile path.
# ---------------------------------------------------------------------------
@pytest.mark.asyncio
-async def test_legacy_no_capability_uses_internal_effort_map():
- """When _cap_active=False, the existing _THINKING_TO_EFFORT writes effort
- on reasoning models. This preserves wire bytes for legacy callers."""
+async def test_default_profile_writes_reasoning_effort():
p = OpenAIResponsesProvider(api_key="x")
payload = await _capture_payload_responses(
- p, _model(reasoning=True), thinking="medium"
+ p,
+ _model(reasoning=True),
+ reasoning=ReasoningControl(mode="on", effort="medium", summary="auto"),
)
assert payload["reasoning"] == {"effort": "medium", "summary": "auto"}
assert "reasoning.encrypted_content" in payload["include"]
@pytest.mark.asyncio
-async def test_legacy_no_capability_off_thinking_skips_reasoning():
- """Regression guard: thinking='off' -> no reasoning param sent."""
+async def test_default_profile_off_writes_minimal_reasoning():
p = OpenAIResponsesProvider(api_key="x")
payload = await _capture_payload_responses(
- p, _model(reasoning=True), thinking="off"
+ p,
+ _model(reasoning=True),
+ reasoning=ReasoningControl(mode="off", effort="minimal", summary="none"),
)
- assert "reasoning" not in payload
+ assert payload["reasoning"] == {"effort": "minimal"}
# ---------------------------------------------------------------------------
@@ -165,20 +169,20 @@ async def test_legacy_no_capability_off_thinking_skips_reasoning():
@pytest.mark.asyncio
-async def test_capability_reasoning_level_overrides_internal_map():
- """When capability.reasoning_level is set, it takes precedence over the
- legacy map (different effort value confirms it)."""
+async def test_capability_reasoning_effort_overrides_profile_value():
cap = CapabilityDescriptor(
- reasoning_on_payload={"reasoning": {"summary": "auto"}},
- reasoning_level=ReasoningLevelSpec(
- path="reasoning.effort",
- kind="effort",
- level_to_effort={"medium": "minimal"},
+ reasoning=ReasoningCapability(
+ summary_path="reasoning.summary",
+ summary_values={"auto": "auto"},
+ effort_path="reasoning.effort",
+ effort_values={"medium": "minimal"},
),
)
p = OpenAIResponsesProvider(api_key="x", capability=cap)
payload = await _capture_payload_responses(
- p, _model(reasoning=True), thinking="medium"
+ p,
+ _model(reasoning=True),
+ reasoning=ReasoningControl(mode="on", effort="medium", summary="auto"),
)
assert payload["reasoning"]["effort"] == "minimal"
@@ -187,7 +191,7 @@ async def test_capability_reasoning_level_overrides_internal_map():
async def test_capability_temperature_ignored_strips():
cap = CapabilityDescriptor(temperature=TemperatureSpec(mode="ignored"))
p = OpenAIResponsesProvider(api_key="x", capability=cap)
- payload = await _capture_payload_responses(p, _model(), thinking="off")
+ payload = await _capture_payload_responses(p, _model())
assert "temperature" not in payload
@@ -212,25 +216,33 @@ async def test_capability_injects_max_output_tokens():
@pytest.mark.asyncio
-async def test_capability_reasoning_off_payload_merged():
+async def test_capability_reasoning_mode_off_payload_merged():
cap = CapabilityDescriptor(
- reasoning_off_payload={"reasoning": {"effort": "minimal"}},
+ reasoning=ReasoningCapability(
+ mode_payloads={"off": {"reasoning": {"effort": "minimal"}}},
+ )
)
p = OpenAIResponsesProvider(api_key="x", capability=cap)
payload = await _capture_payload_responses(
- p, _model(reasoning=True), thinking="off"
+ p,
+ _model(reasoning=True),
+ reasoning=ReasoningControl(mode="off"),
)
assert payload["reasoning"] == {"effort": "minimal"}
@pytest.mark.asyncio
-async def test_capability_reasoning_on_payload_merged():
+async def test_capability_reasoning_mode_on_payload_merged():
cap = CapabilityDescriptor(
- reasoning_on_payload={"reasoning": {"summary": "auto"}},
+ reasoning=ReasoningCapability(
+ mode_payloads={"on": {"reasoning": {"summary": "auto"}}},
+ )
)
p = OpenAIResponsesProvider(api_key="x", capability=cap)
payload = await _capture_payload_responses(
- p, _model(reasoning=True), thinking="medium"
+ p,
+ _model(reasoning=True),
+ reasoning=ReasoningControl(mode="on"),
)
assert payload["reasoning"] == {"summary": "auto"}
@@ -243,13 +255,13 @@ async def test_capability_does_not_set_temperature_on_reasoning_model():
# Model with reasoning=True
m = Model(
id="o3-test",
- provider="test",
+ provider_id="test",
context_window=200_000,
max_tokens=16384,
temperature=1.0,
reasoning=True,
)
- payload = await _capture_payload_responses(p, m, thinking="off")
+ payload = await _capture_payload_responses(p, m)
assert "temperature" not in payload
@@ -264,22 +276,21 @@ async def test_capability_on_payload_overrides_max_output_tokens():
return kwargs
payload = await _capture_payload_responses(
- p, _model(), thinking="off", on_payload=set_max
+ p, _model(), on_payload=set_max
)
assert payload["max_output_tokens"] == 1234
@pytest.mark.asyncio
-async def test_legacy_no_capability_preserves_on_payload_max_output_tokens():
- """Regression: when on_payload sets max_output_tokens, legacy path preserves it."""
- p = OpenAIResponsesProvider(api_key="x") # legacy, no capability
+async def test_default_profile_preserves_on_payload_max_output_tokens():
+ p = OpenAIResponsesProvider(api_key="x")
async def set_max(kwargs, model):
kwargs["max_output_tokens"] = 999
return kwargs
payload = await _capture_payload_responses(
- p, _model(), thinking="off", on_payload=set_max
+ p, _model(), on_payload=set_max
)
assert payload["max_output_tokens"] == 999
@@ -288,21 +299,24 @@ async def test_legacy_no_capability_preserves_on_payload_max_output_tokens():
async def test_capability_skips_reasoning_for_non_reasoning_model():
"""Capability path must not write reasoning fields when model.reasoning=False."""
cap = CapabilityDescriptor(
- reasoning_on_payload={"reasoning": {"effort": "low"}},
- reasoning_level=ReasoningLevelSpec(
- path="reasoning.effort",
- kind="effort",
- level_to_effort={"medium": "medium"},
+ reasoning=ReasoningCapability(
+ mode_payloads={"on": {"reasoning": {"effort": "low"}}},
+ effort_path="reasoning.effort",
+ effort_values={"medium": "medium"},
),
)
p = OpenAIResponsesProvider(api_key="x", capability=cap)
m = Model(
id="gpt-4o-test",
- provider="test",
+ provider_id="test",
context_window=128000,
max_tokens=16384,
temperature=1.0,
reasoning=False, # non-reasoning
)
- payload = await _capture_payload_responses(p, m, thinking="medium")
+ payload = await _capture_payload_responses(
+ p,
+ m,
+ reasoning=ReasoningControl(mode="on", effort="medium"),
+ )
assert "reasoning" not in payload
diff --git a/tests/providers/test_thinking_budgets.py b/tests/providers/test_thinking_budgets.py
deleted file mode 100644
index 6809cb1..0000000
--- a/tests/providers/test_thinking_budgets.py
+++ /dev/null
@@ -1,155 +0,0 @@
-from cubepi.providers.base import ThinkingBudgets, adjust_max_tokens_for_thinking
-
-
-class TestThinkingBudgets:
- def test_defaults(self):
- b = ThinkingBudgets()
- assert b.low == 2048
- assert b.medium == 8192
- assert b.high == 16384
-
- def test_custom_values(self):
- b = ThinkingBudgets(low=1024, medium=4096, high=8192)
- assert b.low == 1024
- assert b.high == 8192
-
-
-class TestAdjustMaxTokensForThinking:
- def test_off_returns_base_unchanged(self):
- max_tokens, budget = adjust_max_tokens_for_thinking(
- base_max_tokens=8192,
- model_max_tokens=128_000,
- reasoning_level="off",
- )
- assert max_tokens == 8192
- assert budget == 0
-
- def test_low_adds_2048(self):
- max_tokens, budget = adjust_max_tokens_for_thinking(
- base_max_tokens=8192,
- model_max_tokens=128_000,
- reasoning_level="low",
- )
- assert budget == 2048
- assert max_tokens == 8192 + 2048
-
- def test_medium_adds_8192(self):
- max_tokens, budget = adjust_max_tokens_for_thinking(
- base_max_tokens=8192,
- model_max_tokens=128_000,
- reasoning_level="medium",
- )
- assert budget == 8192
- assert max_tokens == 8192 + 8192
-
- def test_high_adds_16384(self):
- max_tokens, budget = adjust_max_tokens_for_thinking(
- base_max_tokens=8192,
- model_max_tokens=128_000,
- reasoning_level="high",
- )
- assert budget == 16384
- assert max_tokens == 8192 + 16384
-
- def test_xhigh_clamps_to_high(self):
- max_tokens, budget = adjust_max_tokens_for_thinking(
- base_max_tokens=8192,
- model_max_tokens=128_000,
- reasoning_level="xhigh",
- )
- # xhigh should be clamped to high (16384)
- assert budget == 16384
- assert max_tokens == 8192 + 16384
-
- def test_model_cap_limits_max_tokens(self):
- # Model only allows 10000 total, but base + budget = 8192 + 8192 = 16384
- max_tokens, budget = adjust_max_tokens_for_thinking(
- base_max_tokens=8192,
- model_max_tokens=10000,
- reasoning_level="medium",
- )
- assert max_tokens == 10000
- assert budget == 8192 # budget still fits (10000 > 8192)
-
- def test_budget_reduced_when_model_too_small(self):
- # Model allows only 2000 total, budget would be 8192 (medium)
- # Since max_tokens(2000) <= budget(8192), budget = max(0, 2000 - 1024) = 976
- max_tokens, budget = adjust_max_tokens_for_thinking(
- base_max_tokens=8192,
- model_max_tokens=2000,
- reasoning_level="medium",
- )
- assert max_tokens == 2000
- assert budget == 976
-
- def test_budget_zero_when_model_extremely_small(self):
- # Model allows only 500 total, budget would be 8192
- # max_tokens = min(8192 + 8192, 500) = 500
- # 500 <= 8192 so budget = max(0, 500 - 1024) = 0
- max_tokens, budget = adjust_max_tokens_for_thinking(
- base_max_tokens=8192,
- model_max_tokens=500,
- reasoning_level="medium",
- )
- assert max_tokens == 500
- assert budget == 0
-
- def test_custom_budgets_override_defaults(self):
- custom = ThinkingBudgets(low=512, medium=2048, high=4096)
- max_tokens, budget = adjust_max_tokens_for_thinking(
- base_max_tokens=8192,
- model_max_tokens=128_000,
- reasoning_level="medium",
- custom_budgets=custom,
- )
- assert budget == 2048
- assert max_tokens == 8192 + 2048
-
- def test_custom_budgets_xhigh_uses_custom_high(self):
- custom = ThinkingBudgets(high=4096)
- max_tokens, budget = adjust_max_tokens_for_thinking(
- base_max_tokens=8192,
- model_max_tokens=128_000,
- reasoning_level="xhigh",
- custom_budgets=custom,
- )
- assert budget == 4096
- assert max_tokens == 8192 + 4096
-
- def test_exact_model_cap_equals_budget(self):
- # Edge case: model cap exactly equals the budget
- # max_tokens = min(8192 + 2048, 2048) = 2048
- # 2048 - 2048 = 0 < min_output_tokens(1024), budget = max(0, 2048 - 1024) = 1024
- max_tokens, budget = adjust_max_tokens_for_thinking(
- base_max_tokens=8192,
- model_max_tokens=2048,
- reasoning_level="low",
- )
- assert max_tokens == 2048
- assert budget == 1024
-
- def test_model_cap_just_above_budget(self):
- # base=8192, model=2049, low budget=2048
- # max_tokens = min(8192 + 2048, 2049) = 2049
- # 2049 - 2048 = 1 < min_output_tokens(1024), budget = max(0, 2049 - 1024) = 1025
- max_tokens, budget = adjust_max_tokens_for_thinking(
- base_max_tokens=8192,
- model_max_tokens=2049,
- reasoning_level="low",
- )
- assert max_tokens == 2049
- assert budget == 1025
-
- def test_output_tokens_minimum_guaranteed(self):
- # Bug case: base=8192, model=9000, medium budget=8192
- # max_tokens = min(16384, 9000) = 9000
- # Without fix: 9000 > 8192 so budget stays 8192, only 808 for output
- # With fix: 9000 - 8192 = 808 < 1024, so budget = 9000 - 1024 = 7976
- max_tokens, budget = adjust_max_tokens_for_thinking(
- base_max_tokens=8192,
- model_max_tokens=9000,
- reasoning_level="medium",
- )
- assert max_tokens == 9000
- assert budget == 7976
- assert max_tokens - budget >= 1024
diff --git a/tests/test_capability.py b/tests/test_capability.py
index d5dfa2d..bdf435f 100644
--- a/tests/test_capability.py
+++ b/tests/test_capability.py
@@ -1,24 +1,22 @@
+import pytest
+from pydantic import ValidationError
+
+from cubepi.providers.base import Model, ReasoningControl
from cubepi.providers.capability import (
CapabilityDescriptor,
- ReasoningLevelSpec,
+ ReasoningCapability,
TemperatureSpec,
- _resolve_level_value,
+ apply_reasoning_control,
apply_temperature,
+ lint_capability,
merge_capability_payload,
- write_reasoning_level,
)
-def test_descriptor_defaults_are_legacy_safe():
- """Empty descriptor must encode 'no-op' so existing callers behave the same."""
+def test_descriptor_defaults_are_safe_noop():
cap = CapabilityDescriptor()
- assert cap.reasoning_off_payload == {}
- assert cap.reasoning_on_payload == {}
- assert cap.reasoning_level is None
+ assert cap.reasoning is None
assert cap.temperature.mode == "free"
- assert cap.temperature.min == 0.0
- assert cap.temperature.max == 2.0
- assert cap.temperature.default == 1.0
assert cap.max_tokens_field == "max_tokens"
assert cap.supports_tools is True
assert cap.supports_images is False
@@ -26,304 +24,97 @@ def test_descriptor_defaults_are_legacy_safe():
def test_temperature_fixed_requires_value():
- """mode=fixed without fixed_value must fail validation."""
- import pytest
- from pydantic import ValidationError
-
with pytest.raises(ValidationError):
TemperatureSpec(mode="fixed")
-def test_reasoning_level_int_budget_requires_map():
- """kind=int_budget without level_budgets must fail."""
- import pytest
- from pydantic import ValidationError
-
- with pytest.raises(ValidationError):
- ReasoningLevelSpec(path="thinking.budget_tokens", kind="int_budget")
-
-
-def test_reasoning_level_effort_requires_map():
- import pytest
- from pydantic import ValidationError
-
- with pytest.raises(ValidationError):
- ReasoningLevelSpec(path="reasoning_effort", kind="effort")
-
-
-def test_reasoning_level_enum_requires_map():
- import pytest
- from pydantic import ValidationError
-
- with pytest.raises(ValidationError):
- ReasoningLevelSpec(path="extra_body.thinking.type", kind="enum")
-
-
def test_temperature_default_must_be_within_range():
- import pytest
- from pydantic import ValidationError
-
with pytest.raises(ValidationError):
TemperatureSpec(min=0.0, max=1.0, default=2.0)
-def test_merge_empty_patch_is_noop():
- kwargs = {"a": 1, "extra_body": {"b": 2}}
- merge_capability_payload(kwargs, {})
- assert kwargs == {"a": 1, "extra_body": {"b": 2}}
-
-
-def test_merge_adds_new_top_level_keys():
- kwargs = {"a": 1}
- merge_capability_payload(kwargs, {"reasoning_effort": "low"})
- assert kwargs == {"a": 1, "reasoning_effort": "low"}
-
-
-def test_merge_recurses_into_nested_dicts():
- kwargs: dict = {"extra_body": {"existing": True}}
- merge_capability_payload(kwargs, {"extra_body": {"enable_thinking": False}})
- assert kwargs == {"extra_body": {"existing": True, "enable_thinking": False}}
-
-
-def test_merge_capability_wins_on_leaf_collision():
- kwargs = {"extra_body": {"enable_thinking": True}}
- merge_capability_payload(kwargs, {"extra_body": {"enable_thinking": False}})
- assert kwargs == {"extra_body": {"enable_thinking": False}}
+def test_merge_recurses_and_capability_wins():
+ kwargs: dict = {"extra_body": {"existing": True}, "stop": ["\n"]}
+ patch = {"extra_body": {"enable_thinking": False}, "stop": ["END"]}
-
-def test_merge_arrays_are_atomic_capability_wins():
- """Arrays at colliding keys are replaced, not unioned."""
- kwargs = {"stop": ["\n", "."]}
- merge_capability_payload(kwargs, {"stop": ["END"]})
- assert kwargs == {"stop": ["END"]}
-
-
-def test_merge_does_not_mutate_patch():
- """The patch dict the caller passes in must be left untouched."""
- patch = {"extra_body": {"enable_thinking": False}}
- kwargs: dict = {}
merge_capability_payload(kwargs, patch)
- kwargs["extra_body"]["enable_thinking"] = True
- assert patch == {"extra_body": {"enable_thinking": False}}
-
-def test_merge_patch_dict_overwrites_scalar():
- """When patch has a dict at a key where kwargs has a scalar, capability wins —
- the scalar is replaced with the dict (consistent with rule 3)."""
- kwargs = {"x": 5}
- merge_capability_payload(kwargs, {"x": {"y": 1}})
- assert kwargs == {"x": {"y": 1}}
-
-
-def test_merge_none_patch_value_overwrites():
- """None in patch overwrites a nested dict in kwargs (capability wins, rule 3)."""
- kwargs: dict = {"x": {"nested": True}}
- merge_capability_payload(kwargs, {"x": None})
- assert kwargs["x"] is None
-
-
-def test_apply_temperature_free_passes_through():
- kwargs = {"temperature": 0.7}
- apply_temperature(kwargs, TemperatureSpec(mode="free"))
- assert kwargs == {"temperature": 0.7}
+ assert kwargs == {
+ "extra_body": {"existing": True, "enable_thinking": False},
+ "stop": ["END"],
+ }
+ kwargs["extra_body"]["enable_thinking"] = True
+ assert patch == {"extra_body": {"enable_thinking": False}, "stop": ["END"]}
-def test_apply_temperature_free_clamps_above_max():
+def test_apply_temperature_modes():
kwargs = {"temperature": 5.0}
apply_temperature(kwargs, TemperatureSpec(mode="free", min=0, max=2))
assert kwargs == {"temperature": 2.0}
-
-def test_apply_temperature_free_clamps_below_min():
- kwargs = {"temperature": -1.0}
- apply_temperature(kwargs, TemperatureSpec(mode="free", min=0, max=2))
- assert kwargs == {"temperature": 0.0}
-
-
-def test_apply_temperature_ignored_strips():
- kwargs = {"temperature": 0.7}
- apply_temperature(kwargs, TemperatureSpec(mode="ignored"))
- assert "temperature" not in kwargs
-
-
-def test_apply_temperature_fixed_overwrites():
- kwargs = {"temperature": 0.7}
- apply_temperature(kwargs, TemperatureSpec(mode="fixed", fixed_value=0.0))
- assert kwargs == {"temperature": 0.0}
-
-
-def test_apply_temperature_fixed_sets_when_absent():
- kwargs: dict = {}
apply_temperature(kwargs, TemperatureSpec(mode="fixed", fixed_value=0.0))
assert kwargs == {"temperature": 0.0}
-
-def test_apply_temperature_free_no_op_when_absent():
- kwargs: dict = {}
- apply_temperature(kwargs, TemperatureSpec(mode="free"))
+ apply_temperature(kwargs, TemperatureSpec(mode="ignored"))
assert kwargs == {}
-def test_apply_temperature_free_clamp_inclusive_at_min():
- """Value exactly at min stays unchanged (inclusive clamp)."""
- kwargs = {"temperature": 0.0}
- apply_temperature(kwargs, TemperatureSpec(mode="free", min=0.0, max=2.0))
- assert kwargs == {"temperature": 0.0}
-
-
-def test_apply_temperature_free_clamp_inclusive_at_max():
- """Value exactly at max stays unchanged (inclusive clamp)."""
- kwargs = {"temperature": 2.0}
- apply_temperature(kwargs, TemperatureSpec(mode="free", min=0.0, max=2.0))
- assert kwargs == {"temperature": 2.0}
-
-
-def test_int_budget_writes_top_level_path():
+def test_apply_reasoning_control_writes_mode_effort_and_summary():
kwargs: dict = {}
- spec = ReasoningLevelSpec(
- path="thinking.budget_tokens",
- kind="int_budget",
- level_budgets={"off": 0, "low": 4000, "medium": 10000, "high": 32000},
+ cap = CapabilityDescriptor(
+ reasoning=ReasoningCapability(
+ mode_payloads={"on": {"extra_body": {"thinking": {"type": "enabled"}}}},
+ effort_path="reasoning_effort",
+ effort_values={"high": "high"},
+ summary_path="reasoning.summary",
+ summary_values={"auto": "auto"},
+ )
)
- write_reasoning_level(kwargs, spec, "medium")
- assert kwargs == {"thinking": {"budget_tokens": 10000}}
-
-def test_int_budget_skips_when_level_absent_in_map():
- kwargs: dict = {}
- spec = ReasoningLevelSpec(
- path="thinking.budget_tokens",
- kind="int_budget",
- level_budgets={"low": 4000},
+ apply_reasoning_control(
+ kwargs,
+ cap,
+ ReasoningControl(mode="on", effort="high", summary="auto"),
)
- write_reasoning_level(kwargs, spec, "xhigh")
- assert kwargs == {}
-
-def test_effort_writes_string():
- kwargs: dict = {}
- spec = ReasoningLevelSpec(
- path="reasoning_effort",
- kind="effort",
- level_to_effort={"low": "low", "medium": "medium", "high": "high"},
- )
- write_reasoning_level(kwargs, spec, "high")
- assert kwargs == {"reasoning_effort": "high"}
+ assert kwargs == {
+ "extra_body": {"thinking": {"type": "enabled"}},
+ "reasoning_effort": "high",
+ "reasoning": {"summary": "auto"},
+ }
-def test_enum_writes_nested_extra_body():
+def test_apply_reasoning_control_can_skip_effort_when_off():
kwargs: dict = {}
- spec = ReasoningLevelSpec(
- path="extra_body.thinking.type",
- kind="enum",
- level_to_enum={
- "off": "disabled",
- "low": "enabled",
- "medium": "enabled",
- "high": "enabled",
- },
- )
- write_reasoning_level(kwargs, spec, "medium")
- assert kwargs == {"extra_body": {"thinking": {"type": "enabled"}}}
-
-
-def test_writes_into_existing_nested_dict():
- kwargs: dict = {"extra_body": {"other": True}}
- spec = ReasoningLevelSpec(
- path="extra_body.thinking.type",
- kind="enum",
- level_to_enum={"off": "disabled", "medium": "enabled"},
- )
- write_reasoning_level(kwargs, spec, "off")
- assert kwargs == {"extra_body": {"other": True, "thinking": {"type": "disabled"}}}
-
-
-def test_write_reasoning_level_overwrites_existing_leaf():
- """Pre-existing leaf value at the spec's path is replaced (last writer wins)."""
- kwargs: dict = {"reasoning_effort": "low"}
- spec = ReasoningLevelSpec(
- path="reasoning_effort",
- kind="effort",
- level_to_effort={"high": "high"},
+ cap = CapabilityDescriptor(
+ reasoning=ReasoningCapability(
+ mode_payloads={"off": {"reasoning_effort": "minimal"}},
+ effort_path="reasoning_effort",
+ effort_values={"high": "high"},
+ apply_effort_when_off=False,
+ )
)
- write_reasoning_level(kwargs, spec, "high")
- assert kwargs == {"reasoning_effort": "high"}
-
-def test_write_reasoning_level_replaces_non_dict_intermediate():
- """A non-dict scalar at an intermediate segment is clobbered with a dict."""
- kwargs: dict = {"thinking": "stale-string"}
- spec = ReasoningLevelSpec(
- path="thinking.budget_tokens",
- kind="int_budget",
- level_budgets={"medium": 8192},
+ apply_reasoning_control(
+ kwargs,
+ cap,
+ ReasoningControl(mode="off", effort="high"),
)
- write_reasoning_level(kwargs, spec, "medium")
- assert kwargs == {"thinking": {"budget_tokens": 8192}}
+ assert kwargs == {"reasoning_effort": "minimal"}
-def test_reasoning_level_path_must_be_non_empty():
- import pytest
- from pydantic import ValidationError
- with pytest.raises(ValidationError):
- ReasoningLevelSpec(
- path="",
- kind="int_budget",
- level_budgets={"low": 4000},
+def test_lint_warns_for_top_level_thinking_on_openai_chat():
+ cap = CapabilityDescriptor(
+ reasoning=ReasoningCapability(
+ mode_payloads={"off": {"thinking": {"type": "disabled"}}},
)
-
-
-def test_apply_temperature_fixed_raises_on_bypassed_validator():
- """Defensive guard: if validator is bypassed and fixed_value is None, raise."""
- import pytest
-
- # model_construct bypasses validation.
- spec = TemperatureSpec.model_construct(mode="fixed", fixed_value=None)
- with pytest.raises(RuntimeError, match="validator was bypassed"):
- apply_temperature({}, spec)
-
-
-def test_resolve_level_int_budget_raises_on_bypassed_validator():
- import pytest
-
- spec = ReasoningLevelSpec.model_construct(
- path="thinking.budget_tokens",
- kind="int_budget",
- level_budgets=None,
- )
- with pytest.raises(RuntimeError, match="validator was bypassed"):
- _resolve_level_value(spec, "medium")
-
-
-def test_resolve_level_effort_raises_on_bypassed_validator():
- import pytest
-
- spec = ReasoningLevelSpec.model_construct(
- path="reasoning_effort",
- kind="effort",
- level_to_effort=None,
)
- with pytest.raises(RuntimeError, match="validator was bypassed"):
- _resolve_level_value(spec, "medium")
-
-
-def test_resolve_level_enum_raises_on_bypassed_validator():
- import pytest
- spec = ReasoningLevelSpec.model_construct(
- path="extra_body.thinking.type",
- kind="enum",
- level_to_enum=None,
+ warnings = lint_capability(
+ Model(id="glm-5.2", provider_id="volcengine", api="openai-completions"),
+ cap,
)
- with pytest.raises(RuntimeError, match="validator was bypassed"):
- _resolve_level_value(spec, "medium")
-
-def test_resolve_level_unknown_kind_returns_none():
- """Defensive fall-through: a bogus kind (model_construct bypass) returns None."""
- spec = ReasoningLevelSpec.model_construct(
- path="whatever",
- kind="something-bogus", # not a valid Literal value
- )
- assert _resolve_level_value(spec, "medium") is None
+ assert warnings
+ assert warnings[0].code == "openai_chat_top_level_thinking"
diff --git a/tests/test_init.py b/tests/test_init.py
index e57b193..bce2e1e 100644
--- a/tests/test_init.py
+++ b/tests/test_init.py
@@ -7,5 +7,6 @@ def test_capability_types_re_exported():
import cubepi
assert hasattr(cubepi, "CapabilityDescriptor")
+ assert hasattr(cubepi, "ReasoningCapability")
assert hasattr(cubepi, "TemperatureSpec")
- assert hasattr(cubepi, "ReasoningLevelSpec")
+ assert not hasattr(cubepi, "ReasoningLevelSpec")
diff --git a/tests/tracing/test_oneshot.py b/tests/tracing/test_oneshot.py
index 2cc15a7..9ba27a2 100644
--- a/tests/tracing/test_oneshot.py
+++ b/tests/tracing/test_oneshot.py
@@ -13,6 +13,7 @@ from cubepi.providers.base import (
Message,
MessageStream,
Model,
+ ReasoningControl,
StreamEvent,
StreamOptions,
TextContent,
@@ -702,11 +703,9 @@ class _GenerateOnlyProvider(FauxProvider):
options: StreamOptions | None = None,
max_output_tokens: int | None = None,
temperature: float | None = None,
- thinking=None,
- thinking_budgets=None,
+ reasoning: ReasoningControl | None = None,
) -> AssistantMessage:
- del model, messages, system_prompt, tools, tool_choice, temperature, thinking
- del thinking_budgets
+ del model, messages, system_prompt, tools, tool_choice, temperature, reasoning
self.seen_max_output_tokens = max_output_tokens
self.seen_options = options
return AssistantMessage(content=[TextContent(text="via generate")])