feat(rust): add immutable model catalog crate (#42605)

* feat(rust): add immutable model catalog crate

* feat(rust): add typed model info mirror, error module, and schema feature

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

* refactor(rust): split catalog module, rstest tests, and repo data parity tests

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

---------

Co-authored-by: Yujong Lee <yujong@berri.ai>
Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

litellm-rust/Cargo.lock

@@ -3054,6 +3054,20 @@ dependencies = [
  "url",
 ]
 
+[[package]]
+name = "litellm-model-catalog"
+version = "0.1.0"
+dependencies = [
+ "criterion",
+ "indexmap 2.14.0",
+ "litellm-model-catalog",
+ "rstest",
+ "schemars 1.2.2",
+ "serde",
+ "serde_json",
+ "thiserror 2.0.19",
+]
+
 [[package]]
 name = "litellm-python-bridge"
 version = "0.1.0"
@@ -4756,10 +4770,23 @@ checksum = "687274d293b6cdc6e73e0fee520bf2049650090d7164f87672d212a3c530cf4a"
 dependencies = [
  "dyn-clone",
  "ref-cast",
+ "schemars_derive",
  "serde",
  "serde_json",
 ]
 
+[[package]]
+name = "schemars_derive"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d98c67716b46af2f0b8cf752abc930f6f9aecfbf671ecfb531db8a31dbe4e2ba"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "serde_derive_internals",
+ "syn 3.0.0",
+]
+
 [[package]]
 name = "scopeguard"
 version = "1.2.0"
@@ -4848,6 +4875,17 @@ dependencies = [
  "syn 3.0.0",
 ]
 
+[[package]]
+name = "serde_derive_internals"
+version = "0.30.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f852137cce035d6a4df67ccce505ff6b3e9fd3a10e3e52b24dc71e650bb1a9bd"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.0",
+]
+
 [[package]]
 name = "serde_json"
 version = "1.0.150"

litellm-rust/crates/model-catalog/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "litellm-model-catalog"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[features]
+schema = ["dep:schemars"]
+
+[dependencies]
+indexmap = { version = "2.14.0", features = ["serde"] }
+schemars = { version = "1.0", optional = true }
+serde.workspace = true
+serde_json.workspace = true
+thiserror.workspace = true
+
+[dev-dependencies]
+criterion.workspace = true
+rstest.workspace = true
+litellm-model-catalog = { path = ".", features = ["schema"] }
+
+[[bench]]
+name = "catalog"
+harness = false

litellm-rust/crates/model-catalog/README.md

@@ -0,0 +1,25 @@
+# Model catalog
+
+`litellm-model-catalog` builds an immutable snapshot from caller supplied JSON bytes. It has no network, Python, registration, or refresh behavior. The caller supplies optional source, revision, and ETag provenance. Parse and validation are separate so small synthetic catalogs can use explicit integrity limits
+
+The parser treats `sample_spec` and `fallback_generalizations` as reserved top level metadata. `fallback_rules()` exposes the typed rule array when present; this crate does not execute regex generalizations. Model entries retain all JSON fields except `aliases`, including unknown fields. `field()` returns `None` for an absent key and a JSON null, false, or zero value for a present key. The returned values are borrowed, so callers cannot mutate the snapshot
+
+Each entry also deserializes into `ModelInfo`, a typed mirror of `model_prices_and_context_window.schema.json`'s `modelEntry` definition, reachable via `ModelEntry::info()`. All schema fields are optional on `ModelInfo`, including `litellm_provider` which the schema marks required, so small synthetic catalogs still parse. Unknown fields are not part of `ModelInfo`; they remain on `fields()`. Building with the `schema` feature adds `schemars` derives and exposes `model_entry_json_schema()` for emitting the entry's JSON Schema. Parse and validation failures are reported by the `Error` enum in `error.rs`, while catalog logic lives in `catalog.rs`
+
+The integration tests read the repository's catalog and schema files at test time, assert every entry round-trips through `ModelInfo`, and verify that the generated schema's properties match the repository schema
+
+Aliases point to their canonical entries. An alias that exactly matches any canonical key is skipped; the first canonical entry claiming an alias wins. Invalid alias lists and nonstring names are skipped and reported by `alias_issues()`. Exact lookup wins. For a case insensitive miss, the last key with the same lowercase spelling wins, following Python's lowercase map built after aliases are appended. This uses Rust Unicode lowercasing, which can differ from Python for unusual Unicode model IDs
+
+`validate()` counts canonical entries before alias expansion and excludes both reserved keys. It enforces an explicit minimum and backup shrink ratio, with Python defaults of 50 models and 0.5. Parsing rejects nonobject model entries and known fields with the wrong JSON type, but ignores unknown fields. It does not enforce every constraint in the JSON schema, calculate prices, resolve providers, or check provenance authenticity. The caller decides how to handle validation failures
+
+This snapshot does not represent Python's live mutable `litellm.model_cost`, nested dict and list mutation, or mutation of dicts previously returned by Python APIs. It has no bridge or runtime integration
+
+## Benchmarks
+
+`cargo bench -p litellm-model-catalog --bench catalog` measures parsing plus alias indexing and exact lookup. For a local Python baseline on the same fixture, use:
+
+```sh
+python3 -m timeit -s 'import json, pathlib; body = pathlib.Path("../model_prices_and_context_window.json").read_bytes()' 'json.loads(body)'
+```
+
+Run these commands from `litellm-rust`. Python's command measures JSON loading only, without alias expansion or snapshot construction. The Rust benchmark does not include future Python object materialization, so these numbers are not an end to end runtime comparison

litellm-rust/crates/model-catalog/benches/catalog.rs

@@ -0,0 +1,21 @@
+use criterion::{Criterion, criterion_group, criterion_main};
+use litellm_model_catalog::{Catalog, Provenance};
+use std::hint::black_box;
+
+fn benchmarks(c: &mut Criterion) {
+    let body = include_bytes!("../../../../model_prices_and_context_window.json");
+    c.bench_function("parse_current_catalog", |b| {
+        b.iter(|| Catalog::parse(black_box(body), Provenance::default()).unwrap())
+    });
+    let catalog = Catalog::parse(body, Provenance::default()).unwrap();
+    let key = catalog
+        .model_names()
+        .next()
+        .expect("catalog must have a benchmark key");
+    c.bench_function("lookup_catalog_key", |b| {
+        b.iter(|| black_box(&catalog).lookup(black_box(key)))
+    });
+}
+
+criterion_group!(benches, benchmarks);
+criterion_main!(benches);

litellm-rust/crates/model-catalog/src/catalog.rs

@@ -0,0 +1,241 @@
+use crate::error::Error;
+use crate::model_info::{FallbackGeneralizations, FallbackRule, ModelInfo};
+use indexmap::IndexMap;
+use serde::Deserialize;
+use serde_json::{Map, Value};
+use std::collections::HashMap;
+
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct Provenance {
+    pub source: Option<String>,
+    pub revision: Option<String>,
+    pub etag: Option<String>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct IntegrityLimits {
+    pub backup_model_count: usize,
+    pub min_model_count: usize,
+    pub min_backup_ratio: f64,
+}
+
+impl IntegrityLimits {
+    pub fn python_defaults(backup_model_count: usize) -> Self {
+        Self {
+            backup_model_count,
+            min_model_count: 50,
+            min_backup_ratio: 0.5,
+        }
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum AliasIssue {
+    InvalidList { model: String },
+    InvalidName { model: String },
+    CanonicalCollision { model: String, alias: String },
+    AliasCollision { model: String, alias: String },
+}
+
+#[derive(Clone, Debug)]
+pub struct ModelEntry {
+    fields: Map<String, Value>,
+    info: ModelInfo,
+}
+
+impl ModelEntry {
+    pub fn field(&self, name: &str) -> Option<&Value> {
+        self.fields.get(name)
+    }
+    pub fn fields(&self) -> &Map<String, Value> {
+        &self.fields
+    }
+    /// The entry deserialized into the typed mirror of the catalog schema.
+    pub fn info(&self) -> &ModelInfo {
+        &self.info
+    }
+}
+
+#[derive(Clone, Copy, Debug)]
+pub struct ModelMatch<'a> {
+    pub matched_key: &'a str,
+    pub canonical_key: &'a str,
+    pub entry: &'a ModelEntry,
+}
+
+#[derive(Debug)]
+pub struct Catalog {
+    entries: IndexMap<String, ModelEntry>,
+    aliases: IndexMap<String, String>,
+    lowercase_keys: HashMap<String, String>,
+    sample_spec: Option<Value>,
+    fallback_generalizations: Option<FallbackGeneralizations>,
+    provenance: Provenance,
+    alias_issues: Vec<AliasIssue>,
+}
+
+impl Catalog {
+    pub fn parse(body: &[u8], provenance: Provenance) -> Result<Self, Error> {
+        let root: IndexMap<String, Value> = serde_json::from_slice(body)?;
+        if root.is_empty() {
+            return Err(Error::Empty);
+        }
+
+        let mut entries = IndexMap::with_capacity(root.len());
+        let mut alias_lists = Vec::new();
+        let mut alias_issues = Vec::new();
+        let mut sample_spec = None;
+        let mut fallback_generalizations = None;
+        for (name, value) in root {
+            match name.as_str() {
+                "sample_spec" => {
+                    sample_spec = Some(value);
+                    continue;
+                }
+                "fallback_generalizations" => {
+                    fallback_generalizations =
+                        Some(serde_json::from_value::<FallbackGeneralizations>(value)?);
+                    continue;
+                }
+                _ => {}
+            }
+            let Value::Object(ref object) = value else {
+                return Err(Error::EntryNotObject { model: name });
+            };
+            let info = ModelInfo::deserialize(object)?;
+            let Value::Object(mut fields) = value else {
+                unreachable!("value checked is_object above")
+            };
+            if let Some(aliases) = fields.remove("aliases")
+                && !aliases.is_null()
+            {
+                match aliases {
+                    Value::Array(names) => alias_lists.push((name.clone(), names)),
+                    _ => alias_issues.push(AliasIssue::InvalidList {
+                        model: name.clone(),
+                    }),
+                }
+            }
+            entries.insert(name, ModelEntry { fields, info });
+        }
+
+        let mut aliases = IndexMap::new();
+        for (model, names) in alias_lists {
+            for name in names {
+                let Value::String(alias) = name else {
+                    alias_issues.push(AliasIssue::InvalidName {
+                        model: model.clone(),
+                    });
+                    continue;
+                };
+                if entries.contains_key(&alias) {
+                    alias_issues.push(AliasIssue::CanonicalCollision {
+                        model: model.clone(),
+                        alias,
+                    });
+                } else if aliases.contains_key(&alias) {
+                    alias_issues.push(AliasIssue::AliasCollision {
+                        model: model.clone(),
+                        alias,
+                    });
+                } else {
+                    aliases.insert(alias, model.clone());
+                }
+            }
+        }
+
+        let lowercase_keys = entries
+            .keys()
+            .chain(aliases.keys())
+            .map(|key| (key.to_lowercase(), key.clone()))
+            .collect();
+        Ok(Self {
+            entries,
+            aliases,
+            lowercase_keys,
+            sample_spec,
+            fallback_generalizations,
+            provenance,
+            alias_issues,
+        })
+    }
+
+    pub fn validate(&self, limits: IntegrityLimits) -> Result<(), Error> {
+        if !limits.min_backup_ratio.is_finite() || !(0.0..=1.0).contains(&limits.min_backup_ratio) {
+            return Err(Error::InvalidRatio);
+        }
+        let actual = self.entries.len();
+        if actual < limits.min_model_count {
+            return Err(Error::BelowMinimum {
+                actual,
+                minimum: limits.min_model_count,
+            });
+        }
+        if limits.backup_model_count > 0
+            && (actual as f64) < (limits.backup_model_count as f64) * limits.min_backup_ratio
+        {
+            return Err(Error::Shrunk {
+                actual,
+                backup: limits.backup_model_count,
+                ratio: limits.min_backup_ratio,
+            });
+        }
+        Ok(())
+    }
+
+    pub fn lookup(&self, key: &str) -> Option<ModelMatch<'_>> {
+        let matched_key = if self.entries.contains_key(key) || self.aliases.contains_key(key) {
+            key
+        } else {
+            self.lowercase_keys.get(&key.to_lowercase())?.as_str()
+        };
+        let canonical_key = self
+            .aliases
+            .get(matched_key)
+            .map(String::as_str)
+            .unwrap_or(matched_key);
+        let (canonical_key, entry) = self.entries.get_key_value(canonical_key)?;
+        let matched_key = self
+            .entries
+            .get_key_value(matched_key)
+            .map(|(key, _)| key.as_str())
+            .or_else(|| {
+                self.aliases
+                    .get_key_value(matched_key)
+                    .map(|(key, _)| key.as_str())
+            })?;
+        Some(ModelMatch {
+            matched_key,
+            canonical_key,
+            entry,
+        })
+    }
+
+    pub fn model_count(&self) -> usize {
+        self.entries.len()
+    }
+    pub fn model_names(&self) -> impl Iterator<Item = &str> {
+        self.entries.keys().map(String::as_str)
+    }
+    pub fn alias_count(&self) -> usize {
+        self.aliases.len()
+    }
+    pub fn aliases(&self) -> &IndexMap<String, String> {
+        &self.aliases
+    }
+    pub fn alias_issues(&self) -> &[AliasIssue] {
+        &self.alias_issues
+    }
+    pub fn sample_spec(&self) -> Option<&Value> {
+        self.sample_spec.as_ref()
+    }
+    pub fn fallback_generalizations(&self) -> Option<&FallbackGeneralizations> {
+        self.fallback_generalizations.as_ref()
+    }
+    pub fn fallback_rules(&self) -> Option<&[FallbackRule]> {
+        Some(self.fallback_generalizations.as_ref()?.rules.as_slice())
+    }
+    pub fn provenance(&self) -> &Provenance {
+        &self.provenance
+    }
+}

litellm-rust/crates/model-catalog/src/error.rs

@@ -0,0 +1,28 @@
+use thiserror::Error;
+
+/// Failures from parsing or validating a catalog snapshot.
+#[derive(Debug, Error)]
+pub enum Error {
+    /// The body is not valid JSON, or a model entry fails typed deserialization.
+    #[error("invalid JSON: {0}")]
+    Json(#[from] serde_json::Error),
+    /// The catalog has no entries at all.
+    #[error("catalog is empty")]
+    Empty,
+    /// A non-reserved top level value is not a JSON object.
+    #[error("model {model:?} must be an object")]
+    EntryNotObject { model: String },
+    /// Canonical entry count is under the configured minimum.
+    #[error("catalog has {actual} models, below minimum {minimum}")]
+    BelowMinimum { actual: usize, minimum: usize },
+    /// Canonical entry count is under the configured backup shrink ratio.
+    #[error("catalog has {actual} models, below {ratio} of backup count {backup}")]
+    Shrunk {
+        actual: usize,
+        backup: usize,
+        ratio: f64,
+    },
+    /// The configured minimum backup ratio is not finite or outside `[0, 1]`.
+    #[error("minimum backup ratio must be finite and between zero and one")]
+    InvalidRatio,
+}

litellm-rust/crates/model-catalog/src/lib.rs

@@ -0,0 +1,16 @@
+mod catalog;
+mod error;
+mod model_info;
+#[cfg(feature = "schema")]
+mod schema;
+
+pub use catalog::{AliasIssue, Catalog, IntegrityLimits, ModelEntry, ModelMatch, Provenance};
+pub use error::Error;
+pub use model_info::{
+    AudioFormat, FallbackGeneralizations, FallbackRule, InputModality, Mode, ModelInfo,
+    OffPeakPricing, OffPeakWindow, OutputModality, ReasoningEffort, SearchContextCostPerQuery,
+    TieredRate, UtcHours, VertexAiAudioApi, WebSearchBillingUnit, Weekday,
+};
+
+#[cfg(feature = "schema")]
+pub use schema::model_entry_json_schema;

litellm-rust/crates/model-catalog/src/model_info.rs

@@ -0,0 +1,665 @@
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use std::collections::BTreeMap;
+
+/// Primary API surface / task type of the model.
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum Mode {
+    AudioSpeech,
+    AudioTranscription,
+    Chat,
+    Completion,
+    Embedding,
+    Evaluation,
+    Guardrail,
+    ImageEdit,
+    ImageGeneration,
+    Moderation,
+    Ocr,
+    Realtime,
+    Rerank,
+    Responses,
+    Search,
+    VectorStore,
+    VideoGeneration,
+}
+
+/// Reasoning effort level accepted or applied by the model.
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum ReasoningEffort {
+    None,
+    Minimal,
+    Low,
+    Medium,
+    High,
+    Xhigh,
+    Max,
+}
+
+/// Gemini audio generation API the model is served through.
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum VertexAiAudioApi {
+    LyriaPredict,
+    LyriaInteractions,
+}
+
+/// Whether web search is billed per query or per prompt.
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum WebSearchBillingUnit {
+    PerQuery,
+    PerPrompt,
+}
+
+/// Audio container format the model can return.
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum AudioFormat {
+    Mp3,
+    Wav,
+}
+
+/// Input modality the model accepts.
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum InputModality {
+    Text,
+    Image,
+    Audio,
+    Video,
+}
+
+/// Output modality the model can produce.
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+#[serde(rename_all = "snake_case")]
+pub enum OutputModality {
+    Text,
+    Image,
+    Audio,
+    Video,
+    Code,
+}
+
+/// UTC "HH:MM-HH:MM" window, or a list of them; a window may wrap past midnight.
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+#[serde(untagged)]
+pub enum UtcHours {
+    Single(String),
+    Multiple(Vec<String>),
+}
+
+/// ISO-8601 weekday number (1 = Monday .. 7 = Sunday) or English day name.
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+#[serde(untagged)]
+pub enum Weekday {
+    Number(u8),
+    Name(String),
+}
+
+/// One off-peak window entry inside `windows`.
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct OffPeakWindow {
+    pub hours_utc: UtcHours,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub weekdays: Option<Vec<Weekday>>,
+}
+
+/// Rates that replace the same-named base fields inside the stated UTC windows.
+#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct OffPeakPricing {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub hours_utc: Option<UtcHours>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub windows: Option<Vec<OffPeakWindow>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub weekday_timezone: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_token: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_token: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_reasoning_token: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_token_cost: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_creation_input_token_cost: Option<f64>,
+}
+
+/// USD cost per web search query, keyed by search context size.
+#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct SearchContextCostPerQuery {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub search_context_size_low: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub search_context_size_medium: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub search_context_size_high: Option<f64>,
+}
+
+/// One tier of a context-length or result-count tiered rate.
+#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct TieredRate {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub range: Option<[f64; 2]>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_results_range: Option<[f64; 2]>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_token: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_token: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_reasoning_token: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_token_cost: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_creation_input_token_cost: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_query: Option<f64>,
+}
+
+/// One regex rule generalizing unknown model ids to known families.
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+pub struct FallbackRule {
+    pub name: String,
+    pub pattern: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub description: Option<String>,
+    #[serde(flatten)]
+    pub extra: BTreeMap<String, Value>,
+}
+
+/// Regex rules that generalize unknown model ids to known families; not a model entry.
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+#[serde(deny_unknown_fields)]
+pub struct FallbackGeneralizations {
+    pub rules: Vec<FallbackRule>,
+}
+
+/// Typed mirror of one catalog model entry.
+#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
+#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
+pub struct ModelInfo {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub annotation_cost_per_page: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub annotation_cost_per_page_batches: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub audio_transcription_config: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub bedrock_converse_supports_strict_tools: Option<bool>,
+    /// Highest reasoning effort the Bedrock output_config accepts for this model.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub bedrock_output_config_effort_ceiling: Option<ReasoningEffort>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_creation_input_audio_token_cost: Option<f64>,
+    /// USD per token written to the provider's prompt cache.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_creation_input_token_cost: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_creation_input_token_cost_above_128k_tokens: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_creation_input_token_cost_above_1hr: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_creation_input_token_cost_above_1hr_above_200k_tokens: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_creation_input_token_cost_above_200k_tokens: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_creation_input_token_cost_above_256k_tokens: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_creation_input_token_cost_above_272k_tokens: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_creation_input_token_cost_above_272k_tokens_batches: Option<f64>,
+    /// Flex service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_creation_input_token_cost_above_272k_tokens_flex: Option<f64>,
+    /// Priority service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_creation_input_token_cost_above_272k_tokens_priority: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_creation_input_token_cost_batches: Option<f64>,
+    /// Flex service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_creation_input_token_cost_flex: Option<f64>,
+    /// Priority service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_creation_input_token_cost_priority: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_audio_token_cost: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_image_token_cost: Option<f64>,
+    /// USD per prompt token served from the provider's prompt cache.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_token_cost: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_token_cost_above_128k_tokens: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_token_cost_above_200k_tokens: Option<f64>,
+    /// Priority service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_token_cost_above_200k_tokens_priority: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_token_cost_above_256k_tokens: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_token_cost_above_272k_tokens: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_token_cost_above_272k_tokens_batches: Option<f64>,
+    /// Flex service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_token_cost_above_272k_tokens_flex: Option<f64>,
+    /// Priority service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_token_cost_above_272k_tokens_priority: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_token_cost_above_512k_tokens: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_token_cost_batches: Option<f64>,
+    /// Flex service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_token_cost_flex: Option<f64>,
+    /// Priority service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cache_read_input_token_cost_priority: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub citation_cost_per_token: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub code_interpreter_cost_per_session: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub comment: Option<String>,
+    /// Reasoning effort the provider applies when the request omits reasoning_effort. Gates whether a non-default temperature or the top_p/logprobs sampling params are accepted, which hold only when the effort resolves to 'none'.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub default_reasoning_effort: Option<ReasoningEffort>,
+    /// Date the provider deprecates the model, YYYY-MM-DD.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub deprecation_date: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub gemini_audio_only_live: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub gemini_native_audio: Option<bool>,
+    /// USD per Grounding with Google Maps request; billed per query or per prompt per web_search_billing_unit.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub google_maps_grounding_cost_per_query: Option<f64>,
+    /// USD cost per billable guardrail unit, keyed by the provider's usage counter name (e.g. Bedrock's contentPolicyUnits).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub guardrail_cost_per_unit: Option<BTreeMap<String, f64>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_audio_per_second: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_audio_per_second_above_128k_tokens: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_audio_token: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_audio_token_batches: Option<f64>,
+    /// Priority service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_audio_token_priority: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_character: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_character_above_128k_tokens: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_image: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_image_above_128k_tokens: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_image_token: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_image_token_batches: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_pixel: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_query: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_request: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_second: Option<f64>,
+    /// USD per prompt token.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_token: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_token_above_128k_tokens: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_token_above_200k_tokens: Option<f64>,
+    /// Priority service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_token_above_200k_tokens_priority: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_token_above_256k_tokens: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_token_above_272k_tokens: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_token_above_272k_tokens_batches: Option<f64>,
+    /// Flex service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_token_above_272k_tokens_flex: Option<f64>,
+    /// Priority service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_token_above_272k_tokens_priority: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_token_above_512k_tokens: Option<f64>,
+    /// USD per prompt token via the provider's batch API.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_token_batches: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_token_cache_hit: Option<f64>,
+    /// Flex service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_token_flex: Option<f64>,
+    /// Priority service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_token_priority: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_video_per_second: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_video_per_second_above_128k_tokens: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_video_per_second_above_15s_interval: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_video_per_second_above_8s_interval: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_video_token: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_cost_per_video_token_batches: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub input_dbu_cost_per_token: Option<f64>,
+    /// LiteLLM provider slug; one of https://docs.litellm.ai/docs/providers.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub litellm_provider: Option<String>,
+    /// Maximum prompt/context tokens the model accepts.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_input_tokens: Option<u64>,
+    /// Maximum tokens the model can generate in one response.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_output_tokens: Option<u64>,
+    /// Legacy field: max output tokens if the provider specifies it, else max input tokens.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub max_tokens: Option<u64>,
+    /// Free-form notes about the entry (e.g. pricing derivation).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub metadata: Option<BTreeMap<String, Value>>,
+    /// Primary API surface / task type of the model.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub mode: Option<Mode>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub ocr_cost_per_credit: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub ocr_cost_per_page: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub ocr_cost_per_page_batches: Option<f64>,
+    /// Rates that replace the same-named base fields while the request falls inside the stated UTC windows.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub off_peak_pricing: Option<OffPeakPricing>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_audio_token: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_character: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_character_above_128k_tokens: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_image: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_image_1024: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_image_1536: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_image_512: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_image_token: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_pixel: Option<f64>,
+    /// USD per reasoning/thinking token, when billed separately.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_reasoning_token: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_second: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_second_1080p: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_second_2k: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_second_480p: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_second_4k: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_second_720p: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_second_768p: Option<f64>,
+    /// USD per generated token.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_token: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_token_above_128k_tokens: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_token_above_200k_tokens: Option<f64>,
+    /// Priority service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_token_above_200k_tokens_priority: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_token_above_256k_tokens: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_token_above_272k_tokens: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_token_above_272k_tokens_batches: Option<f64>,
+    /// Flex service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_token_above_272k_tokens_flex: Option<f64>,
+    /// Priority service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_token_above_272k_tokens_priority: Option<f64>,
+    /// Rate applied once the prompt exceeds the token threshold in the field name.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_token_above_512k_tokens: Option<f64>,
+    /// USD per generated token via the provider's batch API.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_token_batches: Option<f64>,
+    /// Flex service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_token_flex: Option<f64>,
+    /// Priority service-tier rate for the same-named base field.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_token_priority: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_video_per_second: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_cost_per_video_token: Option<f64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_dbu_cost_per_token: Option<f64>,
+    /// Embedding dimension for embedding models.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_vector_size: Option<u64>,
+    /// Smallest prefix the provider will actually cache; absent means the provider default applies.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub prompt_cache_min_tokens: Option<u64>,
+    /// Provider-internal routing hints (e.g. bedrock_invocation_schema).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub provider_specific_entry: Option<BTreeMap<String, Value>>,
+    /// Exact reasoning_effort levels this deployment accepts; wins over supports_* flags.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub reasoning_effort_levels: Option<Vec<ReasoningEffort>>,
+    /// Multiplier applied to all token costs when served from a non-global Vertex AI endpoint (e.g. 1.10 = +10%).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub regional_endpoint_uplift_multiplier: Option<f64>,
+    /// Multiplier applied to all token costs for EU data residency (e.g. 1.10 = +10%).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub regional_processing_uplift_multiplier_eu: Option<f64>,
+    /// Multiplier applied to all token costs for US data residency (e.g. 1.10 = +10%).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub regional_processing_uplift_multiplier_us: Option<f64>,
+    /// Provider default requests-per-minute limit.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub rpm: Option<u64>,
+    /// USD cost per web search query, keyed by search context size.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub search_context_cost_per_query: Option<SearchContextCostPerQuery>,
+    /// URL of the provider pricing/model page this entry was taken from.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub source: Option<String>,
+    /// Audio container formats the model can return.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supported_audio_formats: Option<Vec<AudioFormat>>,
+    /// OpenAI-style API routes this model can be called through, e.g. /v1/chat/completions.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supported_endpoints: Option<Vec<String>>,
+    /// Input modalities the model accepts.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supported_modalities: Option<Vec<InputModality>>,
+    /// Output modalities the model can produce.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supported_output_modalities: Option<Vec<OutputModality>>,
+    /// Cloud regions the model is available in ('global' or region ids).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supported_regions: Option<Vec<String>>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_adaptive_thinking: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_anthropic_compaction: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_anthropic_thinking_payload: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_assistant_prefill: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_audio_input: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_audio_output: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_computer_use: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_embedding_image_input: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_fast_mode: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_forced_tool_use: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_function_calling: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_image_input: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_image_size: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_legacy_thinking: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_low_reasoning_effort: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_max_reasoning_effort: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_mid_conversation_system: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_minimal_reasoning_effort: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_multimodal: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_native_streaming: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_native_structured_output: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_none_reasoning_effort: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_nova_canvas_image_edit: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_output_config: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_parallel_function_calling: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_parallel_tool_use_config: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_pdf_input: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_prompt_cache_breakpoint: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_prompt_caching: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_reasoning: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_response_schema: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_sampling_params: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_speed: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_system_messages: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_thinking_cache_preservation: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_tool_choice: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_tool_search: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_url_context: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_video_input: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_vision: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_web_search: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub supports_xhigh_reasoning_effort: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub thinking_always_on: Option<bool>,
+    /// Context-length or result-count tiered rates; each tier's costs apply within its range.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tiered_pricing: Option<Vec<TieredRate>>,
+    /// Provider default tokens-per-minute limit.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tpm: Option<u64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub use_openai_responses_path: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub uses_embed_content: Option<bool>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub vertex_ai_audio_api: Option<VertexAiAudioApi>,
+    /// Whether web search is billed per query or per prompt.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub web_search_billing_unit: Option<WebSearchBillingUnit>,
+}

litellm-rust/crates/model-catalog/src/schema.rs

@@ -0,0 +1,7 @@
+use crate::model_info::ModelInfo;
+
+/// JSON Schema for one catalog model entry, mirroring
+/// `model_prices_and_context_window.schema.json`'s `modelEntry` definition.
+pub fn model_entry_json_schema() -> schemars::Schema {
+    schemars::schema_for!(ModelInfo)
+}

litellm-rust/crates/model-catalog/tests/catalog.rs

@@ -0,0 +1,253 @@
+use std::path::{Path, PathBuf};
+
+use litellm_model_catalog::{AliasIssue, Catalog, Error, IntegrityLimits, Provenance};
+use rstest::{fixture, rstest};
+use serde_json::json;
+
+const ALPHA_FIXTURE: &[u8] = br#"{
+    "sample_spec":{"explanation":"example"},
+    "fallback_generalizations":{"rules":[{"name":"family","pattern":"^new-","model_info":{"mode":"chat"}}]},
+    "Alpha":{"litellm_provider":"test","aliases":["short"],"price":0,"enabled":false,
+             "optional":null,"unknown":{"nested":[1,{"x":true}]}}
+}"#;
+
+#[fixture]
+fn repo_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR")).join("../../..")
+}
+
+#[fixture]
+fn current_catalog(repo_root: PathBuf) -> Catalog {
+    let body = std::fs::read(repo_root.join("model_prices_and_context_window.json")).unwrap();
+    Catalog::parse(&body, Provenance::default()).unwrap()
+}
+
+#[fixture]
+fn backup_catalog(repo_root: PathBuf) -> Catalog {
+    let body = std::fs::read(repo_root.join("litellm/model_prices_and_context_window_backup.json"))
+        .unwrap();
+    Catalog::parse(&body, Provenance::default()).unwrap()
+}
+
+#[fixture]
+fn fixture_catalog() -> Catalog {
+    Catalog::parse(
+        ALPHA_FIXTURE,
+        Provenance {
+            source: Some("fixture".into()),
+            revision: Some("rev".into()),
+            etag: None,
+        },
+    )
+    .unwrap()
+}
+
+#[rstest]
+fn preserves_fields_and_metadata(fixture_catalog: Catalog) {
+    let catalog = fixture_catalog;
+    let entry = catalog.lookup("SHORT").unwrap();
+    assert_eq!(entry.canonical_key, "Alpha");
+    assert_eq!(entry.matched_key, "short");
+    assert_eq!(entry.entry.field("price"), Some(&json!(0)));
+    assert_eq!(entry.entry.field("enabled"), Some(&json!(false)));
+    assert_eq!(entry.entry.field("optional"), Some(&json!(null)));
+    assert_eq!(entry.entry.field("missing"), None);
+    assert_eq!(
+        entry.entry.field("unknown"),
+        Some(&json!({"nested":[1,{"x":true}]}))
+    );
+    assert_eq!(entry.entry.field("aliases"), None);
+    assert_eq!(entry.entry.info().litellm_provider.as_deref(), Some("test"));
+    assert_eq!(
+        catalog.sample_spec(),
+        Some(&json!({"explanation":"example"}))
+    );
+    assert_eq!(catalog.fallback_rules().unwrap().len(), 1);
+    assert_eq!(catalog.provenance().revision.as_deref(), Some("rev"));
+    assert_eq!(catalog.model_count(), 1);
+}
+
+#[rstest]
+fn snapshot_does_not_borrow_source() {
+    let mut source = ALPHA_FIXTURE.to_vec();
+    let catalog = Catalog::parse(&source, Provenance::default()).unwrap();
+    source.fill(b' ');
+
+    let entry = catalog.lookup("short").unwrap();
+    assert_eq!(entry.canonical_key, "Alpha");
+    assert_eq!(entry.entry.field("price"), Some(&json!(0)));
+}
+
+#[rstest]
+#[case("Shared", "First")]
+#[case("Second", "Second")]
+#[case("shared", "Second")]
+#[case("FIRST", "First")]
+#[case("sHaReD", "Second")]
+fn alias_collisions_and_case_fallback_follow_python_order(
+    #[case] lookup: &str,
+    #[case] expected: &str,
+) {
+    let catalog = Catalog::parse(
+        br#"{
+            "First":{"aliases":["Shared","Second","first"],"value":1},
+            "Second":{"aliases":["Shared","sHaReD"],"value":2},
+            "SHARED":{"value":3}
+        }"#,
+        Provenance::default(),
+    )
+    .unwrap();
+    assert_eq!(catalog.lookup(lookup).unwrap().canonical_key, expected);
+    assert_eq!(catalog.alias_count(), 3);
+    assert!(
+        catalog
+            .alias_issues()
+            .contains(&AliasIssue::CanonicalCollision {
+                model: "First".into(),
+                alias: "Second".into(),
+            })
+    );
+    assert!(
+        catalog
+            .alias_issues()
+            .contains(&AliasIssue::AliasCollision {
+                model: "Second".into(),
+                alias: "Shared".into(),
+            })
+    );
+}
+
+#[derive(Debug)]
+enum ValidationOutcome {
+    Ok,
+    Shrunk,
+    BelowMinimum,
+    InvalidRatio,
+}
+
+#[rstest]
+#[case(
+    IntegrityLimits {
+        backup_model_count: 2,
+        min_model_count: 1,
+        min_backup_ratio: 0.5,
+    },
+    ValidationOutcome::Ok
+)]
+#[case(
+    IntegrityLimits {
+        backup_model_count: 3,
+        min_model_count: 1,
+        min_backup_ratio: 0.5,
+    },
+    ValidationOutcome::Shrunk
+)]
+#[case(
+    IntegrityLimits {
+        backup_model_count: 0,
+        min_model_count: 2,
+        min_backup_ratio: 0.5,
+    },
+    ValidationOutcome::BelowMinimum
+)]
+#[case(
+    IntegrityLimits {
+        backup_model_count: 0,
+        min_model_count: 0,
+        min_backup_ratio: f64::NAN,
+    },
+    ValidationOutcome::InvalidRatio
+)]
+fn integrity_uses_canonical_count_and_strict_shrink_boundary(
+    #[case] limits: IntegrityLimits,
+    #[case] expected: ValidationOutcome,
+) {
+    let catalog = Catalog::parse(
+        br#"{"sample_spec":{},"fallback_generalizations":{"rules":[]},"a":{"aliases":["b","c"]}}"#,
+        Provenance::default(),
+    )
+    .unwrap();
+    let actual = catalog.validate(limits);
+    match expected {
+        ValidationOutcome::Ok => assert!(actual.is_ok()),
+        ValidationOutcome::Shrunk => {
+            assert!(matches!(actual, Err(Error::Shrunk { actual: 1, .. })))
+        }
+        ValidationOutcome::BelowMinimum => {
+            assert!(matches!(actual, Err(Error::BelowMinimum { actual: 1, .. })))
+        }
+        ValidationOutcome::InvalidRatio => assert!(matches!(actual, Err(Error::InvalidRatio))),
+    }
+}
+
+#[derive(Debug)]
+enum MalformedOutcome {
+    Empty,
+    Json,
+    EntryNotObject,
+}
+
+#[rstest]
+#[case::empty(b"{}", MalformedOutcome::Empty)]
+#[case::invalid_json(b"{", MalformedOutcome::Json)]
+#[case::entry_not_object(br#"{"a":1}"#, MalformedOutcome::EntryNotObject)]
+#[case::fallback_rules_missing(
+    br#"{"fallback_generalizations":{},"a":{}}"#,
+    MalformedOutcome::Json
+)]
+fn malformed_input_and_aliases_have_typed_outcomes(
+    #[case] body: &[u8],
+    #[case] expected: MalformedOutcome,
+) {
+    let actual = Catalog::parse(body, Provenance::default());
+    match expected {
+        MalformedOutcome::Empty => assert!(matches!(actual, Err(Error::Empty))),
+        MalformedOutcome::Json => assert!(matches!(actual, Err(Error::Json(_)))),
+        MalformedOutcome::EntryNotObject => {
+            assert!(matches!(actual, Err(Error::EntryNotObject { .. })))
+        }
+    }
+}
+
+#[rstest]
+fn invalid_aliases_are_reported_not_fatal() {
+    let catalog = Catalog::parse(
+        br#"{"a":{"aliases":"bad"},"b":{"aliases":[9,"ok"]}}"#,
+        Provenance::default(),
+    )
+    .unwrap();
+    assert_eq!(
+        catalog.alias_issues(),
+        &[
+            AliasIssue::InvalidList { model: "a".into() },
+            AliasIssue::InvalidName { model: "b".into() },
+        ]
+    );
+    assert_eq!(catalog.lookup("ok").unwrap().canonical_key, "b");
+    assert!(catalog.lookup("missing").is_none());
+}
+
+#[rstest]
+fn parses_current_and_packaged_catalogs_without_pinning_counts(
+    current_catalog: Catalog,
+    backup_catalog: Catalog,
+) {
+    assert!(current_catalog.model_count() > 0);
+    assert!(backup_catalog.model_count() > 0);
+    assert!(current_catalog.sample_spec().is_some());
+    assert!(backup_catalog.sample_spec().is_some());
+    assert!(
+        current_catalog
+            .validate(IntegrityLimits::python_defaults(
+                backup_catalog.model_count()
+            ))
+            .is_ok()
+    );
+    for name in current_catalog.model_names() {
+        let entry = current_catalog.lookup(name).unwrap().entry;
+        assert_eq!(
+            entry.info().litellm_provider.is_some(),
+            entry.field("litellm_provider").is_some()
+        );
+    }
+}

litellm-rust/crates/model-catalog/tests/spec_parity.rs

@@ -0,0 +1,121 @@
+use std::collections::{BTreeSet, HashSet};
+use std::path::{Path, PathBuf};
+
+use indexmap::IndexMap;
+use litellm_model_catalog::{
+    Catalog, FallbackGeneralizations, ModelInfo, Provenance, model_entry_json_schema,
+};
+use rstest::{fixture, rstest};
+use serde_json::{Map, Value};
+
+#[fixture]
+fn repo_root() -> PathBuf {
+    Path::new(env!("CARGO_MANIFEST_DIR")).join("../../..")
+}
+
+fn json_eq(left: &Value, right: &Value) -> bool {
+    match (left, right) {
+        (Value::Number(left), Value::Number(right)) => left.as_f64() == right.as_f64(),
+        (Value::Array(left), Value::Array(right)) => {
+            left.len() == right.len() && left.iter().zip(right).all(|(a, b)| json_eq(a, b))
+        }
+        (Value::Object(left), Value::Object(right)) => {
+            left.len() == right.len()
+                && left
+                    .iter()
+                    .all(|(key, value)| right.get(key).is_some_and(|other| json_eq(value, other)))
+        }
+        _ => left == right,
+    }
+}
+
+fn keys(value: &Map<String, Value>) -> BTreeSet<String> {
+    value.keys().cloned().collect()
+}
+
+fn symmetric_difference(left: &BTreeSet<String>, right: &BTreeSet<String>) -> BTreeSet<String> {
+    left.symmetric_difference(right).cloned().collect()
+}
+
+#[rstest]
+#[case("model_prices_and_context_window.json")]
+#[case("litellm/model_prices_and_context_window_backup.json")]
+fn every_entry_round_trips_through_model_info(repo_root: PathBuf, #[case] filename: &str) {
+    let body = std::fs::read(repo_root.join(filename)).unwrap();
+    let document: IndexMap<String, Value> = serde_json::from_slice(&body).unwrap();
+    for (model_name, value) in document {
+        if matches!(
+            model_name.as_str(),
+            "sample_spec" | "fallback_generalizations"
+        ) {
+            continue;
+        }
+        let object = value
+            .as_object()
+            .unwrap_or_else(|| panic!("{model_name} is not an object"));
+        let info: ModelInfo = serde_json::from_value(value.clone())
+            .unwrap_or_else(|error| panic!("{model_name} does not deserialize: {error}"));
+        let serialized = serde_json::to_value(info).unwrap();
+        let serialized_object = serialized
+            .as_object()
+            .unwrap_or_else(|| panic!("{model_name} did not serialize as an object"));
+        let mut expected = object.clone();
+        expected.remove("aliases");
+        let expected_keys = keys(&expected);
+        let serialized_keys = keys(serialized_object);
+        assert_eq!(
+            expected_keys,
+            serialized_keys,
+            "{model_name} key difference: {:?}",
+            symmetric_difference(&expected_keys, &serialized_keys)
+        );
+        assert!(
+            json_eq(&Value::Object(expected), &serialized),
+            "{model_name} changed during ModelInfo round-trip"
+        );
+    }
+}
+
+#[rstest]
+fn fallback_generalizations_are_typed(repo_root: PathBuf) {
+    let body = std::fs::read(repo_root.join("model_prices_and_context_window.json")).unwrap();
+    let document: Map<String, Value> = serde_json::from_slice(&body).unwrap();
+    let Some(raw_rules) = document.get("fallback_generalizations") else {
+        return;
+    };
+    let _: FallbackGeneralizations = serde_json::from_value(raw_rules.clone()).unwrap();
+    let catalog = Catalog::parse(&body, Provenance::default()).unwrap();
+    assert!(
+        catalog
+            .fallback_rules()
+            .is_some_and(|rules| !rules.is_empty())
+    );
+}
+
+#[rstest]
+fn generated_schema_properties_match_repo_schema(repo_root: PathBuf) {
+    let body =
+        std::fs::read(repo_root.join("model_prices_and_context_window.schema.json")).unwrap();
+    let document: Value = serde_json::from_slice(&body).unwrap();
+    let repo_entry_properties = document["$defs"]["modelEntry"]["properties"]
+        .as_object()
+        .unwrap();
+    let generated = serde_json::to_value(model_entry_json_schema()).unwrap();
+    let generated_properties = generated["properties"].as_object().unwrap();
+    let expected = keys(repo_entry_properties);
+    let actual = keys(generated_properties);
+    assert_eq!(
+        expected,
+        actual,
+        "modelEntry property difference: {:?}",
+        symmetric_difference(&expected, &actual)
+    );
+
+    let repo_root_properties = document["properties"].as_object().unwrap();
+    let actual_root: HashSet<String> = repo_root_properties.keys().cloned().collect();
+    let expected_root: HashSet<String> = ["sample_spec", "fallback_generalizations"]
+        .into_iter()
+        .map(str::to_owned)
+        .collect();
+    assert_eq!(actual_root, expected_root);
+}