ooai_llm.settings

Settings models for ooai_llm.

Purpose:

Centralize application configuration for provider credentials, default model selection, and LangChain LLM cache behavior.

Design:

• Accept both app-prefixed and provider-native environment variables.

• Keep model defaults configurable through semantic aliases and per-provider preset bundles.

• Expose the application directory and default cache path as computed values derived from the working directory.

• Make model-string defaults reusable through a typed ModelString.

Type aliases:

ModelPresetName: Semantic preset names available per provider. ModelAliasName: Global semantic aliases.

Examples

>>> settings = AppSettings()
>>> settings.resolve_model(alias="testing")
'openai:gpt-5.4-nano'

Attributes

ModelPresetName
ModelAliasName

Classes

ProviderCredentials	Provider credentials with native-env fallback aliases.
ProviderModelPresets	Provider-specific model presets.
DefaultModelsByProvider	Default model presets keyed by provider.
DefaultModelAliases	Global semantic aliases for common model selections.
CatalogProviderSettings	Provider-specific model-catalog settings.
CatalogSettings	Settings for live model discovery and provider catalog access.
LiteLLMSettings	Native LiteLLM integration settings.
ModelDefaultsAutoRefreshSettings	Factory-time model-default refresh settings.
LLMCacheSettings	LLM cache configuration.
LLMSettings	Top-level LLM settings.
AppSettings	Application settings for the LLM layer.

Module Contents

ooai_llm.settings.ModelPresetName

ooai_llm.settings.ModelAliasName

class ooai_llm.settings.ProviderCredentials(/, **data: Any)

Bases: pydantic.BaseModel

Provider credentials with native-env fallback aliases.

Parameters:

• openai_api_key – OpenAI API key.

• anthropic_api_key – Anthropic API key.

• google_api_key – Google or Gemini API key.

• xai_api_key – xAI API key.

• deepseek_api_key – DeepSeek API key.

• mistral_api_key – Mistral API key.

• google_use_vertexai – Whether to route Gemini through Vertex AI.

• google_cloud_project – Optional Google Cloud project ID.

• google_cloud_location – Optional Google Cloud location.

Examples

>>> creds = ProviderCredentials()
>>> isinstance(creds, ProviderCredentials)
True

model_config

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

openai_api_key: pydantic.SecretStr | None = None

anthropic_api_key: pydantic.SecretStr | None = None

google_api_key: pydantic.SecretStr | None = None

xai_api_key: pydantic.SecretStr | None = None

deepseek_api_key: pydantic.SecretStr | None = None

mistral_api_key: pydantic.SecretStr | None = None

google_use_vertexai: bool | None = None

google_cloud_project: str | None = None

google_cloud_location: str | None = None

classmethod from_environment() → Self

Build provider credentials from native and app-scoped env vars.

Returns:

Credentials populated from environment variables.

get_api_key(provider: ooai_llm.providers.Provider | str) → str | None

Return the resolved API key for a provider.

Parameters:

provider – Canonical provider or provider alias.

Returns:

The plain API key string, or None when unavailable.

require_api_key(provider: ooai_llm.providers.Provider | str) → str

Return the API key for a provider or raise.

Parameters:

provider – Canonical provider or provider alias.

Returns:

The plain API key string.

Raises:

ValueError – If no API key is configured for the provider.

to_native_environment() → dict[str, str]

Return provider-native environment variables.

Returns:

Mapping of native environment-variable names to string values.

class ooai_llm.settings.ProviderModelPresets(/, **data: Any)

Bases: pydantic.BaseModel

Provider-specific model presets.

Parameters:

• default – Recommended default model for general use.

• latest – Latest recommended model when dynamic defaults are refreshed.

• cheap – Lowest-cost reasonable default.

• testing – Lightweight default for development and smoke tests.

• fast – Lower-latency model.

• balanced – Balanced cost/performance model.

• reasoning – Stronger reasoning-oriented model.

• coding – Coding-oriented model.

• vision – Vision-capable model.

Examples

>>> presets = ProviderModelPresets(
...     default="openai:gpt-5.4-mini",
...     cheap="openai:gpt-5.4-nano",
...     testing="openai:gpt-5.4-nano",
...     fast="openai:gpt-5.4-mini",
...     balanced="openai:gpt-5.4-mini",
...     reasoning="openai:gpt-5.4",
...     coding="openai:gpt-5.4",
...     vision="openai:gpt-5.4-mini",
... )
>>> presets.get("cheap")
'openai:gpt-5.4-nano'

model_config

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

default: str

latest: str | None = None

cheap: str

testing: str

fast: str

balanced: str

reasoning: str

coding: str

vision: str

get(preset: ModelPresetName) → str

Return the model configured for a preset.

Parameters:

preset – Preset name.

Returns:

Configured model string.

class ooai_llm.settings.DefaultModelsByProvider(/, **data: Any)

Bases: pydantic.BaseModel

Default model presets keyed by provider.

Notes

These defaults are intentionally practical application defaults. They are not a replacement for a live model catalog or dynamic router.

Examples

>>> defaults = DefaultModelsByProvider()
>>> defaults.openai.cheap
'openai:gpt-5.4-nano'

model_config

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

openai: ProviderModelPresets = None

anthropic: ProviderModelPresets = None

google_genai: ProviderModelPresets = None

xai: ProviderModelPresets = None

deepseek: ProviderModelPresets = None

mistral: ProviderModelPresets = None

get(provider: ooai_llm.providers.Provider | str) → ProviderModelPresets

Return the preset bundle for a provider.

Parameters:

provider – Canonical provider or alias.

Returns:

Provider-specific preset bundle.

class ooai_llm.settings.DefaultModelAliases(/, **data: Any)

Bases: pydantic.BaseModel

Global semantic aliases for common model selections.

Examples

>>> aliases = DefaultModelAliases()
>>> aliases.cheap
'openai:gpt-5.4-nano'

model_config

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

default: str = 'openai:gpt-5.4-mini'

latest: str | None = 'openai:gpt-5.5'

cheap: str = 'openai:gpt-5.4-nano'

testing: str = 'openai:gpt-5.4-nano'

fast: str = 'openai:gpt-5.4-mini'

balanced: str = 'openai:gpt-5.4-mini'

reasoning: str = 'openai:gpt-5.4'

coding: str = 'openai:gpt-5.4'

vision: str = 'openai:gpt-5.4-mini'

get(alias: ModelAliasName) → str

Return the model configured for an alias.

Parameters:

alias – Alias name.

Returns:

Configured model string.

class ooai_llm.settings.CatalogProviderSettings(/, **data: Any)

Bases: pydantic.BaseModel

Provider-specific model-catalog settings.

Parameters:

• prefer_sdk – Whether SDK-based model listing should be preferred for this provider.

• limit – Optional default cap on the number of returned models.

• page_size – Optional provider-native page size for paginated model listings.

• query_base – Optional Google GenAI flag controlling whether base models are included in listings.

• base_url – Optional provider base URL override for model listing.

• api_version – Optional provider API version override.

Examples

>>> cfg = CatalogProviderSettings(base_url="https://api.example.com/v1")
>>> cfg.base_url
'https://api.example.com/v1'

model_config

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

prefer_sdk: bool | None = None

limit: int | None = None

page_size: int | None = None

query_base: bool | None = None

base_url: str | None = None

api_version: str | None = None

class ooai_llm.settings.CatalogSettings(/, **data: Any)

Bases: pydantic.BaseModel

Settings for live model discovery and provider catalog access.

Parameters:

• prefer_sdk – Whether SDK-based model listing should be preferred by default.

• limit – Optional default cap on the number of returned models.

• page_size – Optional provider-native page size for paginated model listings.

• query_base – Optional default Google GenAI flag controlling whether base models are included in listings.

• openai – OpenAI-specific catalog settings.

• anthropic – Anthropic-specific catalog settings.

• google_genai – Google GenAI-specific catalog settings.

• xai – xAI-specific catalog settings.

• deepseek – DeepSeek-specific catalog settings.

• mistral – Mistral-specific catalog settings.

Examples

>>> catalog = CatalogSettings()
>>> catalog.xai.base_url
'https://api.x.ai'
>>> catalog.build_list_models_options('openai')['prefer_sdk']
True

model_config

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

prefer_sdk: bool = True

limit: int | None = None

page_size: int | None = None

query_base: bool | None = None

openai: CatalogProviderSettings = None

anthropic: CatalogProviderSettings = None

google_genai: CatalogProviderSettings = None

xai: CatalogProviderSettings = None

deepseek: CatalogProviderSettings = None

mistral: CatalogProviderSettings = None

get(provider: ooai_llm.providers.Provider | str) → CatalogProviderSettings

Return catalog settings for a provider.

Parameters:

provider – Canonical provider or provider alias.

Returns:

Provider-specific catalog settings.

build_list_models_options(provider: ooai_llm.providers.Provider | str) → dict[str, object]

Build default list-model options for a provider.

Parameters:

provider – Canonical provider or provider alias.

Returns:

Dictionary of options that can seed ListModelsConfig.

build_transport_kwargs(provider: ooai_llm.providers.Provider | str) → dict[str, str]

Build provider-specific transport overrides for model discovery.

Parameters:

provider – Canonical provider or provider alias.

Returns:

Transport keyword arguments such as base_url or anthropic_version.

class ooai_llm.settings.LiteLLMSettings(/, **data: Any)

Bases: pydantic.BaseModel

Native LiteLLM integration settings.

Parameters:

• enabled – Whether native LiteLLM integration is enabled.

• enrich_metadata – Whether LiteLLM pricing/model metadata should be used to enrich LangChain-first metadata resolution.

• profile_resolution_mode – How LangChain profiles and LiteLLM metadata should be combined.

• provider_prefixes – Optional per-provider LiteLLM prefix overrides.

• success_callbacks – Default named LiteLLM success callbacks.

• failure_callbacks – Default named LiteLLM failure callbacks.

Examples

>>> cfg = LiteLLMSettings()
>>> cfg.provider_prefixes["google_genai"]
'gemini'

model_config

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

enabled: bool = True

enrich_metadata: bool = True

profile_resolution_mode: Literal['langchain_only', 'langchain_then_litellm', 'litellm_only'] = 'langchain_then_litellm'

provider_prefixes: dict[str, str] = None

success_callbacks: list[str] = None

failure_callbacks: list[str] = None

class ooai_llm.settings.ModelDefaultsAutoRefreshSettings(/, **data: Any)

Bases: pydantic.BaseModel

Factory-time model-default refresh settings.

Parameters:

• enabled – Whether factories should refresh model defaults before model resolution.

• source – Refresh source. "auto" uses provider catalogs when a credential is configured and falls back to LiteLLM metadata.

• providers – Optional provider list. Defaults to every supported provider.

• primary_alias_provider – Provider whose refreshed presets update global aliases such as alias="latest".

• strict – Whether refresh failures should raise instead of preserving existing defaults.

• cache_seconds – Process-local TTL for automatic refresh results. Set to 0 to refresh on every factory call.

Examples

>>> cfg = ModelDefaultsAutoRefreshSettings(enabled=True, providers=["openai"])
>>> cfg.source
'auto'

model_config

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

enabled: bool = False

source: Literal['auto', 'provider', 'litellm'] = 'auto'

providers: list[str] | None = None

primary_alias_provider: str = 'openai'

strict: bool = False

cache_seconds: int | None = None

class ooai_llm.settings.LLMCacheSettings(/, **data: Any)

Bases: pydantic.BaseModel

LLM cache configuration.

Parameters:

• enabled – Whether global LLM caching should be enabled by default.

• backend – Cache backend identifier.

• path – Optional explicit cache path.

• filename – Cache filename when path is not explicitly provided.

• create_dirs – Whether parent directories should be created automatically.

• ttl – Optional time-to-live in seconds for backends that support it.

• redis_url – Redis connection URL for the redis backend.

• redis_host – Redis host when redis_url is not supplied.

• redis_port – Redis port when redis_url is not supplied.

• redis_db – Redis database index when redis_url is not supplied.

• redis_username – Redis username when redis_url is not supplied.

• redis_password – Redis password when redis_url is not supplied.

• redis_ssl – Whether Redis should use TLS when redis_url is absent.

• redis_connection_kwargs – Additional Redis client constructor kwargs.

• upstash_url – Upstash Redis REST URL.

• upstash_token – Upstash Redis REST token.

• sqlalchemy_url – SQLAlchemy database URL for the sqlalchemy backend.

Examples

>>> cache = LLMCacheSettings()
>>> cache.backend
'sqlite'

model_config

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

enabled: bool = True

backend: str = 'sqlite'

path: pathlib.Path | None = None

filename: str = 'langchain_llm_cache.sqlite3'

create_dirs: bool = True

ttl: int | None = None

redis_url: str | None = None

redis_host: str = 'localhost'

redis_port: int = None

redis_db: int = None

redis_username: str | None = None

redis_password: pydantic.SecretStr | None = None

redis_ssl: bool = False

redis_connection_kwargs: dict[str, object] = None

upstash_url: str | None = None

upstash_token: pydantic.SecretStr | None = None

sqlalchemy_url: str | None = None

class ooai_llm.settings.LLMSettings(/, **data: Any)

Bases: pydantic.BaseModel

Top-level LLM settings.

Parameters:

• default_model – Fallback model when no alias or provider default is used.

• defaults_by_provider – Default model preset bundles per provider.

• aliases – Global semantic aliases.

• auto_refresh_models – Factory-time model-default refresh settings.

• cache – Global cache settings.

Examples

>>> llm = LLMSettings()
>>> llm.default_model
'openai:gpt-5.4-mini'

model_config

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

default_model: str = 'openai:gpt-5.4-mini'

defaults_by_provider: DefaultModelsByProvider = None

aliases: DefaultModelAliases = None

auto_refresh_models: ModelDefaultsAutoRefreshSettings = None

cache: LLMCacheSettings = None

class ooai_llm.settings.AppSettings(_case_sensitive: bool | None = None, _nested_model_default_partial_update: bool | None = None, _env_prefix: str | None = None, _env_prefix_target: pydantic_settings.sources.EnvPrefixTarget | None = None, _env_file: pydantic_settings.sources.DotenvType | None = ENV_FILE_SENTINEL, _env_file_encoding: str | None = None, _env_ignore_empty: bool | None = None, _env_nested_delimiter: str | None = None, _env_nested_max_split: int | None = None, _env_parse_none_str: str | None = None, _env_parse_enums: bool | None = None, _cli_prog_name: str | None = None, _cli_parse_args: bool | list[str] | tuple[str, Ellipsis] | None = None, _cli_settings_source: pydantic_settings.sources.CliSettingsSource[Any] | None = None, _cli_parse_none_str: str | None = None, _cli_hide_none_type: bool | None = None, _cli_avoid_json: bool | None = None, _cli_enforce_required: bool | None = None, _cli_use_class_docs_for_groups: bool | None = None, _cli_exit_on_error: bool | None = None, _cli_prefix: str | None = None, _cli_flag_prefix_char: str | None = None, _cli_implicit_flags: bool | Literal['dual', 'toggle'] | None = None, _cli_ignore_unknown_args: bool | None = None, _cli_kebab_case: bool | Literal['all', 'no_enums'] | None = None, _cli_shortcuts: collections.abc.Mapping[str, str | list[str]] | None = None, _secrets_dir: pydantic_settings.sources.PathType | None = None, _build_sources: tuple[tuple[pydantic_settings.sources.PydanticBaseSettingsSource, Ellipsis], dict[str, Any]] | None = None, **values: Any)

Bases: pydantic_settings.BaseSettings

Application settings for the LLM layer.

Parameters:

• app_name – Human-readable application name.

• app_root – Root directory used for derived paths.

• app_dir_name – Hidden directory rooted under app_root for local cache and application files.

• credentials – Provider credential settings.

• llm – LLM settings.

• catalog – Live model-discovery settings.

• litellm – Native LiteLLM integration settings.

Examples

>>> settings = AppSettings()
>>> settings.resolve_model(alias="reasoning")
'openai:gpt-5.4'
>>> settings.catalog.xai.base_url
'https://api.x.ai'
>>> settings.litellm.profile_resolution_mode
'langchain_then_litellm'

model_config

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

app_name: str = 'ooai'

app_root: pathlib.Path = None

app_dir_name: str = '.ooai'

credentials: ProviderCredentials = None

llm: LLMSettings = None

catalog: CatalogSettings = None

litellm: LiteLLMSettings = None

property app_dir: pathlib.Path

Return the resolved application directory.

Returns:

Resolved application directory.

property default_llm_cache_path: pathlib.Path

Return the resolved default LLM cache path.

Returns:

Effective cache file path.

property default_model_string: ooai_llm.types.ModelString

Return the configured top-level default as a typed model string.

Returns:

Typed default model string.

model_copy_with_root(app_root: pathlib.Path) → Self

Return a copy of the settings with a new application root.

Parameters:

app_root – New application root.

Returns:

Updated settings copy.

resolve_model(*, model: str | None = None, alias: ModelAliasName | None = None, provider: ooai_llm.providers.Provider | str | None = None, preset: ModelPresetName = 'default') → str

Resolve the effective model string.

Resolution order:

1. Explicit model.

2. Global semantic alias.

3. Provider-specific preset.

4. Global fallback llm.default_model.

Parameters:

• model – Explicit model string.

• alias – Optional semantic alias.

• provider – Optional provider name or alias.

• preset – Provider-specific preset name.

Returns:

Resolved model string.

Raises:

ValueError – If an alias and provider are both supplied.

resolve_model_string(*, model: str | ooai_llm.types.ModelString | None = None, alias: ModelAliasName | None = None, provider: ooai_llm.providers.Provider | str | None = None, preset: ModelPresetName = 'default') → ooai_llm.types.ModelString

Resolve the effective model as a typed model string.

Parameters:

• model – Explicit model string or typed model string.

• alias – Optional semantic alias.

• provider – Optional provider name or alias.

• preset – Provider-specific preset name.

Returns:

Typed model string.