ooai_llm.catalog_insights

Cost and capability comparisons over the model catalog.

Purpose:

Turn provider/LiteLLM model catalog rows into practical comparison tables: cheapest models, coding-capable shortlists, per-call cost estimates, and “how many calls of X equal one call of Y” ratios.

Design:

• Reuse ooai_llm.model_defaults.list_model_catalog() as the source of truth so pricing and model availability can be refreshed independently.

• Keep estimates explicit about the assumed input/output token shape.

• Treat catalog pricing as planning data; observed provider usage metadata remains the billing source of truth after a real call.

Attributes

CatalogModelStyle
ModelComparisonSortName

Classes

ModelCallShape	Token shape used to estimate one representative model call.
ModelCostEstimate	One model's estimated cost for a representative call shape.
ModelCallEquivalent	Cost ratio between a baseline model call and another model call.
ModelCostComparison	Iterable cost comparison result for catalog models.

Functions

estimate_model_call_cost(→ decimal.Decimal | None)	Estimate one call cost from catalog pricing and token shape.
compare_model_candidates(, sort_by, notes)	Build a cost comparison from preloaded catalog candidates.
compare_model_catalog(, per_provider, sort_by, limit, ...)	Compare model costs across a filtered model catalog.
get_cheapest_models(→ ModelCostComparison)	Return the cheapest catalog-priced models for a token shape.
get_coding_model_comparison(→ ModelCostComparison)	Return a cost-ranked comparison of coding-oriented catalog models.

Module Contents

ooai_llm.catalog_insights.CatalogModelStyle

ooai_llm.catalog_insights.ModelComparisonSortName

class ooai_llm.catalog_insights.ModelCallShape(/, **data: Any)

Bases: pydantic.BaseModel

Token shape used to estimate one representative model call.

model_config

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

input_tokens: int = None

output_tokens: int = None

property total_tokens: int

Return total input plus output tokens.

class ooai_llm.catalog_insights.ModelCostEstimate(/, **data: Any)

Bases: pydantic.BaseModel

One model’s estimated cost for a representative call shape.

model_config

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

provider: ooai_llm.providers.Provider

model: ooai_llm.types.ModelString

source: str

release_date: str | None = None

input_cost_per_1m_tokens: decimal.Decimal | None = None

output_cost_per_1m_tokens: decimal.Decimal | None = None

max_input_tokens: int | None = None

max_output_tokens: int | None = None

context_window: int | None = None

capabilities: list[str] = None

call_cost_usd: decimal.Decimal | None = None

calls_per_usd: decimal.Decimal | None = None

calls_per_budget: decimal.Decimal | None = None

budget_usd: decimal.Decimal

model_name(*, style: CatalogModelStyle = 'langchain') → str

Return the model string in the requested style.

class ooai_llm.catalog_insights.ModelCallEquivalent(/, **data: Any)

Bases: pydantic.BaseModel

Cost ratio between a baseline model call and another model call.

model_config

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

baseline_model: ooai_llm.types.ModelString

compared_model: ooai_llm.types.ModelString

baseline_call_cost_usd: decimal.Decimal

compared_call_cost_usd: decimal.Decimal

compared_calls_per_baseline_call: decimal.Decimal

class ooai_llm.catalog_insights.ModelCostComparison(/, **data: Any)

Bases: pydantic.BaseModel

Iterable cost comparison result for catalog models.

model_config

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

shape: ModelCallShape = None

budget_usd: decimal.Decimal

estimates: list[ModelCostEstimate] = None

notes: list[str] = None

__iter__() → collections.abc.Iterator[ModelCostEstimate]

Iterate over cost estimates.

__len__() → int

Return the number of estimates.

model_list(*, style: CatalogModelStyle = 'langchain') → list[str]

Return compared models as an ordered list of strings.

model_dict(*, style: CatalogModelStyle = 'langchain') → dict[str, str]

Return compared models keyed by provider/model string.

by_provider() → dict[str, list[ModelCostEstimate]]

Group estimates by provider.

cheapest_per_provider() → list[ModelCostEstimate]

Return the cheapest known estimate for each provider.

find_model(model: str | ooai_llm.types.ModelString) → ModelCostEstimate | None

Find an estimate by LangChain, LiteLLM, bare, or raw model string.

equivalents(baseline_model: str | ooai_llm.types.ModelString) → list[ModelCallEquivalent]

Return ratios against a baseline model in this comparison.

The ratio answers: “how many calls of the compared model cost the same as one call of the baseline model” for the configured call shape.

ooai_llm.catalog_insights.estimate_model_call_cost(candidate: ooai_llm.model_defaults.ModelDefaultCandidate, shape: ModelCallShape | None = None) → decimal.Decimal | None

Estimate one call cost from catalog pricing and token shape.

Parameters:

• candidate – Catalog model row with per-token input/output prices.

• shape – Representative token shape. Defaults to 10k input and 2k output.

Returns:

Estimated USD cost, or None when required pricing is unknown.

ooai_llm.catalog_insights.compare_model_candidates(candidates: collections.abc.Sequence[ooai_llm.model_defaults.ModelDefaultCandidate], *, shape: ModelCallShape | None = None, budget_usd: decimal.Decimal = Decimal('1'), sort_by: ModelComparisonSortName = 'call_cost', notes: collections.abc.Iterable[str] | None = None) → ModelCostComparison

Build a cost comparison from preloaded catalog candidates.

ooai_llm.catalog_insights.compare_model_catalog(settings: ooai_llm.settings.AppSettings | None = None, *, providers: collections.abc.Iterable[ooai_llm.providers.Provider | str] | None = None, source: ooai_llm.model_defaults.ModelDefaultSource = 'auto', config: ooai_llm.catalog.ListModelsConfig | None = None, include_non_chat: bool = False, capabilities: collections.abc.Iterable[ooai_llm.model_defaults.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, shape: ModelCallShape | None = None, input_tokens: int | None = None, output_tokens: int | None = None, budget_usd: decimal.Decimal = Decimal('1'), per_provider: bool = False, sort_by: ModelComparisonSortName = 'call_cost', limit: int | None = None, strict: bool = False) → ModelCostComparison

Compare model costs across a filtered model catalog.

Parameters:

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

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

• source – "provider", "litellm", or "auto" catalog source.

• config – Optional provider-listing configuration.

• include_non_chat – Include non-chat-like models.

• capabilities – Required capability labels, such as "coding".

• 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.

• released_before – Optional upper release-date bound.

• shape – Representative input/output token shape.

• input_tokens – Override shape.input_tokens.

• output_tokens – Override shape.output_tokens.

• budget_usd – Budget used for calls-per-budget estimates. Defaults to $1.

• per_provider – Keep only the cheapest row for each provider.

• sort_by – Sort mode for returned estimates. Defaults to call cost.

• limit – Optional maximum number of returned estimates. 0 disables it.

• strict – Raise on provider listing failure.

Returns:

Cost comparison sorted by the requested estimate field.

ooai_llm.catalog_insights.get_cheapest_models(settings: ooai_llm.settings.AppSettings | None = None, *, providers: collections.abc.Iterable[ooai_llm.providers.Provider | str] | None = None, source: ooai_llm.model_defaults.ModelDefaultSource = 'auto', per_provider: bool = False, limit: int | None = 20, **kwargs: Any) → ModelCostComparison

Return the cheapest catalog-priced models for a token shape.

ooai_llm.catalog_insights.get_coding_model_comparison(settings: ooai_llm.settings.AppSettings | None = None, *, providers: collections.abc.Iterable[ooai_llm.providers.Provider | str] | None = None, source: ooai_llm.model_defaults.ModelDefaultSource = 'auto', limit: int | None = 20, **kwargs: Any) → ModelCostComparison

Return a cost-ranked comparison of coding-oriented catalog models.