ooai_llm.factory

Chat-model factory helpers.

Purpose:

Provide an ergonomic wrapper around LangChain’s init_chat_model that integrates app settings, default model resolution, optional reasoning adaptation, temporary native environment-variable injection, and optional metadata bundling that merges LangChain profiles with native LiteLLM pricing.

Design:

  • Keep create_llm thin and transparent.

  • Reuse ooai_llm.types.ModelString, ooai_llm.settings.AppSettings, and ooai_llm.reasoning.

  • Use a context manager to mirror app-prefixed credentials into the provider-native environment variable names expected by integration packages.

  • Allow explicit **kwargs to override any auto-generated constructor kwargs such as cache or provider-specific reasoning settings.

Examples

>>> settings = AppSettings()
>>> resolved = resolve_model_string(settings=settings, alias="testing")
>>> resolved.model_name == "gpt-5.4-nano"
True

Attributes

logger

Functions

resolve_model_string(→ ooai_llm.types.ModelString)

Resolve the effective model string from settings and call arguments.

resolve_factory_settings(→ ooai_llm.settings.AppSettings)

Resolve settings for a factory call, applying opt-in model refresh.

native_environment_overrides(→ Iterator[None])

Temporarily set provider-native environment variables from settings.

create_llm(→ langchain.chat_models.base.BaseChatModel)

Create a LangChain chat model.

create_llm_bundle(→ ooai_llm.metadata.CreatedLLMBundle)

Create a chat model and resolve merged metadata for it.

Module Contents

ooai_llm.factory.logger[source]
ooai_llm.factory.resolve_model_string(*, settings: ooai_llm.settings.AppSettings, model: str | ooai_llm.types.ModelString | None = None, alias: ooai_llm.settings.ModelAliasName | None = None, provider: ooai_llm.providers.Provider | str | None = None, preset: ooai_llm.settings.ModelPresetName = 'default') → ooai_llm.types.ModelString[source]

Resolve the effective model string from settings and call arguments.

Parameters:

  • settings – Application settings.

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

  • alias – Optional semantic alias.

  • provider – Optional provider enum or alias.

  • preset – Provider-specific preset name.

Returns:

Typed model-string object.

ooai_llm.factory.resolve_factory_settings(settings: ooai_llm.settings.AppSettings | None = None, *, auto_refresh_models: bool | None = None, force_model_refresh: bool = False) → ooai_llm.settings.AppSettings[source]

Resolve settings for a factory call, applying opt-in model refresh.

Parameters:

  • settings – Optional application settings.

  • auto_refresh_models – Optional per-call override for settings.llm.auto_refresh_models.enabled.

  • force_model_refresh – Whether to bypass the process-local refresh cache.

Returns:

Original or refreshed settings.

ooai_llm.factory.native_environment_overrides(settings: ooai_llm.settings.AppSettings, *, force: bool = False) → Iterator[None][source]

Temporarily set provider-native environment variables from settings.

Parameters:

  • settings – Application settings.

  • force – Whether to overwrite existing environment variables.

Yields:

None while the temporary environment is active.

ooai_llm.factory.create_llm(model: str | ooai_llm.types.ModelString | None = None, *, settings: ooai_llm.settings.AppSettings | None = None, alias: ooai_llm.settings.ModelAliasName | None = None, provider: ooai_llm.providers.Provider | str | None = None, preset: ooai_llm.settings.ModelPresetName = 'default', cache: BaseCache | bool | None = None, reasoning: ooai_llm.reasoning.ReasoningInput = None, auto_refresh_models: bool | None = None, force_model_refresh: bool = False, configurable_fields: str | list[str] | tuple[str, Ellipsis] | None = None, config_prefix: str | None = None, **kwargs: Any) → langchain.chat_models.base.BaseChatModel[source]

Create a LangChain chat model.

Parameters:

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

  • settings – Optional application settings. Defaults to AppSettings().

  • alias – Optional semantic alias used when model is omitted.

  • provider – Optional provider used when model is omitted or bare.

  • preset – Provider preset used with provider.

  • cache – Optional per-model cache override.

  • reasoning – Optional semantic reasoning preset, reasoning-effort string, or typed ooai_llm.reasoning.ReasoningConfig.

  • auto_refresh_models – Opt-in model-default refresh before model resolution. Defaults to settings.llm.auto_refresh_models.enabled.

  • force_model_refresh – Bypass the process-local model-default refresh cache when automatic refresh is enabled.

  • configurable_fields – Optional LangChain configurable field spec.

  • config_prefix – Optional LangChain configuration prefix.

  • **kwargs – Additional keyword arguments passed to init_chat_model. Explicit kwargs override auto-generated cache and reasoning kwargs.

Returns:

LangChain chat model instance.

Raises:

ImportError – If langchain is not installed.

ooai_llm.factory.create_llm_bundle(model: str | ooai_llm.types.ModelString | None = None, *, settings: ooai_llm.settings.AppSettings | None = None, alias: ooai_llm.settings.ModelAliasName | None = None, provider: ooai_llm.providers.Provider | str | None = None, preset: ooai_llm.settings.ModelPresetName = 'default', cache: BaseCache | bool | None = None, reasoning: ooai_llm.reasoning.ReasoningInput = None, auto_refresh_models: bool | None = None, force_model_refresh: bool = False, billing_model_name: str | None = None, messages: ooai_llm.messages.MessagesLike | None = None, tools: list[Any] | tuple[Any, Ellipsis] | None = None, configurable_fields: str | list[str] | tuple[str, Ellipsis] | None = None, config_prefix: str | None = None, **kwargs: Any) → ooai_llm.metadata.CreatedLLMBundle[source]

Create a chat model and resolve merged metadata for it.

Parameters:

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

  • settings – Optional application settings. Defaults to AppSettings().

  • alias – Optional semantic alias used when model is omitted.

  • provider – Optional provider used when model is omitted or bare.

  • preset – Provider preset used with provider.

  • cache – Optional per-model cache override.

  • reasoning – Optional reasoning preset or typed config.

  • auto_refresh_models – Opt-in model-default refresh before model resolution. Defaults to settings.llm.auto_refresh_models.enabled.

  • force_model_refresh – Bypass the process-local model-default refresh cache when automatic refresh is enabled.

  • billing_model_name – Optional explicit LiteLLM billing-model override.

  • messages – Optional message input used for best-effort token estimates.

  • tools – Optional tool schema list used for token estimation.

  • configurable_fields – Optional LangChain configurable field spec.

  • config_prefix – Optional LangChain configuration prefix.

  • **kwargs – Additional keyword arguments passed to init_chat_model.

Returns:

Convenience bundle containing the created LLM, the typed model string, resolved metadata, and the applied reasoning resolution.