Catalog

The main entry point for the package.

llm_catalogue.catalogue.Catalog

Catalog(registry_path: Optional[Path] = None, auto_update: bool = False, cache_ttl_seconds: int = 86400)

Queries model pricing and free-tier metadata for OpenAI, Anthropic, and Google.

Reads only the registry bundled with the package (or a previously cached one) by default -- constructing a Catalog never makes a network call. Call refresh() explicitly to pull the latest registry from GitHub.

Loads model data, without making a network call unless asked to.

Parameters:

Name	Type	Description	Default
registry_path	Optional[Path]	Load registry data from this path instead of the default lookup (a previously cached refresh under ~/.cache/llm_catalogue/, falling back to the registry bundled with the package). Mainly useful for tests or for pointing at a registry built by your own scraper run.	None
auto_update	bool	If True, calls :meth:refresh immediately after loading -- so construction can make a network call, but only if you opt in.	False
cache_ttl_seconds	int	How long a cached refresh is considered fresh before :meth:refresh will re-fetch it. Defaults to 24 hours.	86400

all_models

all_models() -> List[AIModel]

Returns every model in the currently loaded registry, across all vendors.

find_free_models

find_free_models() -> List[AIModel]

Returns free-tier-eligible models across every vendor.

get_free_models

get_free_models(vendor: Union[str, Vendor]) -> List[AIModel]

Returns free-tier-eligible models for a vendor, or [] if none exist.

Equivalent to get_models(vendor, free_only=True). Useful for driving "show me what's free" UI without special-casing providers that have no free tier at all (e.g. OpenAI, Anthropic today).

get_model

get_model(model_id: str) -> Optional[AIModel]

Looks up a single model by its provider-native id (e.g. "gpt-4o").

Returns:

Type	Description
Optional[AIModel]	The matching :class:~llm_catalogue.models.AIModel, or None
Optional[AIModel]	if no model in the loaded registry has that id.

get_models

get_models(vendor: Union[str, Vendor], free_only: bool = False) -> List[AIModel]

Returns all models for a vendor, or [] if the vendor has none.

Parameters:

Name	Type	Description	Default
vendor	Union[str, Vendor]	A :class:~llm_catalogue.models.Vendor or one of its string aliases ("openai", "anthropic"/"claude", "google"/"gemini").	required
free_only	bool	If True, only returns models where :attr:~llm_catalogue.models.AIModel.is_free is True.	False

Raises:

Type	Description
ValueError	If vendor isn't a recognized provider or alias.

has_free_tier

has_free_tier(vendor: Union[str, Vendor]) -> bool

Returns True if the given vendor has at least one free-tier-eligible model.

Handy for a UI toggle: if catalog.has_free_tier("google"): show_free_toggle().

refresh

refresh(timeout: float = 5.0, force: bool = False) -> bool

Pulls the latest registry.json from GitHub and reloads it.

Skips the network call if a cached copy is younger than cache_ttl_seconds, unless force=True. Never raises: on any failure (offline, timeout, bad JSON) the currently loaded data is left untouched and False is returned.

Parameters:

Name	Type	Description	Default
timeout	float	Socket timeout in seconds for the HTTP request.	5.0
force	bool	If True, fetches even if a fresh-enough cache exists.	False

Returns:

Type	Description
bool	True if the loaded data is now up to date (either freshly
bool	fetched or served from a cache within TTL), False if the fetch
bool	failed and the previously loaded data is still in place.