Skip to content

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

docs(release): document late-merged 0.10 changes before tagging

xf gongf46ac66c145d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b368e9e..fb27242 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,8 +9,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [0.10.0] - 2026-06-10
+### Removed (BREAKING)
+
+- **`"minimal"` removed from `ThinkingLevel`.** `ThinkingLevel` now reads
+ `Literal["off", "low", "medium", "high", "xhigh"]`; the `.minimal` field
+ is gone from `ThinkingBudgets`; `THINKING_LEVELS` no longer contains it;
+ Anthropic's default `level_budgets` and OpenAI Responses' `_THINKING_TO_EFFORT`
+ no longer map it. **Callers that previously passed `thinking="minimal"`
+ must switch to `thinking="low"` (or `"off"`).** Rationale: DeepSeek's
+ Anthropic-shape endpoint rejects `effort=minimal` on `output_config`,
+ and OpenAI's `reasoning.effort` path rewrote it to `"low"` downstream
+ anyway — keeping it was a footgun that surfaced as a 400 + fallback.
+
### Added
+- **`synthetic_user_message(text, *, source) -> UserMessage`** and
+ **`is_synthetic_message(message) -> bool`** — public marker for
+ framework-injected user-role messages. Middleware-injected nudges
+ (todo guard errors, goal continuations, compaction summaries,
+ `generate_structured` retry feedback) now stamp
+ `metadata["synthetic"] = True` so downstream UIs can tell internal
+ scaffolding apart from real human input. Real `Agent.prompt()` /
+ `Agent.steer()` messages remain unmarked. Closes #171. Exported from
+ `cubepi` and `cubepi.providers`. Use this factory (not bare
+ `UserMessage`) when returning messages from `TurnAction.inject_messages`
+ or `on_run_end`.
+
- **`DeferredToolGroup` / `DeferredToolsMiddleware`** — progressive tool
disclosure primitive. Hides MCP tool schemas from the model by default,
injecting a compact catalog into the system prompt instead. The model
diff --git a/website/docs/guides/providers/anthropic.md b/website/docs/guides/providers/anthropic.md
index c1f4acc..cbf5878 100644
--- a/website/docs/guides/providers/anthropic.md
+++ b/website/docs/guides/providers/anthropic.md
@@ -49,7 +49,6 @@ CubePi maps a `ThinkingLevel` enum onto Anthropic's `budget_tokens`:
| Level | Default budget |
|---|---|
| `"off"` | thinking disabled |
-| `"minimal"` | 1024 |
| `"low"` | 2048 |
| `"medium"` | 8192 |
| `"high"` | 16384 |
@@ -78,7 +77,7 @@ provider = AnthropicProvider(
reasoning_level=ReasoningLevelSpec(
path="thinking.budget_tokens",
kind="int_budget",
- level_budgets={"off": 0, "minimal": 1024, "low": 4096,
+ level_budgets={"off": 0, "low": 4096,
"medium": 12288, "high": 16384, "xhigh": 16384},
),
),
diff --git a/website/docs/guides/providers/overview.md b/website/docs/guides/providers/overview.md
index 476b24e..920f96b 100644
--- a/website/docs/guides/providers/overview.md
+++ b/website/docs/guides/providers/overview.md
@@ -107,7 +107,7 @@ provider = OpenAIProvider(
- `reasoning_on_payload / reasoning_off_payload` — payload merged when
reasoning is on/off.
-- `reasoning_level` (`ReasoningLevelSpec`) — map `off`/`minimal`/... to backend
+- `reasoning_level` (`ReasoningLevelSpec`) — map `off`/`low`/... to backend
payload paths.
- `temperature` (`TemperatureSpec`) — clip, force, or strip temperature.
- `max_tokens_field` — pick `max_tokens` or `max_completion_tokens`.
@@ -225,14 +225,14 @@ the capability value wins.
### Reasoning level: `reasoning_level` (three shapes)
Beyond on/off, CubePi maps a `ThinkingLevel`
-(`off`/`minimal`/`low`/`medium`/`high`/`xhigh`) onto a concrete wire value
+(`off`/`low`/`medium`/`high`/`xhigh`) onto a concrete wire value
written at a dotted `path`. `kind` picks the shape:
`ReasoningLevelSpec` only changes how that level is serialized. You still need
two call-site controls:
- set `reasoning=True` when binding the model (enable reasoning for that model)
-- set the Agent's `thinking` argument to one of `off|minimal|low|medium|high|xhigh`
+- set the Agent's `thinking` argument to one of `off|low|medium|high|xhigh`
(defaults to `off`).
```python
@@ -249,7 +249,6 @@ provider = OpenAIProvider(
kind="effort",
level_to_effort={
"off": "low",
- "minimal": "low",
"low": "low",
"medium": "medium",
"high": "high",
@@ -268,15 +267,15 @@ from cubepi import ReasoningLevelSpec
# int_budget — a token budget (Anthropic).
ReasoningLevelSpec(
path="thinking.budget_tokens", kind="int_budget",
- level_budgets={"off": 0, "minimal": 1024, "low": 2048,
+ level_budgets={"off": 0, "low": 2048,
"medium": 8192, "high": 16384, "xhigh": 16384},
)
# effort — an effort string (OpenAI Responses).
ReasoningLevelSpec(
path="reasoning.effort", kind="effort",
- level_to_effort={"minimal": "minimal", "low": "low",
- "medium": "medium", "high": "high", "xhigh": "high"},
+ level_to_effort={"low": "low", "medium": "medium",
+ "high": "high", "xhigh": "high"},
)
# enum — a vendor-specific state (Doubao's 3-state thinking).
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/hooks.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/hooks.md
index a30d06c..d2265c9 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/hooks.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/middleware/hooks.md
@@ -160,15 +160,22 @@ async def after_model_response(
```python
from cubepi.middleware.base import TurnAction
-from cubepi.providers.base import UserMessage, TextContent
+from cubepi.providers.base import synthetic_user_message
TurnAction(
response=modified_message, # 替换消息;None 则保留原消息
- inject_messages=[UserMessage(...)], # 在下一轮之前追加的额外消息
+ inject_messages=[ # 在下一轮之前追加的额外消息
+ synthetic_user_message("…", source="my_middleware"),
+ ],
decision="natural", # "natural" | "stop" | "loop_to_model"
)
```
+注入的 user 角色消息**必须**用 `synthetic_user_message(text, source=...)`
+构造,不要直接 `UserMessage(...)`。工厂会写入 `metadata["synthetic"] = True`,
+下游消费者(重放历史的 UI)就能把框架插入的提示和用户真正输入的区分开来;
+`source` 是个自由格式标签,只用于 trace。判断可用 `is_synthetic_message(msg)`。
+
三个控制流旋钮:
- `decision="natural"`(默认)—— 正常进入工具执行 / 下一轮。
@@ -194,12 +201,13 @@ async def on_run_end(
...
```
-**每次 `prompt()` 调用结束时触发一次**——所有轮次和工具调用完成后、
-`AgentEndEvent` 发出前。返回非空 `list[Message]` 会将这些消息注入上下文
-并运行**一轮额外的模型调用**(run-end pass)。返回 `None` 或 `[]` 不做任何操作。
+**每次外层循环迭代后触发**——所有轮次和工具调用完成、循环本应退出之前。
+返回非空 `list[Message]` 会将这些消息注入上下文并继续循环(agent 再跑一次)。
+返回 `None` 或 `[]` 什么也不做(循环退出)。和 `inject_messages` 一样,
+返回的 user 角色消息要用 `synthetic_user_message(...)` 构造,让它们带上
+synthetic 标记。
-额外轮次只触发一次——循环内的 `_reflection_fired` 标志阻止注入轮次再次触发
-`on_run_end`。
+每次 `prompt()` 内**可以多次触发**。中间件每次返回消息,worker 就再跑一轮。
**何时触发:**
- 正常完成(所有轮次结束后循环自然 break)。
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/providers/anthropic.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/providers/anthropic.md
index ff7b846..c493b22 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/providers/anthropic.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/providers/anthropic.md
@@ -46,7 +46,6 @@ CubePi 把 `ThinkingLevel` 枚举映射到 Anthropic 的 `budget_tokens`:
| Level | 默认 budget |
|---|---|
| `"off"` | 关闭思考 |
-| `"minimal"` | 1024 |
| `"low"` | 2048 |
| `"medium"` | 8192 |
| `"high"` | 16384 |
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/providers/overview.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/providers/overview.md
index 37193ee..5537541 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/providers/overview.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/providers/overview.md
@@ -72,7 +72,7 @@ provider = OpenAIProvider(
- `reasoning_on_payload / reasoning_off_payload` — 在 reasoning 开/关时,深度
合并到最终 payload。
-- `reasoning_level`(`ReasoningLevelSpec`)— 将 `off`/`minimal`/... 映射到后端字段。
+- `reasoning_level`(`ReasoningLevelSpec`)— 将 `off`/`low`/... 映射到后端字段。
- `temperature`(`TemperatureSpec`)— 裁剪、固定或去掉温度参数。
- `max_tokens_field` — 选 `max_tokens` 或 `max_completion_tokens`。
- `supports_tools` / `supports_images` / `supports_streaming` — 供宿主应用或前端消费的能力元数据。
@@ -161,12 +161,12 @@ CapabilityDescriptor(
### 推理级别:`reasoning_level`(三种形状)
-在开/关之外,CubePi 将 `ThinkingLevel`(`off`/`minimal`/`low`/`medium`/`high`/`xhigh`)映射到通过点路径 `path` 写入的具体 wire 值。`kind` 决定形状:
+在开/关之外,CubePi 将 `ThinkingLevel`(`off`/`low`/`medium`/`high`/`xhigh`)映射到通过点路径 `path` 写入的具体 wire 值。`kind` 决定形状:
-`ReasoningLevelSpec` 只负责「`thinking`/`minimal`/`low`/... 具体映射成后端字段」;要真正生效,还要配两个参数:
+`ReasoningLevelSpec` 只负责「`thinking`/`low`/... 具体映射成后端字段」;要真正生效,还要配两个参数:
- 在 `provider.model(...)` 时把 `reasoning=True`(把这个模型设为推理模型)
-- 在 `Agent(...)` 初始化时把 `thinking` 设成 `off|minimal|low|medium|high|xhigh`(默认 `off`)
+- 在 `Agent(...)` 初始化时把 `thinking` 设成 `off|low|medium|high|xhigh`(默认 `off`)
```python
from cubepi import Agent, CapabilityDescriptor, ReasoningLevelSpec
@@ -181,7 +181,6 @@ provider = OpenAIProvider(
kind="effort",
level_to_effort={
"off": "low",
- "minimal": "low",
"low": "low",
"medium": "medium",
"high": "high",
@@ -200,15 +199,15 @@ from cubepi import ReasoningLevelSpec
# int_budget — a token budget (Anthropic).
ReasoningLevelSpec(
path="thinking.budget_tokens", kind="int_budget",
- level_budgets={"off": 0, "minimal": 1024, "low": 2048,
+ level_budgets={"off": 0, "low": 2048,
"medium": 8192, "high": 16384, "xhigh": 16384},
)
# effort — an effort string (OpenAI Responses).
ReasoningLevelSpec(
path="reasoning.effort", kind="effort",
- level_to_effort={"minimal": "minimal", "low": "low",
- "medium": "medium", "high": "high", "xhigh": "high"},
+ level_to_effort={"low": "low", "medium": "medium",
+ "high": "high", "xhigh": "high"},
)
# enum — a vendor-specific state (Doubao's 3-state thinking).
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/middleware/hooks.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/middleware/hooks.md
index a30d06c..d2265c9 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/middleware/hooks.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/middleware/hooks.md
@@ -160,15 +160,22 @@ async def after_model_response(
```python
from cubepi.middleware.base import TurnAction
-from cubepi.providers.base import UserMessage, TextContent
+from cubepi.providers.base import synthetic_user_message
TurnAction(
response=modified_message, # 替换消息;None 则保留原消息
- inject_messages=[UserMessage(...)], # 在下一轮之前追加的额外消息
+ inject_messages=[ # 在下一轮之前追加的额外消息
+ synthetic_user_message("…", source="my_middleware"),
+ ],
decision="natural", # "natural" | "stop" | "loop_to_model"
)
```
+注入的 user 角色消息**必须**用 `synthetic_user_message(text, source=...)`
+构造,不要直接 `UserMessage(...)`。工厂会写入 `metadata["synthetic"] = True`,
+下游消费者(重放历史的 UI)就能把框架插入的提示和用户真正输入的区分开来;
+`source` 是个自由格式标签,只用于 trace。判断可用 `is_synthetic_message(msg)`。
+
三个控制流旋钮:
- `decision="natural"`(默认)—— 正常进入工具执行 / 下一轮。
@@ -194,12 +201,13 @@ async def on_run_end(
...
```
-**每次 `prompt()` 调用结束时触发一次**——所有轮次和工具调用完成后、
-`AgentEndEvent` 发出前。返回非空 `list[Message]` 会将这些消息注入上下文
-并运行**一轮额外的模型调用**(run-end pass)。返回 `None` 或 `[]` 不做任何操作。
+**每次外层循环迭代后触发**——所有轮次和工具调用完成、循环本应退出之前。
+返回非空 `list[Message]` 会将这些消息注入上下文并继续循环(agent 再跑一次)。
+返回 `None` 或 `[]` 什么也不做(循环退出)。和 `inject_messages` 一样,
+返回的 user 角色消息要用 `synthetic_user_message(...)` 构造,让它们带上
+synthetic 标记。
-额外轮次只触发一次——循环内的 `_reflection_fired` 标志阻止注入轮次再次触发
-`on_run_end`。
+每次 `prompt()` 内**可以多次触发**。中间件每次返回消息,worker 就再跑一轮。
**何时触发:**
- 正常完成(所有轮次结束后循环自然 break)。
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/providers/anthropic.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/providers/anthropic.md
index ff7b846..c493b22 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/providers/anthropic.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/providers/anthropic.md
@@ -46,7 +46,6 @@ CubePi 把 `ThinkingLevel` 枚举映射到 Anthropic 的 `budget_tokens`:
| Level | 默认 budget |
|---|---|
| `"off"` | 关闭思考 |
-| `"minimal"` | 1024 |
| `"low"` | 2048 |
| `"medium"` | 8192 |
| `"high"` | 16384 |
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/providers/overview.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/providers/overview.md
index 37193ee..5537541 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/providers/overview.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/version-0.10/guides/providers/overview.md
@@ -72,7 +72,7 @@ provider = OpenAIProvider(
- `reasoning_on_payload / reasoning_off_payload` — 在 reasoning 开/关时,深度
合并到最终 payload。
-- `reasoning_level`(`ReasoningLevelSpec`)— 将 `off`/`minimal`/... 映射到后端字段。
+- `reasoning_level`(`ReasoningLevelSpec`)— 将 `off`/`low`/... 映射到后端字段。
- `temperature`(`TemperatureSpec`)— 裁剪、固定或去掉温度参数。
- `max_tokens_field` — 选 `max_tokens` 或 `max_completion_tokens`。
- `supports_tools` / `supports_images` / `supports_streaming` — 供宿主应用或前端消费的能力元数据。
@@ -161,12 +161,12 @@ CapabilityDescriptor(
### 推理级别:`reasoning_level`(三种形状)
-在开/关之外,CubePi 将 `ThinkingLevel`(`off`/`minimal`/`low`/`medium`/`high`/`xhigh`)映射到通过点路径 `path` 写入的具体 wire 值。`kind` 决定形状:
+在开/关之外,CubePi 将 `ThinkingLevel`(`off`/`low`/`medium`/`high`/`xhigh`)映射到通过点路径 `path` 写入的具体 wire 值。`kind` 决定形状:
-`ReasoningLevelSpec` 只负责「`thinking`/`minimal`/`low`/... 具体映射成后端字段」;要真正生效,还要配两个参数:
+`ReasoningLevelSpec` 只负责「`thinking`/`low`/... 具体映射成后端字段」;要真正生效,还要配两个参数:
- 在 `provider.model(...)` 时把 `reasoning=True`(把这个模型设为推理模型)
-- 在 `Agent(...)` 初始化时把 `thinking` 设成 `off|minimal|low|medium|high|xhigh`(默认 `off`)
+- 在 `Agent(...)` 初始化时把 `thinking` 设成 `off|low|medium|high|xhigh`(默认 `off`)
```python
from cubepi import Agent, CapabilityDescriptor, ReasoningLevelSpec
@@ -181,7 +181,6 @@ provider = OpenAIProvider(
kind="effort",
level_to_effort={
"off": "low",
- "minimal": "low",
"low": "low",
"medium": "medium",
"high": "high",
@@ -200,15 +199,15 @@ from cubepi import ReasoningLevelSpec
# int_budget — a token budget (Anthropic).
ReasoningLevelSpec(
path="thinking.budget_tokens", kind="int_budget",
- level_budgets={"off": 0, "minimal": 1024, "low": 2048,
+ level_budgets={"off": 0, "low": 2048,
"medium": 8192, "high": 16384, "xhigh": 16384},
)
# effort — an effort string (OpenAI Responses).
ReasoningLevelSpec(
path="reasoning.effort", kind="effort",
- level_to_effort={"minimal": "minimal", "low": "low",
- "medium": "medium", "high": "high", "xhigh": "high"},
+ level_to_effort={"low": "low", "medium": "medium",
+ "high": "high", "xhigh": "high"},
)
# enum — a vendor-specific state (Doubao's 3-state thinking).
diff --git a/website/versioned_docs/version-0.10/api/cubepi-middleware.mdx b/website/versioned_docs/version-0.10/api/cubepi-middleware.mdx
index a8fa20c..2617281 100644
--- a/website/versioned_docs/version-0.10/api/cubepi-middleware.mdx
+++ b/website/versioned_docs/version-0.10/api/cubepi-middleware.mdx
@@ -232,7 +232,7 @@ GoalMiddleware(self, evaluator: BoundModel, max_evaluations: int = 10)
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/goal.py#L72)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/goal.py#L73)
**Methods**
@@ -243,7 +243,7 @@ GoalMiddleware(self, evaluator: BoundModel, max_evaluations: int = 10)
extra_llm_calls() -> Iterable[BoundModel]
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/goal.py#L83)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/goal.py#L84)
#### `transform_context` {#goalmiddleware-transform-context}
@@ -252,7 +252,7 @@ extra_llm_calls() -> Iterable[BoundModel]
transform_context(messages: list[Message], *, ctx: AgentContext, signal: asyncio.Event | None = None) -> list[Message]
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/goal.py#L86)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/goal.py#L87)
#### `on_run_end` {#goalmiddleware-on-run-end}
@@ -261,7 +261,7 @@ transform_context(messages: list[Message], *, ctx: AgentContext, signal: asyncio
on_run_end(ctx: AgentContext, *, signal: asyncio.Event | None = None) -> list[Message] | None
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/goal.py#L121)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/goal.py#L122)
@@ -350,7 +350,7 @@ _class_
A single todo item with content and status.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L131)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L132)
**Attributes**
@@ -365,7 +365,7 @@ _class_
A guard escalation payload carried across the forced end turn.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L148)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L149)
**Attributes**
@@ -435,7 +435,7 @@ Hooks:
* finalization hard guard → loop_to_model with correction message
* otherwise → return None (natural flow)
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L465)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L466)
**Attributes**
@@ -453,7 +453,7 @@ transform_system_prompt(system_prompt: str, *, ctx: AgentContext, signal: asynci
Append the write_todos system instructions.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L507)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L508)
#### `transform_context` {#todolistmiddleware-transform-context}
@@ -470,7 +470,7 @@ context to ensure the model always sees the current todo list.
When no todos are set, messages are returned unchanged (no injection).
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L522)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L523)
#### `after_tool_call` {#todolistmiddleware-after-tool-call}
@@ -489,7 +489,7 @@ in extra["_todos_snapshot"]. Each duplicate write_todos call's result is
replaced with an error here, and extra["todos"] is restored to the snapshot
so the turn leaves the checklist unchanged.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L556)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L557)
#### `after_model_response` {#todolistmiddleware-after-model-response}
@@ -504,7 +504,7 @@ Inspects the latest assistant message, transitions the blocked /
stale-iteration state stored in `extra`, and returns a
`TurnAction` when the loop needs an injected nudge or hard stop.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L647)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L653)
@@ -514,7 +514,7 @@ _class_
Input schema for the `write_todos` tool.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L261)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/middleware/todo.py#L262)
**Attributes**
diff --git a/website/versioned_docs/version-0.10/api/cubepi-providers.mdx b/website/versioned_docs/version-0.10/api/cubepi-providers.mdx
index fb77d97..641c133 100644
--- a/website/versioned_docs/version-0.10/api/cubepi-providers.mdx
+++ b/website/versioned_docs/version-0.10/api/cubepi-providers.mdx
@@ -56,7 +56,7 @@ Per-call mutators (`StreamOptions.on_payload`,
semantics and fire independently of the persistent listener registry
below.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L611)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L639)
**Attributes**
@@ -72,7 +72,7 @@ below.
model(id: str, *, api: str = '', reasoning: bool = False, context_window: int = 200000, max_tokens: int = 8192, temperature: float = 0.7, cost: ModelCost | None = None, thinking_level_map: dict[str, str | None] | None = None) -> BoundModel
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L637)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L665)
#### `stream` {#baseprovider-stream}
@@ -81,7 +81,7 @@ model(id: str, *, api: str = '', reasoning: bool = False, context_window: int =
stream(model: Model, messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefinition] | None = None, tool_choice: ToolChoice | None = None, options: StreamOptions | None = None) -> MessageStream
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L664)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L692)
#### `generate` {#baseprovider-generate}
@@ -92,7 +92,7 @@ generate(model: Model, messages: list[Message], *, system_prompt: str = '', tool
Run a single provider call and return the final assistant message.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L676)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L704)
#### `subscribe_request` {#baseprovider-subscribe-request}
@@ -105,7 +105,7 @@ Register a persistent observer for request payloads.
Returns a detach callable that removes this specific subscription.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L729)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L757)
#### `subscribe_chunk` {#baseprovider-subscribe-chunk}
@@ -118,7 +118,7 @@ Register a persistent observer for stream chunks.
Returns a detach callable.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L737)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L765)
#### `subscribe_response` {#baseprovider-subscribe-response}
@@ -131,7 +131,7 @@ Register a persistent observer for assembled responses.
Returns a detach callable.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L745)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L773)
@@ -144,7 +144,7 @@ BoundModel(self, provider: Provider, spec: Model)
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L779)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L807)
**Attributes**
@@ -161,7 +161,7 @@ BoundModel(self, provider: Provider, spec: Model)
stream(messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefinition] | None = None, tool_choice: ToolChoice | None = None, options: StreamOptions | None = None) -> MessageStream
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L784)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L812)
#### `generate` {#boundmodel-generate}
@@ -170,7 +170,7 @@ stream(messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefi
generate(messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefinition] | None = None, tool_choice: ToolChoice | None = None, options: StreamOptions | None = None, max_output_tokens: int | None = None, temperature: float | None = None, thinking: ThinkingLevel | None = None, thinking_budgets: ThinkingBudgets | None = None) -> AssistantMessage
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L808)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L836)
#### `generate_structured` {#boundmodel-generate-structured}
@@ -179,7 +179,7 @@ generate(messages: list[Message], *, system_prompt: str = '', tools: list[ToolDe
generate_structured(output_type: type[BaseModelT], messages: list[Message], *, system_prompt: str = '', tool_name: str = 'structured_output', tool_description: str = 'Return the structured output', max_output_tokens: int | None = None, temperature: float | None = None, max_retries: int = 1) -> BaseModelT
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L835)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L863)
@@ -231,7 +231,7 @@ MessageStream(self)
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L223)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L260)
**Methods**
@@ -242,7 +242,7 @@ MessageStream(self)
attach_task(task: asyncio.Task) -> None
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L231)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L268)
#### `push` {#messagestream-push}
@@ -251,7 +251,7 @@ attach_task(task: asyncio.Task) -> None
push(event: StreamEvent) -> None
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L243)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L280)
#### `set_result` {#messagestream-set-result}
@@ -260,7 +260,7 @@ push(event: StreamEvent) -> None
set_result(message: AssistantMessage) -> None
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L248)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L285)
#### `result` {#messagestream-result}
@@ -279,7 +279,7 @@ teardown could exit before async response listeners have run.
Producer exceptions are NOT re-raised here; they were already
surfaced via the result future or the stream's error events.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L261)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L298)
@@ -333,7 +333,7 @@ Persistent observer. Fires for every StreamEvent pushed onto the stream
Heavy listeners should early-return on irrelevant event types — this hook
fires hot. Return value is ignored.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L315)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L352)
### OnPayloadCallback {#onpayloadcallback}
@@ -347,7 +347,7 @@ OnPayloadCallback = Callable[[dict, Model], Awaitable[dict | None] | dict | None
Optional callback for inspecting/replacing provider payloads before sending.
Return a dict to replace the payload, or None to keep unchanged.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L302)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L339)
### OnRequestCallback {#onrequestcallback}
@@ -362,7 +362,7 @@ Persistent observer. Fires just before HTTP send, after any per-call
`StreamOptions.on_payload` mutation has been applied. Receives the final
wire payload dict and the Model. Return value is ignored.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L310)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L347)
### OnResponseBodyCallback {#onresponsebodycallback}
@@ -383,7 +383,7 @@ finally block, after the stream terminates.
`asyncio.CancelledError`), or None on normal completion.
Return value is ignored.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L321)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L358)
### OnResponseCallback {#onresponsecallback}
@@ -396,7 +396,7 @@ OnResponseCallback = Callable[['ProviderResponse', Model], Awaitable[None] | Non
Optional callback invoked after an HTTP response is received.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L306)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L343)
### Provider {#provider}
@@ -404,7 +404,7 @@ Optional callback invoked after an HTTP response is received.
_class_
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L582)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L610)
**Methods**
@@ -415,7 +415,7 @@ _class_
stream(model: Model, messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefinition] | None = None, tool_choice: ToolChoice | None = None, options: StreamOptions | None = None) -> MessageStream
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L584)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L612)
#### `generate` {#provider-generate}
@@ -424,7 +424,7 @@ stream(model: Model, messages: list[Message], *, system_prompt: str = '', tools:
generate(model: Model, messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefinition] | None = None, tool_choice: ToolChoice | None = None, options: StreamOptions | None = None, max_output_tokens: int | None = None, temperature: float | None = None, thinking: ThinkingLevel | None = None, thinking_budgets: ThinkingBudgets | None = None) -> AssistantMessage
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L595)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L623)
@@ -438,7 +438,7 @@ ProviderResponse(self, status: int, headers: dict[str, str] = dict())
HTTP response metadata exposed to on_response callbacks.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L294)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L331)
**Attributes**
@@ -452,7 +452,7 @@ HTTP response metadata exposed to on_response callbacks.
_class_
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L171)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L208)
**Attributes**
@@ -470,7 +470,7 @@ _class_
Options bag for Provider.stream(), transparent to the agent loop.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L543)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L571)
**Attributes**
@@ -503,12 +503,11 @@ _class_
Token budgets for each thinking level.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L29)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L30)
**Attributes**
-- `minimal`: `int`
- `low`: `int`
- `medium`: `int`
- `high`: `int`
@@ -533,11 +532,11 @@ _class_
_attribute_
```python
-ThinkingLevel = Literal['off', 'minimal', 'low', 'medium', 'high', 'xhigh']
+ThinkingLevel = Literal['off', 'low', 'medium', 'high', 'xhigh']
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L24)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L25)
### ToolCall {#toolcall}
@@ -561,7 +560,7 @@ _class_
_class_
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L165)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L202)
**Attributes**
@@ -625,6 +624,38 @@ _class_
- `run_id`: `str | None`
+### is_synthetic_message {#is-synthetic-message}
+
+_function_
+
+```python
+is_synthetic_message(message: Message) -> bool
+```
+
+True if `message` was injected by the framework rather than a human.
+
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L197)
+
+
+### synthetic_user_message {#synthetic-user-message}
+
+_function_
+
+```python
+synthetic_user_message(text: str, *, source: str) -> UserMessage
+```
+
+Build a user-role message injected by the framework, not typed by a human.
+
+All injected user-role messages MUST be created through this factory so
+downstream consumers can branch on a single marker
+(`metadata["synthetic"] is True`). `source` (e.g. `"todo_guard"`,
+`"goal_continuation"`) is for tracing/debugging only — UI behavior
+should never depend on it.
+
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L179)
+
+
### adjust_max_tokens_for_thinking {#adjust-max-tokens-for-thinking}
_function_
@@ -680,7 +711,7 @@ Used by `cubepi.tracing.recorder.Recorder.attach` and
fallback chain so post-failover provider events land in the trace /
metric stream.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L907)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L937)
### collect_agent_providers {#collect-agent-providers}
@@ -699,7 +730,7 @@ by both `cubepi.tracing.recorder.Recorder.attach` and
`cubepi.tracing.meter.Meter.attach` to dedupe the prelude that
finds providers to subscribe to.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L960)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/base.py#L988)
### FauxProvider {#fauxprovider}
@@ -819,7 +850,7 @@ DEFAULT_TRIGGER_ERRORS: frozenset[type[ProviderError]] = frozenset({RateLimited,
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/fallback.py#L40)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/fallback.py#L36)
### FallbackBoundModel {#fallbackboundmodel}
@@ -847,7 +878,7 @@ chain (via chain_providers() below), so post-failover chat spans and
provider metrics land in the trace / metric stream like primary-leg
calls do.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/fallback.py#L45)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/fallback.py#L41)
**Attributes**
@@ -867,7 +898,7 @@ calls do.
stream(messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefinition] | None = None, tool_choice: ToolChoice | None = None, options: StreamOptions | None = None) -> MessageStream
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/fallback.py#L124)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/fallback.py#L120)
#### `generate` {#fallbackboundmodel-generate}
@@ -876,7 +907,7 @@ stream(messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefi
generate(messages: list[Message], *, system_prompt: str = '', tools: list[ToolDefinition] | None = None, tool_choice: ToolChoice | None = None, options: StreamOptions | None = None, max_output_tokens: int | None = None, temperature: float | None = None, thinking: ThinkingLevel | None = None, thinking_budgets: ThinkingBudgets | None = None) -> AssistantMessage
```
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/fallback.py#L200)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/fallback.py#L196)
@@ -885,7 +916,7 @@ generate(messages: list[Message], *, system_prompt: str = '', tools: list[ToolDe
_attribute_
```python
-THINKING_LEVELS: list[ThinkingLevel] = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh']
+THINKING_LEVELS: list[ThinkingLevel] = ['off', 'low', 'medium', 'high', 'xhigh']
```
@@ -906,7 +937,7 @@ 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.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/models.py#L54)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/models.py#L53)
### get_supported_thinking_levels {#get-supported-thinking-levels}
@@ -925,7 +956,7 @@ Return the thinking levels supported by *model*.
`"xhigh"` is only included when it has an explicit (non-None) mapping.
All other levels are included by default when the map omits them.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/models.py#L22)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/models.py#L21)
### models_are_equal {#models-are-equal}
@@ -941,7 +972,7 @@ Return `True` if *a* and *b* refer to the same model.
Comparison is by `id` and `provider_id`. Returns `False` when either
argument is `None`.
-[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/models.py#L87)
+[source](https://github.com/cubeplexai/cubepi/blob/main/cubepi/providers/models.py#L86)
diff --git a/website/versioned_docs/version-0.10/guides/middleware/hooks.md b/website/versioned_docs/version-0.10/guides/middleware/hooks.md
index cf49486..bde1e27 100644
--- a/website/versioned_docs/version-0.10/guides/middleware/hooks.md
+++ b/website/versioned_docs/version-0.10/guides/middleware/hooks.md
@@ -170,15 +170,24 @@ hook returns a `TurnAction`:
```python
from cubepi.middleware.base import TurnAction
-from cubepi.providers.base import UserMessage, TextContent
+from cubepi.providers.base import synthetic_user_message
TurnAction(
response=modified_message, # replace the message; None to keep
- inject_messages=[UserMessage(...)], # extra messages to append before next turn
+ inject_messages=[ # extra messages to append before next turn
+ synthetic_user_message("…", source="my_middleware"),
+ ],
decision="natural", # "natural" | "stop" | "loop_to_model"
)
```
+Injected user-role messages **must** be built with
+`synthetic_user_message(text, source=...)`, never with a bare
+`UserMessage`. The factory stamps `metadata["synthetic"] = True` so
+downstream consumers (UIs replaying history) can tell framework nudges
+apart from messages the human actually typed; `source` is a free-form
+tag for traces only. Check with `is_synthetic_message(msg)`.
+
Three control-flow knobs:
- `decision="natural"` (default) — proceed to tool execution / next
@@ -211,7 +220,9 @@ Fires **after each outer-loop iteration** — i.e. after all turns and
tool calls complete before the loop would normally exit. Return a
non-empty `list[Message]` to inject those messages into context and
continue the loop (the agent runs again). Return `None` or `[]` to do
-nothing (the loop exits).
+nothing (the loop exits). As with `inject_messages`, build returned
+user-role messages with `synthetic_user_message(...)` so they carry
+the synthetic marker.
This hook can fire **multiple times** per `prompt()` call. Each time
the middleware returns messages, the worker gets another run. Return
diff --git a/website/versioned_docs/version-0.10/guides/providers/anthropic.md b/website/versioned_docs/version-0.10/guides/providers/anthropic.md
index c1f4acc..cbf5878 100644
--- a/website/versioned_docs/version-0.10/guides/providers/anthropic.md
+++ b/website/versioned_docs/version-0.10/guides/providers/anthropic.md
@@ -49,7 +49,6 @@ CubePi maps a `ThinkingLevel` enum onto Anthropic's `budget_tokens`:
| Level | Default budget |
|---|---|
| `"off"` | thinking disabled |
-| `"minimal"` | 1024 |
| `"low"` | 2048 |
| `"medium"` | 8192 |
| `"high"` | 16384 |
@@ -78,7 +77,7 @@ provider = AnthropicProvider(
reasoning_level=ReasoningLevelSpec(
path="thinking.budget_tokens",
kind="int_budget",
- level_budgets={"off": 0, "minimal": 1024, "low": 4096,
+ level_budgets={"off": 0, "low": 4096,
"medium": 12288, "high": 16384, "xhigh": 16384},
),
),
diff --git a/website/versioned_docs/version-0.10/guides/providers/overview.md b/website/versioned_docs/version-0.10/guides/providers/overview.md
index 476b24e..920f96b 100644
--- a/website/versioned_docs/version-0.10/guides/providers/overview.md
+++ b/website/versioned_docs/version-0.10/guides/providers/overview.md
@@ -107,7 +107,7 @@ provider = OpenAIProvider(
- `reasoning_on_payload / reasoning_off_payload` — payload merged when
reasoning is on/off.
-- `reasoning_level` (`ReasoningLevelSpec`) — map `off`/`minimal`/... to backend
+- `reasoning_level` (`ReasoningLevelSpec`) — map `off`/`low`/... to backend
payload paths.
- `temperature` (`TemperatureSpec`) — clip, force, or strip temperature.
- `max_tokens_field` — pick `max_tokens` or `max_completion_tokens`.
@@ -225,14 +225,14 @@ the capability value wins.
### Reasoning level: `reasoning_level` (three shapes)
Beyond on/off, CubePi maps a `ThinkingLevel`
-(`off`/`minimal`/`low`/`medium`/`high`/`xhigh`) onto a concrete wire value
+(`off`/`low`/`medium`/`high`/`xhigh`) onto a concrete wire value
written at a dotted `path`. `kind` picks the shape:
`ReasoningLevelSpec` only changes how that level is serialized. You still need
two call-site controls:
- set `reasoning=True` when binding the model (enable reasoning for that model)
-- set the Agent's `thinking` argument to one of `off|minimal|low|medium|high|xhigh`
+- set the Agent's `thinking` argument to one of `off|low|medium|high|xhigh`
(defaults to `off`).
```python
@@ -249,7 +249,6 @@ provider = OpenAIProvider(
kind="effort",
level_to_effort={
"off": "low",
- "minimal": "low",
"low": "low",
"medium": "medium",
"high": "high",
@@ -268,15 +267,15 @@ from cubepi import ReasoningLevelSpec
# int_budget — a token budget (Anthropic).
ReasoningLevelSpec(
path="thinking.budget_tokens", kind="int_budget",
- level_budgets={"off": 0, "minimal": 1024, "low": 2048,
+ level_budgets={"off": 0, "low": 2048,
"medium": 8192, "high": 16384, "xhigh": 16384},
)
# effort — an effort string (OpenAI Responses).
ReasoningLevelSpec(
path="reasoning.effort", kind="effort",
- level_to_effort={"minimal": "minimal", "low": "low",
- "medium": "medium", "high": "high", "xhigh": "high"},
+ level_to_effort={"low": "low", "medium": "medium",
+ "high": "high", "xhigh": "high"},
)
# enum — a vendor-specific state (Doubao's 3-state thinking).