Models

The data model every Catalog query returns. All of these are plain dataclasses with to_dict()/from_dict() for JSON round-tripping.

llm_catalogue.models.AIModel dataclass

AIModel(id: str, name: str, vendor: Vendor, pricing: TokenPricing, context_window: Optional[int] = None, tiered_pricing: Optional[TieredPricing] = None, free_tier: Optional[FreeTierPolicy] = None, status: ModelStatus = ModelStatus.ACTIVE, tool_costs: Dict[str, float] = dict())

A single model from a single provider, with its pricing and metadata.

This is the unit of data returned by every :class:~llm_catalogue.catalogue.Catalog query method (get_models, get_free_models, find_free_models, get_model).

Attributes:

Name	Type	Description
id	str	The provider's own model identifier, e.g. "gemini-2.5-flash". Use this to look models up with Catalog.get_model().
name	str	Human-readable display name, e.g. "Gemini 2.5 Flash".
vendor	Vendor	Which provider this model belongs to.
pricing	TokenPricing	Standard-tier USD pricing for this model.
context_window	Optional[int]	Max input tokens, if known. None when not documented on the pricing page itself.
tiered_pricing	Optional[TieredPricing]	Alternate pricing that applies past a token threshold (see :class:TieredPricing), or None if this model's price doesn't change with context length.
free_tier	Optional[FreeTierPolicy]	Free-tier eligibility and terms, or None if the provider doesn't document one at all.
status	ModelStatus	Lifecycle state (active/deprecated/retired/limited).
tool_costs	Dict[str, float]	Reserved for per-tool costs (e.g. web search, code execution) keyed by tool name. Not populated by the bundled scraper in v1.

is_free property

is_free: bool

Whether this model has any free tier at all.

Shorthand for bool(model.free_tier and model.free_tier.has_free_tier). This is what :class:~llm_catalogue.catalogue.Catalog's get_free_models/find_free_models/has_free_tier filter on.

calculate_cost

calculate_cost(input_tokens: int, output_tokens: int, cached_tokens: int = 0, is_batch: bool = False) -> float

Estimates the USD cost of a single request against this model's pricing.

Parameters:

Name	Type	Description	Default
input_tokens	int	Total input/prompt tokens for the request, including any cached tokens (cached_tokens must be a subset of this count, not additional to it).	required
output_tokens	int	Total output/completion tokens for the request.	required
cached_tokens	int	How many of input_tokens were served from a prompt cache and billed at pricing.cached_input instead of the standard input rate. Defaults to 0 (no caching).	0
is_batch	bool	If True and the model has batch pricing configured, bills at pricing.batch_input/pricing.batch_output instead of standard rates, and caching is ignored (batch APIs generally don't support prompt caching).	False

Returns:

Type	Description
float	Estimated cost in USD, rounded to 6 decimal places. If
float	tiered_pricing is set and input_tokens exceeds its
float	threshold_tokens, the over-threshold rate is used instead
float	of pricing.

from_dict classmethod

from_dict(data: Dict[str, Any]) -> 'AIModel'

Rebuilds an AIModel from a dict produced by :meth:to_dict.

to_dict

to_dict() -> Dict[str, Any]

Returns a plain, JSON-serializable dict of this model.

This is the exact shape stored per-entry in registry.json's "models" list.

llm_catalogue.models.TokenPricing dataclass

TokenPricing(standard_input: float, output: float, cached_input: Optional[float] = None, batch_input: Optional[float] = None, batch_output: Optional[float] = None)

USD price per 1 million tokens for one pricing tier of one model.

Attributes:

Name	Type	Description
standard_input	float	Price per 1M input tokens at standard (non-batch) rates.
output	float	Price per 1M output tokens at standard (non-batch) rates.
cached_input	Optional[float]	Price per 1M cache-read input tokens, if the provider offers prompt caching. None if unknown/not applicable. Note this is the cache-read price -- separate cache-write premiums (e.g. Anthropic's 5m/1h writes) aren't modelled.
batch_input	Optional[float]	Price per 1M input tokens via the provider's batch/async API, if any.
batch_output	Optional[float]	Price per 1M output tokens via the provider's batch/async API, if any.

from_dict classmethod

from_dict(data: Dict[str, Any]) -> 'TokenPricing'

Rebuilds a TokenPricing from a dict produced by :meth:to_dict.

to_dict

to_dict() -> Dict[str, Any]

Returns a plain, JSON-serializable dict of this pricing.

llm_catalogue.models.TieredPricing dataclass

TieredPricing(threshold_tokens: int, base_rate: TokenPricing, over_threshold_rate: TokenPricing)

Context-length-dependent pricing.

Some models (e.g. Gemini 2.5 Pro past 200k tokens) charge a higher rate once the prompt crosses a token threshold. :meth:AIModel.calculate_cost picks over_threshold_rate automatically when input_tokens exceeds threshold_tokens.

Attributes:

Name	Type	Description
threshold_tokens	int	The input-token count at which the higher rate kicks in.
base_rate	TokenPricing	Pricing used at or below threshold_tokens.
over_threshold_rate	TokenPricing	Pricing used above threshold_tokens.

from_dict classmethod

from_dict(data: Dict[str, Any]) -> 'TieredPricing'

Rebuilds a TieredPricing from a dict produced by :meth:to_dict.

to_dict

to_dict() -> Dict[str, Any]

Returns a plain, JSON-serializable dict of this tiered pricing.

llm_catalogue.models.FreeTierPolicy dataclass

FreeTierPolicy(has_free_tier: bool, rate_limit_rpm: Optional[int] = None, data_used_for_training: Optional[bool] = None)

Whether, and how, a model can be used free of charge.

Attributes:

Name	Type	Description
has_free_tier	bool	Whether the provider lets you call this model without paying. This is what :attr:AIModel.is_free and :meth:Catalog.get_free_models key off of.
rate_limit_rpm	Optional[int]	Free-tier requests-per-minute limit, if known. Not currently populated for Gemini -- see README.
data_used_for_training	Optional[bool]	Whether using the free tier means the provider may use your prompts/outputs to improve their models. None when not applicable (e.g. no free tier exists at all).

from_dict classmethod

from_dict(data: Dict[str, Any]) -> 'FreeTierPolicy'

Rebuilds a FreeTierPolicy from a dict produced by :meth:to_dict.

to_dict

to_dict() -> Dict[str, Any]

Returns a plain, JSON-serializable dict of this policy.

llm_catalogue.models.Vendor

Bases: str, Enum

The AI providers this package tracks.

A str subclass, so Vendor.OPENAI == "openai" and it serializes as a plain string in JSON without needing a custom encoder.

llm_catalogue.models.ModelStatus

Bases: str, Enum

Lifecycle state of a model, as stated by the provider's own docs.

Attributes:

Name	Type	Description
ACTIVE		Generally available and recommended for new use.
DEPRECATED		Still usable but the provider is steering users away.
RETIRED		Shut down, or only available on a narrow legacy channel (e.g. "except on Bedrock and Google Cloud").
LIMITED		Gated behind restricted/limited availability.