ooai_llm.reasoning

Provider-aware reasoning configuration.

Purpose:

Normalize one ergonomic reasoning policy into provider-specific keyword arguments for chat-model construction.

Design:

• Accept either string presets or a typed configuration object.

• Keep provider differences explicit through a structured resolution object that records notes about lossy mappings and unsupported options.

• Focus on constructor kwargs consumed by create_llm(...) while leaving room for future invoke-time configuration.

Type aliases:

ReasoningPresetName: Semantic presets for common reasoning modes. ReasoningEffortName: Provider-agnostic effort scale. ReasoningSummaryName: Cross-provider summary visibility preference.

Examples

>>> from ooai_llm.types import ModelString
>>> resolution = build_reasoning_resolution(
...     model=ModelString.parse("openai:gpt-5.4-mini"),
...     reasoning="deep",
... )
>>> resolution.constructor_kwargs["reasoning"]["effort"]
'high'
>>> resolution.provider.value
'openai'

Attributes

ReasoningPresetName
ReasoningEffortName
ReasoningSummaryName
ReasoningInput

Classes

ReasoningConfig	Provider-agnostic reasoning preferences.
ReasoningResolution	Provider-specific reasoning kwargs resolution.

Functions

build_reasoning_resolution(→ ReasoningResolution | None)

Resolve provider-specific reasoning kwargs.

Module Contents

ooai_llm.reasoning.ReasoningPresetName

ooai_llm.reasoning.ReasoningEffortName

ooai_llm.reasoning.ReasoningSummaryName

class ooai_llm.reasoning.ReasoningConfig(/, **data: Any)

Bases: pydantic.BaseModel

Provider-agnostic reasoning preferences.

Parameters:

• effort – Normalized reasoning effort.

• summary – Desired reasoning-summary visibility.

• budget_tokens – Optional explicit reasoning-budget token count.

• dynamic_budget – Whether the provider should choose the budget when it exposes a dynamic mode.

• include_thoughts – Whether provider-visible thought summaries should be included when supported.

• strict – Whether unsupported or lossy mappings should raise errors.

Examples

>>> config = ReasoningConfig.from_preset("balanced")
>>> config.effort
'medium'
>>> config.summary
'auto'

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

effort: ReasoningEffortName = 'auto'

summary: ReasoningSummaryName = 'auto'

budget_tokens: int | None = None

dynamic_budget: bool | None = None

include_thoughts: bool = False

strict: bool = False

property enabled: bool

Whether reasoning is conceptually enabled.

Returns:

True when reasoning is enabled or a nonzero budget is present.

classmethod from_preset(preset: ReasoningPresetName) → Self

Build a configuration from a semantic preset.

Parameters:

preset – Semantic preset name.

Returns:

Normalized reasoning configuration.

Raises:

ValueError – If the preset is unknown.

classmethod normalize(reasoning: ReasoningInput) → Self | None

Normalize string or typed input into a config object.

Parameters:

reasoning – Reasoning input.

Returns:

Typed config or None when reasoning is absent.

Raises:

ValueError – If the string value is unknown.

type ooai_llm.reasoning.ReasoningInput = ReasoningConfig | ReasoningPresetName | ReasoningEffortName | None

class ooai_llm.reasoning.ReasoningResolution(/, **data: Any)

Bases: pydantic.BaseModel

Provider-specific reasoning kwargs resolution.

Parameters:

• model – Canonical model string.

• provider – Resolved provider.

• config – Normalized reasoning config.

• constructor_kwargs – Keyword arguments suitable for chat-model construction.

• invoke_kwargs – Reserved for future invoke-time reasoning configuration.

• notes – Informational notes about ignored or lossy mappings.

Examples

>>> resolution = ReasoningResolution(
...     model=ModelString.parse("openai:gpt-5.4"),
...     provider=Provider.OPENAI,
...     config=ReasoningConfig(),
... )
>>> resolution.constructor_kwargs
{}

model_config

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model: ooai_llm.types.ModelString

provider: ooai_llm.providers.Provider

config: ReasoningConfig

constructor_kwargs: dict[str, Any] = None

invoke_kwargs: dict[str, Any] = None

notes: list[str] = None

ooai_llm.reasoning.build_reasoning_resolution(*, model: str | ooai_llm.types.ModelString, provider: ooai_llm.providers.Provider | str | None = None, reasoning: ReasoningInput) → ReasoningResolution | None

Resolve provider-specific reasoning kwargs.

Parameters:

• model – Model string or typed model-string object.

• provider – Optional explicit provider.

• reasoning – Semantic preset, effort string, typed config, or None.

Returns:

Structured reasoning resolution or None when reasoning is absent.