Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

feature/Structured-output-reasoning · L-261006-36433a (#1360)

Louis Choquele474c338657d
diff --git a/.claude/skills/add-model/SKILL.md b/.claude/skills/add-model/SKILL.md
index b21724ef9..2758d79c5 100644
--- a/.claude/skills/add-model/SKILL.md
+++ b/.claude/skills/add-model/SKILL.md
@@ -31,7 +31,7 @@ Build a fact sheet before touching a file, and give every fact its source. The p
| SDK and structure method | `sdk`, `structure_method` | Both come from the file's `[defaults]`, and an entry overrides them where its family differs: the image-generation entries of `azure_openai.toml` replace the file's `azure_openai_responses` with `azure_rest_img_gen`. `sdk` has no default in code, so a wrong one boots and fails at the first call |
| Costs | `costs = { input = …, output = … }` | USD per million tokens. Image models may price differently; copy the sibling's shape |
| Thinking | `thinking_mode` | `none`, `manual` (a budget the caller sets) or `adaptive` (the model decides) |
-| Refused parameters | `listed_constraints`, `valued_constraints` | `temperature_unsupported`, `temperature_must_be_multiplied_by_2`, `max_tokens_must_be_high_enough`; `valued_constraints = { fixed_temperature = 1 }`. The vocabulary is `pipelex/cogt/model_backends/constraints.py` |
+| Refused parameters | `listed_constraints`, `valued_constraints` | `temperature_unsupported`, `temperature_must_be_multiplied_by_2`, `max_tokens_must_be_high_enough`, and `thinking_cannot_be_disabled` for a Gemini model that refuses a thinking budget of 0; `valued_constraints = { fixed_temperature = 1 }`, and for a model thinking on a token budget the range its provider accepts, `min_thinking_budget` and `max_thinking_budget` (Anthropic's floor is 1,024, declared in `anthropic.toml`'s defaults but on each model in `bedrock.toml`). The vocabulary is `pipelex/cogt/model_backends/constraints.py` |
| Limits | `max_tokens`, `max_prompt_images` | Only where the sibling declares them |
A model spec declares nothing about how its prompts are formatted: templating style is authored on the pipe. And do not invent keys: a key the model-spec blueprint does not know fails the boot, unless it is a hyphenated header name with a plain string value, which is sent to the provider as an outbound HTTP header.
diff --git a/.pipelex/inference/backends/anthropic.toml b/.pipelex/inference/backends/anthropic.toml
index dbe8fd8cf..0e57a6feb 100644
--- a/.pipelex/inference/backends/anthropic.toml
+++ b/.pipelex/inference/backends/anthropic.toml
@@ -25,6 +25,7 @@ model_type = "llm"
sdk = "anthropic"
structure_method = "instructor/anthropic_tools"
thinking_mode = "manual"
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
################################################################################
# LANGUAGE MODELS
diff --git a/.pipelex/inference/backends/bedrock.toml b/.pipelex/inference/backends/bedrock.toml
index e876def7c..6f75eceb3 100644
--- a/.pipelex/inference/backends/bedrock.toml
+++ b/.pipelex/inference/backends/bedrock.toml
@@ -72,6 +72,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 3.0, output = 15.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
[claude-4-opus]
@@ -82,6 +83,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 3.0, output = 15.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
["claude-4.1-opus"]
@@ -92,6 +94,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 3.0, output = 15.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
["claude-4.5-sonnet"]
@@ -102,6 +105,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 3.0, output = 15.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
["claude-4.5-haiku"]
@@ -112,6 +116,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 1.0, output = 5.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
["claude-4.5-opus"]
@@ -122,6 +127,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 5.0, output = 25.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
["claude-4.6-sonnet"]
@@ -132,6 +138,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 3.0, output = 15.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "adaptive"
["claude-4.6-opus"]
@@ -142,6 +149,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 5.0, output = 25.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "adaptive"
# --- Claude 4.7 Series --------------------------------------------------------
@@ -153,6 +161,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 5.0, output = 25.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "adaptive"
listed_constraints = ["temperature_unsupported"]
@@ -165,5 +174,6 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 5.0, output = 25.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "adaptive"
listed_constraints = ["temperature_unsupported"]
diff --git a/.pipelex/inference/backends/google.toml b/.pipelex/inference/backends/google.toml
index 69d8ddf68..7552d99c9 100644
--- a/.pipelex/inference/backends/google.toml
+++ b/.pipelex/inference/backends/google.toml
@@ -37,6 +37,9 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 1.25, output = 10.0 }
+valued_constraints = { min_thinking_budget = 128, max_thinking_budget = 32768 }
+# Gemini refuses a thinking budget of 0 for this model
+listed_constraints = ["thinking_cannot_be_disabled"]
["gemini-2.5-flash"]
model_id = "gemini-2.5-flash"
@@ -44,6 +47,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 0.30, output = 2.50 }
+valued_constraints = { max_thinking_budget = 24576 }
["gemini-2.5-flash-lite"]
model_id = "gemini-2.5-flash-lite"
@@ -51,6 +55,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 0.10, output = 0.40 }
+valued_constraints = { min_thinking_budget = 512, max_thinking_budget = 24576 }
# --- Gemini 3.0 Series ----------------------------------------
["gemini-3.0-flash"]
@@ -76,6 +81,8 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 2, output = 12.0 }
+# Gemini refuses a thinking budget of 0 for this model
+listed_constraints = ["thinking_cannot_be_disabled"]
thinking_mode = "adaptive"
# --- Gemini 3.5 Series ----------------------------------------
@@ -93,6 +100,8 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 1.25, output = 10.0 }
+# Gemini refuses a thinking budget of 0 for this model: the alias resolved to gemini-3.1-pro-preview, which always thinks, in October 2026
+listed_constraints = ["thinking_cannot_be_disabled"]
thinking_mode = "adaptive"
["gemini-flash-latest"]
@@ -107,6 +116,8 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 0.10, output = 0.40 }
+# Gemini refuses a thinking budget of 0 for this model: the alias resolved to gemini-3.5-flash-lite, which always thinks, in October 2026
+listed_constraints = ["thinking_cannot_be_disabled"]
thinking_mode = "adaptive"
################################################################################
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7b5e46cb3..3b020814c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,14 @@
# Changelog
+## [Unreleased]
+
+### Fixed
+
+- **A reasoning setting reaches a structured output**: a pipe whose model setting carries `reasoning_effort` or `reasoning_budget`, the deck's `$deep-analysis`, `$quick-reasoning` and `$retrieval-premium` presets included, now generates its structured output with that setting on every provider, where every language-model worker refused it with `LLMCapabilityError` "does not support reasoning parameters for structured generation". A model refuses a reasoning setting on a structured output only where it refuses it on text, or on Mistral where its structure method is not `instructor/mistral_tools`, whose JSON parsing cannot read a reasoning reply; a structured call on an Anthropic tool method with thinking on leaves the tool choice to the model, since a forced tool choice cannot carry thinking.
+- **A manual thinking budget leaves room for the answer and stays in the model's range (Breaking)**: an Anthropic or Gemini thinking budget, resolved from an effort or set explicitly, is cut to leave a quarter of `max_tokens` for the answer, where it could take all but one token of it, and held within the range the model declares with the new `min_thinking_budget` and `max_thinking_budget` valued constraints. The kit's Anthropic models declare the API's minimum of 1,024 tokens, so the 512 that `minimal` maps to is raised to it, and its Gemini 2.5 models declare their ranges, so `max` effort's 65,536 tokens, which every Gemini 2.5 model refused, are cut to the model's maximum even without a `max_tokens`. A `max_tokens` too small to hold the model's minimum beside the answer reserve is refused with an `LLMCapabilityError` naming the numbers, where the request was sent, and a reasoning effort of `none` on a Gemini model that always thinks, which the kit marks with the new `thinking_cannot_be_disabled` listed constraint, is refused rather than sent as a budget of 0 that Gemini answers with a 400; a project that copied the kit's `anthropic.toml`, `bedrock.toml` or `google.toml` gets the bounds by declaring them in its copy.
+- **Mistral reasoning is sent as `reasoning_effort`**: a reasoning effort on a Mistral model is sent as `reasoning_effort = "high"`, the only reasoning value Mistral's reasoning models accept, where it was sent as `prompt_mode = "reasoning"`, which every current Mistral model refuses, so any reasoning effort on Mistral failed. The `reasoning` level of `[inference.llm.mistral.effort_to_level_map]` is unchanged.
+- **A structured output on Google without a system prompt no longer fails**: a structured call on the `google` backend whose prompt has no system text failed with `TypeError` "generate_content() got an unexpected keyword argument 'system'", and is now sent with no system instruction.
+
## [v0.76.0] - 2026-10-06
### Added
diff --git a/api/.pipelex/inference/backends/anthropic.toml b/api/.pipelex/inference/backends/anthropic.toml
index dbe8fd8cf..0e57a6feb 100644
--- a/api/.pipelex/inference/backends/anthropic.toml
+++ b/api/.pipelex/inference/backends/anthropic.toml
@@ -25,6 +25,7 @@ model_type = "llm"
sdk = "anthropic"
structure_method = "instructor/anthropic_tools"
thinking_mode = "manual"
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
################################################################################
# LANGUAGE MODELS
diff --git a/api/.pipelex/inference/backends/bedrock.toml b/api/.pipelex/inference/backends/bedrock.toml
index e876def7c..6f75eceb3 100644
--- a/api/.pipelex/inference/backends/bedrock.toml
+++ b/api/.pipelex/inference/backends/bedrock.toml
@@ -72,6 +72,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 3.0, output = 15.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
[claude-4-opus]
@@ -82,6 +83,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 3.0, output = 15.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
["claude-4.1-opus"]
@@ -92,6 +94,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 3.0, output = 15.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
["claude-4.5-sonnet"]
@@ -102,6 +105,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 3.0, output = 15.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
["claude-4.5-haiku"]
@@ -112,6 +116,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 1.0, output = 5.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
["claude-4.5-opus"]
@@ -122,6 +127,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 5.0, output = 25.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
["claude-4.6-sonnet"]
@@ -132,6 +138,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 3.0, output = 15.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "adaptive"
["claude-4.6-opus"]
@@ -142,6 +149,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 5.0, output = 25.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "adaptive"
# --- Claude 4.7 Series --------------------------------------------------------
@@ -153,6 +161,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 5.0, output = 25.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "adaptive"
listed_constraints = ["temperature_unsupported"]
@@ -165,5 +174,6 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 5.0, output = 25.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "adaptive"
listed_constraints = ["temperature_unsupported"]
diff --git a/api/.pipelex/inference/backends/google.toml b/api/.pipelex/inference/backends/google.toml
index 69d8ddf68..7552d99c9 100644
--- a/api/.pipelex/inference/backends/google.toml
+++ b/api/.pipelex/inference/backends/google.toml
@@ -37,6 +37,9 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 1.25, output = 10.0 }
+valued_constraints = { min_thinking_budget = 128, max_thinking_budget = 32768 }
+# Gemini refuses a thinking budget of 0 for this model
+listed_constraints = ["thinking_cannot_be_disabled"]
["gemini-2.5-flash"]
model_id = "gemini-2.5-flash"
@@ -44,6 +47,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 0.30, output = 2.50 }
+valued_constraints = { max_thinking_budget = 24576 }
["gemini-2.5-flash-lite"]
model_id = "gemini-2.5-flash-lite"
@@ -51,6 +55,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 0.10, output = 0.40 }
+valued_constraints = { min_thinking_budget = 512, max_thinking_budget = 24576 }
# --- Gemini 3.0 Series ----------------------------------------
["gemini-3.0-flash"]
@@ -76,6 +81,8 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 2, output = 12.0 }
+# Gemini refuses a thinking budget of 0 for this model
+listed_constraints = ["thinking_cannot_be_disabled"]
thinking_mode = "adaptive"
# --- Gemini 3.5 Series ----------------------------------------
@@ -93,6 +100,8 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 1.25, output = 10.0 }
+# Gemini refuses a thinking budget of 0 for this model: the alias resolved to gemini-3.1-pro-preview, which always thinks, in October 2026
+listed_constraints = ["thinking_cannot_be_disabled"]
thinking_mode = "adaptive"
["gemini-flash-latest"]
@@ -107,6 +116,8 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 0.10, output = 0.40 }
+# Gemini refuses a thinking budget of 0 for this model: the alias resolved to gemini-3.5-flash-lite, which always thinks, in October 2026
+listed_constraints = ["thinking_cannot_be_disabled"]
thinking_mode = "adaptive"
################################################################################
diff --git a/docs/building-methods/pipes/pipe-operators/PipeLLM.md b/docs/building-methods/pipes/pipe-operators/PipeLLM.md
index 9158f656a..abea48b42 100644
--- a/docs/building-methods/pipes/pipe-operators/PipeLLM.md
+++ b/docs/building-methods/pipes/pipe-operators/PipeLLM.md
@@ -251,7 +251,7 @@ When `model` is specified as a table (inline LLM setting), it accepts the follow
| `model` | string | Model name or alias (e.g., `"claude-4.5-sonnet"`, `"@default-premium"`) |
| `temperature` | float | Sampling temperature (0.0 – 1.0) |
| `max_tokens` | integer | Maximum output tokens |
-| `reasoning_effort` | string | Reasoning depth: `"none"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`. Not supported for structured generation. |
+| `reasoning_effort` | string | Reasoning depth: `"none"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`. Applies to structured outputs too, generated with this setting when no `model_to_structure` is named. |
| `reasoning_budget` | integer | Explicit token budget for reasoning. Mutually exclusive with `reasoning_effort`. Supported by Anthropic and Google only. |
| `description` | string | Human-readable description (for presets) |
diff --git a/docs/configuration/config-technical/inference-backend-config.md b/docs/configuration/config-technical/inference-backend-config.md
index 3543b948d..5f364893b 100644
--- a/docs/configuration/config-technical/inference-backend-config.md
+++ b/docs/configuration/config-technical/inference-backend-config.md
@@ -231,10 +231,34 @@ A file whose format the consuming model does not declare is refused with an inpu
`structure_method` says how a model is asked for structured output. A structure method names a provider, but the SDK decides how the request is sent. Each method stands for one of `instructor`'s core modes: every `*_tools` method is tool calling, and so is `instructor/openai_structured_outputs`, which sends OpenAI a non-strict tool schema; `instructor/mistral_structured_outputs` or `instructor/openrouter_structured_outputs` is a JSON-schema response format. So a method named after another provider still works through an OpenAI-compatible SDK.
-One method keeps a behaviour of its own on the `anthropic` and `bedrock_anthropic` SDKs: tool calling forces the model to call the response tool, and `instructor/anthropic_reasoning_tools` leaves that choice to the model instead, steering it to the tool with a system line, for a model that refuses a forced tool choice.
+One method keeps a behaviour of its own on the `anthropic` and `bedrock_anthropic` SDKs: tool calling forces the model to call the response tool, and `instructor/anthropic_reasoning_tools` leaves that choice to the model instead, steering it to the tool with a system line, for a model that refuses a forced tool choice. A structured call with thinking on, manual or adaptive, makes that same request on any Anthropic tool method, since a forced choice cannot carry thinking; so `instructor/anthropic_reasoning_tools` is only needed for a model that refuses a forced choice even without thinking.
+
+On the `mistral` SDK, a reasoning setting on a structured output needs `instructor/mistral_tools`: a reasoning reply carries its answer beside a thinking chunk, which `instructor/mistral_structured_outputs` cannot parse, so that method refuses one.
The `google` backend uses `instructor/genai_structured_outputs`, Gemini's native JSON output. `instructor/genai_tools` works on it too: Gemini returns the function-call arguments as plain values, so pipelex validates them in pydantic's lax mode, where a string reaches an enum field as its member.
+#### Thinking budget bounds
+
+A model that thinks on a token budget (`thinking_mode = "manual"` on the `anthropic`, `bedrock_anthropic` and `google` SDKs) may declare the range of budgets its provider accepts, as two valued constraints, both inclusive and both optional:
+
+```toml
+# google.toml
+["gemini-2.5-flash-lite"]
+model_id = "gemini-2.5-flash-lite"
+valued_constraints = { min_thinking_budget = 512, max_thinking_budget = 24576 }
+```
+
+A budget resolved from a reasoning effort, or set explicitly, is held within that range, and a `max_tokens` too small to hold the minimum beside the quarter kept for the answer is refused before the call is sent. The kit's Anthropic models declare Anthropic's minimum of 1,024 tokens, and its Gemini 2.5 models declare their ranges; a model that declares neither gets its budget fitted inside `max_tokens` alone.
+
+On the `google` SDK, a reasoning effort of `none` is sent as a thinking budget of 0, which turns thinking off. A Gemini model that always thinks refuses that budget, so it lists the `thinking_cannot_be_disabled` constraint, and `none` on it is refused before the call is sent. The kit declares it on Gemini 2.5 Pro, Gemini 3.1 Pro and the `-latest` aliases that currently resolve to a model that always thinks:
+
+```toml
+# google.toml
+["gemini-3.1-pro"]
+model_id = "gemini-3.1-pro-preview"
+listed_constraints = ["thinking_cannot_be_disabled"]
+```
+
#### Sending extra request headers per model
A model table may carry keys beyond the model-spec fields. A key shaped like a request header — it contains a hyphen and its value is a string — is sent to the provider **as an HTTP request header** on each call to that model; this is how, for example, the Portkey backend routes each model to its upstream provider:
diff --git a/docs/under-the-hood/reasoning-controls.md b/docs/under-the-hood/reasoning-controls.md
index 589bb5891..2e1ccd428 100644
--- a/docs/under-the-hood/reasoning-controls.md
+++ b/docs/under-the-hood/reasoning-controls.md
@@ -97,7 +97,7 @@ model = { model = "gpt-5.4", temperature = 0.1, reasoning_effort = "max" }
```
!!! note "Structured Generation"
- Reasoning parameters are not supported for structured generation. See [Structured Generation](#structured-generation) for details.
+ Reasoning parameters apply to structured outputs as they do to text. See [Structured Generation](#structured-generation) for how each provider carries them.
!!! tip "Test Coverage"
These examples are exercised in `tests/integration/pipelex/cogt/test_llm_reasoning.py`.
@@ -127,7 +127,7 @@ The `ThinkingMode` enum (`pipelex/cogt/llm/thinking_mode.py`) defines how a mode
| Mode | Meaning |
|------|---------|
| `none` | Model does not support reasoning. Attempting to use reasoning params raises `LLMCapabilityError`. |
-| `manual` | Pipelex translates effort to a provider-specific value (token budget, effort string, or prompt mode). |
+| `manual` | Pipelex translates effort to a provider-specific value (a token budget or an effort string). |
| `adaptive` | The provider's SDK dynamically adjusts reasoning depth. Only Anthropic and Google (Gemini 3) support this today. |
Each model spec in the backend TOML files declares a `thinking_mode`. This is a required field on `InferenceModelSpec` — models without reasoning capabilities set `thinking_mode = "none"` (or inherit it from `[defaults]`).
@@ -157,7 +157,7 @@ flowchart TB
C -->|OpenAI Responses| D2["_resolve_reasoning()<br>-> Reasoning dict"]
C -->|Anthropic| E["_build_thinking_params()<br>-> _ThinkingParams"]
C -->|Google| F["_build_thinking_config()<br>-> ThinkingConfig"]
- C -->|Mistral| G["_resolve_prompt_mode()<br>-> prompt_mode"]
+ C -->|Mistral| G["_resolve_reasoning_effort()<br>-> reasoning_effort"]
C -->|Bedrock (aiobotocore)| H["_validate_no_reasoning_params()<br>-> LLMCapabilityError if set"]
```
@@ -228,12 +228,12 @@ Both modes first check `inference.llm.anthropic.effort_to_level_map` to gate rea
**ADAPTIVE mode** uses `{"type": "adaptive"}` with an `OutputConfigParam(effort=...)` where the effort value comes from the level map.
-**MANUAL mode** resolves effort to a token budget via the `effort_to_budget_maps` config (keyed by the worker-owned reasoning family — `"anthropic"` for the Anthropic worker), then sends `{"type": "enabled", "budget_tokens": N}`. The budget is capped to `min(budget, max_tokens - 1)` to satisfy Anthropic's API constraint.
+**MANUAL mode** resolves effort to a token budget via the `effort_to_budget_maps` config (keyed by the worker-owned reasoning family — `"anthropic"` for the Anthropic worker), then sends `{"type": "enabled", "budget_tokens": N}`. The budget is fitted inside `max_tokens` as described in [Fitting a Budget Inside max_tokens](#fitting-a-budget-inside-max_tokens): a quarter of `max_tokens` is kept for the answer, and a budget below Anthropic's minimum of 1,024 tokens, which the kit's Anthropic models declare as their `min_thinking_budget`, is raised to it.
-**`reasoning_budget`** (explicit) always uses `{"type": "enabled", "budget_tokens": N}` regardless of thinking mode. The same `min(budget, max_tokens - 1)` cap is applied.
+**`reasoning_budget`** (explicit) uses `{"type": "enabled", "budget_tokens": N}` on a manual-mode model, fitted the same way. An adaptive-mode model refuses an explicit budget with `LLMCapabilityError`, since adaptive thinking takes an effort.
!!! note
- `MINIMAL` and `LOW` both map to `"low"` in the level map. In ADAPTIVE mode they produce identical behavior. In MANUAL mode they are differentiated by the budget map (512 vs 1024 tokens). This matches the granularity that each mode supports.
+ `MINIMAL` and `LOW` both map to `"low"` in the level map. In ADAPTIVE mode they produce identical behavior. In MANUAL mode the budget map gives `MINIMAL` 512 tokens, which the 1,024 minimum raises to the budget `LOW` has, so they also behave alike there.
When thinking is active, `temperature` is suppressed (Anthropic requires `temperature=1` or omission with thinking).
@@ -252,7 +252,7 @@ xhigh = "high"
max = "high"
```
-If the level map returns `"disabled"` (e.g., for `NONE` effort), thinking is disabled with `thinking_budget=0` regardless of mode.
+If the level map returns `"disabled"` (e.g., for `NONE` effort), thinking is disabled with `thinking_budget=0` regardless of mode. Some Gemini models always think and refuse a budget of 0 with a 400 error, among them Gemini 2.5 Pro and 3.1 Pro: such a model lists the `thinking_cannot_be_disabled` constraint in its backend file, and `NONE` on it is refused with an `LLMCapabilityError` before the call is sent.
!!! note
`MAX` maps to `"high"` because Google's `ThinkingLevel` enum tops out at `HIGH` — there is no higher level.
@@ -274,7 +274,7 @@ If the level map returns `"disabled"` (e.g., for `NONE` effort), thinking is dis
| `XHIGH` | `32768` |
| `MAX` | `65536` |
-**`reasoning_budget`** (explicit) passes through directly as `thinking_budget`. When `max_tokens` is known, the budget is capped to `min(budget, max_tokens - 1)`.
+**`reasoning_budget`** (explicit) is sent as `thinking_budget`, fitted as described in [Fitting a Budget Inside max_tokens](#fitting-a-budget-inside-max_tokens): a quarter of `max_tokens` is kept for the answer when the request sets one, and the budget is held within the range the model accepts, which each Gemini 2.5 model declares in its spec (`gemini-2.5-pro` takes 128 to 32,768, `gemini-2.5-flash` at most 24,576 and `gemini-2.5-flash-lite` 512 to 24,576). The same fitting applies to a budget resolved from an effort, so `MAX` effort's 65,536 tokens are cut to the model's maximum even when no `max_tokens` is set.
!!! note
An explicit `reasoning_budget` always produces a `thinking_budget`-based config, even when the model uses `thinking_mode = "adaptive"`. This overrides the `thinking_level` approach that adaptive mode normally uses.
@@ -301,8 +301,10 @@ max = "reasoning"
| ReasoningEffort | Mistral behavior |
|-----------------|-----------------|
-| `NONE` | `prompt_mode` omitted (no reasoning) |
-| `MINIMAL` through `MAX` | `prompt_mode = "reasoning"` |
+| `NONE` | `reasoning_effort` omitted (no reasoning) |
+| `MINIMAL` through `MAX` | `reasoning_effort = "high"` |
+
+Mistral's reasoning models have one reasoning setting, on or off: their `reasoning_effort` parameter accepts only `"none"` and `"high"`, so the `reasoning` level turns reasoning on as `reasoning_effort = "high"`. The older `prompt_mode = "reasoning"` parameter is refused by every current Mistral model.
Mistral does not support `reasoning_budget` or `thinking_mode = "adaptive"`. Both raise `LLMCapabilityError`.
@@ -324,6 +326,8 @@ Gateway and proxy backends (Azure OpenAI, Portkey, BlackBoxAI, OpenRouter) route
- **BlackBoxAI** uses `sdk = "openai"` or `"openai_responses"`. Proxied models follow OpenAI reasoning semantics.
- **OpenRouter** uses `sdk = "openai"` for its language models, which declare `thinking_mode = "none"`, so the kit's OpenRouter models take no reasoning controls.
+Whether a server behind the OpenAI chat-completions SDK accepts a reasoning effort beside the function tool a structured output uses is that server's decision; see [Structured Generation](#structured-generation).
+
!!! note
When a provider's models are accessed through a gateway using an OpenAI-compatible SDK, the reasoning controls follow OpenAI semantics (`reasoning_effort`) rather than the provider's native semantics. For native reasoning controls (e.g., Anthropic thinking budgets, Google thinking levels), use the direct provider backend.
@@ -365,6 +369,16 @@ The map is keyed by the reasoning family each worker owns (`reasoning_budget_fam
The budget is resolved at runtime via `LLMConfig.get_reasoning_budget()` (`pipelex/cogt/config_cogt.py`).
+### Fitting a Budget Inside max_tokens
+
+Anthropic and Gemini count the thinking budget against `max_tokens`, so a budget that fills it leaves the answer, a tool call on a structured output, nothing to be written in. Every manual budget, resolved from an effort or set explicitly, is therefore fitted by `fit_thinking_budget()` (`pipelex/cogt/llm/thinking_budget.py`) before it is sent:
+
+- The budget is held within the range the provider accepts for the model, which the model's spec declares as two valued constraints, `min_thinking_budget` and `max_thinking_budget`, both inclusive and both optional. The kit's Anthropic models declare Anthropic's minimum of 1,024, and its Gemini 2.5 models declare their ranges. A server reached through the `anthropic` SDK that is not Anthropic, such as MiniMax, declares no minimum and gets none.
+- When the request sets `max_tokens`, a quarter of it, and never less than one token, is reserved for the answer, so the budget is cut to at most `max_tokens` minus that reserve.
+- When `max_tokens` cannot hold the model's minimum beside the reserve, or a single thinking token for a model that declares no minimum, the call is refused with an `LLMCapabilityError` naming `max_tokens`, the reserve and the minimum, rather than sent to fail at the provider.
+
+On the Anthropic structured path, `max_tokens` is first capped by the number of tokens the structured-output timeout (`inference.llm.anthropic.structured_output_timeout_seconds`) leaves time to generate, so a `MAX` effort's budget is fitted inside that cap rather than inside the model's own output limit.
+
---
## Backend TOML Configuration
@@ -400,9 +414,19 @@ thinking_mode = "none"
## Structured Generation
-Reasoning parameters (`reasoning_effort` and `reasoning_budget`) are not supported for structured generation (`_gen_object`). If either parameter is set when calling structured generation, an `LLMCapabilityError` is raised with the message "does not support reasoning parameters for structured generation".
+Reasoning parameters apply to structured generation (`_gen_object`) exactly as they do to text: each worker resolves them with the same helper its text path uses, so a model refuses on a structured output only what it refuses on text, with the same message. A pipe whose model setting carries a reasoning effort, a deck preset such as `$deep-analysis` included, generates its structured output with that effort when it names no `model_to_structure`.
+
+How each provider carries the setting beside its structuring path:
+
+- **OpenAI Responses** (`openai_responses`, `azure_openai_responses`, `portkey_responses` and the hosted gateway) sends `reasoning={"effort": …}` beside the function tool and drops `temperature`, as on text.
+- **OpenAI chat completions** sends `reasoning_effort` beside the tool or JSON schema and drops `temperature`. Whether the server accepts a reasoning effort beside a function tool is its own decision: OpenAI's own chat-completions endpoint refuses it on GPT-5 models ("Function tools with reasoning_effort are not supported"), and accepts it with the `instructor/json_schema` structure method or on the Responses SDK, which every OpenAI model in the kit uses. Gemini's OpenAI-compatible endpoint accepts it beside a function tool.
+- **Anthropic** sends `thinking` (and `output_config` for adaptive models). On the tool structure methods it leaves the tool choice to the model whenever thinking is on, with parallel tool use disabled and a system line steering it to the tool call. A forced tool choice cannot carry thinking: Anthropic refuses it beside manual thinking, and under adaptive thinking it accepts it and the model silently does not think. The same request is what `instructor/anthropic_reasoning_tools` sends without thinking, for a model that refuses a forced choice outright. `instructor/anthropic_json` defines no tool, so its request carries thinking and nothing about a tool choice.
+- **Google** passes the same `ThinkingConfig` as on text, under both `instructor/genai_structured_outputs` and `instructor/genai_tools`.
+- **Mistral** sends `reasoning_effort` beside its tool call, as on text. A reasoning reply carries its answer in a list of content chunks beside the thinking, which instructor's JSON parsers cannot read, so a model whose structure method is `instructor/mistral_structured_outputs` refuses a reasoning setting on a structured output with an `LLMCapabilityError` naming `instructor/mistral_tools`.
+
+Bedrock native models (`bedrock_aioboto`) refuse every reasoning parameter on text, and have no structured path at all: their worker refuses every structured output.
-This applies to all providers (OpenAI, Anthropic, Google, Mistral). Bedrock native models already reject all reasoning parameters before reaching `_gen_object`.
+Reasoning spends the same output budget as the answer, so a structured output on a high effort needs room for both; see [Fitting a Budget Inside max_tokens](#fitting-a-budget-inside-max_tokens) for the budget-based providers.
## NONE Semantics
@@ -411,7 +435,7 @@ The behavior of `ReasoningEffort.NONE` varies by provider:
- **OpenAI**: Sends `reasoning_effort="none"` to the API, which is a valid API value that minimizes reasoning.
- **Anthropic**: Disabled via `effort_to_level_map` gate — no `thinking` parameter is sent.
- **Google**: Disabled via `effort_to_level_map` gate, sets `thinking_budget=0`.
-- **Mistral**: Omits `prompt_mode` (no reasoning).
+- **Mistral**: Omits `reasoning_effort` (no reasoning).
---
@@ -425,7 +449,9 @@ All reasoning-related errors use `LLMCapabilityError` (`pipelex/cogt/exceptions.
| `reasoning_budget` on a provider that doesn't support it | "does not support reasoning_budget" |
| `thinking_mode = "adaptive"` on OpenAI or Mistral | "adaptive ... not supported" |
| Any reasoning param on Bedrock (aiobotocore) models | "does not support reasoning parameters" |
-| Reasoning params during structured generation | "does not support reasoning parameters for structured generation" |
+| A manual budget that `max_tokens` cannot hold beside the answer reserve, under the model's `min_thinking_budget` | "cannot think within max_tokens" |
+| `NONE` effort on a Gemini model that lists `thinking_cannot_be_disabled` | "cannot turn thinking off" |
+| A reasoning setting on a Mistral structured output whose structure method is not `instructor/mistral_tools` | "cannot reason on a structured output" |
| Both `reasoning_effort` and `reasoning_budget` set | `ValueError` / `LLMSettingValueError` (mutual exclusivity) |
---
@@ -439,16 +465,17 @@ All reasoning-related errors use `LLMCapabilityError` (`pipelex/cogt/exceptions.
| `pipelex/cogt/llm/reasoning_config_base.py` | Shared helpers: `EffortToLevelMap`, `validate_effort_to_level_map()`, `get_reasoning_level_str()` |
| `pipelex/cogt/llm/llm_setting.py` | `LLMSetting` with reasoning fields and `make_llm_job_params()` |
| `pipelex/cogt/config_cogt.py` | `LLMConfig` with `get_reasoning_budget()` and effort-to-budget map validation |
+| `pipelex/cogt/llm/thinking_budget.py` | `fit_thinking_budget()`: the answer reserve and the model's budget bounds |
| `pipelex/providers/openai/openai_config.py` | `OpenAIConfig` with `get_reasoning_level()` returning `ChatCompletionReasoningEffort \| None` |
| `pipelex/providers/anthropic/anthropic_config.py` | `AnthropicConfig` with `get_reasoning_level()` returning `AnthropicEffortLevel \| None` |
| `pipelex/providers/google/google_config.py` | `GoogleConfig` with `get_reasoning_level()` returning `genai_types.ThinkingLevel \| None` |
-| `pipelex/providers/mistral/mistral_config.py` | `MistralConfig` with `get_reasoning_level()` returning `MistralPromptMode \| None` |
-| `pipelex/cogt/model_backends/model_spec.py` | `InferenceModelSpec.thinking_mode` field |
+| `pipelex/providers/mistral/mistral_config.py` | `MistralConfig` with `get_reasoning_level()` returning Mistral's `ReasoningEffort \| None` |
+| `pipelex/cogt/model_backends/model_spec.py` | `InferenceModelSpec.thinking_mode` field, and the `min_thinking_budget` and `max_thinking_budget` bounds read from its valued constraints |
| `pipelex/providers/openai/openai_completions_llm_worker.py` | OpenAI Completions reasoning resolution |
| `pipelex/providers/openai/openai_responses_llm_worker.py` | OpenAI Responses reasoning resolution |
| `pipelex/providers/anthropic/anthropic_llm_worker.py` | Anthropic thinking params builder |
| `pipelex/providers/google/google_llm_worker.py` | Google thinking config builder |
-| `pipelex/providers/mistral/mistral_llm_worker.py` | Mistral prompt mode resolution |
+| `pipelex/providers/mistral/mistral_llm_worker.py` | Mistral reasoning effort resolution |
| `pipelex/providers/bedrock/bedrock_llm_worker.py` | Bedrock reasoning validation |
| `pipelex/pipelex.toml` | Default effort-to-budget maps and effort-to-level maps |
diff --git a/pipelex/cogt/llm/llm_worker_abstract.py b/pipelex/cogt/llm/llm_worker_abstract.py
index a3c3ee9ee..8fdfbbf97 100644
--- a/pipelex/cogt/llm/llm_worker_abstract.py
+++ b/pipelex/cogt/llm/llm_worker_abstract.py
@@ -417,11 +417,6 @@ class LLMWorkerAbstract(InferenceWorkerAbstract, ABC):
self._check_vision_support(llm_job=llm_job)
self._check_document_support(llm_job=llm_job)
- def _validate_no_reasoning_for_structured_gen(self, job_params: LLMJobParams):
- if job_params.reasoning_effort is not None or job_params.reasoning_budget is not None:
- msg = f"Model '{self.inference_model.desc}' does not support reasoning parameters for structured generation"
- raise LLMCapabilityError(msg)
-
def _check_vision_support(self, llm_job: LLMJob):
if llm_job.llm_prompt.user_images:
if not self.inference_model.is_vision_supported:
diff --git a/pipelex/cogt/llm/thinking_budget.py b/pipelex/cogt/llm/thinking_budget.py
new file mode 100644
index 000000000..571bb1f6a
--- /dev/null
+++ b/pipelex/cogt/llm/thinking_budget.py
@@ -0,0 +1,51 @@
+"""Fitting a manual thinking budget inside the bounds the model accepts and the output limit of the request that carries it.
+
+Anthropic and Gemini count the thinking budget against `max_tokens`, so a budget that fills it leaves the
+answer, a tool call on a structured output, nothing to be written in. The budget is cut to leave a quarter of
+`max_tokens` for the answer, and held within the range the provider accepts for the model, which its spec
+declares as the `min_thinking_budget` and `max_thinking_budget` valued constraints: Anthropic refuses a
+`budget_tokens` below 1,024, and each Gemini 2.5 model has a range of its own.
+"""
+
+from pipelex.cogt.exceptions import LLMCapabilityError
+
+# The share of max_tokens kept for the answer is 1 / THINKING_ANSWER_RESERVE_DIVISOR
+THINKING_ANSWER_RESERVE_DIVISOR = 4
+
+
+def fit_thinking_budget(*, budget: int, max_tokens: int | None, min_budget: int | None, max_budget: int | None, model_desc: str) -> int:
+ """Return the thinking budget to send, given the budget asked for, the request's max_tokens and the model's bounds.
+
+ Args:
+ budget: The thinking budget resolved from the reasoning effort, or the explicit reasoning budget.
+ max_tokens: The request's output limit, which the thinking budget counts against, or None when the request sets none.
+ min_budget: The smallest budget the provider accepts for the model, or None when it declares none.
+ max_budget: The largest budget the provider accepts for the model, or None when it declares none.
+ model_desc: The model's description, for the error message.
+
+ Returns:
+ The budget, cut to max_budget and to leave a quarter of max_tokens (at least one token) for the answer, and raised to min_budget.
+
+ Raises:
+ LLMCapabilityError: When max_tokens cannot hold min_budget, or a single thinking token when the model declares no minimum,
+ beside the answer reserve.
+
+ """
+ fitted_budget = budget
+ if max_budget is not None:
+ fitted_budget = min(fitted_budget, max_budget)
+ if max_tokens is not None:
+ answer_reserve = max(1, max_tokens // THINKING_ANSWER_RESERVE_DIVISOR)
+ ceiling = max_tokens - answer_reserve
+ smallest_budget = min_budget if min_budget is not None else 1
+ if ceiling < smallest_budget:
+ msg = (
+ f"Model '{model_desc}' cannot think within max_tokens={max_tokens}: after reserving {answer_reserve} tokens for the answer, "
+ f"{ceiling} remain for thinking, below the smallest thinking budget of {smallest_budget}. "
+ f"Raise max_tokens or remove the reasoning setting."
+ )
+ raise LLMCapabilityError(msg)
+ fitted_budget = min(fitted_budget, ceiling)
+ if min_budget is not None:
+ fitted_budget = max(fitted_budget, min_budget)
+ return fitted_budget
diff --git a/pipelex/cogt/model_backends/constraints.py b/pipelex/cogt/model_backends/constraints.py
index f05925dc9..94f2174e5 100644
--- a/pipelex/cogt/model_backends/constraints.py
+++ b/pipelex/cogt/model_backends/constraints.py
@@ -5,7 +5,12 @@ class ListedConstraint(StrEnum):
TEMPERATURE_MUST_BE_MULTIPLIED_BY_2 = "temperature_must_be_multiplied_by_2"
TEMPERATURE_UNSUPPORTED = "temperature_unsupported"
MAX_TOKENS_MUST_BE_HIGH_ENOUGH = "max_tokens_must_be_high_enough"
+ # The model always thinks: its provider refuses a request that turns thinking off
+ THINKING_CANNOT_BE_DISABLED = "thinking_cannot_be_disabled"
class ValuedConstraint(StrEnum):
FIXED_TEMPERATURE = "fixed_temperature"
+ # The bounds of the manual thinking budget the provider accepts for the model, both inclusive
+ MIN_THINKING_BUDGET = "min_thinking_budget"
+ MAX_THINKING_BUDGET = "max_thinking_budget"
diff --git a/pipelex/cogt/model_backends/model_spec.py b/pipelex/cogt/model_backends/model_spec.py
index fc062a491..ed45be13c 100644
--- a/pipelex/cogt/model_backends/model_spec.py
+++ b/pipelex/cogt/model_backends/model_spec.py
@@ -1,6 +1,7 @@
from typing import TYPE_CHECKING, Any, Final
-from pydantic import Field
+from pydantic import Field, model_validator
+from typing_extensions import Self
from pipelex.cogt.img_gen.img_gen_model_rules import ImgGenModelRules
from pipelex.cogt.llm.structured_output import StructureMethod
@@ -42,6 +43,34 @@ class InferenceModelSpec(ConfigModel):
rules: ImgGenModelRules | None = None
endpoint_path: str | None = None
+ @model_validator(mode="after")
+ def validate_thinking_budget_bounds(self) -> Self:
+ bounds: dict[ValuedConstraint, int] = {}
+ for constraint in (ValuedConstraint.MIN_THINKING_BUDGET, ValuedConstraint.MAX_THINKING_BUDGET):
+ value = self.valued_constraints.get(constraint)
+ if value is None:
+ continue
+ if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+ msg = f"Model '{self.name}' declares {constraint}={value!r}, which must be a non-negative integer"
+ raise ValueError(msg)
+ bounds[constraint] = value
+ min_budget = bounds.get(ValuedConstraint.MIN_THINKING_BUDGET)
+ max_budget = bounds.get(ValuedConstraint.MAX_THINKING_BUDGET)
+ if min_budget is not None and max_budget is not None and min_budget > max_budget:
+ msg = f"Model '{self.name}' declares min_thinking_budget={min_budget} above max_thinking_budget={max_budget}"
+ raise ValueError(msg)
+ return self
+
+ @property
+ def min_thinking_budget(self) -> int | None:
+ """The smallest manual thinking budget the provider accepts for this model, when it declares one."""
+ return self.valued_constraints.get(ValuedConstraint.MIN_THINKING_BUDGET)
+
+ @property
+ def max_thinking_budget(self) -> int | None:
+ """The largest manual thinking budget the provider accepts for this model, when it declares one."""
+ return self.valued_constraints.get(ValuedConstraint.MAX_THINKING_BUDGET)
+
@property
def tag(self) -> str:
return rf"{self.name} → \[{self.sdk}@{self.backend_name}]({self.model_id})"
diff --git a/pipelex/kit/configs/inference/backends/anthropic.toml b/pipelex/kit/configs/inference/backends/anthropic.toml
index dbe8fd8cf..0e57a6feb 100644
--- a/pipelex/kit/configs/inference/backends/anthropic.toml
+++ b/pipelex/kit/configs/inference/backends/anthropic.toml
@@ -25,6 +25,7 @@ model_type = "llm"
sdk = "anthropic"
structure_method = "instructor/anthropic_tools"
thinking_mode = "manual"
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
################################################################################
# LANGUAGE MODELS
diff --git a/pipelex/kit/configs/inference/backends/bedrock.toml b/pipelex/kit/configs/inference/backends/bedrock.toml
index e876def7c..6f75eceb3 100644
--- a/pipelex/kit/configs/inference/backends/bedrock.toml
+++ b/pipelex/kit/configs/inference/backends/bedrock.toml
@@ -72,6 +72,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 3.0, output = 15.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
[claude-4-opus]
@@ -82,6 +83,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 3.0, output = 15.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
["claude-4.1-opus"]
@@ -92,6 +94,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 3.0, output = 15.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
["claude-4.5-sonnet"]
@@ -102,6 +105,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 3.0, output = 15.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
["claude-4.5-haiku"]
@@ -112,6 +116,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 1.0, output = 5.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
["claude-4.5-opus"]
@@ -122,6 +127,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 5.0, output = 25.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "manual"
["claude-4.6-sonnet"]
@@ -132,6 +138,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 3.0, output = 15.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "adaptive"
["claude-4.6-opus"]
@@ -142,6 +149,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 5.0, output = 25.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "adaptive"
# --- Claude 4.7 Series --------------------------------------------------------
@@ -153,6 +161,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 5.0, output = 25.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "adaptive"
listed_constraints = ["temperature_unsupported"]
@@ -165,5 +174,6 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 100
costs = { input = 5.0, output = 25.0 }
+valued_constraints = { min_thinking_budget = 1024 } # Anthropic refuses a smaller budget_tokens
thinking_mode = "adaptive"
listed_constraints = ["temperature_unsupported"]
diff --git a/pipelex/kit/configs/inference/backends/google.toml b/pipelex/kit/configs/inference/backends/google.toml
index 69d8ddf68..7552d99c9 100644
--- a/pipelex/kit/configs/inference/backends/google.toml
+++ b/pipelex/kit/configs/inference/backends/google.toml
@@ -37,6 +37,9 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 1.25, output = 10.0 }
+valued_constraints = { min_thinking_budget = 128, max_thinking_budget = 32768 }
+# Gemini refuses a thinking budget of 0 for this model
+listed_constraints = ["thinking_cannot_be_disabled"]
["gemini-2.5-flash"]
model_id = "gemini-2.5-flash"
@@ -44,6 +47,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 0.30, output = 2.50 }
+valued_constraints = { max_thinking_budget = 24576 }
["gemini-2.5-flash-lite"]
model_id = "gemini-2.5-flash-lite"
@@ -51,6 +55,7 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 0.10, output = 0.40 }
+valued_constraints = { min_thinking_budget = 512, max_thinking_budget = 24576 }
# --- Gemini 3.0 Series ----------------------------------------
["gemini-3.0-flash"]
@@ -76,6 +81,8 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 2, output = 12.0 }
+# Gemini refuses a thinking budget of 0 for this model
+listed_constraints = ["thinking_cannot_be_disabled"]
thinking_mode = "adaptive"
# --- Gemini 3.5 Series ----------------------------------------
@@ -93,6 +100,8 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 1.25, output = 10.0 }
+# Gemini refuses a thinking budget of 0 for this model: the alias resolved to gemini-3.1-pro-preview, which always thinks, in October 2026
+listed_constraints = ["thinking_cannot_be_disabled"]
thinking_mode = "adaptive"
["gemini-flash-latest"]
@@ -107,6 +116,8 @@ inputs = ["text", "images", "pdf"]
outputs = ["text", "structured"]
max_prompt_images = 3000
costs = { input = 0.10, output = 0.40 }
+# Gemini refuses a thinking budget of 0 for this model: the alias resolved to gemini-3.5-flash-lite, which always thinks, in October 2026
+listed_constraints = ["thinking_cannot_be_disabled"]
thinking_mode = "adaptive"
################################################################################
diff --git a/pipelex/migration/goldens/inference-backend/[email protected] b/pipelex/migration/goldens/inference-backend/[email protected]
index fb9e10a20..fdddaf448 100644
--- a/pipelex/migration/goldens/inference-backend/[email protected]
+++ b/pipelex/migration/goldens/inference-backend/[email protected]
@@ -39,7 +39,8 @@
"enum_members": [
"max_tokens_must_be_high_enough",
"temperature_must_be_multiplied_by_2",
- "temperature_unsupported"
+ "temperature_unsupported",
+ "thinking_cannot_be_disabled"
],
"open_node": false
},
diff --git a/pipelex/providers/anthropic/anthropic_llm_worker.py b/pipelex/providers/anthropic/anthropic_llm_worker.py
index e9e1ab346..f3aaadb95 100644
--- a/pipelex/providers/anthropic/anthropic_llm_worker.py
+++ b/pipelex/providers/anthropic/anthropic_llm_worker.py
@@ -31,6 +31,7 @@ from pipelex.cogt.llm.llm_utils import (
)
from pipelex.cogt.llm.llm_worker_abstract import LLMWorkerAbstract
from pipelex.cogt.llm.structured_output import StructureMethod
+from pipelex.cogt.llm.thinking_budget import fit_thinking_budget
from pipelex.cogt.llm.thinking_mode import ThinkingMode
from pipelex.cogt.model_backends.constraints import ListedConstraint
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
@@ -189,7 +190,13 @@ class AnthropicLLMWorker(LLMWorkerAbstract):
family=self.reasoning_budget_family,
effort=effort,
)
- safe_budget = min(budget, max_tokens - 1)
+ safe_budget = fit_thinking_budget(
+ budget=budget,
+ max_tokens=max_tokens,
+ min_budget=self.inference_model.min_thinking_budget,
+ max_budget=self.inference_model.max_thinking_budget,
+ model_desc=self.inference_model.desc,
+ )
log.verbose(f"Anthropic manual thinking with budget_tokens={safe_budget} (from effort={effort})")
thinking_config = {"type": "enabled", "budget_tokens": safe_budget}
return _ThinkingParams(
@@ -217,7 +224,13 @@ class AnthropicLLMWorker(LLMWorkerAbstract):
)
raise LLMCapabilityError(msg)
case ThinkingMode.MANUAL:
- safe_budget = min(budget, max_tokens - 1)
+ safe_budget = fit_thinking_budget(
+ budget=budget,
+ max_tokens=max_tokens,
+ min_budget=self.inference_model.min_thinking_budget,
+ max_budget=self.inference_model.max_thinking_budget,
+ model_desc=self.inference_model.desc,
+ )
log.verbose(f"Anthropic thinking with explicit budget_tokens={safe_budget}")
thinking_config: ThinkingConfigParam = {"type": "enabled", "budget_tokens": safe_budget}
return _ThinkingParams(
@@ -329,19 +342,29 @@ class AnthropicLLMWorker(LLMWorkerAbstract):
kwargs["extra_body"] = extra_body
return kwargs
- def _structure_method_kwargs(self) -> dict[str, Any]:
- """What the structured call sends, beyond what instructor's mode sets, for the model's structure method.
-
- instructor resolves `anthropic_reasoning_tools` to its core tool mode, which forces `tool_choice` onto
- the response tool unless thinking is on, and thinking never is for a structured call. A model that
- refuses a forced tool choice, Fable 5.1 among them, names that method to get the request instructor used
- to make for it: `tool_choice` left on auto, with a system line steering the model to the tool call.
- instructor leaves a `tool_choice` it is given as it is, and sends a `system` it is given ahead of the prompt's.
+ def _structure_method_kwargs(self, *, thinking_params: _ThinkingParams) -> dict[str, Any]:
+ """What the structured call sends, beyond what instructor's mode sets, for the model's structure method and thinking.
+
+ instructor's tool mode forces `tool_choice` onto the response tool unless the request enables manual
+ thinking, and Anthropic refuses a forced choice beside thinking. instructor does not recognise adaptive
+ thinking, under which Anthropic accepts a forced choice and the model silently does not think. So whenever
+ thinking is on, manual or adaptive, the request leaves `tool_choice` on auto with a system line steering the
+ model to the tool call, the request instructor makes for manual thinking. A model that refuses a forced tool
+ choice even without thinking, Fable 5.1 among them, names `anthropic_reasoning_tools` to get the same request
+ always. instructor leaves a `tool_choice` it is given as it is, and sends a `system` it is given ahead of the
+ prompt's. An auto choice would let the model answer with several tool calls, which instructor's parser
+ refuses, so parallel tool use is disabled as instructor does on a forced choice. All of this concerns the
+ tool modes only: a JSON mode defines no tool, and its request is left as instructor makes it.
"""
- if self.inference_model.structure_method != StructureMethod.INSTRUCTOR_ANTHROPIC_REASONING_TOOLS:
+ from instructor import Mode as InstructorMode # ruff: ignore[import-outside-top-level]
+
+ if self.instructor_for_objects.mode != InstructorMode.TOOLS:
+ return {}
+ is_thinking = thinking_params.thinking is not None
+ if not is_thinking and self.inference_model.structure_method != StructureMethod.INSTRUCTOR_ANTHROPIC_REASONING_TOOLS:
return {}
return {
- "tool_choice": {"type": "auto"},
+ "tool_choice": {"type": "auto", "disable_parallel_tool_use": True},
"system": [{"type": "text", "text": "Return only the tool call and no additional text."}],
}
@@ -353,7 +376,6 @@ class AnthropicLLMWorker(LLMWorkerAbstract):
schema: type[BaseModelTypeVar],
) -> BaseModelTypeVar:
job_params = llm_job.applied_job_params or llm_job.job_params
- self._validate_no_reasoning_for_structured_gen(job_params=job_params)
messages = await AnthropicFactory.make_simple_messages(llm_job=llm_job)
# Get Anthropic-specific config for structured output
@@ -367,6 +389,10 @@ class AnthropicLLMWorker(LLMWorkerAbstract):
requested_max_tokens = job_params.max_tokens or self.default_max_tokens
effective_max_tokens = min(requested_max_tokens, safe_max_tokens)
+ # The thinking budget is fitted against the max_tokens this call actually sends
+ thinking_params = self._build_thinking_params(job_params=job_params, max_tokens=effective_max_tokens)
+ log.verbose(thinking_params, title="Thinking params")
+
# Deferred import: avoid pulling heavy SDK at module-load time
from instructor.core import InstructorRetryException # ruff: ignore[import-outside-top-level]
@@ -381,10 +407,12 @@ class AnthropicLLMWorker(LLMWorkerAbstract):
# SDK client floor (Tier 1) alone.
max_retries=make_instructor_schema_retrying(max_attempts=llm_job.job_config.schema_reask_max_attempts),
model=self.inference_model.model_id,
- temperature=omit if temperature_unsupported else job_params.temperature,
+ temperature=omit if (thinking_params.suppress_temperature or temperature_unsupported) else job_params.temperature,
max_tokens=effective_max_tokens,
+ thinking=thinking_params.thinking or omit,
+ output_config=thinking_params.output_config or omit,
timeout=float(timeout_seconds), # Explicit timeout disables SDK's long-request protection
- **self._structure_method_kwargs(),
+ **self._structure_method_kwargs(thinking_params=thinking_params),
**self._request_extras_kwargs(llm_job=llm_job, output_desc=schema.__name__),
)
except InstructorRetryException as instructor_exc:
diff --git a/pipelex/providers/google/google_llm_worker.py b/pipelex/providers/google/google_llm_worker.py
index c55be2a51..8f1efa178 100644
--- a/pipelex/providers/google/google_llm_worker.py
+++ b/pipelex/providers/google/google_llm_worker.py
@@ -1,5 +1,5 @@
import asyncio
-from typing import TYPE_CHECKING, ClassVar, cast
+from typing import TYPE_CHECKING, Any, ClassVar, cast
import httpx
from google.genai import errors as genai_errors
@@ -22,7 +22,9 @@ from pipelex.cogt.llm.llm_job import LLMJob
from pipelex.cogt.llm.llm_job_components import LLMJobParams, ReasoningEffort
from pipelex.cogt.llm.llm_utils import dump_error, dump_kwargs, dump_response_from_structured_gen
from pipelex.cogt.llm.llm_worker_abstract import LLMWorkerAbstract
+from pipelex.cogt.llm.thinking_budget import fit_thinking_budget
from pipelex.cogt.llm.thinking_mode import ThinkingMode
+from pipelex.cogt.model_backends.constraints import ListedConstraint
from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
from pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategory
from pipelex.config import get_config
@@ -148,26 +150,41 @@ class GoogleLLMWorker(LLMWorkerAbstract):
google_level = get_config().inference.llm.google.get_reasoning_level(effort=effort)
if google_level is None:
log.verbose("Google manual thinking disabled (effort mapped to disabled)")
- return genai_types.ThinkingConfig(thinking_budget=0)
+ return self._thinking_off_config()
budget = get_config().inference.llm.get_reasoning_budget(
family=self.reasoning_budget_family,
effort=effort,
)
- if max_tokens is not None:
- budget = min(budget, max_tokens - 1)
+ budget = fit_thinking_budget(
+ budget=budget,
+ max_tokens=max_tokens,
+ min_budget=self.inference_model.min_thinking_budget,
+ max_budget=self.inference_model.max_thinking_budget,
+ model_desc=self.inference_model.desc,
+ )
log.verbose(f"Google manual thinking with thinking_budget={budget} (from effort={effort})")
return genai_types.ThinkingConfig(thinking_budget=budget)
case ThinkingMode.ADAPTIVE:
thinking_level = get_config().inference.llm.google.get_reasoning_level(effort=effort)
if thinking_level is None:
log.verbose("Google adaptive thinking disabled (effort=NONE)")
- return genai_types.ThinkingConfig(thinking_budget=0)
+ return self._thinking_off_config()
log.verbose(f"Google adaptive thinking with thinking_level={thinking_level}")
return genai_types.ThinkingConfig(thinking_level=thinking_level)
case ThinkingMode.NONE:
msg = f"Model '{self.inference_model.desc}' does not support reasoning (thinking_mode=none)"
raise LLMCapabilityError(msg)
+ def _thinking_off_config(self) -> genai_types.ThinkingConfig:
+ """Build the thinking config that turns thinking off, which a model that always thinks refuses with a 400."""
+ if ListedConstraint.THINKING_CANNOT_BE_DISABLED in self.inference_model.listed_constraints:
+ msg = (
+ f"Model '{self.inference_model.desc}' cannot turn thinking off, so it cannot take reasoning_effort 'none': "
+ f"set another reasoning effort, or remove the reasoning setting"
+ )
+ raise LLMCapabilityError(msg)
+ return genai_types.ThinkingConfig(thinking_budget=0)
+
def _build_thinking_config_for_budget(
self,
thinking_mode: ThinkingMode,
@@ -178,8 +195,13 @@ class GoogleLLMWorker(LLMWorkerAbstract):
"""Build thinking config when reasoning_budget is specified."""
match thinking_mode:
case ThinkingMode.MANUAL | ThinkingMode.ADAPTIVE:
- if max_tokens is not None:
- budget = min(budget, max_tokens - 1)
+ budget = fit_thinking_budget(
+ budget=budget,
+ max_tokens=max_tokens,
+ min_budget=self.inference_model.min_thinking_budget,
+ max_budget=self.inference_model.max_thinking_budget,
+ model_desc=self.inference_model.desc,
+ )
log.verbose(f"Google thinking with explicit thinking_budget={budget}")
return genai_types.ThinkingConfig(thinking_budget=budget)
case ThinkingMode.NONE:
@@ -265,7 +287,10 @@ class GoogleLLMWorker(LLMWorkerAbstract):
) -> BaseModelTypeVar:
"""Generate structured output using Google Gemini API with instructor."""
job_params = llm_job.applied_job_params or llm_job.job_params
- self._validate_no_reasoning_for_structured_gen(job_params=job_params)
+ thinking_config = self._build_thinking_config(job_params=job_params, max_tokens=job_params.max_tokens)
+ # instructor's genai handlers read the system prompt only from `system`, and pop it only when it is not
+ # None: a `system=None` reaches `generate_content`, which refuses the unknown keyword
+ system_kwargs: dict[str, Any] = {"system": system_text} if (system_text := llm_job.llm_prompt.system_text) else {}
contents = await GoogleFactory.prepare_user_contents(llm_job.llm_prompt)
# Deferred import: avoid pulling heavy SDK at module-load time
@@ -283,12 +308,14 @@ class GoogleLLMWorker(LLMWorkerAbstract):
model=self.inference_model.model_id,
# instructor's genai handlers build the Google config themselves and read these as
# top-level OpenAI-style kwargs: a `GenerateContentConfig` passed as `generation_config`
- # or `config` is dropped, and the system prompt is read only from `system`.
- system=llm_job.llm_prompt.system_text,
+ # or `config` is dropped.
+ **system_kwargs,
temperature=job_params.temperature,
max_tokens=job_params.max_tokens,
n=1,
strict=self._validates_structured_output_strictly(),
+ # Read into the config the handlers build, as the other kwargs above; None sets no thinking config
+ thinking_config=thinking_config,
)
except InstructorRetryException as instructor_exc:
# instructor wraps SDK exceptions during retries; recover the underlying
diff --git a/pipelex/providers/mistral/mistral_config.py b/pipelex/providers/mistral/mistral_config.py
index 4fb9ccd8e..55eebc9b2 100644
--- a/pipelex/providers/mistral/mistral_config.py
+++ b/pipelex/providers/mistral/mistral_config.py
@@ -1,7 +1,7 @@
from __future__ import annotations
from enum import StrEnum
-from typing import TYPE_CHECKING, cast
+from typing import TYPE_CHECKING
from pydantic import field_validator
@@ -9,14 +9,26 @@ from pipelex.cogt.llm.reasoning_config_base import EffortToLevelMap, get_reasoni
from pipelex.system.configuration.config_model import ConfigModel
if TYPE_CHECKING:
- from mistralai.client.models import MistralPromptMode
+ from mistralai.client.models import ReasoningEffort as MistralReasoningEffort
from pipelex.cogt.llm.llm_job_components import ReasoningEffort
class MistralReasoningLevel(StrEnum):
+ """The level map's vocabulary for Mistral, whose reasoning models have one reasoning setting: on."""
+
REASONING = "reasoning"
+ def as_reasoning_effort(self) -> MistralReasoningEffort:
+ """The `reasoning_effort` value that turns this level on.
+
+ Mistral's reasoning models take `reasoning_effort`, refuse every value but `none` and `high`, and refuse
+ the older `prompt_mode="reasoning"` this level was first sent as.
+ """
+ match self:
+ case MistralReasoningLevel.REASONING:
+ return "high"
+
class MistralConfig(ConfigModel):
effort_to_level_map: EffortToLevelMap
@@ -26,15 +38,14 @@ class MistralConfig(ConfigModel):
def validate_effort_map(cls, value: EffortToLevelMap) -> EffortToLevelMap:
return validate_effort_to_level_map(value, config_name="mistral_config", level_type=MistralReasoningLevel)
- def get_reasoning_level(self, effort: ReasoningEffort) -> MistralPromptMode | None:
- """Resolve a ReasoningEffort to a Mistral MistralPromptMode value.
+ def get_reasoning_level(self, effort: ReasoningEffort) -> MistralReasoningEffort | None:
+ """Resolve a ReasoningEffort to a Mistral `reasoning_effort` value.
Returns:
- The Mistral prompt mode, or None if reasoning is disabled.
+ The Mistral reasoning effort, or None if reasoning is disabled.
"""
level_str = get_reasoning_level_str(effort_to_level_map=self.effort_to_level_map, effort=effort)
if level_str is None:
return None
- mistral_level = MistralReasoningLevel(level_str)
- return cast("MistralPromptMode", mistral_level)
+ return MistralReasoningLevel(level_str).as_reasoning_effort()
diff --git a/pipelex/providers/mistral/mistral_llm_worker.py b/pipelex/providers/mistral/mistral_llm_worker.py
index 869678fb7..9d476d003 100644
--- a/pipelex/providers/mistral/mistral_llm_worker.py
+++ b/pipelex/providers/mistral/mistral_llm_worker.py
@@ -3,7 +3,8 @@ from typing import TYPE_CHECKING, Any
import httpx
from mistralai.client import Mistral
from mistralai.client.errors import MistralError
-from mistralai.client.models import MistralPromptMode, TextChunk, ThinkChunk
+from mistralai.client.models import ReasoningEffort as MistralReasoningEffort
+from mistralai.client.models import TextChunk, ThinkChunk
from mistralai.client.types import UNSET
from typing_extensions import override
@@ -66,14 +67,16 @@ class MistralLLMWorker(LLMWorkerAbstract):
else:
self.instructor_for_objects = from_mistral(client=sdk_instance, use_async=True)
- def _resolve_prompt_mode(self, job_params: LLMJobParams) -> "OptionalNullable[MistralPromptMode]":
- """Resolve reasoning parameters to a Mistral prompt_mode value.
+ def _resolve_reasoning_effort(self, job_params: LLMJobParams) -> "OptionalNullable[MistralReasoningEffort]":
+ """Resolve reasoning parameters to a Mistral reasoning_effort value.
+
+ Mistral's reasoning models take `reasoning_effort` and refuse the older `prompt_mode="reasoning"`.
Args:
job_params: The LLM job parameters containing reasoning_effort/reasoning_budget.
Returns:
- The Mistral prompt_mode value, or UNSET if reasoning is not requested.
+ The Mistral reasoning_effort value, or UNSET if reasoning is not requested.
"""
thinking_mode = self.inference_model.thinking_mode
@@ -81,7 +84,7 @@ class MistralLLMWorker(LLMWorkerAbstract):
if job_params.reasoning_budget is not None:
match thinking_mode:
case ThinkingMode.MANUAL:
- msg = f"Model '{self.inference_model.desc}' does not support reasoning_budget; Mistral uses prompt_mode instead"
+ msg = f"Model '{self.inference_model.desc}' does not support reasoning_budget; Mistral uses reasoning_effort instead"
raise LLMCapabilityError(msg)
case ThinkingMode.ADAPTIVE:
msg = f"Model '{self.inference_model.desc}' has thinking_mode=adaptive which is not supported for Mistral models"
@@ -94,12 +97,12 @@ class MistralLLMWorker(LLMWorkerAbstract):
effort = job_params.reasoning_effort
match thinking_mode:
case ThinkingMode.MANUAL:
- prompt_mode = get_config().inference.llm.mistral.get_reasoning_level(effort=effort)
- if prompt_mode is None:
- log.verbose("Mistral prompt_mode omitted (reasoning disabled)")
+ mistral_effort = get_config().inference.llm.mistral.get_reasoning_level(effort=effort)
+ if mistral_effort is None:
+ log.verbose("Mistral reasoning_effort omitted (reasoning disabled)")
return UNSET
- log.verbose(f"Mistral prompt_mode={prompt_mode}")
- return prompt_mode
+ log.verbose(f"Mistral reasoning_effort={mistral_effort}")
+ return mistral_effort
case ThinkingMode.ADAPTIVE:
msg = f"Model '{self.inference_model.desc}' has thinking_mode=adaptive which is not supported for Mistral models"
raise LLMCapabilityError(msg)
@@ -116,14 +119,14 @@ class MistralLLMWorker(LLMWorkerAbstract):
) -> str:
job_params = llm_job.applied_job_params or llm_job.job_params
messages = await self.mistral_factory.make_simple_messages(llm_job=llm_job)
- prompt_mode = self._resolve_prompt_mode(job_params=job_params)
+ reasoning_effort = self._resolve_reasoning_effort(job_params=job_params)
try:
response: ChatCompletionResponse | None = await self.mistral_client_for_text.chat.complete_async(
messages=messages,
model=self.inference_model.model_id,
temperature=job_params.temperature,
max_tokens=job_params.max_tokens or self.default_max_tokens,
- prompt_mode=prompt_mode,
+ reasoning_effort=reasoning_effort,
)
except (MistralError, httpx.TransportError) as sdk_exc:
metadata = extract_mistral_metadata(sdk_exc)
@@ -223,11 +226,21 @@ class MistralLLMWorker(LLMWorkerAbstract):
schema: type[BaseModelTypeVar],
) -> BaseModelTypeVar:
job_params = llm_job.applied_job_params or llm_job.job_params
- self._validate_no_reasoning_for_structured_gen(job_params=job_params)
- messages = await self.mistral_factory.make_simple_messages_openai_typed(llm_job=llm_job)
- # Deferred import: avoid pulling heavy SDK at module-load time
+ reasoning_effort = self._resolve_reasoning_effort(job_params=job_params)
+ # Deferred imports: avoid pulling heavy SDK at module-load time
+ from instructor import Mode as InstructorMode # ruff: ignore[import-outside-top-level]
from instructor.core import InstructorRetryException # ruff: ignore[import-outside-top-level]
+ if reasoning_effort is not UNSET and self.instructor_for_objects.mode != InstructorMode.TOOLS:
+ # A reasoning reply carries its answer beside a thinking chunk in a list of content chunks, which instructor's
+ # JSON parsers read as one string and refuse on every attempt; its tool mode reads the tool call and validates
+ msg = (
+ f"Model '{self.inference_model.desc}' cannot reason on a structured output with structure method "
+ f"'{self.inference_model.structure_method}': use 'instructor/mistral_tools', or remove the reasoning setting"
+ )
+ raise LLMCapabilityError(msg)
+ messages = await self.mistral_factory.make_simple_messages_openai_typed(llm_job=llm_job)
+
try:
result_object, completion = await self.instructor_for_objects.chat.completions.create_with_completion(
response_model=schema,
@@ -235,6 +248,7 @@ class MistralLLMWorker(LLMWorkerAbstract):
model=self.inference_model.model_id,
temperature=job_params.temperature,
max_tokens=job_params.max_tokens or self.default_max_tokens,
+ reasoning_effort=reasoning_effort,
# instructor's retry is confined to schema re-ask: this validation-only AsyncRetrying
# re-asks on a malformed/invalid output but never retries a transport error, which ends the
# loop and comes out wrapped, for the except clause below to unwrap — transport retry is the
diff --git a/pipelex/providers/openai/openai_completions_llm_worker.py b/pipelex/providers/openai/openai_completions_llm_worker.py
index e4be1667f..4cd601dac 100644
--- a/pipelex/providers/openai/openai_completions_llm_worker.py
+++ b/pipelex/providers/openai/openai_completions_llm_worker.py
@@ -210,7 +210,7 @@ class OpenAICompletionsLLMWorker(LLMWorkerAbstract):
schema: type[BaseModelTypeVar],
) -> BaseModelTypeVar:
job_params = llm_job.applied_job_params or llm_job.job_params
- self._validate_no_reasoning_for_structured_gen(job_params=job_params)
+ openai_reasoning_effort = self._resolve_reasoning_effort(job_params=job_params)
messages = await self.openai_completions_factory.make_simple_messages(llm_job=llm_job)
# Deferred import: avoid pulling heavy SDK at module-load time
from instructor.core import InstructorRetryException # ruff: ignore[import-outside-top-level]
@@ -222,10 +222,11 @@ class OpenAICompletionsLLMWorker(LLMWorkerAbstract):
try:
result_object, completion = await self.instructor_for_objects.chat.completions.create_with_completion(
model=self.inference_model.model_id,
- temperature=omit if temperature_unsupported else job_params.temperature,
+ temperature=omit if (openai_reasoning_effort is not None or temperature_unsupported) else job_params.temperature,
max_tokens=job_params.max_tokens or NOT_GIVEN,
seed=job_params.seed,
messages=messages,
+ reasoning_effort=openai_reasoning_effort if openai_reasoning_effort is not None else omit,
response_model=schema,
# instructor's retry is confined to schema re-ask: this validation-only AsyncRetrying
# re-asks on a malformed/invalid output but never retries a transport error, which ends the
diff --git a/pipelex/providers/openai/openai_responses_llm_worker.py b/pipelex/providers/openai/openai_responses_llm_worker.py
index b37a88f6c..9b70bed3c 100644
--- a/pipelex/providers/openai/openai_responses_llm_worker.py
+++ b/pipelex/providers/openai/openai_responses_llm_worker.py
@@ -189,7 +189,7 @@ class OpenAIResponsesLLMWorker(LLMWorkerAbstract):
schema: type[BaseModelTypeVar],
) -> BaseModelTypeVar:
job_params = llm_job.applied_job_params or llm_job.job_params
- self._validate_no_reasoning_for_structured_gen(job_params=job_params)
+ openai_reasoning = self._resolve_reasoning(job_params=job_params)
from instructor.core import InstructorRetryException # ruff: ignore[import-outside-top-level]
if not hasattr(self.instructor_for_objects, "responses"):
@@ -225,8 +225,9 @@ class OpenAIResponsesLLMWorker(LLMWorkerAbstract):
max_retries=make_instructor_schema_retrying(max_attempts=llm_job.job_config.schema_reask_max_attempts),
model=self.inference_model.model_id,
instructions=llm_job.llm_prompt.system_text,
- temperature=job_params.temperature,
+ temperature=omit if openai_reasoning is not None else job_params.temperature,
max_output_tokens=job_params.max_tokens or NOT_GIVEN,
+ reasoning=openai_reasoning if openai_reasoning is not None else omit,
extra_headers=extra_headers,
extra_body=extra_body,
)
diff --git a/subject_grants.toml b/subject_grants.toml
index 11dc7df6f..df68fc84f 100644
--- a/subject_grants.toml
+++ b/subject_grants.toml
@@ -1932,10 +1932,6 @@ rationale = "Worker verb–object: processes the llm_job; single operand."
param = "llm_job"
rationale = "Operates on the llm_job; single operand (attached data keyword-only)."
-["pipelex/cogt/llm/llm_worker_abstract.py::LLMWorkerAbstract._validate_no_reasoning_for_structured_gen"]
-param = "job_params"
-rationale = "Validator: the job params are the single operand checked."
-
["pipelex/cogt/llm/llm_worker_abstract.py::LLMWorkerAbstract.gen_object"]
param = "llm_job"
rationale = "Worker verb–object: processes the llm_job; single operand."
@@ -5020,9 +5016,9 @@ rationale = "Verb–object: renders the model list; single operand."
param = "models"
rationale = "Verb–object: renders the model list; single operand."
-["pipelex/providers/mistral/mistral_llm_worker.py::MistralLLMWorker._resolve_prompt_mode"]
+["pipelex/providers/mistral/mistral_llm_worker.py::MistralLLMWorker._resolve_reasoning_effort"]
param = "job_params"
-rationale = "Resolves the prompt mode from the job params; single operand."
+rationale = "Resolves the reasoning effort from the job params; single operand."
["pipelex/providers/mistral/mistral_plugin.py::MistralPlugin.register"]
param = "registrar"
diff --git a/tests/helpers/anthropic_structured_request.py b/tests/helpers/anthropic_structured_request.py
new file mode 100644
index 000000000..3d9c5521a
--- /dev/null
+++ b/tests/helpers/anthropic_structured_request.py
@@ -0,0 +1,117 @@
+"""Fakes for driving the Anthropic worker's structured call through a real instructor client.
+
+The worker is built as it builds itself, over an Anthropic SDK client whose ``messages.create`` records the
+request and answers with a tool call, so a test asserts what instructor actually sends rather than the
+arguments the worker hands it.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from anthropic import AsyncAnthropic
+from anthropic.types import ContentBlock, Message, ToolUseBlock, Usage
+
+from pipelex.cogt.llm.thinking_mode import ThinkingMode
+from pipelex.providers.anthropic.anthropic_config import AnthropicConfig
+from pipelex.providers.anthropic.anthropic_llm_worker import AnthropicLLMWorker
+
+if TYPE_CHECKING:
+ from unittest.mock import AsyncMock
+
+ from pytest_mock import MockerFixture
+
+ from pipelex.cogt.llm.structured_output import StructureMethod
+
+ANTHROPIC_LEVEL_MAP: dict[str, str] = {
+ "none": "disabled",
+ "minimal": "low",
+ "low": "low",
+ "medium": "medium",
+ "high": "high",
+ "xhigh": "xhigh",
+ "max": "max",
+}
+ANTHROPIC_BUDGET_MAP: dict[str, int] = {"none": 0, "minimal": 512, "low": 1024, "medium": 5000, "high": 16384, "xhigh": 32768, "max": 65536}
+# The minimum the kit's Anthropic backends declare as the model's min_thinking_budget
+ANTHROPIC_MIN_THINKING_BUDGET = 1024
+
+STEERING_LINE = "Return only the tool call and no additional text."
+PROMPT_SYSTEM_TEXT = "You are a helpful test assistant."
+
+
+def anthropic_budget(*, family: str, effort: str) -> int:
+ assert family == "anthropic"
+ return ANTHROPIC_BUDGET_MAP[effort]
+
+
+def make_message(*content: ContentBlock) -> Message:
+ return Message(
+ id="msg_test",
+ type="message",
+ role="assistant",
+ model="claude-test",
+ content=list(content),
+ stop_reason="tool_use",
+ stop_sequence=None,
+ usage=Usage(input_tokens=1, output_tokens=1),
+ )
+
+
+def tool_call_message() -> Message:
+ return make_message(ToolUseBlock(type="tool_use", id="toolu_test", name="DummySchema", input={"text": "answer"}))
+
+
+def make_structured_worker(
+ mocker: MockerFixture,
+ *,
+ structure_method: StructureMethod,
+ thinking_mode: ThinkingMode = ThinkingMode.NONE,
+ default_max_tokens: int = 4096,
+ responses: list[Message] | None = None,
+) -> tuple[AnthropicLLMWorker, AsyncMock]:
+ """A worker whose instructor client is built as the worker builds it, over an SDK call that records the request."""
+ from instructor import from_anthropic # ruff: ignore[import-outside-top-level]
+
+ sdk_client = AsyncAnthropic(api_key="test-key")
+ if responses is None:
+ create = mocker.AsyncMock(return_value=tool_call_message())
+ else:
+ create = mocker.AsyncMock(side_effect=responses)
+ mocker.patch.object(sdk_client.messages, "create", new=create)
+
+ worker = object.__new__(AnthropicLLMWorker)
+
+ worker.extras_factory = None
+ model = mocker.MagicMock()
+ model.desc = "test-model-desc"
+ model.model_id = "claude-test"
+ model.name = "claude-test"
+ model.listed_constraints = []
+ model.structure_method = structure_method
+ model.thinking_mode = thinking_mode
+ model.min_thinking_budget = ANTHROPIC_MIN_THINKING_BUDGET
+ model.max_thinking_budget = None
+ worker.inference_model = model
+ worker.default_max_tokens = default_max_tokens
+ worker.instructor_for_objects = from_anthropic(client=sdk_client, mode=structure_method.as_instructor_mode())
+
+ config = mocker.MagicMock()
+ config.inference.llm.anthropic = AnthropicConfig(structured_output_timeout_seconds=1200, effort_to_level_map=ANTHROPIC_LEVEL_MAP)
+ config.inference.llm.get_reasoning_budget = mocker.MagicMock(side_effect=anthropic_budget)
+ mocker.patch("pipelex.providers.anthropic.anthropic_llm_worker.get_config", return_value=config)
+ return worker, create
+
+
+def sent_request(create: AsyncMock) -> dict[str, Any]:
+ create.assert_awaited_once()
+ await_args = create.await_args
+ assert await_args is not None
+ return dict(await_args.kwargs)
+
+
+def system_texts(request: dict[str, Any]) -> list[str]:
+ system = request["system"]
+ if isinstance(system, str):
+ return [system]
+ return [block["text"] for block in system]
diff --git a/tests/helpers/google_structured_request.py b/tests/helpers/google_structured_request.py
new file mode 100644
index 000000000..7840a85c2
--- /dev/null
+++ b/tests/helpers/google_structured_request.py
@@ -0,0 +1,96 @@
+"""Fakes for driving the Google LLM worker's structured call through a real instructor client.
+
+``_gen_object`` goes through instructor's genai handlers, which build the Google ``GenerateContentConfig``
+themselves from the kwargs they recognise and silently drop the rest. The worker is built over a real
+``from_genai`` client whose ``generate_content`` captures what reaches it, so a test asserts what is actually sent.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from google import genai
+from google.genai import types as genai_types
+from instructor import from_genai
+
+from pipelex.cogt.llm.structured_output import StructureMethod
+from pipelex.providers.google.google_config import GoogleConfig
+from pipelex.providers.google.google_llm_worker import GoogleLLMWorker
+from tests.helpers.instructor_test_utils import DummySchema
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
+ from pipelex.cogt.llm.thinking_mode import ThinkingMode
+
+GOOGLE_LEVEL_MAP: dict[str, str] = {
+ "none": "disabled",
+ "minimal": "minimal",
+ "low": "low",
+ "medium": "medium",
+ "high": "high",
+ "xhigh": "high",
+ "max": "high",
+}
+GEMINI_BUDGET_MAP: dict[str, int] = {"none": 0, "minimal": 512, "low": 1024, "medium": 5000, "high": 16384, "xhigh": 32768, "max": 65536}
+GENAI_STRUCTURE_METHODS = [StructureMethod.INSTRUCTOR_GENAI_STRUCTURED_OUTPUTS, StructureMethod.INSTRUCTOR_GENAI_TOOLS]
+
+
+def gemini_budget(*, family: str, effort: str) -> int:
+ assert family == "gemini"
+ return GEMINI_BUDGET_MAP[effort]
+
+
+def make_response(*, structure_method: StructureMethod, schema_name: str, payload: dict[str, Any]) -> genai_types.GenerateContentResponse:
+ match structure_method:
+ case StructureMethod.INSTRUCTOR_GENAI_TOOLS:
+ part = genai_types.Part(function_call=genai_types.FunctionCall(name=schema_name, args=payload))
+ case StructureMethod.INSTRUCTOR_GENAI_STRUCTURED_OUTPUTS:
+ part = genai_types.Part(text=json.dumps(payload))
+ case _:
+ msg = f"No Gemini response shape for {structure_method}"
+ raise ValueError(msg)
+ return genai_types.GenerateContentResponse(candidates=[genai_types.Candidate(content=genai_types.Content(role="model", parts=[part]))])
+
+
+def make_structured_worker(
+ mocker: MockerFixture,
+ *,
+ structure_method: StructureMethod,
+ captured: dict[str, Any],
+ schema_name: str = DummySchema.__name__,
+ payload: dict[str, Any] | None = None,
+ thinking_mode: ThinkingMode | None = None,
+ min_thinking_budget: int | None = None,
+ max_thinking_budget: int | None = None,
+) -> GoogleLLMWorker:
+ """A worker over a real instructor client whose ``generate_content`` records what reaches it in ``captured``."""
+ client = genai.Client(api_key="test-key")
+ response_payload = payload or {"text": "ok"}
+
+ # The real keyword-only signature, so a keyword `generate_content` does not take fails here as it does live
+ def fake_generate_content(
+ *, model: str, contents: Any, config: genai_types.GenerateContentConfig | None = None
+ ) -> genai_types.GenerateContentResponse:
+ captured.update(model=model, contents=contents, config=config)
+ return make_response(structure_method=structure_method, schema_name=schema_name, payload=response_payload)
+
+ mocker.patch.object(client.aio.models, "generate_content", new_callable=mocker.AsyncMock, side_effect=fake_generate_content)
+
+ worker = object.__new__(GoogleLLMWorker)
+ mock_model = mocker.MagicMock()
+ mock_model.desc = "test-model-desc"
+ mock_model.model_id = "gemini-pro"
+ mock_model.name = "gemini-pro"
+ mock_model.thinking_mode = thinking_mode
+ mock_model.min_thinking_budget = min_thinking_budget
+ mock_model.max_thinking_budget = max_thinking_budget
+ worker.inference_model = mock_model
+ worker.instructor_for_objects = from_genai(client=client, mode=structure_method.as_instructor_mode(), use_async=True)
+
+ config = mocker.MagicMock()
+ config.inference.llm.google = GoogleConfig(effort_to_level_map=GOOGLE_LEVEL_MAP)
+ config.inference.llm.get_reasoning_budget = mocker.MagicMock(side_effect=gemini_budget)
+ mocker.patch("pipelex.providers.google.google_llm_worker.get_config", return_value=config)
+ return worker
diff --git a/tests/helpers/mistral_request.py b/tests/helpers/mistral_request.py
new file mode 100644
index 000000000..dd53b9b7f
--- /dev/null
+++ b/tests/helpers/mistral_request.py
@@ -0,0 +1,110 @@
+"""Fakes for driving the Mistral worker's text and structured calls over a recording Mistral SDK client.
+
+The worker's text client and its instructor client share one SDK client whose ``chat.complete_async`` records
+the request and answers with a reasoning reply, a thinking chunk beside the answer, so a test asserts what is
+actually sent, through instructor on the structured path.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from mistralai.client import Mistral
+from mistralai.client.models import (
+ AssistantMessage,
+ ChatCompletionChoice,
+ ChatCompletionResponse,
+ FunctionCall,
+ TextChunk,
+ ThinkChunk,
+ ToolCall,
+ UsageInfo,
+)
+from mistralai.client.types import UNSET
+
+from pipelex.cogt.llm.structured_output import StructureMethod
+from pipelex.providers.mistral.mistral_config import MistralConfig
+from pipelex.providers.mistral.mistral_factory import MistralFactory
+from pipelex.providers.mistral.mistral_llm_worker import MistralLLMWorker
+
+if TYPE_CHECKING:
+ from unittest.mock import AsyncMock
+
+ from pytest_mock import MockerFixture
+
+ from pipelex.cogt.llm.thinking_mode import ThinkingMode
+
+MISTRAL_LEVEL_MAP: dict[str, str] = {
+ "none": "disabled",
+ "minimal": "reasoning",
+ "low": "reasoning",
+ "medium": "reasoning",
+ "high": "reasoning",
+ "xhigh": "reasoning",
+ "max": "reasoning",
+}
+
+
+def _response(message: AssistantMessage) -> ChatCompletionResponse:
+ return ChatCompletionResponse(
+ id="cmpl_test",
+ object="chat.completion",
+ model="magistral-test",
+ created=0,
+ usage=UsageInfo(prompt_tokens=1, completion_tokens=1, total_tokens=2),
+ choices=[ChatCompletionChoice(index=0, finish_reason="tool_calls", message=message)],
+ )
+
+
+def tool_call_response() -> ChatCompletionResponse:
+ tool_call = ToolCall(id="call_test", function=FunctionCall(name="DummySchema", arguments=json.dumps({"text": "answer"})))
+ return _response(AssistantMessage(content=[ThinkChunk(thinking=[TextChunk(text="Reading the schema.")])], tool_calls=[tool_call]))
+
+
+def text_response() -> ChatCompletionResponse:
+ return _response(AssistantMessage(content=[ThinkChunk(thinking=[TextChunk(text="Thinking.")]), TextChunk(text="answer")]))
+
+
+def make_worker(
+ mocker: MockerFixture,
+ *,
+ thinking_mode: ThinkingMode,
+ response: ChatCompletionResponse,
+ structure_method: StructureMethod = StructureMethod.INSTRUCTOR_MISTRAL_TOOLS,
+) -> tuple[MistralLLMWorker, AsyncMock]:
+ """A worker whose text client and instructor client share one SDK client, whose call records the request."""
+ from instructor import from_mistral # ruff: ignore[import-outside-top-level]
+
+ sdk_client = Mistral(api_key="test-key")
+ complete_async = mocker.AsyncMock(return_value=response)
+ mocker.patch.object(sdk_client.chat, "complete_async", new=complete_async)
+
+ worker = object.__new__(MistralLLMWorker)
+ model = mocker.MagicMock()
+ model.desc = "test-model-desc"
+ model.model_id = "magistral-test"
+ model.name = "magistral-test"
+ model.thinking_mode = thinking_mode
+ model.structure_method = structure_method
+ worker.inference_model = model
+ worker.default_max_tokens = 4096
+ worker.mistral_factory = MistralFactory()
+ worker.mistral_client_for_text = sdk_client
+ worker.instructor_for_objects = from_mistral(client=sdk_client, mode=structure_method.as_instructor_mode(), use_async=True)
+
+ config = mocker.MagicMock()
+ config.inference.llm.mistral = MistralConfig(effort_to_level_map=MISTRAL_LEVEL_MAP)
+ mocker.patch("pipelex.providers.mistral.mistral_llm_worker.get_config", return_value=config)
+ return worker, complete_async
+
+
+def sent_request(complete_async: AsyncMock) -> dict[str, Any]:
+ complete_async.assert_awaited_once()
+ await_args = complete_async.await_args
+ assert await_args is not None
+ return dict(await_args.kwargs)
+
+
+def is_unset(request: dict[str, Any], key: str) -> bool:
+ return request.get(key, UNSET) is UNSET
diff --git a/tests/integration/pipelex/cogt/test_data.py b/tests/integration/pipelex/cogt/test_data.py
index 66b667bae..315cbdce9 100644
--- a/tests/integration/pipelex/cogt/test_data.py
+++ b/tests/integration/pipelex/cogt/test_data.py
@@ -253,9 +253,29 @@ class SearchTestCases:
]
+class AnswerConfidence(StrEnum):
+ LOW = "low"
+ MEDIUM = "medium"
+ HIGH = "high"
+
+
+class WorkingStep(BaseModel):
+ description: str = Field(description="One step of the working, in a short sentence")
+
+
+class ReasonedAnswer(BaseModel):
+ """A structured answer with an enum and a nested list, the shapes a structured output breaks on first."""
+
+ answer: str = Field(description="The final answer, as short as possible")
+ confidence: AnswerConfidence
+ steps: list[WorkingStep] = Field(description="The steps of the working, in order")
+
+
class LLMReasoningTestCases:
"""Test cases for LLM reasoning/thinking integration tests."""
+ STRUCTURED_PROMPT = "What is 317 * 723? Give the answer, your confidence in it, and the steps of your working."
+
PROMPTS: ClassVar[list[tuple[str, str]]] = [ # topic, prompt_text
("Comparison", "Which is larger: 0.9 or 0.11?"),
("Letter counting", "How many Rs are in the word 'Strawberry'?"),
diff --git a/tests/integration/pipelex/cogt/test_llm_reasoning.py b/tests/integration/pipelex/cogt/test_llm_reasoning.py
index 1daaf619d..7a9d23926 100644
--- a/tests/integration/pipelex/cogt/test_llm_reasoning.py
+++ b/tests/integration/pipelex/cogt/test_llm_reasoning.py
@@ -5,12 +5,37 @@ from pipelex.cogt.exceptions import LLMCapabilityError
from pipelex.cogt.llm.llm_job_components import LLMJobConfig, LLMJobParams, ReasoningEffort
from pipelex.cogt.llm.llm_job_factory import LLMJobFactory
from pipelex.cogt.llm.llm_prompt import LLMPrompt
+from pipelex.cogt.llm.llm_worker_abstract import LLMWorkerAbstract
+from pipelex.cogt.llm.thinking_mode import ThinkingMode
from pipelex.runtime_hub import get_llm_worker
from pipelex.system.job_metadata import JobMetadata
-from tests.integration.pipelex.cogt.test_data import LLMReasoningTestCases
+from tests.integration.pipelex.cogt.test_data import LLMReasoningTestCases, ReasonedAnswer
from tests.integration.pipelex.fixtures.model_combo import ModelCombo
+def _skip_unless_the_model_reasons(llm_worker: LLMWorkerAbstract) -> None:
+ """Skip a model whose spec declares no reasoning, read from the spec before any call.
+
+ The structured tests never skip on a caught LLMCapabilityError, so a worker that regresses to refusing
+ a reasoning setting on a structured output fails them instead of skipping.
+ """
+ if llm_worker.inference_model.thinking_mode == ThinkingMode.NONE:
+ pytest.skip(f"'{llm_worker.inference_model.name}' declares thinking_mode=none")
+
+
+def _skip_unless_the_model_structures(llm_worker: LLMWorkerAbstract) -> None:
+ """Skip a model whose spec declares no structured output, such as the text-only Magistral models."""
+ if not llm_worker.is_gen_object_supported:
+ pytest.skip(f"'{llm_worker.inference_model.name}' does not support object generation")
+
+
+def _skip_unless_the_model_takes_a_budget(llm_worker: LLMWorkerAbstract) -> None:
+ """Skip a model that takes no explicit reasoning budget: only manual thinking on a budget-mapped worker does."""
+ _skip_unless_the_model_reasons(llm_worker)
+ if llm_worker.inference_model.thinking_mode != ThinkingMode.MANUAL or getattr(llm_worker, "reasoning_budget_family", None) is None:
+ pytest.skip(f"'{llm_worker.inference_model.name}' takes a reasoning effort, not a budget")
+
+
@pytest.mark.llm
@pytest.mark.inference
@pytest.mark.asyncio(loop_scope="class")
@@ -119,3 +144,56 @@ class TestLLMReasoning:
generated_text = await llm_worker.gen_text(llm_job=llm_job)
assert generated_text
pretty_print(generated_text, title=f"Result (baseline, {topic})")
+
+ @pytest.mark.parametrize(
+ ("topic", "reasoning_effort"),
+ [
+ ("Low effort", ReasoningEffort.LOW),
+ ("High effort", ReasoningEffort.HIGH),
+ ],
+ )
+ async def test_gen_object_with_reasoning_effort(
+ self,
+ job_metadata: JobMetadata,
+ llm_combo: ModelCombo,
+ topic: str,
+ reasoning_effort: ReasoningEffort,
+ ):
+ """A reasoning effort on a structured output reaches the provider and the object validates."""
+ llm_worker = get_llm_worker(llm_handle=llm_combo.handle)
+ _skip_unless_the_model_structures(llm_worker)
+ _skip_unless_the_model_reasons(llm_worker)
+ pretty_print(LLMReasoningTestCases.STRUCTURED_PROMPT, title=f"[{topic}] structured using '{llm_combo.handle}'")
+ llm_job = LLMJobFactory.make_llm_job(
+ llm_prompt=LLMPrompt(user_text=LLMReasoningTestCases.STRUCTURED_PROMPT),
+ job_metadata=job_metadata,
+ llm_job_params=LLMJobParams(temperature=0.5, max_tokens=None, reasoning_effort=reasoning_effort),
+ llm_job_config=LLMJobConfig(schema_reask_max_attempts=3),
+ )
+ reasoned_answer = await llm_worker.gen_object(llm_job=llm_job, schema=ReasonedAnswer)
+ assert isinstance(reasoned_answer, ReasonedAnswer)
+ assert reasoned_answer.steps
+ pretty_print(reasoned_answer, title=f"Result ({topic}, structured)")
+
+ @pytest.mark.parametrize("budget", [1024, 4096])
+ async def test_gen_object_with_reasoning_budget(
+ self,
+ job_metadata: JobMetadata,
+ llm_combo: ModelCombo,
+ budget: int,
+ ):
+ """An explicit reasoning budget on a structured output reaches the provider and the object validates."""
+ llm_worker = get_llm_worker(llm_handle=llm_combo.handle)
+ _skip_unless_the_model_structures(llm_worker)
+ _skip_unless_the_model_takes_a_budget(llm_worker)
+ pretty_print(LLMReasoningTestCases.STRUCTURED_PROMPT, title=f"[budget={budget}] structured using '{llm_combo.handle}'")
+ llm_job = LLMJobFactory.make_llm_job(
+ llm_prompt=LLMPrompt(user_text=LLMReasoningTestCases.STRUCTURED_PROMPT),
+ job_metadata=job_metadata,
+ llm_job_params=LLMJobParams(temperature=0.5, max_tokens=None, reasoning_budget=budget),
+ llm_job_config=LLMJobConfig(schema_reask_max_attempts=3),
+ )
+ reasoned_answer = await llm_worker.gen_object(llm_job=llm_job, schema=ReasonedAnswer)
+ assert isinstance(reasoned_answer, ReasonedAnswer)
+ assert reasoned_answer.steps
+ pretty_print(reasoned_answer, title=f"Result (budget={budget}, structured)")
diff --git a/tests/integration/pipelex/pipes/operator/pipe_llm/structured_reasoning.mthds b/tests/integration/pipelex/pipes/operator/pipe_llm/structured_reasoning.mthds
new file mode 100644
index 000000000..ee3c797fe
--- /dev/null
+++ b/tests/integration/pipelex/pipes/operator/pipe_llm/structured_reasoning.mthds
@@ -0,0 +1,19 @@
+domain = "test_structured_reasoning"
+description = "A structured output from a pipe whose model setting carries a reasoning effort"
+
+# The shape of a deck reasoning preset on a structured pipe: the object is generated with the text
+# model setting, reasoning effort included, since no model_to_structure is named.
+[concept.ComparisonVerdict]
+description = "A verdict on which of two numbers is larger"
+
+[concept.ComparisonVerdict.structure]
+larger_number = { type = "text", description = "The larger of the two numbers, as written in the question", required = true }
+reasons = { type = "list", item_type = "text", description = "The reasons for the verdict, one per item", required = true }
+
+[pipe.compare_numbers]
+type = "PipeLLM"
+description = "Compare two numbers, reasoning at low effort, into a structured verdict"
+inputs = { question = "Text" }
+output = "ComparisonVerdict"
+model = { model = "gpt-5.6-luna", temperature = 1, reasoning_effort = "low" }
+prompt = "Answer this question: $question"
diff --git a/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_structured_reasoning.py b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_structured_reasoning.py
new file mode 100644
index 000000000..0e406489b
--- /dev/null
+++ b/tests/integration/pipelex/pipes/operator/pipe_llm/test_pipe_llm_structured_reasoning.py
@@ -0,0 +1,68 @@
+"""A PipeLLM with a structured output and a reasoning effort, run for real.
+
+This is the shape every deck reasoning preset takes on a structured pipe: no `model_to_structure`, so the
+object is generated with the text model setting, its reasoning effort included. Every worker used to refuse
+that call outright, so the presets named for careful reasoning failed on any structured output.
+"""
+
+from pathlib import Path
+from typing import Callable
+
+import pytest
+from pytest_mock import MockerFixture
+
+from pipelex import pretty_print
+from pipelex.cogt.llm.llm_job import LLMJob
+from pipelex.cogt.llm.llm_job_components import ReasoningEffort
+from pipelex.core.concepts.native.concept_native import NativeConceptCode
+from pipelex.core.memory.working_memory_factory import WorkingMemoryFactory
+from pipelex.core.stuffs.stuff_factory import StuffFactory
+from pipelex.core.stuffs.text_content import TextContent
+from pipelex.interpreter_hub import get_native_concept, get_pipe_router, get_required_entry_pipe
+from pipelex.pipe_run.pipe_job_factory import PipeJobFactory
+from pipelex.pipe_run.pipe_run_params_factory import PipeRunParamsFactory
+from pipelex.runtime_hub import get_report_delegate
+from pipelex.system.job_metadata import JobMetadata
+from pipelex.system.pipe_run_mode import PipeRunMode
+
+
[email protected](loop_scope="class")
+class TestPipeLLMStructuredReasoning:
+ async def test_a_structured_output_is_generated_with_the_reasoning_effort(
+ self,
+ mocker: MockerFixture,
+ job_metadata: JobMetadata,
+ pipe_run_mode: PipeRunMode,
+ load_test_library: Callable[[list[Path]], None],
+ ) -> None:
+ load_test_library([Path("tests/integration/pipelex/pipes/operator/pipe_llm")])
+ working_memory = WorkingMemoryFactory.make_from_single_stuff(
+ stuff=StuffFactory.make_stuff(
+ concept=get_native_concept(NativeConceptCode.TEXT),
+ content=TextContent(text="Which is larger: 0.9 or 0.11?"),
+ name="question",
+ ),
+ )
+ pipe_job = PipeJobFactory.make_pipe_job(
+ pipe=get_required_entry_pipe(pipe_code="test_structured_reasoning.compare_numbers"),
+ pipe_run_params=PipeRunParamsFactory.make_run_params(pipe_run_mode=pipe_run_mode),
+ job_metadata=job_metadata,
+ working_memory=working_memory,
+ )
+ report_spy = mocker.spy(get_report_delegate(), "report_inference_job")
+
+ pipe_output = await get_pipe_router().run(pipe_job=pipe_job)
+
+ pretty_print(pipe_output.main_stuff, title="Structured output with a reasoning effort")
+ assert pipe_output.main_stuff.concept.code == "ComparisonVerdict"
+ if pipe_run_mode.is_live:
+ verdict = pipe_output.main_stuff.content
+ assert isinstance(getattr(verdict, "larger_number", None), str)
+ reasons = getattr(verdict, "reasons", None)
+ assert isinstance(reasons, list)
+ assert reasons
+ (llm_job,) = [call.kwargs["inference_job"] for call in report_spy.call_args_list if isinstance(call.kwargs.get("inference_job"), LLMJob)]
+ assert llm_job.job_params.reasoning_effort == ReasoningEffort.LOW
diff --git a/tests/unit/pipelex/cogt/llm/test_llm_config_reasoning.py b/tests/unit/pipelex/cogt/llm/test_llm_config_reasoning.py
index 7d4e9c8c0..006d50116 100644
--- a/tests/unit/pipelex/cogt/llm/test_llm_config_reasoning.py
+++ b/tests/unit/pipelex/cogt/llm/test_llm_config_reasoning.py
@@ -190,9 +190,9 @@ class TestLLMConfigReasoning:
assert config.google.get_reasoning_level(ReasoningEffort.NONE) is None
def test_get_reasoning_level_mistral_reasoning(self):
- """Mistral HIGH maps to 'reasoning'."""
+ """Mistral HIGH maps to the 'reasoning' level, sent as Mistral's reasoning_effort 'high'."""
config = _make_llm_config()
- assert config.mistral.get_reasoning_level(ReasoningEffort.HIGH) == "reasoning"
+ assert config.mistral.get_reasoning_level(ReasoningEffort.HIGH) == "high"
def test_get_reasoning_level_mistral_disabled(self):
"""Mistral NONE returns None (disabled)."""
diff --git a/tests/unit/pipelex/cogt/llm/test_thinking_budget.py b/tests/unit/pipelex/cogt/llm/test_thinking_budget.py
new file mode 100644
index 000000000..f1f3d65e2
--- /dev/null
+++ b/tests/unit/pipelex/cogt/llm/test_thinking_budget.py
@@ -0,0 +1,61 @@
+import pytest
+
+from pipelex.cogt.exceptions import LLMCapabilityError
+from pipelex.cogt.llm.thinking_budget import fit_thinking_budget
+
+
+class TestFitThinkingBudget:
+ """A manual thinking budget is fitted inside max_tokens, leaving a quarter of it for the answer, and held within the model's bounds."""
+
+ def test_a_budget_within_the_ceiling_passes_through(self):
+ assert fit_thinking_budget(budget=5000, max_tokens=64000, min_budget=None, max_budget=None, model_desc="test-model") == 5000
+
+ def test_a_budget_at_the_ceiling_passes_through(self):
+ assert fit_thinking_budget(budget=3000, max_tokens=4000, min_budget=None, max_budget=None, model_desc="test-model") == 3000
+
+ def test_a_budget_over_the_ceiling_is_cut_to_max_tokens_minus_the_reserve(self):
+ assert fit_thinking_budget(budget=16384, max_tokens=2000, min_budget=None, max_budget=None, model_desc="test-model") == 1500
+
+ def test_the_timeout_capped_anthropic_structured_call_leaves_a_quarter_for_the_answer(self):
+ """The structured Anthropic path caps max_tokens at 42,666 for its timeout, and `max` effort asks 65,536."""
+ assert fit_thinking_budget(budget=65536, max_tokens=42666, min_budget=1024, max_budget=None, model_desc="test-model") == 32000
+
+ def test_a_budget_under_the_floor_is_raised_to_it(self):
+ assert fit_thinking_budget(budget=512, max_tokens=64000, min_budget=1024, max_budget=None, model_desc="test-model") == 1024
+
+ def test_the_floor_holds_when_the_ceiling_is_exactly_the_floor(self):
+ # 1365 // 4 = 341 reserved, leaving 1024 for thinking
+ assert fit_thinking_budget(budget=16384, max_tokens=1365, min_budget=1024, max_budget=None, model_desc="test-model") == 1024
+
+ def test_a_max_tokens_that_cannot_hold_the_floor_and_the_reserve_is_refused(self):
+ with pytest.raises(LLMCapabilityError) as exc_info:
+ fit_thinking_budget(budget=1024, max_tokens=1200, min_budget=1024, max_budget=None, model_desc="test-model")
+ message = str(exc_info.value)
+ assert "test-model" in message
+ assert "max_tokens=1200" in message
+ assert "1024" in message
+ assert "300" in message
+
+ def test_without_a_floor_a_small_max_tokens_cuts_the_budget_without_refusing(self):
+ """A model that declares no minimum, such as Gemini 2.5 Flash, has its budget cut rather than refused."""
+ assert fit_thinking_budget(budget=1024, max_tokens=100, min_budget=None, max_budget=None, model_desc="test-model") == 75
+
+ def test_a_tiny_max_tokens_still_keeps_a_token_for_the_answer(self):
+ """A quarter of max_tokens rounds down to nothing below 4, so the reserve is never less than one token."""
+ assert fit_thinking_budget(budget=5000, max_tokens=3, min_budget=None, max_budget=None, model_desc="test-model") == 2
+
+ def test_a_max_tokens_with_no_room_to_think_is_refused_without_a_floor(self):
+ with pytest.raises(LLMCapabilityError) as exc_info:
+ fit_thinking_budget(budget=5000, max_tokens=1, min_budget=None, max_budget=None, model_desc="test-model")
+ assert "max_tokens=1" in str(exc_info.value)
+
+ def test_a_budget_over_the_model_maximum_is_cut_to_it(self):
+ assert fit_thinking_budget(budget=65536, max_tokens=100000, min_budget=128, max_budget=32768, model_desc="test-model") == 32768
+
+ def test_without_max_tokens_only_the_model_bounds_apply(self):
+ assert fit_thinking_budget(budget=65536, max_tokens=None, min_budget=None, max_budget=24576, model_desc="test-model") == 24576
+ assert fit_thinking_budget(budget=200, max_tokens=None, min_budget=512, max_budget=24576, model_desc="test-model") == 512
+ assert fit_thinking_budget(budget=8192, max_tokens=None, min_budget=None, max_budget=None, model_desc="test-model") == 8192
+
+ def test_the_answer_reserve_cuts_below_the_model_maximum(self):
+ assert fit_thinking_budget(budget=32768, max_tokens=8000, min_budget=128, max_budget=32768, model_desc="test-model") == 6000
diff --git a/tests/unit/pipelex/cogt/model_backends/test_model_spec_thinking_budget_bounds.py b/tests/unit/pipelex/cogt/model_backends/test_model_spec_thinking_budget_bounds.py
new file mode 100644
index 000000000..d7ab91341
--- /dev/null
+++ b/tests/unit/pipelex/cogt/model_backends/test_model_spec_thinking_budget_bounds.py
@@ -0,0 +1,69 @@
+"""A model spec declares the range of manual thinking budgets its provider accepts as two valued constraints.
+
+`min_thinking_budget` and `max_thinking_budget` are both inclusive and both optional; a spec declaring a bound
+that is not a non-negative integer, or a minimum above its maximum, is refused when it is built.
+"""
+
+from typing import Any
+
+import pytest
+from pydantic import ValidationError
+
+from pipelex.cogt.llm.thinking_mode import ThinkingMode
+from pipelex.cogt.model_backends.constraints import ValuedConstraint
+from pipelex.cogt.model_backends.model_spec import InferenceModelSpec
+from pipelex.cogt.model_backends.model_type import ModelType
+from pipelex.cogt.usage.cost_category import CostCategory
+
+
+def _make_spec(*, valued_constraints: dict[ValuedConstraint, Any]) -> InferenceModelSpec:
+ return InferenceModelSpec(
+ backend_name="test",
+ name="test-model",
+ sdk="test_sdk",
+ model_type=ModelType.LLM,
+ model_id="test-model-id",
+ outputs=["text"],
+ costs={CostCategory.INPUT: 1.0, CostCategory.OUTPUT: 1.0},
+ thinking_mode=ThinkingMode.MANUAL,
+ max_tokens=None,
+ max_prompt_images=None,
+ valued_constraints=valued_constraints,
+ )
+
+
+class TestModelSpecThinkingBudgetBounds:
+ @pytest.mark.parametrize(
+ ("valued_constraints", "expected_min", "expected_max"),
+ [
+ ({}, None, None),
+ ({ValuedConstraint.MIN_THINKING_BUDGET: 1024}, 1024, None),
+ ({ValuedConstraint.MAX_THINKING_BUDGET: 24576}, None, 24576),
+ ({ValuedConstraint.MIN_THINKING_BUDGET: 128, ValuedConstraint.MAX_THINKING_BUDGET: 32768}, 128, 32768),
+ ({ValuedConstraint.MIN_THINKING_BUDGET: 512, ValuedConstraint.MAX_THINKING_BUDGET: 512}, 512, 512),
+ ],
+ )
+ def test_declared_bounds_are_read_back(
+ self, valued_constraints: dict[ValuedConstraint, Any], expected_min: int | None, expected_max: int | None
+ ) -> None:
+ spec = _make_spec(valued_constraints=valued_constraints)
+ assert spec.min_thinking_budget == expected_min
+ assert spec.max_thinking_budget == expected_max
+
+ @pytest.mark.parametrize(
+ ("valued_constraints", "expected_message"),
+ [
+ ({ValuedConstraint.MIN_THINKING_BUDGET: "1024"}, "min_thinking_budget='1024', which must be a non-negative integer"),
+ ({ValuedConstraint.MAX_THINKING_BUDGET: True}, "max_thinking_budget=True, which must be a non-negative integer"),
+ ({ValuedConstraint.MAX_THINKING_BUDGET: 2.5}, "max_thinking_budget=2.5, which must be a non-negative integer"),
+ ({ValuedConstraint.MIN_THINKING_BUDGET: -1}, "min_thinking_budget=-1, which must be a non-negative integer"),
+ (
+ {ValuedConstraint.MIN_THINKING_BUDGET: 2048, ValuedConstraint.MAX_THINKING_BUDGET: 1024},
+ "min_thinking_budget=2048 above max_thinking_budget=1024",
+ ),
+ ],
+ )
+ def test_an_invalid_declaration_is_refused(self, valued_constraints: dict[ValuedConstraint, Any], expected_message: str) -> None:
+ with pytest.raises(ValidationError) as exc_info:
+ _make_spec(valued_constraints=valued_constraints)
+ assert expected_message in str(exc_info.value)
diff --git a/tests/unit/pipelex/providers/anthropic/test_anthropic_reasoning.py b/tests/unit/pipelex/providers/anthropic/test_anthropic_reasoning.py
index 8a36d8274..97f323d1d 100644
--- a/tests/unit/pipelex/providers/anthropic/test_anthropic_reasoning.py
+++ b/tests/unit/pipelex/providers/anthropic/test_anthropic_reasoning.py
@@ -18,13 +18,15 @@ _ANTHROPIC_LEVEL_MAP: dict[str, str] = {
}
-def _make_worker(mocker: MockerFixture, thinking_mode: ThinkingMode) -> AnthropicLLMWorker:
- """Create a minimal AnthropicLLMWorker with a mocked inference_model."""
+def _make_worker(mocker: MockerFixture, thinking_mode: ThinkingMode, *, min_thinking_budget: int | None = 1024) -> AnthropicLLMWorker:
+ """Create a minimal AnthropicLLMWorker with a mocked inference_model, by default declaring Anthropic's minimum budget."""
worker = object.__new__(AnthropicLLMWorker)
worker.extras_factory = None
mock_model = mocker.MagicMock()
mock_model.thinking_mode = thinking_mode
mock_model.desc = "test-model"
+ mock_model.min_thinking_budget = min_thinking_budget
+ mock_model.max_thinking_budget = None
worker.inference_model = mock_model
return worker
@@ -47,7 +49,6 @@ class TestAnthropicReasoning:
@pytest.mark.parametrize(
("effort", "expected_budget"),
[
- (ReasoningEffort.MINIMAL, 512),
(ReasoningEffort.LOW, 1024),
(ReasoningEffort.MEDIUM, 5000),
(ReasoningEffort.HIGH, 16384),
@@ -71,6 +72,36 @@ class TestAnthropicReasoning:
assert result.suppress_temperature is True
budget_mock.assert_called_once_with(family="anthropic", effort=effort)
+ def test_manual_mode_budget_under_the_minimum_is_raised_to_it(self, mocker: MockerFixture):
+ """Anthropic refuses a budget_tokens below 1,024, so the 512 that MINIMAL maps to is raised to 1,024."""
+ worker = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL)
+ _mock_config(mocker, budget_mock=mocker.MagicMock(return_value=512))
+ job_params = LLMJobParams(temperature=0.5, reasoning_effort=ReasoningEffort.MINIMAL)
+ result = worker._build_thinking_params(job_params=job_params, max_tokens=100000) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ assert result.thinking == {"type": "enabled", "budget_tokens": 1024}
+
+ def test_explicit_budget_under_the_minimum_is_raised_to_it(self, mocker: MockerFixture):
+ worker = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL)
+ job_params = LLMJobParams(temperature=0.5, reasoning_budget=200)
+ result = worker._build_thinking_params(job_params=job_params, max_tokens=100000) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ assert result.thinking == {"type": "enabled", "budget_tokens": 1024}
+
+ def test_max_tokens_too_small_for_the_minimum_budget_is_refused(self, mocker: MockerFixture):
+ """1,200 output tokens leave 900 for thinking after the answer reserve, under Anthropic's minimum of 1,024."""
+ worker = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL)
+ _mock_config(mocker, budget_mock=mocker.MagicMock(return_value=1024))
+ job_params = LLMJobParams(temperature=0.5, reasoning_effort=ReasoningEffort.LOW)
+ with pytest.raises(LLMCapabilityError, match="max_tokens=1200"):
+ worker._build_thinking_params(job_params=job_params, max_tokens=1200) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ def test_a_model_declaring_no_minimum_is_sent_the_fitted_budget(self, mocker: MockerFixture):
+ """A server behind the anthropic SDK that declares no minimum, MiniMax among them, is neither raised nor refused."""
+ worker = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL, min_thinking_budget=None)
+ _mock_config(mocker, budget_mock=mocker.MagicMock(return_value=1024))
+ job_params = LLMJobParams(temperature=0.5, reasoning_effort=ReasoningEffort.LOW)
+ result = worker._build_thinking_params(job_params=job_params, max_tokens=1200) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ assert result.thinking == {"type": "enabled", "budget_tokens": 900}
+
def test_manual_mode_effort_none_disables_thinking(self, mocker: MockerFixture):
"""MANUAL mode with NONE effort disables thinking entirely (no budget lookup)."""
worker = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL)
@@ -83,13 +114,13 @@ class TestAnthropicReasoning:
budget_mock.assert_not_called()
def test_effort_budget_capped_by_max_tokens(self, mocker: MockerFixture):
- """Effort-resolved budget is capped to max_tokens - 1 when max_tokens is small."""
+ """Effort-resolved budget is capped to leave a quarter of max_tokens for the answer when max_tokens is small."""
worker = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL)
budget_mock = mocker.MagicMock(return_value=16384)
_mock_config(mocker, budget_mock=budget_mock)
job_params = LLMJobParams(temperature=0.5, reasoning_effort=ReasoningEffort.HIGH)
result = worker._build_thinking_params(job_params=job_params, max_tokens=2000) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
- assert result.thinking == {"type": "enabled", "budget_tokens": 1999}
+ assert result.thinking == {"type": "enabled", "budget_tokens": 1500}
def test_explicit_budget_passes_through(self, mocker: MockerFixture):
"""Explicit reasoning_budget passes through directly as budget_tokens in MANUAL mode."""
diff --git a/tests/unit/pipelex/providers/anthropic/test_anthropic_structure_method.py b/tests/unit/pipelex/providers/anthropic/test_anthropic_structure_method.py
index 6c20b9cab..e3ccb0593 100644
--- a/tests/unit/pipelex/providers/anthropic/test_anthropic_structure_method.py
+++ b/tests/unit/pipelex/providers/anthropic/test_anthropic_structure_method.py
@@ -1,103 +1,90 @@
-"""The request the Anthropic worker's structured call sends, for each tool structure method.
+"""The request the Anthropic worker's structured call sends for each structure method, thinking aside.
-Driven through a real instructor client over an Anthropic SDK client whose ``messages.create`` records the
-request and answers with a tool call, so what is asserted is what instructor actually sends, not the arguments
-the worker hands it. ``anthropic_reasoning_tools`` is the method a model that refuses a forced tool choice
-names, Fable 5.1 among them, and instructor resolves it to its core tool mode, which forces one.
+``anthropic_reasoning_tools`` is the method a model that refuses a forced tool choice names, Fable 5.1 among
+them, and instructor resolves it to its core tool mode, which forces one. A JSON mode defines no tool, so
+nothing about the tool choice is added to its request, thinking or not.
"""
from __future__ import annotations
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING
import pytest
-from anthropic import AsyncAnthropic
-from anthropic.types import Message, ToolUseBlock, Usage
+from anthropic import Omit
+from anthropic.types import TextBlock
+from pipelex.cogt.llm.llm_job_components import ReasoningEffort
from pipelex.cogt.llm.structured_output import StructureMethod
-from pipelex.providers.anthropic.anthropic_llm_worker import AnthropicLLMWorker
+from pipelex.cogt.llm.thinking_mode import ThinkingMode
+from tests.helpers.anthropic_structured_request import (
+ PROMPT_SYSTEM_TEXT,
+ STEERING_LINE,
+ make_message,
+ make_structured_worker,
+ sent_request,
+ system_texts,
+)
from tests.helpers.instructor_test_utils import DummySchema, make_llm_job
if TYPE_CHECKING:
- from unittest.mock import AsyncMock
-
from pytest_mock import MockerFixture
-def _tool_call_message() -> Message:
- return Message(
- id="msg_test",
- type="message",
- role="assistant",
- model="claude-test",
- content=[ToolUseBlock(type="tool_use", id="toolu_test", name="DummySchema", input={"text": "answer"})],
- stop_reason="tool_use",
- stop_sequence=None,
- usage=Usage(input_tokens=1, output_tokens=1),
- )
-
-
-def _make_worker(mocker: MockerFixture, *, structure_method: StructureMethod) -> tuple[AnthropicLLMWorker, AsyncMock]:
- """A worker whose instructor client is built as the worker builds it, over an SDK call that records the request."""
- from instructor import from_anthropic # ruff: ignore[import-outside-top-level]
-
- sdk_client = AsyncAnthropic(api_key="test-key")
- create = mocker.AsyncMock(return_value=_tool_call_message())
- mocker.patch.object(sdk_client.messages, "create", new=create)
-
- worker = object.__new__(AnthropicLLMWorker)
-
- worker.extras_factory = None
- model = mocker.MagicMock()
- model.desc = "test-model-desc"
- model.model_id = "claude-test"
- model.name = "claude-test"
- model.listed_constraints = []
- model.structure_method = structure_method
- worker.inference_model = model
- worker.default_max_tokens = 4096
- worker.instructor_for_objects = from_anthropic(client=sdk_client, mode=structure_method.as_instructor_mode())
-
- config = mocker.MagicMock()
- config.inference.llm.anthropic.structured_output_timeout_seconds = 1200
- mocker.patch("pipelex.providers.anthropic.anthropic_llm_worker.get_config", return_value=config)
- return worker, create
-
-
-def _sent_request(create: AsyncMock) -> dict[str, Any]:
- create.assert_awaited_once()
- await_args = create.await_args
- assert await_args is not None
- return dict(await_args.kwargs)
-
-
-def _system_texts(request: dict[str, Any]) -> list[str]:
- system = request["system"]
- if isinstance(system, str):
- return [system]
- return [block["text"] for block in system]
-
-
@pytest.mark.asyncio(loop_scope="class")
class TestAnthropicStructureMethod:
async def test_reasoning_tools_leaves_the_tool_choice_on_auto(self, mocker: MockerFixture) -> None:
- worker, create = _make_worker(mocker, structure_method=StructureMethod.INSTRUCTOR_ANTHROPIC_REASONING_TOOLS)
+ worker, create = make_structured_worker(mocker, structure_method=StructureMethod.INSTRUCTOR_ANTHROPIC_REASONING_TOOLS)
result = await worker._gen_object(llm_job=make_llm_job(mocker), schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
assert result.text == "answer"
- request = _sent_request(create)
- assert request["tool_choice"] == {"type": "auto"}
+ request = sent_request(create)
+ assert request["tool_choice"] == {"type": "auto", "disable_parallel_tool_use": True}
assert [tool["name"] for tool in request["tools"]] == ["DummySchema"]
# The steering line goes out beside the prompt's own system text, which it does not replace.
- assert _system_texts(request) == ["Return only the tool call and no additional text.", "You are a helpful test assistant."]
+ assert system_texts(request) == [STEERING_LINE, PROMPT_SYSTEM_TEXT]
async def test_tools_forces_the_response_tool(self, mocker: MockerFixture) -> None:
- worker, create = _make_worker(mocker, structure_method=StructureMethod.INSTRUCTOR_ANTHROPIC_TOOLS)
+ worker, create = make_structured_worker(mocker, structure_method=StructureMethod.INSTRUCTOR_ANTHROPIC_TOOLS)
await worker._gen_object(llm_job=make_llm_job(mocker), schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
- request = _sent_request(create)
+ request = sent_request(create)
assert request["tool_choice"]["type"] == "tool"
assert request["tool_choice"]["name"] == "DummySchema"
- assert _system_texts(request) == ["You are a helpful test assistant."]
+ assert system_texts(request) == ["You are a helpful test assistant."]
+
+ async def test_no_thinking_effort_keeps_the_forced_tool_choice(self, mocker: MockerFixture) -> None:
+ """A NONE effort turns thinking off, so the request stays the forced-choice one."""
+ worker, create = make_structured_worker(
+ mocker, structure_method=StructureMethod.INSTRUCTOR_ANTHROPIC_TOOLS, thinking_mode=ThinkingMode.MANUAL
+ )
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.NONE
+
+ await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ request = sent_request(create)
+ assert request["tool_choice"]["type"] == "tool"
+ assert isinstance(request.get("thinking", Omit()), Omit)
+ assert request["temperature"] == 0.5
+
+ async def test_json_mode_with_thinking_adds_no_tool_choice(self, mocker: MockerFixture) -> None:
+ """A JSON mode defines no tool, so thinking adds no tool choice and no tool steering to its request."""
+ worker, create = make_structured_worker(
+ mocker,
+ structure_method=StructureMethod.INSTRUCTOR_ANTHROPIC_JSON,
+ thinking_mode=ThinkingMode.MANUAL,
+ responses=[make_message(TextBlock(type="text", text='{"text": "answer"}'))],
+ )
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.LOW
+
+ result = await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ assert result.text == "answer"
+ request = sent_request(create)
+ assert request["thinking"] == {"type": "enabled", "budget_tokens": 1024}
+ assert isinstance(request.get("tool_choice", Omit()), Omit)
+ assert "tools" not in request
+ assert STEERING_LINE not in system_texts(request)
diff --git a/tests/unit/pipelex/providers/anthropic/test_anthropic_structured_thinking.py b/tests/unit/pipelex/providers/anthropic/test_anthropic_structured_thinking.py
new file mode 100644
index 000000000..473d356ca
--- /dev/null
+++ b/tests/unit/pipelex/providers/anthropic/test_anthropic_structured_thinking.py
@@ -0,0 +1,127 @@
+"""The request the Anthropic worker's structured call sends with thinking on, for each tool structure method.
+
+Thinking needs the tool choice left on auto: a manual-thinking model refuses a forced choice, and an adaptive one
+accepts it and silently does not think. Driven through a real instructor client, so what is asserted is what
+instructor actually sends.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+from anthropic import Omit
+from anthropic.types import ThinkingBlock, ToolUseBlock
+
+from pipelex.cogt.exceptions import LLMCapabilityError
+from pipelex.cogt.llm.llm_job_components import ReasoningEffort
+from pipelex.cogt.llm.structured_output import StructureMethod
+from pipelex.cogt.llm.thinking_mode import ThinkingMode
+from tests.helpers.anthropic_structured_request import (
+ PROMPT_SYSTEM_TEXT,
+ STEERING_LINE,
+ make_message,
+ make_structured_worker,
+ sent_request,
+ system_texts,
+ tool_call_message,
+)
+from tests.helpers.instructor_test_utils import DummySchema, make_llm_job
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
+_AUTO_TOOL_CHOICE = {"type": "auto", "disable_parallel_tool_use": True}
+
+
[email protected](loop_scope="class")
+ "structure_method",
+ [StructureMethod.INSTRUCTOR_ANTHROPIC_TOOLS, StructureMethod.INSTRUCTOR_ANTHROPIC_REASONING_TOOLS],
+)
+class TestAnthropicStructuredThinking:
+ async def test_manual_thinking_reaches_the_api_with_the_auto_tool_choice(self, mocker: MockerFixture, structure_method: StructureMethod) -> None:
+ worker, create = make_structured_worker(mocker, structure_method=structure_method, thinking_mode=ThinkingMode.MANUAL)
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.LOW
+
+ result = await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ assert result.text == "answer"
+ request = sent_request(create)
+ assert request["thinking"] == {"type": "enabled", "budget_tokens": 1024}
+ assert request["tool_choice"] == _AUTO_TOOL_CHOICE
+ assert system_texts(request) == [STEERING_LINE, PROMPT_SYSTEM_TEXT]
+ assert isinstance(request.get("temperature", Omit()), Omit)
+
+ async def test_adaptive_thinking_reaches_the_api_with_the_auto_tool_choice(
+ self, mocker: MockerFixture, structure_method: StructureMethod
+ ) -> None:
+ worker, create = make_structured_worker(mocker, structure_method=structure_method, thinking_mode=ThinkingMode.ADAPTIVE)
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.HIGH
+
+ await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ request = sent_request(create)
+ assert request["thinking"] == {"type": "adaptive"}
+ assert request["output_config"] == {"effort": "high"}
+ assert request["tool_choice"] == _AUTO_TOOL_CHOICE
+ assert system_texts(request) == [STEERING_LINE, PROMPT_SYSTEM_TEXT]
+ assert isinstance(request.get("temperature", Omit()), Omit)
+
+ async def test_the_budget_leaves_room_for_the_answer_under_the_timeout_cap(
+ self, mocker: MockerFixture, structure_method: StructureMethod
+ ) -> None:
+ """The structured call caps max_tokens at 42,666 for its timeout; `max` effort's 65,536 is cut to leave a quarter of it."""
+ worker, create = make_structured_worker(
+ mocker, structure_method=structure_method, thinking_mode=ThinkingMode.MANUAL, default_max_tokens=128000
+ )
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.MAX
+
+ await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ request = sent_request(create)
+ assert request["max_tokens"] == 42666
+ assert request["thinking"] == {"type": "enabled", "budget_tokens": 32000}
+
+ async def test_a_model_without_thinking_refuses_it_as_its_text_path_does(self, mocker: MockerFixture, structure_method: StructureMethod) -> None:
+ worker, create = make_structured_worker(mocker, structure_method=structure_method, thinking_mode=ThinkingMode.NONE)
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.HIGH
+
+ with pytest.raises(LLMCapabilityError, match=r"does not support reasoning \(thinking_mode=none\)"):
+ await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ create.assert_not_awaited()
+
+ async def test_a_reask_carries_the_signed_thinking_block_back(self, mocker: MockerFixture, structure_method: StructureMethod) -> None:
+ """Anthropic requires the assistant turn before a tool_result to keep its thinking blocks, signature included."""
+ thinking_block = ThinkingBlock(type="thinking", thinking="Let me look at the schema.", signature="sig-test")
+ invalid_call = ToolUseBlock(type="tool_use", id="toolu_invalid", name="DummySchema", input={"wrong_field": "x"})
+ worker, create = make_structured_worker(
+ mocker,
+ structure_method=structure_method,
+ thinking_mode=ThinkingMode.MANUAL,
+ responses=[make_message(thinking_block, invalid_call), tool_call_message()],
+ )
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.LOW
+ llm_job.job_config.schema_reask_max_attempts = 2
+
+ result = await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ assert result.text == "answer"
+ assert create.await_count == 2
+ reask_args = create.await_args_list[1]
+ reask_messages = reask_args.kwargs["messages"]
+ assistant_turn = reask_messages[-2]
+ assert assistant_turn["role"] == "assistant"
+ assert assistant_turn["content"][0] == {"type": "thinking", "thinking": "Let me look at the schema.", "signature": "sig-test"}
+ assert assistant_turn["content"][1]["type"] == "tool_use"
+ tool_result_turn = reask_messages[-1]
+ assert tool_result_turn["content"][0]["type"] == "tool_result"
+ assert tool_result_turn["content"][0]["tool_use_id"] == "toolu_invalid"
+ # The re-ask keeps thinking on and the tool choice on auto
+ assert reask_args.kwargs["thinking"] == {"type": "enabled", "budget_tokens": 1024}
+ assert reask_args.kwargs["tool_choice"] == _AUTO_TOOL_CHOICE
diff --git a/tests/unit/pipelex/providers/google/test_google_llm_worker_structured_request.py b/tests/unit/pipelex/providers/google/test_google_llm_worker_structured_request.py
index 33b67393a..a931e0269 100644
--- a/tests/unit/pipelex/providers/google/test_google_llm_worker_structured_request.py
+++ b/tests/unit/pipelex/providers/google/test_google_llm_worker_structured_request.py
@@ -8,21 +8,19 @@ limit lost on the way fails here rather than in production.
from __future__ import annotations
-import json
from enum import StrEnum
from typing import TYPE_CHECKING, Any
import pytest
-from google import genai
from google.genai import types as genai_types
-from instructor import from_genai
from pydantic import BaseModel
if TYPE_CHECKING:
from pytest_mock import MockerFixture
-from pipelex.cogt.llm.structured_output import StructureMethod
-from pipelex.providers.google.google_llm_worker import GoogleLLMWorker
+ from pipelex.cogt.llm.structured_output import StructureMethod
+
+from tests.helpers.google_structured_request import GENAI_STRUCTURE_METHODS, make_structured_worker
from tests.helpers.instructor_test_utils import DummySchema, make_llm_job
@@ -35,61 +33,18 @@ class _ColoredSchema(BaseModel):
color: _Color
-def _make_response(*, structure_method: StructureMethod, schema_name: str, payload: dict[str, Any]) -> genai_types.GenerateContentResponse:
- match structure_method:
- case StructureMethod.INSTRUCTOR_GENAI_TOOLS:
- part = genai_types.Part(function_call=genai_types.FunctionCall(name=schema_name, args=payload))
- case StructureMethod.INSTRUCTOR_GENAI_STRUCTURED_OUTPUTS:
- part = genai_types.Part(text=json.dumps(payload))
- case _:
- msg = f"No Gemini response shape for {structure_method}"
- raise ValueError(msg)
- return genai_types.GenerateContentResponse(candidates=[genai_types.Candidate(content=genai_types.Content(role="model", parts=[part]))])
-
-
-def _make_worker(
- mocker: MockerFixture,
- *,
- structure_method: StructureMethod,
- captured: dict[str, Any],
- schema_name: str = DummySchema.__name__,
- payload: dict[str, Any] | None = None,
-) -> GoogleLLMWorker:
- client = genai.Client(api_key="test-key")
- response_payload = payload or {"text": "ok"}
-
- def fake_generate_content(**kwargs: Any) -> genai_types.GenerateContentResponse:
- captured.update(kwargs)
- return _make_response(structure_method=structure_method, schema_name=schema_name, payload=response_payload)
-
- mocker.patch.object(client.aio.models, "generate_content", new_callable=mocker.AsyncMock, side_effect=fake_generate_content)
-
- worker = object.__new__(GoogleLLMWorker)
- mock_model = mocker.MagicMock()
- mock_model.desc = "test-model-desc"
- mock_model.model_id = "gemini-pro"
- mock_model.name = "gemini-pro"
- mock_model.thinking_mode = None
- worker.inference_model = mock_model
- worker.instructor_for_objects = from_genai(client=client, mode=structure_method.as_instructor_mode(), use_async=True)
- return worker
-
-
@pytest.mark.asyncio(loop_scope="class")
class TestGoogleLLMWorkerStructuredRequest:
"""``_gen_object`` must hand the prompt's system text and the job's generation controls to Google."""
- @pytest.mark.parametrize(
- "structure_method",
- [StructureMethod.INSTRUCTOR_GENAI_STRUCTURED_OUTPUTS, StructureMethod.INSTRUCTOR_GENAI_TOOLS],
- )
+ @pytest.mark.parametrize("structure_method", GENAI_STRUCTURE_METHODS)
async def test_request_config_carries_system_prompt_and_generation_controls(
self,
mocker: MockerFixture,
structure_method: StructureMethod,
) -> None:
captured: dict[str, Any] = {}
- worker = _make_worker(mocker, structure_method=structure_method, captured=captured)
+ worker = make_structured_worker(mocker, structure_method=structure_method, captured=captured)
llm_job = make_llm_job(mocker)
llm_job.job_params.temperature = 0.3
llm_job.job_params.max_tokens = 123
@@ -104,9 +59,11 @@ class TestGoogleLLMWorkerStructuredRequest:
assert config.max_output_tokens == 123
assert config.candidate_count == 1
- async def test_request_without_system_text_or_token_limit_sends_none(self, mocker: MockerFixture) -> None:
+ @pytest.mark.parametrize("structure_method", GENAI_STRUCTURE_METHODS)
+ async def test_request_without_system_text_or_token_limit_sends_none(self, mocker: MockerFixture, structure_method: StructureMethod) -> None:
+ """A prompt with no system text sends no system instruction, and never a `system` keyword `generate_content` refuses."""
captured: dict[str, Any] = {}
- worker = _make_worker(mocker, structure_method=StructureMethod.INSTRUCTOR_GENAI_STRUCTURED_OUTPUTS, captured=captured)
+ worker = make_structured_worker(mocker, structure_method=structure_method, captured=captured)
llm_job = make_llm_job(mocker)
llm_job.llm_prompt.system_text = None
@@ -117,13 +74,10 @@ class TestGoogleLLMWorkerStructuredRequest:
assert config.temperature == 0.5
assert config.max_output_tokens is None
- @pytest.mark.parametrize(
- "structure_method",
- [StructureMethod.INSTRUCTOR_GENAI_STRUCTURED_OUTPUTS, StructureMethod.INSTRUCTOR_GENAI_TOOLS],
- )
+ @pytest.mark.parametrize("structure_method", GENAI_STRUCTURE_METHODS)
async def test_an_enum_field_is_parsed_from_its_string_value(self, mocker: MockerFixture, structure_method: StructureMethod) -> None:
"""Gemini hands an enum back as its string value, under tool calling and JSON output alike."""
- worker = _make_worker(
+ worker = make_structured_worker(
mocker,
structure_method=structure_method,
captured={},
diff --git a/tests/unit/pipelex/providers/google/test_google_llm_worker_structured_thinking.py b/tests/unit/pipelex/providers/google/test_google_llm_worker_structured_thinking.py
new file mode 100644
index 000000000..45dd6c611
--- /dev/null
+++ b/tests/unit/pipelex/providers/google/test_google_llm_worker_structured_thinking.py
@@ -0,0 +1,98 @@
+"""A reasoning setting reaches Gemini's thinking configuration on a structured output, as it does on text.
+
+Driven through a real ``from_genai`` client whose ``generate_content`` captures the request config.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from google.genai import types as genai_types
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
+ from pipelex.cogt.llm.structured_output import StructureMethod
+
+from pipelex.cogt.exceptions import LLMCapabilityError
+from pipelex.cogt.llm.llm_job_components import ReasoningEffort
+from pipelex.cogt.llm.thinking_mode import ThinkingMode
+from tests.helpers.google_structured_request import GENAI_STRUCTURE_METHODS, make_structured_worker
+from tests.helpers.instructor_test_utils import DummySchema, make_llm_job
+
+
[email protected](loop_scope="class")
[email protected]("structure_method", GENAI_STRUCTURE_METHODS)
+class TestGoogleLLMWorkerStructuredThinking:
+ async def test_a_manual_thinking_budget_reaches_the_request_config(self, mocker: MockerFixture, structure_method: StructureMethod) -> None:
+ captured: dict[str, Any] = {}
+ worker = make_structured_worker(mocker, structure_method=structure_method, captured=captured, thinking_mode=ThinkingMode.MANUAL)
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.LOW
+
+ result = await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ assert result.text == "ok"
+ config = captured["config"]
+ assert config.thinking_config == genai_types.ThinkingConfig(thinking_budget=1024)
+ # Gemini keeps the temperature beside thinking, as the text path does
+ assert config.temperature == 0.5
+
+ async def test_the_budget_is_fitted_inside_max_tokens(self, mocker: MockerFixture, structure_method: StructureMethod) -> None:
+ captured: dict[str, Any] = {}
+ worker = make_structured_worker(mocker, structure_method=structure_method, captured=captured, thinking_mode=ThinkingMode.MANUAL)
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.HIGH
+ llm_job.job_params.max_tokens = 4000
+
+ await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ assert captured["config"].thinking_config == genai_types.ThinkingConfig(thinking_budget=3000)
+
+ async def test_the_budget_is_held_to_the_model_maximum_without_max_tokens(self, mocker: MockerFixture, structure_method: StructureMethod) -> None:
+ """`max` effort's 65,536 is beyond gemini-2.5-pro's 32,768, and no max_tokens is set to fit it in."""
+ captured: dict[str, Any] = {}
+ worker = make_structured_worker(
+ mocker,
+ structure_method=structure_method,
+ captured=captured,
+ thinking_mode=ThinkingMode.MANUAL,
+ min_thinking_budget=128,
+ max_thinking_budget=32768,
+ )
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.MAX
+
+ await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ assert captured["config"].max_output_tokens is None
+ assert captured["config"].thinking_config == genai_types.ThinkingConfig(thinking_budget=32768)
+
+ async def test_an_adaptive_thinking_level_reaches_the_request_config(self, mocker: MockerFixture, structure_method: StructureMethod) -> None:
+ captured: dict[str, Any] = {}
+ worker = make_structured_worker(mocker, structure_method=structure_method, captured=captured, thinking_mode=ThinkingMode.ADAPTIVE)
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.HIGH
+
+ await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ assert captured["config"].thinking_config == genai_types.ThinkingConfig(thinking_level=genai_types.ThinkingLevel.HIGH)
+
+ async def test_without_a_reasoning_setting_no_thinking_config_is_sent(self, mocker: MockerFixture, structure_method: StructureMethod) -> None:
+ captured: dict[str, Any] = {}
+ worker = make_structured_worker(mocker, structure_method=structure_method, captured=captured, thinking_mode=ThinkingMode.MANUAL)
+
+ await worker._gen_object(llm_job=make_llm_job(mocker), schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ assert captured["config"].thinking_config is None
+
+ async def test_a_model_without_thinking_refuses_it_as_its_text_path_does(self, mocker: MockerFixture, structure_method: StructureMethod) -> None:
+ captured: dict[str, Any] = {}
+ worker = make_structured_worker(mocker, structure_method=structure_method, captured=captured, thinking_mode=ThinkingMode.NONE)
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.HIGH
+
+ with pytest.raises(LLMCapabilityError, match=r"does not support reasoning \(thinking_mode=none\)"):
+ await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ assert not captured
diff --git a/tests/unit/pipelex/providers/google/test_google_reasoning.py b/tests/unit/pipelex/providers/google/test_google_reasoning.py
index aa0788e16..d87c72453 100644
--- a/tests/unit/pipelex/providers/google/test_google_reasoning.py
+++ b/tests/unit/pipelex/providers/google/test_google_reasoning.py
@@ -5,6 +5,7 @@ from pytest_mock import MockerFixture
from pipelex.cogt.exceptions import LLMCapabilityError
from pipelex.cogt.llm.llm_job_components import LLMJobParams, ReasoningEffort
from pipelex.cogt.llm.thinking_mode import ThinkingMode
+from pipelex.cogt.model_backends.constraints import ListedConstraint
from pipelex.providers.google.google_config import GoogleConfig
from pipelex.providers.google.google_llm_worker import GoogleLLMWorker
@@ -19,12 +20,22 @@ _GOOGLE_LEVEL_MAP: dict[str, str] = {
}
-def _make_worker(mocker: MockerFixture, thinking_mode: ThinkingMode) -> GoogleLLMWorker:
- """Create a minimal GoogleLLMWorker with a mocked inference_model."""
+def _make_worker(
+ mocker: MockerFixture,
+ thinking_mode: ThinkingMode,
+ *,
+ min_thinking_budget: int | None = None,
+ max_thinking_budget: int | None = None,
+ listed_constraints: list[ListedConstraint] | None = None,
+) -> GoogleLLMWorker:
+ """Create a minimal GoogleLLMWorker with a mocked inference_model, declaring no thinking budget bounds or constraints by default."""
worker = object.__new__(GoogleLLMWorker)
mock_model = mocker.MagicMock()
mock_model.thinking_mode = thinking_mode
mock_model.desc = "test-model"
+ mock_model.listed_constraints = listed_constraints or []
+ mock_model.min_thinking_budget = min_thinking_budget
+ mock_model.max_thinking_budget = max_thinking_budget
worker.inference_model = mock_model
return worker
@@ -138,6 +149,23 @@ class TestGoogleReasoning:
assert result is not None
assert result.thinking_budget == 0
+ @pytest.mark.parametrize("thinking_mode", [ThinkingMode.MANUAL, ThinkingMode.ADAPTIVE])
+ def test_effort_none_is_refused_on_a_model_that_cannot_turn_thinking_off(self, mocker: MockerFixture, thinking_mode: ThinkingMode):
+ """Gemini 2.5 Pro and 3.1 Pro answer a budget of 0 with a 400, so the worker refuses before sending it."""
+ worker = _make_worker(mocker, thinking_mode=thinking_mode, listed_constraints=[ListedConstraint.THINKING_CANNOT_BE_DISABLED])
+ _mock_config_for_adaptive(mocker)
+ job_params = LLMJobParams(temperature=0.5, reasoning_effort=ReasoningEffort.NONE)
+ with pytest.raises(LLMCapabilityError, match="cannot turn thinking off"):
+ worker._build_thinking_config(job_params=job_params, max_tokens=100000) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ def test_another_effort_still_thinks_on_a_model_that_cannot_turn_thinking_off(self, mocker: MockerFixture):
+ worker = _make_worker(mocker, thinking_mode=ThinkingMode.ADAPTIVE, listed_constraints=[ListedConstraint.THINKING_CANNOT_BE_DISABLED])
+ _mock_config_for_adaptive(mocker)
+ job_params = LLMJobParams(temperature=0.5, reasoning_effort=ReasoningEffort.LOW)
+ result = worker._build_thinking_config(job_params=job_params, max_tokens=100000) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ assert result is not None
+ assert result.thinking_level == genai_types.ThinkingLevel.LOW
+
@pytest.mark.parametrize(
"thinking_mode",
[ThinkingMode.MANUAL, ThinkingMode.ADAPTIVE],
@@ -176,15 +204,15 @@ class TestGoogleReasoning:
worker._build_thinking_config(job_params=job_params, max_tokens=100000) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
def test_explicit_budget_capped_by_max_tokens(self, mocker: MockerFixture):
- """Explicit reasoning_budget is capped to max_tokens - 1."""
+ """Explicit reasoning_budget is capped to leave a quarter of max_tokens for the answer."""
worker = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL)
job_params = LLMJobParams(temperature=0.5, reasoning_budget=8192)
result = worker._build_thinking_config(job_params=job_params, max_tokens=4000) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
assert result is not None
- assert result.thinking_budget == 3999
+ assert result.thinking_budget == 3000
def test_effort_budget_capped_by_max_tokens(self, mocker: MockerFixture):
- """Effort-resolved budget is capped to max_tokens - 1 when max_tokens is small."""
+ """Effort-resolved budget is capped to leave a quarter of max_tokens for the answer when max_tokens is small."""
worker = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL)
google_config = GoogleConfig(effort_to_level_map=_GOOGLE_LEVEL_MAP)
mocker.patch(
@@ -201,4 +229,62 @@ class TestGoogleReasoning:
job_params = LLMJobParams(temperature=0.5, reasoning_effort=ReasoningEffort.HIGH)
result = worker._build_thinking_config(job_params=job_params, max_tokens=2000) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
assert result is not None
- assert result.thinking_budget == 1999
+ assert result.thinking_budget == 1500
+
+ @pytest.mark.parametrize(
+ ("min_thinking_budget", "max_thinking_budget", "reasoning_budget", "max_tokens", "expected_budget"),
+ [
+ # gemini-2.5-flash-lite takes 512 to 24576: a budget under it is raised to it
+ (512, 24576, 200, 100000, 512),
+ # and a max_tokens of 800 leaves 600 after the answer reserve, inside the range
+ (512, 24576, 1024, 800, 600),
+ # gemini-2.5-pro takes 128 to 32768
+ (128, 32768, 64, 100000, 128),
+ # gemini-2.5-flash takes at most 24576, with or without a max_tokens to fit in
+ (None, 24576, 32768, None, 24576),
+ (None, 24576, 65536, 100000, 24576),
+ ],
+ )
+ def test_explicit_budget_held_within_the_model_bounds(
+ self,
+ mocker: MockerFixture,
+ min_thinking_budget: int | None,
+ max_thinking_budget: int | None,
+ reasoning_budget: int,
+ max_tokens: int | None,
+ expected_budget: int,
+ ):
+ worker = _make_worker(
+ mocker, thinking_mode=ThinkingMode.MANUAL, min_thinking_budget=min_thinking_budget, max_thinking_budget=max_thinking_budget
+ )
+ job_params = LLMJobParams(temperature=0.5, reasoning_budget=reasoning_budget)
+ result = worker._build_thinking_config(job_params=job_params, max_tokens=max_tokens) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ assert result is not None
+ assert result.thinking_budget == expected_budget
+
+ def test_effort_budget_without_max_tokens_is_cut_to_the_model_maximum(self, mocker: MockerFixture):
+ """`max` effort's 65,536 is beyond every Gemini 2.5 model, so a model's declared maximum applies when no max_tokens is set."""
+ worker = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL, min_thinking_budget=128, max_thinking_budget=32768)
+ google_config = GoogleConfig(effort_to_level_map=_GOOGLE_LEVEL_MAP)
+ mocker.patch(
+ "pipelex.providers.google.google_llm_worker.get_config",
+ return_value=mocker.MagicMock(
+ inference=mocker.MagicMock(
+ llm=mocker.MagicMock(
+ get_reasoning_budget=mocker.MagicMock(return_value=65536),
+ google=google_config,
+ ),
+ ),
+ ),
+ )
+ job_params = LLMJobParams(temperature=0.5, reasoning_effort=ReasoningEffort.MAX)
+ result = worker._build_thinking_config(job_params=job_params, max_tokens=None) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ assert result is not None
+ assert result.thinking_budget == 32768
+
+ def test_max_tokens_too_small_for_the_model_minimum_is_refused(self, mocker: MockerFixture):
+ """gemini-2.5-flash-lite takes no budget under 512, and 600 output tokens leave 450 after the answer reserve."""
+ worker = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL, min_thinking_budget=512, max_thinking_budget=24576)
+ job_params = LLMJobParams(temperature=0.5, reasoning_budget=1024)
+ with pytest.raises(LLMCapabilityError, match="max_tokens=600"):
+ worker._build_thinking_config(job_params=job_params, max_tokens=600) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
diff --git a/tests/unit/pipelex/providers/mistral/test_mistral_reasoning.py b/tests/unit/pipelex/providers/mistral/test_mistral_reasoning.py
index 972f7fae1..789284189 100644
--- a/tests/unit/pipelex/providers/mistral/test_mistral_reasoning.py
+++ b/tests/unit/pipelex/providers/mistral/test_mistral_reasoning.py
@@ -45,59 +45,69 @@ def _mock_config(mocker: MockerFixture) -> None:
class TestMistralReasoning:
- """Tests for _resolve_prompt_mode on MistralLLMWorker."""
+ """Tests for _resolve_reasoning_effort on MistralLLMWorker."""
def test_reasoning_budget_with_thinking_mode_none_raises(self, mocker: MockerFixture):
"""reasoning_budget with thinking_mode=none gives an accurate 'does not support reasoning' error."""
worker = _make_worker(mocker, thinking_mode=ThinkingMode.NONE)
job_params = LLMJobParams(temperature=0.5, reasoning_budget=4096)
with pytest.raises(LLMCapabilityError, match="does not support reasoning"):
- worker._resolve_prompt_mode(job_params=job_params) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ worker._resolve_reasoning_effort(job_params=job_params) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
def test_reasoning_budget_with_thinking_mode_manual_raises(self, mocker: MockerFixture):
- """reasoning_budget with thinking_mode=manual raises with 'prompt_mode' guidance."""
+ """reasoning_budget with thinking_mode=manual raises with 'reasoning_effort' guidance."""
worker = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL)
job_params = LLMJobParams(temperature=0.5, reasoning_budget=4096)
- with pytest.raises(LLMCapabilityError, match="reasoning_budget"):
- worker._resolve_prompt_mode(job_params=job_params) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ with pytest.raises(LLMCapabilityError, match="does not support reasoning_budget; Mistral uses reasoning_effort instead"):
+ worker._resolve_reasoning_effort(job_params=job_params) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
@pytest.mark.parametrize(
- ("effort", "expected_prompt_mode"),
+ ("effort", "expected_mistral_effort"),
[
- (ReasoningEffort.MINIMAL, "reasoning"),
- (ReasoningEffort.LOW, "reasoning"),
- (ReasoningEffort.MEDIUM, "reasoning"),
- (ReasoningEffort.HIGH, "reasoning"),
- (ReasoningEffort.XHIGH, "reasoning"),
- (ReasoningEffort.MAX, "reasoning"),
+ (ReasoningEffort.MINIMAL, "high"),
+ (ReasoningEffort.LOW, "high"),
+ (ReasoningEffort.MEDIUM, "high"),
+ (ReasoningEffort.HIGH, "high"),
+ (ReasoningEffort.XHIGH, "high"),
+ (ReasoningEffort.MAX, "high"),
],
)
def test_reasoning_effort_maps_correctly(
self,
mocker: MockerFixture,
effort: ReasoningEffort,
- expected_prompt_mode: str,
+ expected_mistral_effort: str,
):
- """Each non-NONE ReasoningEffort maps to prompt_mode='reasoning'."""
+ """Each non-NONE ReasoningEffort maps to the `reasoning` level, which Mistral turns on as reasoning_effort `high`."""
worker = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL)
_mock_config(mocker)
job_params = LLMJobParams(temperature=0.5, reasoning_effort=effort)
- result = worker._resolve_prompt_mode(job_params=job_params) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
- assert result == expected_prompt_mode
+ result = worker._resolve_reasoning_effort(job_params=job_params) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ assert result == expected_mistral_effort
def test_thinking_mode_none_raises_capability_error(self, mocker: MockerFixture):
"""Models with thinking_mode=none should raise LLMCapabilityError."""
worker = _make_worker(mocker, thinking_mode=ThinkingMode.NONE)
job_params = LLMJobParams(temperature=0.5, reasoning_effort=ReasoningEffort.HIGH)
with pytest.raises(LLMCapabilityError, match="does not support reasoning"):
- worker._resolve_prompt_mode(job_params=job_params) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ worker._resolve_reasoning_effort(job_params=job_params) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
def test_thinking_mode_adaptive_raises_capability_error(self, mocker: MockerFixture):
"""Adaptive thinking mode is not applicable to Mistral models."""
worker = _make_worker(mocker, thinking_mode=ThinkingMode.ADAPTIVE)
job_params = LLMJobParams(temperature=0.5, reasoning_effort=ReasoningEffort.HIGH)
with pytest.raises(LLMCapabilityError, match="adaptive"):
- worker._resolve_prompt_mode(job_params=job_params) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ worker._resolve_reasoning_effort(job_params=job_params) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ def test_none_effort_omits_the_parameter(self, mocker: MockerFixture):
+ """NONE maps to disabled, so the parameter is left out and the model does not reason."""
+ from mistralai.client.types import UNSET # ruff: ignore[import-outside-top-level]
+
+ worker = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL)
+ _mock_config(mocker)
+ job_params = LLMJobParams(temperature=0.5, reasoning_effort=ReasoningEffort.NONE)
+ result = worker._resolve_reasoning_effort(job_params=job_params) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ assert result is UNSET
def test_no_reasoning_params_returns_unset(self, mocker: MockerFixture):
"""When neither reasoning_effort nor reasoning_budget is set, returns UNSET."""
@@ -105,5 +115,5 @@ class TestMistralReasoning:
worker = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL)
job_params = LLMJobParams(temperature=0.5)
- result = worker._resolve_prompt_mode(job_params=job_params) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ result = worker._resolve_reasoning_effort(job_params=job_params) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
assert result is UNSET
diff --git a/tests/unit/pipelex/providers/mistral/test_mistral_structured_request.py b/tests/unit/pipelex/providers/mistral/test_mistral_structured_request.py
new file mode 100644
index 000000000..b7169bdda
--- /dev/null
+++ b/tests/unit/pipelex/providers/mistral/test_mistral_structured_request.py
@@ -0,0 +1,71 @@
+"""The request the Mistral worker's structured call sends, with and without a reasoning setting.
+
+Mistral refuses `prompt_mode="reasoning"` on every current model and takes `reasoning_effort` instead, through
+instructor's tool path as on a plain call. The call is driven through a real instructor client over a Mistral SDK
+client that answers with a tool call beside a thinking chunk, the shape a reasoning Mistral model returns.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pipelex.cogt.exceptions import LLMCapabilityError
+from pipelex.cogt.llm.llm_job_components import ReasoningEffort
+from pipelex.cogt.llm.structured_output import StructureMethod
+from pipelex.cogt.llm.thinking_mode import ThinkingMode
+from tests.helpers.instructor_test_utils import DummySchema, make_llm_job
+from tests.helpers.mistral_request import is_unset, make_worker, sent_request, tool_call_response
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
+
[email protected](loop_scope="class")
+class TestMistralStructuredRequest:
+ async def test_a_reasoning_effort_reaches_the_api_as_reasoning_effort(self, mocker: MockerFixture) -> None:
+ worker, complete_async = make_worker(mocker, thinking_mode=ThinkingMode.MANUAL, response=tool_call_response())
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.MEDIUM
+
+ result = await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ assert result.text == "answer"
+ request = sent_request(complete_async)
+ assert request["reasoning_effort"] == "high"
+ assert is_unset(request, "prompt_mode")
+ assert request["tool_choice"] == "any"
+
+ async def test_without_a_reasoning_setting_no_effort_is_sent(self, mocker: MockerFixture) -> None:
+ worker, complete_async = make_worker(mocker, thinking_mode=ThinkingMode.MANUAL, response=tool_call_response())
+
+ await worker._gen_object(llm_job=make_llm_job(mocker), schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ request = sent_request(complete_async)
+ assert is_unset(request, "reasoning_effort")
+ assert request["temperature"] == 0.5
+
+ async def test_a_model_without_reasoning_refuses_it_as_its_text_path_does(self, mocker: MockerFixture) -> None:
+ worker, complete_async = make_worker(mocker, thinking_mode=ThinkingMode.NONE, response=tool_call_response())
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.HIGH
+
+ with pytest.raises(LLMCapabilityError, match=r"does not support reasoning \(thinking_mode=none\)"):
+ await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ complete_async.assert_not_awaited()
+
+ async def test_a_json_structure_method_refuses_reasoning(self, mocker: MockerFixture) -> None:
+ """A reasoning reply's content is a list of chunks, which instructor's JSON parsers cannot read, so the call is refused up front."""
+ worker, complete_async = make_worker(
+ mocker,
+ thinking_mode=ThinkingMode.MANUAL,
+ response=tool_call_response(),
+ structure_method=StructureMethod.INSTRUCTOR_MISTRAL_STRUCTURED_OUTPUTS,
+ )
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.HIGH
+
+ with pytest.raises(LLMCapabilityError, match="instructor/mistral_tools"):
+ await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ complete_async.assert_not_awaited()
diff --git a/tests/unit/pipelex/providers/mistral/test_mistral_text_request.py b/tests/unit/pipelex/providers/mistral/test_mistral_text_request.py
new file mode 100644
index 000000000..2d9ae403e
--- /dev/null
+++ b/tests/unit/pipelex/providers/mistral/test_mistral_text_request.py
@@ -0,0 +1,40 @@
+"""The request the Mistral worker's text call sends, with and without a reasoning setting.
+
+Mistral refuses `prompt_mode="reasoning"` on every current model and takes `reasoning_effort` instead.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pipelex.cogt.llm.llm_job_components import ReasoningEffort
+from pipelex.cogt.llm.thinking_mode import ThinkingMode
+from tests.helpers.instructor_test_utils import make_llm_job
+from tests.helpers.mistral_request import is_unset, make_worker, sent_request, text_response
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
+
[email protected](loop_scope="class")
+class TestMistralTextRequest:
+ async def test_a_reasoning_effort_reaches_the_api_as_reasoning_effort(self, mocker: MockerFixture) -> None:
+ worker, complete_async = make_worker(mocker, thinking_mode=ThinkingMode.MANUAL, response=text_response())
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.HIGH
+
+ result = await worker._gen_text(llm_job=llm_job) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ assert result == "answer"
+ request = sent_request(complete_async)
+ assert request["reasoning_effort"] == "high"
+ assert is_unset(request, "prompt_mode")
+
+ async def test_without_a_reasoning_setting_no_effort_is_sent(self, mocker: MockerFixture) -> None:
+ worker, complete_async = make_worker(mocker, thinking_mode=ThinkingMode.MANUAL, response=text_response())
+
+ await worker._gen_text(llm_job=make_llm_job(mocker)) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ assert is_unset(sent_request(complete_async), "reasoning_effort")
diff --git a/tests/unit/pipelex/providers/openai/test_openai_completions_structured_request.py b/tests/unit/pipelex/providers/openai/test_openai_completions_structured_request.py
new file mode 100644
index 000000000..fcbf79178
--- /dev/null
+++ b/tests/unit/pipelex/providers/openai/test_openai_completions_structured_request.py
@@ -0,0 +1,141 @@
+"""The request the OpenAI chat-completions worker's structured call sends, with and without a reasoning setting.
+
+Driven through a real instructor client over an OpenAI SDK client whose ``chat.completions.create`` records the
+request and answers with a tool call, so what is asserted is what instructor actually sends. The worker
+forwards a reasoning effort exactly as its text path does; whether a server accepts it beside function tools
+is the server's call, as OpenAI's own chat completions refuses it on GPT-5.x while gateways serving Claude and
+Gemini through this worker take it.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from openai import AsyncOpenAI, Omit
+from openai.types.chat import ChatCompletion, ChatCompletionMessage, ChatCompletionMessageToolCall
+from openai.types.chat.chat_completion import Choice
+from openai.types.chat.chat_completion_message_tool_call import Function
+
+from pipelex.cogt.exceptions import LLMCapabilityError
+from pipelex.cogt.llm.llm_job_components import ReasoningEffort
+from pipelex.cogt.llm.structured_output import StructureMethod
+from pipelex.cogt.llm.thinking_mode import ThinkingMode
+from pipelex.cogt.model_backends.constraints import ListedConstraint
+from pipelex.providers.openai.openai_completions_factory import OpenAICompletionsFactory
+from pipelex.providers.openai.openai_completions_llm_worker import OpenAICompletionsLLMWorker
+from pipelex.providers.openai.openai_config import OpenAIConfig
+from tests.helpers.instructor_test_utils import DummySchema, make_llm_job
+
+if TYPE_CHECKING:
+ from unittest.mock import AsyncMock
+
+ from pytest_mock import MockerFixture
+
+_OPENAI_LEVEL_MAP: dict[str, str] = {
+ "none": "none",
+ "minimal": "minimal",
+ "low": "low",
+ "medium": "medium",
+ "high": "high",
+ "xhigh": "xhigh",
+ "max": "xhigh",
+}
+
+
+def _tool_call_completion() -> ChatCompletion:
+ tool_call = ChatCompletionMessageToolCall(
+ id="call_test",
+ type="function",
+ function=Function(name="DummySchema", arguments=json.dumps({"text": "answer"})),
+ )
+ return ChatCompletion(
+ id="chatcmpl_test",
+ object="chat.completion",
+ created=0,
+ model="test-model",
+ choices=[Choice(index=0, finish_reason="tool_calls", message=ChatCompletionMessage(role="assistant", content=None, tool_calls=[tool_call]))],
+ )
+
+
+def _make_worker(
+ mocker: MockerFixture,
+ *,
+ thinking_mode: ThinkingMode,
+ listed_constraints: list[ListedConstraint] | None = None,
+) -> tuple[OpenAICompletionsLLMWorker, AsyncMock]:
+ """A worker whose instructor client is built as the worker builds it, over an SDK call that records the request."""
+ from instructor import from_openai # ruff: ignore[import-outside-top-level]
+
+ sdk_client = AsyncOpenAI(api_key="test-key")
+ create = mocker.AsyncMock(return_value=_tool_call_completion())
+ mocker.patch.object(sdk_client.chat.completions, "create", new=create)
+
+ worker = object.__new__(OpenAICompletionsLLMWorker)
+ model = mocker.MagicMock()
+ model.desc = "test-model-desc"
+ model.model_id = "test-model"
+ model.name = "test-model"
+ model.thinking_mode = thinking_mode
+ model.extra_headers = None
+ model.listed_constraints = listed_constraints or []
+ worker.inference_model = model
+ worker.openai_completions_factory = OpenAICompletionsFactory(is_http_url_enabled=False)
+ worker.instructor_for_objects = from_openai(client=sdk_client, mode=StructureMethod.INSTRUCTOR_OPENAI_TOOLS.as_instructor_mode())
+
+ config = mocker.MagicMock()
+ config.inference.llm.openai = OpenAIConfig(effort_to_level_map=_OPENAI_LEVEL_MAP)
+ mocker.patch("pipelex.providers.openai.openai_completions_llm_worker.get_config", return_value=config)
+ return worker, create
+
+
+def _sent_request(create: AsyncMock) -> dict[str, Any]:
+ create.assert_awaited_once()
+ await_args = create.await_args
+ assert await_args is not None
+ return dict(await_args.kwargs)
+
+
+def _is_omitted(request: dict[str, Any], key: str) -> bool:
+ return key not in request or isinstance(request[key], Omit)
+
+
[email protected](loop_scope="class")
+class TestOpenAICompletionsStructuredRequest:
+ async def test_a_reasoning_effort_reaches_the_api_and_drops_the_temperature(self, mocker: MockerFixture) -> None:
+ worker, create = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL)
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.LOW
+
+ result = await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ assert result.text == "answer"
+ request = _sent_request(create)
+ assert request["reasoning_effort"] == "low"
+ assert _is_omitted(request, "temperature")
+
+ async def test_without_a_reasoning_setting_the_request_is_unchanged(self, mocker: MockerFixture) -> None:
+ worker, create = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL)
+
+ await worker._gen_object(llm_job=make_llm_job(mocker), schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ request = _sent_request(create)
+ assert _is_omitted(request, "reasoning_effort")
+ assert request["temperature"] == 0.5
+
+ async def test_a_model_refusing_temperature_still_omits_it_without_reasoning(self, mocker: MockerFixture) -> None:
+ worker, create = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL, listed_constraints=[ListedConstraint.TEMPERATURE_UNSUPPORTED])
+
+ await worker._gen_object(llm_job=make_llm_job(mocker), schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ assert _is_omitted(_sent_request(create), "temperature")
+
+ async def test_a_model_without_reasoning_refuses_it_as_its_text_path_does(self, mocker: MockerFixture) -> None:
+ worker, create = _make_worker(mocker, thinking_mode=ThinkingMode.NONE)
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.HIGH
+
+ with pytest.raises(LLMCapabilityError, match=r"does not support reasoning \(thinking_mode=none\)"):
+ await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ create.assert_not_awaited()
diff --git a/tests/unit/pipelex/providers/openai/test_openai_responses_structured_request.py b/tests/unit/pipelex/providers/openai/test_openai_responses_structured_request.py
new file mode 100644
index 000000000..2ef57bfd6
--- /dev/null
+++ b/tests/unit/pipelex/providers/openai/test_openai_responses_structured_request.py
@@ -0,0 +1,135 @@
+"""The request the OpenAI Responses worker's structured call sends, with and without a reasoning setting.
+
+Driven through a real instructor client in ``RESPONSES_TOOLS`` mode over an OpenAI SDK client whose
+``responses.create`` records the request and answers with a function call, so what is asserted is what
+instructor actually sends. The hosted plane's ``manifold_responses`` SDK runs this worker, so a reasoning
+preset on a structured pipe reaches the gateway through exactly this request.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from openai import AsyncOpenAI, Omit
+from openai.types.responses import Response, ResponseFunctionToolCall
+
+from pipelex.cogt.exceptions import LLMCapabilityError
+from pipelex.cogt.llm.llm_job_components import ReasoningEffort
+from pipelex.cogt.llm.structured_output import StructureMethod
+from pipelex.cogt.llm.thinking_mode import ThinkingMode
+from pipelex.providers.openai.openai_config import OpenAIConfig
+from pipelex.providers.openai.openai_responses_factory import OpenAIResponsesFactory
+from pipelex.providers.openai.openai_responses_llm_worker import OpenAIResponsesLLMWorker
+from tests.helpers.instructor_test_utils import DummySchema, make_llm_job
+
+if TYPE_CHECKING:
+ from unittest.mock import AsyncMock
+
+ from pytest_mock import MockerFixture
+
+_OPENAI_LEVEL_MAP: dict[str, str] = {
+ "none": "none",
+ "minimal": "minimal",
+ "low": "low",
+ "medium": "medium",
+ "high": "high",
+ "xhigh": "xhigh",
+ "max": "xhigh",
+}
+
+
+def _function_call_response() -> Response:
+ return Response(
+ id="resp_test",
+ created_at=0,
+ model="gpt-test",
+ object="response",
+ output=[ResponseFunctionToolCall(type="function_call", call_id="call_test", name="DummySchema", arguments=json.dumps({"text": "answer"}))],
+ parallel_tool_calls=False,
+ tool_choice="auto",
+ tools=[],
+ )
+
+
+def _make_worker(mocker: MockerFixture, *, thinking_mode: ThinkingMode) -> tuple[OpenAIResponsesLLMWorker, AsyncMock]:
+ """A worker whose instructor client is built as the worker builds it, over an SDK call that records the request."""
+ from instructor import from_openai # ruff: ignore[import-outside-top-level]
+
+ sdk_client = AsyncOpenAI(api_key="test-key")
+ create = mocker.AsyncMock(return_value=_function_call_response())
+ mocker.patch.object(sdk_client.responses, "create", new=create)
+
+ worker = object.__new__(OpenAIResponsesLLMWorker)
+ model = mocker.MagicMock()
+ model.desc = "test-model-desc"
+ model.model_id = "gpt-test"
+ model.name = "gpt-test"
+ model.thinking_mode = thinking_mode
+ model.extra_headers = None
+ worker.inference_model = model
+ factory = OpenAIResponsesFactory(is_http_url_enabled=False)
+ mocker.patch.object(factory, "make_input_items", new_callable=mocker.AsyncMock, return_value=[{"role": "user", "content": "Generate."}])
+ worker.openai_responses_factory = factory
+ worker.instructor_for_objects = from_openai(client=sdk_client, mode=StructureMethod.INSTRUCTOR_OPENAI_RESPONSES_TOOLS.as_instructor_mode())
+
+ config = mocker.MagicMock()
+ config.inference.llm.openai = OpenAIConfig(effort_to_level_map=_OPENAI_LEVEL_MAP)
+ mocker.patch("pipelex.providers.openai.openai_responses_llm_worker.get_config", return_value=config)
+ return worker, create
+
+
+def _sent_request(create: AsyncMock) -> dict[str, Any]:
+ create.assert_awaited_once()
+ await_args = create.await_args
+ assert await_args is not None
+ return dict(await_args.kwargs)
+
+
+def _is_omitted(request: dict[str, Any], key: str) -> bool:
+ return key not in request or isinstance(request[key], Omit)
+
+
[email protected](loop_scope="class")
+class TestOpenAIResponsesStructuredRequest:
+ async def test_a_reasoning_effort_reaches_the_api_and_drops_the_temperature(self, mocker: MockerFixture) -> None:
+ worker, create = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL)
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.HIGH
+
+ result = await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ assert result.text == "answer"
+ request = _sent_request(create)
+ assert request["reasoning"] == {"effort": "high"}
+ assert _is_omitted(request, "temperature")
+ # The structuring path itself is unchanged: the response tool is still the forced one
+ assert request["tool_choice"] == {"type": "function", "name": "DummySchema"}
+
+ async def test_without_a_reasoning_setting_the_request_is_unchanged(self, mocker: MockerFixture) -> None:
+ worker, create = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL)
+
+ await worker._gen_object(llm_job=make_llm_job(mocker), schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+
+ request = _sent_request(create)
+ assert _is_omitted(request, "reasoning")
+ assert request["temperature"] == 0.5
+
+ async def test_a_model_without_reasoning_refuses_it_as_its_text_path_does(self, mocker: MockerFixture) -> None:
+ worker, create = _make_worker(mocker, thinking_mode=ThinkingMode.NONE)
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_effort = ReasoningEffort.HIGH
+
+ with pytest.raises(LLMCapabilityError, match=r"does not support reasoning \(thinking_mode=none\)"):
+ await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ create.assert_not_awaited()
+
+ async def test_a_reasoning_budget_is_refused_as_its_text_path_does(self, mocker: MockerFixture) -> None:
+ worker, create = _make_worker(mocker, thinking_mode=ThinkingMode.MANUAL)
+ llm_job = make_llm_job(mocker)
+ llm_job.job_params.reasoning_budget = 4096
+
+ with pytest.raises(LLMCapabilityError, match="does not support reasoning_budget; OpenAI uses reasoning_effort instead"):
+ await worker._gen_object(llm_job=llm_job, schema=DummySchema) # ruff: ignore[private-member-access] # pyright: ignore[reportPrivateUsage]
+ create.assert_not_awaited()