"""Public package API for ``ooai_llm``.
Purpose:
Expose a small, ergonomic public surface centered on chat-model creation,
model discovery, and model inspection.
Design:
- Keep the top-level API intentionally small.
- Preserve older names through deprecated lazy aliases to avoid sudden
breakage for early adopters.
- Re-export the core settings and typed model-string helpers that users are
most likely to configure directly.
Public names:
__all__: Curated public API.
Examples:
>>> from ooai_llm import AppSettings, create_llm, get_model_info
>>> settings = AppSettings()
>>> callable(create_llm) and callable(get_model_info)
True
"""
from __future__ import annotations
from warnings import warn
from .cache import (
NamespacedCache,
build_llm_cache,
build_memory_cache,
build_namespaced_cache,
build_redis_cache,
build_sqlalchemy_cache,
build_sqlite_cache,
build_upstash_redis_cache,
configure_global_llm_cache,
resolve_llm_cache_path,
)
from .callbacks import (
BudgetExceededError,
BudgetPolicy,
CountSource,
LangChainUsageCallbackHandler,
UsageEvent,
UsageRecorder,
UsageSummary,
build_langchain_usage_event,
estimate_and_record_langchain_usage,
extract_response_model_name,
extract_usage_metadata,
make_litellm_cost_callback,
record_langchain_response_usage,
)
from .catalog import (
ListModelsConfig,
ModelListResult,
ProviderClientInfo,
ProviderModelInfo,
get_provider_client_info,
list_available_models,
list_model_ids,
)
from .catalog_insights import (
CatalogModelStyle,
ModelCallEquivalent,
ModelCallShape,
ModelComparisonSortName,
ModelCostComparison,
ModelCostEstimate,
compare_model_candidates,
compare_model_catalog,
estimate_model_call_cost,
get_cheapest_models,
get_coding_model_comparison,
)
from .dspy import (
CreatedDSPyLMBundle,
DSPyDependencyError,
DSPyLMConfig,
DSPyModelType,
build_dspy_usage_event,
configure_dspy_lm,
create_dspy_lm,
create_dspy_lm_bundle,
extract_dspy_usage,
record_dspy_usage,
resolve_dspy_model_name,
)
from .factory import create_llm, create_llm_bundle, resolve_factory_settings
from .logging import configure_logging, get_logger, logging_context
from .litellm_registry import LiteLLMRegistryModel, LiteLLMRegistryResult, list_litellm_registry
from .messages import MessageEstimate, NormalizedMessages, normalize_messages
from .metadata import ModelInfo, get_model_info
from .model_defaults import (
ModelCatalogResult,
ModelCapabilityName,
ModelCatalogSortName,
ModelDefaultCandidate,
ModelDefaultsRefreshResult,
ModelDefaultsUpdateResult,
ModelPresetRecommendation,
auto_refresh_model_defaults,
build_model_default_overrides,
list_model_catalog,
model_default_overrides_to_env,
model_default_overrides_to_json,
recommend_provider_model_presets,
refresh_model_defaults,
render_model_default_overrides,
update_model_defaults,
)
from .model_suites import (
ModelSuite,
ModelSuiteEntry,
ModelSuiteName,
ModelSuiteRoleName,
ModelSuiteStyle,
get_model_suite,
list_model_suite_names,
model_suite_from_catalog,
model_suite_from_presets,
)
from .providers import Provider, get_litellm_provider_prefix, infer_provider_from_model_name, normalize_provider_name
from .profiles import CacheKeyPolicy, ChatModelProfile, ChatModelProfileResolution, LLM
from .reasoning import ReasoningConfig, ReasoningResolution, build_reasoning_resolution
from .settings import AppSettings, ModelDefaultsAutoRefreshSettings
from .types import ModelString
[docs]
list_models = list_available_models
__all__ = [
"AppSettings",
"BudgetExceededError",
"BudgetPolicy",
"CacheKeyPolicy",
"CatalogModelStyle",
"ChatModelProfile",
"ChatModelProfileResolution",
"CountSource",
"CreatedDSPyLMBundle",
"DSPyDependencyError",
"DSPyLMConfig",
"DSPyModelType",
"LangChainUsageCallbackHandler",
"LLM",
"MessageEstimate",
"ModelCallEquivalent",
"ModelCallShape",
"ModelComparisonSortName",
"ModelCostComparison",
"ModelCostEstimate",
"ModelInfo",
"ModelCatalogResult",
"ModelCapabilityName",
"ModelCatalogSortName",
"ModelDefaultCandidate",
"ModelDefaultsRefreshResult",
"ModelDefaultsUpdateResult",
"ModelDefaultsAutoRefreshSettings",
"ModelListResult",
"ModelPresetRecommendation",
"ModelSuite",
"ModelSuiteEntry",
"ModelSuiteName",
"ModelSuiteRoleName",
"ModelSuiteStyle",
"ModelString",
"NormalizedMessages",
"Provider",
"ProviderClientInfo",
"ProviderModelInfo",
"ReasoningConfig",
"ReasoningResolution",
"UsageEvent",
"UsageRecorder",
"UsageSummary",
"auto_refresh_model_defaults",
"build_langchain_usage_event",
"build_llm_cache",
"build_memory_cache",
"build_model_default_overrides",
"build_namespaced_cache",
"build_redis_cache",
"build_reasoning_resolution",
"build_sqlalchemy_cache",
"build_sqlite_cache",
"build_upstash_redis_cache",
"compare_model_candidates",
"compare_model_catalog",
"configure_global_llm_cache",
"configure_logging",
"configure_dspy_lm",
"create_dspy_lm",
"create_dspy_lm_bundle",
"create_llm",
"create_llm_bundle",
"build_dspy_usage_event",
"estimate_model_call_cost",
"estimate_and_record_langchain_usage",
"extract_dspy_usage",
"extract_response_model_name",
"extract_usage_metadata",
"get_litellm_provider_prefix",
"get_logger",
"get_cheapest_models",
"get_coding_model_comparison",
"get_model_info",
"get_model_suite",
"get_provider_client_info",
"infer_provider_from_model_name",
"ListModelsConfig",
"LiteLLMRegistryModel",
"LiteLLMRegistryResult",
"list_available_models",
"list_model_ids",
"list_model_catalog",
"list_model_suite_names",
"list_models",
"list_litellm_registry",
"logging_context",
"make_litellm_cost_callback",
"model_default_overrides_to_env",
"model_default_overrides_to_json",
"model_suite_from_catalog",
"model_suite_from_presets",
"NamespacedCache",
"normalize_messages",
"normalize_provider_name",
"record_langchain_response_usage",
"record_dspy_usage",
"recommend_provider_model_presets",
"refresh_model_defaults",
"render_model_default_overrides",
"resolve_llm_cache_path",
"resolve_factory_settings",
"resolve_dspy_model_name",
"update_model_defaults",
]
_DEPRECATED_IMPORTS = {
"CapabilityProfile": (".metadata", "CapabilityProfile"),
"CreatedLLMBundle": (".metadata", "CreatedLLMBundle"),
"PriceEntry": (".metadata", "PriceEntry"),
"ResolvedModelIdentity": (".metadata", "ResolvedModelIdentity"),
"ResolvedModelMeta": (".metadata", "ResolvedModelMeta"),
"UsageSnapshot": (".metadata", "UsageSnapshot"),
"build_capability_profile": (".metadata", "build_capability_profile"),
"build_model_profile": (".metadata", "build_model_profile"),
"build_usage_snapshot": (".metadata", "build_usage_snapshot"),
"calculate_cost": (".metadata", "calculate_cost"),
"LiteLLMSettings": (".settings", "LiteLLMSettings"),
"LLMCacheSettings": (".settings", "LLMCacheSettings"),
"LLMSettings": (".settings", "LLMSettings"),
"native_environment_overrides": (".factory", "native_environment_overrides"),
"normalize_model_name": (".metadata", "normalize_model_name"),
"ProviderCredentials": (".settings", "ProviderCredentials"),
"ProviderModelPresets": (".settings", "ProviderModelPresets"),
"resolve_litellm_model_name": (".metadata", "resolve_litellm_model_name"),
"resolve_model_meta": (".metadata", "resolve_model_meta"),
"resolve_model_meta_from_langchain_model": (".metadata", "resolve_model_meta_from_langchain_model"),
"resolve_model_string": (".factory", "resolve_model_string"),
"CatalogProviderSettings": (".settings", "CatalogProviderSettings"),
"CatalogSettings": (".settings", "CatalogSettings"),
"DefaultModelAliases": (".settings", "DefaultModelAliases"),
"DefaultModelsByProvider": (".settings", "DefaultModelsByProvider"),
"normalize_langchain_model_name": (".metadata", "normalize_langchain_model_name"),
}
def __getattr__(name: str):
"""Resolve deprecated top-level imports lazily.
Args:
name: Requested attribute name.
Returns:
Deprecated object imported from its home module.
Raises:
AttributeError: If the name is unknown.
"""
target = _DEPRECATED_IMPORTS.get(name)
if target is None:
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
module_name, attribute_name = target
warn(
f"`ooai_llm.{name}` is deprecated as a top-level import. Import it from {module_name} instead.",
DeprecationWarning,
stacklevel=2,
)
module = __import__(f"{__name__}{module_name}", fromlist=[attribute_name])
return getattr(module, attribute_name)