Module catalog 

Model facts by provider and model id: limits, input modalities, reasoning, caching, prices.

A catalog is built in layers, each sharing the rows it does not change:

1. Catalog::builtin: generated from models.dev by cargo xtask catalog sync, its main providers reviewed by hand;
2. a newer models.dev copy (Catalog::from_models_dev, lenient; laid on with Catalog::with_models_dev, which keeps the hand-reviewed fields);
3. the user’s overrides (Catalog::from_overrides, strict, with a close alternative for every mistake; laid on with Catalog::with_overrides).

A model connected earlier keeps the facts it was connected with.

use std::path::Path;
use rig_core::catalog::Catalog;

fn catalog(cache: &Path, config: &Path) -> Result<Catalog, Box<dyn std::error::Error>> {
    let mut catalog = Catalog::builtin().clone();
    let fetched = cache.join("models-dev.json");
    if std::fs::metadata(&fetched)
        .and_then(|file| file.modified())
        .is_ok_and(|fetched_at| fetched_at > Catalog::generated_at())
    {
        let (models_dev, _skipped) = Catalog::from_models_dev(&std::fs::read_to_string(&fetched)?)?;
        catalog = catalog.with_models_dev(&models_dev);
    }
    if let Ok(json) = std::fs::read_to_string(config.join("models.json")) {
        catalog = catalog.with_overrides(&Catalog::from_overrides(&json, &catalog)?);
    }
    Ok(catalog)
}

Catalog::connect builds a model from vendor/model with the key from the environment; it encodes and prices with the ModelFacts it was connected with. ModelSpec::validate checks a request’s options before anything is sent:

use rig_core::catalog::Catalog;
use rig_core::completion::{Effort, GenerationOptions};

let haiku = Catalog::builtin().resolve("anthropic/claude-haiku-4-5")?.spec;
let options = GenerationOptions::default().reasoning(Effort::High);
assert!(haiku.validate(&options).is_err(), "Haiku 4.5 takes a budget");

Structs

CacheSupport

The cache retentions a model honours.

Catalog

Model facts by provider and model id. Cloning is cheap: the rows are shared, and a change copies only the list of handles to them.

Compat

Wire facts the encoders read that no portable field holds. Each defaults to false or None, which is what a model the field does not concern has. An override file sets each one by its field name under a row’s rig object, and a spec built in code sets it with the with_* setter of the same name.

Connector

The models an application can use and how each is reached: a catalog, rig’s built-in one by default, whose models connect through the provider registered for their vendor (Self::provide), else with the environment’s keys, else through the first SignIn that serves them, each on an HTTP client wrapped by its Transport. Cloning is cheap. It is Send and Sync natively; on browser wasm its providers, sign-ins and wrappers may hold JavaScript values instead.

Modalities

What a model reads.

ModelFacts

The facts a completion wire encodes with: the spec of the model it was connected to, and the catalog that spec came from, which answers for any other model a request names. Every completion wire holds one, and its Descriptor hands it to the completion fold, which prices usage from it.

ModelSpec

One model’s facts: limits, input modalities, the reasoning and caching it takes, and its prices. Catalog builds one per row of its data; ModelSpec::new and the with_* setters build one in code, for a model the catalog does not list, and Catalog::insert adds it.

NotFound

A reference the catalog does not list, with up to five listed models whose references are close to it, or else the closest models of its vendor.

OverrideError

One mistake in an override file.

OverrideErrors

Every mistake Catalog::from_overrides found, in file order.

Pricing

Prices in USD per million tokens.

ReasoningChoice

A reasoning setting a model takes, by the name a picker shows: the provider default (default, no setting), off, an effort level, or a named budget.

Resolved

A model the catalog found, and how the requested id matched it.

Skipped

A part of a models.dev file Catalog::from_models_dev did not read.

Transport

The wrappers a Connector applies to every HTTP client its models are reached through, in the order added: the first is closest to the network. Cloning is cheap.

UnknownReasoning

A reasoning setting a model does not take, and the ones it does.

Enums

CatalogError

Why catalog data did not load.

Matched

How a requested model id matched its catalog entry.

ModelStatus

Whether a Connector can reach a catalog model for an agent, and why not, for a picker’s note.

OverrideErrorKind

What is wrong at an OverrideError’s path.

ReasoningSupport

The reasoning a model takes, in one of three states: it does not reason, it reasons but the catalog does not say which controls it takes, or it reasons and takes exactly the listed controls.

Sampling

When a model takes sampling parameters.

SkipReason

Why Catalog::from_models_dev skipped part of its input.

Traits

Provide

How a Connector reaches every model of one vendor, in place of the registry’s preset and the environment: a vendor declared at run time (ProviderId::declare) on a gateway of its own, a built-in vendor at another address, or a scripted model in a test.

SignIn

A way to reach catalog models no key is set for, such as a subscription plan signed in to. A Connector asks it for a model only when the provider registered for the model’s vendor, else the environment, has no key for it.