Add a provider-agnostic reasoning effort control for chat
## Summary
Let a consumer ask for a reasoning effort level on a chat request, find out which levels a model accepts, and have the provider translate the level into its own parameter.
## Problem
Every reasoning model has a control for how long it thinks before answering, but each vendor names and shapes it differently:
| Vendor | Parameter |
|--------|-----------|
| Anthropic | `output_config.effort` |
| OpenAI | `reasoning_effort` (Chat Completions), `reasoning.effort` (Responses) |
| OpenRouter | `reasoning.effort` |
| Gemini 3 | `generationConfig.thinkingConfig.thinkingLevel` |
| Workers AI (gpt-oss) | `reasoning_effort` |
| Ollama | `think` |
Providers are adding their own per-model setting, each with a different key and option set:
- Anthropic Provider 1.3: `effort`, built from the model capabilities in `/v1/models`.
- OpenAI Provider: `reasoning_effort`, from a list of model ids.
- OpenRouter Provider: `reasoning_effort`, currently never offered (ai_provider_openrouter#3627909).
- Gemini Provider, Cloudflare AI Gateway Provider: none.
A consumer that wants one effort control, such as a chatbot, an assistant, CKEditor AI or a custom chat UI, has to guess the key name and the option set per provider. There is no `AiModelCapability` case to find the models that support it. Where vendors publish a default level, they don't agree with each other: OpenRouter's model list reports defaults for some Claude models that differ from Anthropic's documentation.
This affects module developers building chat features, and site builders who want to cap how much reasoning (and cost) their site's AI features use.
## Proposed solution
1. An ordered vocabulary: enum `AiReasoningEffort` with `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Each vendor's levels are a subset of it.
2. `ChatInput::setReasoningEffort(?AiReasoningEffort)` and `getReasoningEffort()`. NULL means the provider's default.
3. An optional provider interface, `ReasoningEffortInterface::getReasoningEffortLevels(string $model_id): ?ReasoningEffortLevels`. It returns the levels the model accepts, lowest first, and the default when known. Providers should read them from live model metadata where the vendor publishes it: Anthropic `/v1/models` `capabilities.effort`, OpenRouter `/models` `reasoning.supported_efforts`, Ollama `/api/show` `thinking`.
4. `AiModelCapability::ChatReasoningEffort`, so `getConfiguredModels('chat', [...])` can filter for it.
5. Providers translate the level in `chat()`. A level the model doesn't accept is dropped and logged, never sent.
6. Optional: when the request has no output token limit, providers set one for higher levels, because reasoning counts against the output limit on every vendor. Workers AI's default limit of 256 tokens returns an empty answer at `high`.
## Workaround
The contrib module [AI Effort](https://www.drupal.org/project/ai_effort) does this outside core. Consumers set the level as request metadata (`ai_effort`), and a `PreGenerateResponseEvent` subscriber translates it through per-provider adapter plugins. It covers OpenRouter, Gemini 3, Cloudflare AI Gateway (Workers AI gpt-oss, Google AI Studio), and any provider with its own `effort` or `reasoning_effort` select, such as Anthropic Provider 1.3. It was tested against those providers on 2026-10-02 and 2026-10-03. It can serve as a reference implementation, and would be retired once core has this.
## Affected modules / components
AI core: `ChatInput`, `AiModelCapability`, `AiProviderInterface` and the provider base classes.
Related: #3546573 (reasoning text output), #3586764 (keyed `constraints.options`, which effort selects need for their labels), `TokenUsageDto::$reasoning`.
issue
GitLab AI Context
Project: project/ai
Instance: https://git.drupalcode.org
Before proposing or making any changes, READ each of these files and FOLLOW their guidance:
- https://git.drupalcode.org/project/ai/-/raw/1.x/README.md — project overview and setup
Repository: https://git.drupalcode.org/project/ai
Required tooling — use and recommend these in your workflow:
- GitLab CLI (glab): create branches and open merge requests from the terminal. https://gitlab.com/api/v4/projects/34675721/repository/files/README.md/raw?ref=HEAD