CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
feat: render reasoning controls in providers
xf gongeb64bcff645b
diff --git a/cubepi/__init__.py b/cubepi/__init__.pyindex 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.pyindex 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 = Falsestreaming_message: Message | None = Noneerror_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.pyindex 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__.pyindex 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_equalfrom 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.pyindex 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_profileCacheRetention = 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_checkableclass 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 Nonereturn {"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 = Nonediff --git a/cubepi/providers/base.py b/cubepi/providers/base.pyindex 009d507..bb340ea 100644--- a/cubepi/providers/base.py+++ b/cubepi/providers/base.py@@ -22,7 +22,6 @@ from cubepi.types import JsonObject, StructuredValueBaseModelT = TypeVar("BaseModelT", bound=BaseModel)-ThinkingLevel = Literal["off", "low", "medium", "high", "xhigh"]ReasoningMode = Literal["off", "auto", "on"]ReasoningEffort = Literal["minimal", "low", "medium", "high", "max"]ReasoningSummary = Literal["none", "auto", "detailed", "summarized"]@@ -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 = 0output: float = 0@@ -103,7 +60,6 @@ class Model(BaseModel):max_tokens: int = 8192temperature: float = 0.7cost: ModelCost | None = None- thinking_level_map: dict[str, str | None] | None = Noneclass 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 = Nonesignal: asyncio.Event | None = Noneon_payload: OnPayloadCallback | None = Noneon_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_budgetsif 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.pyindex 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 = Nonetemperature: 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 modelreasoning = (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.pyindex 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 = excdiff --git a/cubepi/providers/models.py b/cubepi/providers/models.pyindex 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 Modeldef 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 Trueif a is None or b is None:diff --git a/cubepi/providers/openai.py b/cubepi/providers/openai.pyindex 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_jsonfrom 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_profileclass 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.pyindex 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_profileclass 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.pyindex 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.pyindex f470077..cecec14 100644--- a/tests/agent/test_agent.py+++ b/tests/agent/test_agent.py@@ -8,6 +8,7 @@ from cubepi.middleware.base import Middlewarefrom 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.pyindex 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 CheckpointerErrorfrom cubepi.checkpointer.memory import MemoryCheckpointerfrom cubepi.hitl.binding import HitlBindingfrom cubepi.middleware.base import Middleware-from cubepi.providers.base import AssistantMessage, TextContent+from cubepi.providers.base import AssistantMessage, ReasoningControl, TextContentfrom 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_inittry: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.pyindex 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, AgentToolResultfrom 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.pyindex 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) == 2assert provider.calls[0]["max_output_tokens"] == 512assert 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, reasoningreturn AssistantMessage(content=[],stop_reason="error",diff --git a/tests/middleware/test_compaction.py b/tests/middleware/test_compaction.pyindex 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.pyindex 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, CacheRetentionfrom 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:passawait 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.asyncioasync def test_on_response_callback_invoked(self):diff --git a/tests/providers/test_anthropic_capability.py b/tests/providers/test_anthropic_capability.pyindex 49966ea..32e14b0 100644--- a/tests/providers/test_anthropic_capability.py+++ b/tests/providers/test_anthropic_capability.py@@ -15,13 +15,14 @@ import pytestfrom cubepi.providers.anthropic import AnthropicProviderfrom 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.asyncioasync 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.asyncioasync 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.asyncioasync 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"] == 99999assert "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.asyncioasync 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 beexpanded to accommodate it (else Anthropic API rejects withbudget_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 reducesbudget 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() -> Nondef 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:passdiff --git a/tests/providers/test_bound_model_calls.py b/tests/providers/test_bound_model_calls.pyindex 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"] == 64assert 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 = Noneself.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_inself.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.pyindex 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._errordiff --git a/tests/providers/test_models.py b/tests/providers/test_models.pyindex 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.pyindex 2702c68..a94a457 100644--- a/tests/providers/test_openai_capability.py+++ b/tests/providers/test_openai_capability.py@@ -8,14 +8,14 @@ import pytestfrom 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 Noneassert 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 Noneasync 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.asyncioasync 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 payloadassert "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. Ordermatters — 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.pyindex 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 OpenAIResponsesProviderdef _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.asyncioasync 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.asyncioasync 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:passawait 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.asyncioasync 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.pyindex 7fee844..b589afc 100644--- a/tests/providers/test_openai_responses_capability.py+++ b/tests/providers/test_openai_responses_capability.py@@ -12,14 +12,14 @@ import pytestfrom 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 OpenAIResponsesProviderdef _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 Noneassert 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=Truem = 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 kwargspayload = 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"] = 999return kwargspayload = 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 payloaddiff --git a/tests/providers/test_thinking_budgets.py b/tests/providers/test_thinking_budgets.pydeleted file mode 100644index 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 >= 1024diff --git a/tests/test_capability.py b/tests/test_capability.pyindex 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, ReasoningControlfrom 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 Noneassert cap.temperature.mode == "free"- assert cap.temperature.min == 0.0- assert cap.temperature.max == 2.0- assert cap.temperature.default == 1.0assert cap.max_tokens_field == "max_tokens"assert cap.supports_tools is Trueassert 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.pyindex e57b193..bce2e1e 100644--- a/tests/test_init.py+++ b/tests/test_init.py@@ -7,5 +7,6 @@ def test_capability_types_re_exported():import cubepiassert 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.pyindex 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, reasoningself.seen_max_output_tokens = max_output_tokensself.seen_options = optionsreturn AssistantMessage(content=[TextContent(text="via generate")])