feat(llm): reasoning levels (LLMOptions.reasoning_effort)

[treo]

Thinking models all have a reasoning level dial, and none of them spell it the same way. LLMOptions had temperature, top_p, max_tokens, stop_sequences, functions and vendor_specific, so asking for less thinking meant either hand-writing a provider-specific payload or not asking at all.

This adds one framework-level option and lets each provider implementation translate it into the shape its API expects.

from xaibo.core.models.llm import LLMOptions

response = await llm.generate(messages, LLMOptions(reasoning_effort="high"))

What's in the core

ReasoningEffort — none / minimal / low / medium / high / xhigh / max, the union of what these APIs accept today — and one optional field. Unset is the default and sends nothing at all, which is what makes this non-breaking: a
request that doesn't ask for a level carries no reasoning field (verified on all four providers' request builders, see Testing).

The core carries the vocabulary only. How a level reaches the wire is each provider's business, the same way its message format and usage fields already are — the protocol/implementation split is the reason. Three rules the option
asks of every implementation are documented on the enum itself, where someone writing a provider will read them:

• unset sends nothing — a model not asked how much to think uses its own
  default; inventing a value would make a UI's "default" a lie;
• a level the model cannot express is lowered, never dropped — asking for
  more thinking and silently getting none is the wrong direction of error;
• a model with no off switch has no NONE — take its lowest rung instead of
  sending a disable flag it rejects.

What each provider sends

provider	fields	reasoning_mode
OpenAILLM	reasoning_effort — already that API's own name, so there is nothing to map	—
AnthropicLLM	thinking: {type: adaptive} + output_config.effort, or thinking: {type: enabled, budget_tokens} + a raised max_tokens	"effort" (default) / "budget"
BedrockLLM	the same Anthropic fields, in additionalModelRequestFields; the ceiling is inferenceConfig.maxTokens	"effort" / "budget" / "off"
GoogleLLM	thinkingConfig.thinking_level (enum) or thinkingConfig.thinking_budget (tokens)	"level" (default) / "budget"

The shape is a constructor choice because the same vendor changed spelling between generations: Anthropic's thinking.budget_tokens is deprecated on Claude 4.6 and 400-rejected by 4.7+, which take output_config.effort; Gemini's thinkingLevel errors on 2.5, which take a budget. A level alone cannot pick the shape, so the module asks which one its model speaks. Defaults are the shape current models accept — the deprecated form is the opt-in.

Clamping, per the rules above: minimal → low on Claude (not on its ladder), xhigh/max → HIGH on Gemini (its enum stops there), none → LOW on Gemini 3 (which cannot disable thinking) but thinking: {type: "disabled"} on
Claude (which can). Budget-shaped requests get their output ceiling raised to fit the budget: thinking tokens are billed against max_tokens, which must be strictly above it, or the response comes back truncated.

vendor_specific always wins for the same field — someone who wrote thinking or thinking_config by hand meant it, so the level is applied first and only fills a gap. reasoning_mode is excluded from each module's default_kwargs, so it never leaks into a request body.