Struct Catalog 

pub struct Catalog { /* private fields */ }

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.

Implementations

impl Catalog

pub fn facts(&self, provider: ProviderId, model: &str) -> ModelFacts

The facts of provider’s model from this catalog: its entry by Self::get’s rule, bound to model as written, and this catalog for every other model a request names. A model the catalog does not list binds nothing.

impl Catalog

pub fn from_overrides( json: &str, base: &Catalog, ) -> Result<Catalog, OverrideErrors>

Read a user’s override file, laid over base afterwards with Self::with_overrides. The file is in the shape of Self::from_models_dev’s, with each section holding only models, and each row only the keys rig reads plus its hand-entered facts under rig.

base is the catalog the file will be laid over. A row for a model base does not list exactly adds that model, so it must set reasoning, tool_call and modalities, which an absent key would otherwise turn into “the model does not”. That catches a misspelt model id, and a dated snapshot id whose row would hide its base model’s facts.

Errors

OverrideErrors holding every mistake found, each with its path: an unknown vendor key or field, with the closest known one; a new model that leaves out a needed key, with the closest listed id; and a value of the wrong type. Text that is not a JSON object is one error with an empty path.

pub fn from_models_dev( json: &str, ) -> Result<(Catalog, Vec<Skipped>), CatalogError>

Read models.dev’s api.json, or a file in its shape: an object of provider keys, each with a models object keyed by model id. A provider key is a models.dev key (google, amazon-bedrock) or a rig vendor name (gcp.gemini). Keys rig does not read are ignored, and a provider rig does not know, or a section or row that does not read, is skipped and listed, so the rest of the file still loads.

A row may carry rig’s hand-entered facts under rig, among them format, the protocol family the model is reached by when that is not its vendor’s own (see ProviderId::catalog).

Errors

CatalogError::Json when the text is not a JSON object.

impl Catalog

pub fn builtin() -> &'static Catalog

The catalog this build ships.

Panics

Panics on first use if the data compiled into this build does not parse whole. The data is checked in and a unit test parses it, so a build that passed its tests never panics here.

pub fn generated_at() -> SystemTime

When the models.dev data behind Self::builtin was read. Lay a fetched copy on only when it is newer, so an old cache never hides what this rig shipped.

pub fn get(&self, provider: ProviderId, model: &str) -> Option<Resolved<'_>>

The model provider serves as model, by the one rule every lookup in rig follows: the id as listed, or else the longest listed id that model extends with -20 and a year, a dated snapshot of it (claude-sonnet-4-5-20250929, gpt-5-2025-08-07, claude-opus-5-5-20260601-v1:0). Any selection of a vendor finds that vendor’s models.

pub fn get_exact(&self, provider: ProviderId, model: &str) -> Option<&ModelSpec>

The model provider lists as exactly model, for a caller that must not read a snapshot as its base model.

pub fn resolve(&self, reference: &str) -> Result<Resolved<'_>, NotFound>

The model a reference names, by Self::get’s rule. A reference is vendor/model, split at the first /, so the model id keeps any / and : of its own (openrouter/anthropic/claude-sonnet-4.5, ollama/qwen3:4b). The older vendor/format:model spelling is still read; its format plays no part in the lookup.

Errors

NotFound when the reference names no listed model, with up to five close references to models that are not deprecated, or else the closest ones of its vendor.

pub fn iter(&self) -> impl Iterator<Item = &ModelSpec>

Every model, by vendor then id.

pub fn with_overrides(&self, overrides: &Catalog) -> Catalog

This catalog with overrides laid over it, field by field. A model in both keeps every field the override leaves out; a model only in overrides is added. self is unchanged, and the result shares every row the override does not touch.

Every field the override sets wins, including the facts rig reviewed by hand, so lay a fetched copy of models.dev on with Self::with_models_dev instead.

pub fn with_models_dev(&self, fetched: &Catalog) -> Catalog

This catalog with fetched, a newer copy of models.dev read with Self::from_models_dev, laid over it as Self::with_overrides lays an override, except for the fields of a row that rig’s own data pins. The built-in data pins the fields rig reviewed by hand and the ones its generator joins from another row (a gateway’s Claude row takes Anthropic’s reasoning options), so a refresh updates prices and limits models.dev changes but keeps those. A model only in fetched is added as models.dev lists it.

pub fn insert(&mut self, spec: ModelSpec)

Add spec, replacing any model of the same vendor and id whole. A later Self::with_overrides lays an override on it field by field, as on any other row.

impl Catalog

pub fn connect<'a>( &self, model: impl Into<ModelSelector<'a>>, ) -> Result<DynModel<Completion>, ConnectError>

Available on crate feature reqwest only.

The completion model model selects, with the key from the environment, on the shared reqwest client. See Self::connect_with.

use rig_core::catalog::Catalog;

let catalog = Catalog::builtin();
let model = catalog.connect("anthropic/claude-opus-5-5")?; // ANTHROPIC_API_KEY
let spec = catalog.resolve("openai/gpt-5.5")?.spec;
let other = catalog.connect(spec)?; // OPENAI_API_KEY

pub fn connect_with<'a>( &self, model: impl Into<ModelSelector<'a>>, options: ConnectOptions, ) -> Result<DynModel<Completion>, ConnectError>

The completion model model selects, connected as options say.

A reference is read as Self::resolve reads it, and the model id is sent as written. A model this catalog does not list still connects, on a vendor it knows. The family is options’s, else the one the older vendor/format:model spelling names, else the one the catalog row (or the spec) is reached by, else the vendor’s primary. Unless options give a key, it is read from the first of the vendor’s api_key_envs set to a non-empty value, along with the base URL and other settings its dialect reads from the environment. An account options name replaces the one the dialect reads.

The model encodes and prices with this catalog’s facts: the spec it was connected from, and this catalog for any other model a request names, so the catalog’s overrides reach its requests and reported cost.

Errors

ConnectError::Malformed for a reference that is not vendor/model, ConnectError::NotFound for an unknown vendor, ConnectError::CatalogOnly for a provider a companion crate serves, ConnectError::Selection for a family the vendor is not registered for, ConnectError::MissingKey when no key is given or set, and ConnectError::NoHttpClient without the reqwest feature and an HTTP client.

Trait Implementations

impl Clone for Catalog

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Catalog

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Catalog

fn default() -> Self

Returns the “default value” for a type.