ooai_llm.catalog

Live model discovery helpers.

Purpose:

Discover available models from provider-native APIs or SDKs and normalize the results into one typed shape reusable across chat, embeddings, and other future model families.

Design:

• Use official provider SDKs when available.

• Fall back to documented REST endpoints when an SDK is absent or a simple models-list endpoint is easier to support robustly.

• Keep the returned model objects provider-agnostic while preserving the raw payload for debugging or deeper inspection.

• Focus on read-only discovery so the module stays useful even before more advanced routing, pricing, or profile-merging features are added.

Important constants:

DEFAULT_DEEPSEEK_BASE_URL: OpenAI-compatible DeepSeek base URL. DEFAULT_XAI_BASE_URL: xAI REST API base URL.

Examples

>>> from ooai_llm import ProviderModelInfo
>>> info = ProviderModelInfo(provider="openai", model_id="gpt-5.4-mini")
>>> str(info.model_string)
'openai:gpt-5.4-mini'

Attributes

DEFAULT_DEEPSEEK_BASE_URL
DEFAULT_XAI_BASE_URL
DEFAULT_ANTHROPIC_API_VERSION

Classes

ListModelsConfig	Configuration for live model discovery.
ProviderModelInfo	Normalized model metadata from a provider listing.
ModelListResult	Normalized result of a provider model-list call.
ProviderClientInfo	Metadata about a provider's native SDK integration.

Functions

get_provider_client_info(→ ProviderClientInfo)	Return installation metadata for a provider.
list_model_ids(→ list[str])	List only model identifiers for a provider.
list_available_models(→ ModelListResult)	List available models from a provider.

Module Contents

ooai_llm.catalog.DEFAULT_DEEPSEEK_BASE_URL = 'https://api.deepseek.com/v1'

ooai_llm.catalog.DEFAULT_XAI_BASE_URL = 'https://api.x.ai'

ooai_llm.catalog.DEFAULT_ANTHROPIC_API_VERSION = '2023-06-01'

class ooai_llm.catalog.ListModelsConfig(/, **data: Any)

Bases: pydantic.BaseModel

Configuration for live model discovery.

Parameters:

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

• page_size – Provider-specific page size when supported.

• query_base – Google GenAI SDK flag controlling whether base models are listed alongside tuned models.

• prefer_sdk – Whether the helper should prefer an installed SDK over a direct REST call when both are supported.

model_config

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

limit: int | None = None

page_size: int | None = None

query_base: bool | None = None

prefer_sdk: bool = True

class ooai_llm.catalog.ProviderModelInfo(/, **data: Any)

Bases: pydantic.BaseModel

Normalized model metadata from a provider listing.

Parameters:

• provider – Canonical provider.

• model_id – Provider-native model identifier.

• display_name – Human-readable name when available.

• type – Provider object type.

• owned_by – Owner identifier when provided.

• created – Unix timestamp when provided.

• created_at – ISO-style timestamp when provided.

• aliases – Optional model aliases.

• supported_actions – Optional supported actions such as generateContent or embedContent.

• input_token_limit – Maximum input tokens when returned by the provider.

• output_token_limit – Maximum output tokens when returned by the provider.

• raw – Original provider payload as a plain dictionary.

Examples

>>> info = ProviderModelInfo(provider="openai", model_id="gpt-5.4")
>>> str(info.model_string)
'openai:gpt-5.4'

model_config

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

provider: ooai_llm.providers.Provider

model_id: str

display_name: str | None = None

type: str | None = None

owned_by: str | None = None

created: int | None = None

created_at: str | None = None

aliases: list[str] = None

supported_actions: list[str] = None

input_token_limit: int | None = None

output_token_limit: int | None = None

raw: dict[str, Any] = None

property model_string: ooai_llm.types.ModelString

Return the canonical provider-prefixed model string.

class ooai_llm.catalog.ModelListResult(/, **data: Any)

Bases: pydantic.BaseModel

Normalized result of a provider model-list call.

Parameters:

• provider – Canonical provider.

• models – Listed models.

• next_page_token – Provider-native continuation token when exposed.

• used_sdk – Whether a native SDK path was used.

• notes – Informational notes about fallbacks or partial support.

model_config

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

provider: ooai_llm.providers.Provider

models: list[ProviderModelInfo] = None

next_page_token: str | None = None

used_sdk: bool | None = None

notes: list[str] = None

class ooai_llm.catalog.ProviderClientInfo(/, **data: Any)

Bases: pydantic.BaseModel

Metadata about a provider’s native SDK integration.

Parameters:

• provider – Canonical provider.

• extra_name – Optional package extra that installs support.

• native_sdk_package – Native SDK import/package name when known.

• langchain_package – LangChain integration package when known.

model_config

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

provider: ooai_llm.providers.Provider

extra_name: str | None = None

native_sdk_package: str | None = None

langchain_package: str | None = None

ooai_llm.catalog.get_provider_client_info(provider: ooai_llm.providers.Provider | str) → ProviderClientInfo

Return installation metadata for a provider.

Parameters:

provider – Canonical provider or alias.

Returns:

Installation metadata.

ooai_llm.catalog.list_model_ids(provider: ooai_llm.providers.Provider | str, *, settings: ooai_llm.settings.AppSettings | None = None, api_key: str | None = None, config: ListModelsConfig | None = None, **kwargs: Any) → list[str]

List only model identifiers for a provider.

Parameters:

• provider – Canonical provider or alias.

• settings – Optional application settings.

• api_key – Optional explicit API key override.

• config – Optional listing configuration.

• **kwargs – Provider-specific constructor or transport kwargs.

Returns:

List of provider-native model IDs.

ooai_llm.catalog.list_available_models(provider: ooai_llm.providers.Provider | str, *, settings: ooai_llm.settings.AppSettings | None = None, api_key: str | None = None, config: ListModelsConfig | None = None, **kwargs: Any) → ModelListResult

List available models from a provider.

Parameters:

• provider – Canonical provider or alias.

• settings – Optional application settings.

• api_key – Optional explicit API key override.

• config – Optional listing configuration.

• **kwargs – Provider-specific client kwargs such as base_url.

Returns:

Structured model-list result.

Raises:

• ValueError – If the provider cannot be resolved.

• RuntimeError – If no API key can be resolved when the provider requires one.

• ImportError – If a provider SDK is required but unavailable and no REST fallback is implemented.