ooai_llm.model_defaults

Provider-generic model default refresh helpers.

Purpose:

Build refreshed provider presets from live provider catalogs or LiteLLM’s local model registry so convenience factories can track newer models without hard-coding every provider release.

Design:

• Keep factory refresh opt-in and cache automatic refresh results in-process.

• Prefer provider-native model listings when credentials are available.

• Use LiteLLM metadata as an optional no-credential fallback.

• Select presets with transparent name/cost/capability heuristics and return notes when a provider cannot be refreshed.

Examples

>>> from ooai_llm import AppSettings, refresh_model_defaults
>>> result = refresh_model_defaults(
...     AppSettings(),
...     providers=["openai"],
...     source="litellm",
... )
>>> isinstance(result.settings, AppSettings)
True

Attributes

ModelDefaultSource
ModelDefaultsExportFormat
ModelCapabilityName
ModelCatalogSortName

Classes

ModelDefaultCandidate	Candidate chat model used for provider preset selection.
ModelPresetRecommendation	Recommended provider presets and the candidates used to pick them.
ModelDefaultsRefreshResult	Result of refreshing model defaults for one or more providers.
ModelDefaultsUpdateResult	Result of updating model defaults for immediate or persisted use.
ModelCatalogResult	Cross-provider model catalog result for CLI and application display.

Functions

recommend_provider_model_presets(...)	Recommend provider presets from candidate chat models.
list_model_catalog(→ ModelCatalogResult)	List model candidates across providers from live catalogs or LiteLLM.
refresh_model_defaults(→ ModelDefaultsRefreshResult)	Return settings with refreshed provider presets.
auto_refresh_model_defaults(→ ModelDefaultsRefreshResult)	Refresh model defaults according to factory auto-refresh settings.
build_model_default_overrides(→ dict[str, Any])	Build a non-secret settings override payload for model defaults.
model_default_overrides_to_env(→ str)	Render model-default overrides as OOAI_ nested environment variables.
model_default_overrides_to_json(→ str)	Render model-default overrides as formatted JSON.
render_model_default_overrides(→ str)	Render model-default overrides in a supported persistence format.
update_model_defaults(→ ModelDefaultsUpdateResult)	Refresh model defaults and optionally write reusable overrides.

Module Contents

ooai_llm.model_defaults.ModelDefaultSource

ooai_llm.model_defaults.ModelDefaultsExportFormat

ooai_llm.model_defaults.ModelCapabilityName

ooai_llm.model_defaults.ModelCatalogSortName

class ooai_llm.model_defaults.ModelDefaultCandidate(/, **data: Any)

Bases: pydantic.BaseModel

Candidate chat model used for provider preset selection.

model_config

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

provider: ooai_llm.providers.Provider

model_id: str

source: str

display_name: str | None = None

created: int | None = None

created_at: str | None = None

supported_actions: list[str] = None

input_cost_per_token: decimal.Decimal | None = None

output_cost_per_token: decimal.Decimal | None = None

max_input_tokens: int | None = None

max_output_tokens: int | None = None

mode: str | None = None

supports_vision: bool | None = None

supports_function_calling: bool | None = None

supports_tool_choice: bool | None = None

supports_parallel_tool_calls: bool | None = None

supports_structured_output: bool | None = None

raw: dict[str, Any] = None

property model_string: ooai_llm.types.ModelString

Return the provider-prefixed model string.

property release_date: str | None

Return the best available release-date label for display.

property input_cost_per_1m_tokens: decimal.Decimal | None

Return input-token cost normalized to one million tokens.

property output_cost_per_1m_tokens: decimal.Decimal | None

Return output-token cost normalized to one million tokens.

property context_window: int | None

Return the best known input/context window.

property supports_chat: bool

Return whether this candidate looks usable for chat/generation.

property supports_reasoning: bool

Return whether this candidate appears reasoning-oriented.

property supports_coding: bool

Return whether this candidate appears coding-oriented.

property supports_tool_calling: bool

Return whether this candidate appears tool/function-call capable.

property capability_labels: list[str]

Return display labels for inferred model capabilities.

class ooai_llm.model_defaults.ModelPresetRecommendation(/, **data: Any)

Bases: pydantic.BaseModel

Recommended provider presets and the candidates used to pick them.

model_config

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

provider: ooai_llm.providers.Provider

presets: ooai_llm.settings.ProviderModelPresets

source: str

candidates: list[ModelDefaultCandidate] = None

notes: list[str] = None

class ooai_llm.model_defaults.ModelDefaultsRefreshResult(/, **data: Any)

Bases: pydantic.BaseModel

Result of refreshing model defaults for one or more providers.

model_config

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

settings: ooai_llm.settings.AppSettings

recommendations: dict[str, ModelPresetRecommendation] = None

notes: list[str] = None

class ooai_llm.model_defaults.ModelDefaultsUpdateResult(/, **data: Any)

Bases: pydantic.BaseModel

Result of updating model defaults for immediate or persisted use.

model_config

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

settings: ooai_llm.settings.AppSettings

recommendations: dict[str, ModelPresetRecommendation] = None

overrides: dict[str, Any] = None

notes: list[str] = None

output_path: pathlib.Path | None = None

output_format: ModelDefaultsExportFormat | None = None

output_text: str | None = None

class ooai_llm.model_defaults.ModelCatalogResult(/, **data: Any)

Bases: pydantic.BaseModel

Cross-provider model catalog result for CLI and application display.

model_config

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

models: list[ModelDefaultCandidate] = None

notes: list[str] = None

ooai_llm.model_defaults.recommend_provider_model_presets(provider: ooai_llm.providers.Provider | str, candidates: Sequence[ModelDefaultCandidate], *, source: str = 'custom') → ModelPresetRecommendation

Recommend provider presets from candidate chat models.

Parameters:

• provider – Provider being refreshed.

• candidates – Candidate models from a provider catalog or LiteLLM.

• source – Human-readable source label.

Returns:

Preset recommendation for the provider.

Raises:

ValueError – If no chat-like candidates are available.

ooai_llm.model_defaults.list_model_catalog(settings: ooai_llm.settings.AppSettings | None = None, *, providers: Iterable[ooai_llm.providers.Provider | str] | None = None, source: ModelDefaultSource = 'auto', config: ooai_llm.catalog.ListModelsConfig | None = None, include_non_chat: bool = False, capabilities: Iterable[ModelCapabilityName] | None = None, min_context_tokens: int | None = None, min_output_tokens: int | None = None, max_input_cost_per_1m: decimal.Decimal | None = None, max_output_cost_per_1m: decimal.Decimal | None = None, released_after: str | None = None, released_before: str | None = None, sort_by: ModelCatalogSortName = 'recency', strict: bool = False) → ModelCatalogResult

List model candidates across providers from live catalogs or LiteLLM.

Parameters:

• settings – Base settings. Defaults to AppSettings().

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

• source – "provider" for live model-listing APIs, "litellm" for LiteLLM metadata, or "auto" to use provider catalogs when credentials exist and LiteLLM otherwise.

• config – Optional provider-listing configuration.

• include_non_chat – Include embeddings, audio, image, and other non-chat-like models instead of filtering to chat candidates.

• capabilities – Optional capability labels that every returned model must satisfy, such as "reasoning", "coding", or "vision".

• min_context_tokens – Optional minimum context/input-token window.

• min_output_tokens – Optional minimum output-token limit.

• max_input_cost_per_1m – Optional maximum input cost per one million tokens.

• max_output_cost_per_1m – Optional maximum output cost per one million tokens.

• released_after – Optional lower release-date bound. Accepts YYYY-MM-DD, YYYY-MM, or common date-like model-name suffixes.

• released_before – Optional upper release-date bound.

• sort_by – Sort mode for the returned rows.

• strict – Raise on the first provider listing failure.

Returns:

Catalog result containing model rows and non-fatal notes.

ooai_llm.model_defaults.refresh_model_defaults(settings: ooai_llm.settings.AppSettings | None = None, *, providers: Iterable[ooai_llm.providers.Provider | str] | None = None, source: ModelDefaultSource = 'auto', config: ooai_llm.catalog.ListModelsConfig | None = None, primary_alias_provider: ooai_llm.providers.Provider | str = Provider.OPENAI, strict: bool = False) → ModelDefaultsRefreshResult

Return settings with refreshed provider presets.

Parameters:

• settings – Base settings. Defaults to AppSettings().

• providers – Providers to refresh. Defaults to every supported provider.

• source – "provider" for live provider APIs, "litellm" for LiteLLM’s local registry, or "auto" to prefer live APIs when credentials are present and fall back to LiteLLM.

• config – Optional provider-listing configuration.

• primary_alias_provider – Provider whose refreshed presets should update global aliases like alias="latest" and alias="cheap".

• strict – Raise on the first provider refresh failure instead of returning notes and leaving that provider unchanged.

Returns:

Refresh result containing copied settings and per-provider recommendations.

ooai_llm.model_defaults.auto_refresh_model_defaults(settings: ooai_llm.settings.AppSettings | None = None, *, enabled: bool | None = None, force: bool = False) → ModelDefaultsRefreshResult

Refresh model defaults according to factory auto-refresh settings.

Parameters:

• settings – Base settings. Defaults to AppSettings().

• enabled – Optional override for settings.llm.auto_refresh_models.enabled.

• force – Bypass the process-local refresh cache.

Returns:

Refresh result. When automatic refresh is disabled, the original settings are returned unchanged with no recommendations.

ooai_llm.model_defaults.build_model_default_overrides(settings: ooai_llm.settings.AppSettings, *, providers: Iterable[ooai_llm.providers.Provider | str] | None = None, include_aliases: bool = True) → dict[str, Any]

Build a non-secret settings override payload for model defaults.

Parameters:

• settings – Settings containing the desired model defaults.

• providers – Providers to include. Defaults to every supported provider.

• include_aliases – Whether to include global aliases and default model.

Returns:

Nested dictionary suitable for AppSettings(**payload).

ooai_llm.model_defaults.model_default_overrides_to_env(overrides: Mapping[str, Any]) → str

Render model-default overrides as OOAI_ nested environment variables.

ooai_llm.model_defaults.model_default_overrides_to_json(overrides: Mapping[str, Any]) → str

Render model-default overrides as formatted JSON.

ooai_llm.model_defaults.render_model_default_overrides(overrides: Mapping[str, Any], *, output_format: ModelDefaultsExportFormat) → str

Render model-default overrides in a supported persistence format.

ooai_llm.model_defaults.update_model_defaults(settings: ooai_llm.settings.AppSettings | None = None, *, providers: Iterable[ooai_llm.providers.Provider | str] | None = None, source: ModelDefaultSource = 'auto', config: ooai_llm.catalog.ListModelsConfig | None = None, primary_alias_provider: ooai_llm.providers.Provider | str = Provider.OPENAI, strict: bool = False, output_path: str | pathlib.Path | None = None, output_format: ModelDefaultsExportFormat = 'json', include_aliases: bool = True) → ModelDefaultsUpdateResult

Refresh model defaults and optionally write reusable overrides.

Parameters:

• settings – Base settings. Defaults to AppSettings().

• providers – Providers to update. Defaults to every supported provider.

• source – Model source, passed through to refresh_model_defaults.

• config – Optional provider-listing configuration.

• primary_alias_provider – Provider whose presets update global aliases.

• strict – Raise on provider refresh failure.

• output_path – Optional file path to write rendered overrides.

• output_format – "json" or "env".

• include_aliases – Whether exported overrides include global aliases.

Returns:

Update result with refreshed settings, overrides, and rendered text when output_path is omitted.