liter-llm 2.0.1

//! Cost estimation for LLM API calls.
//!
//! Pricing and capability data is embedded at compile time from the nested
//! model catalog at `schemas/catalog.json`, generated by the
//! `liter-llm-catalog-gen` crate from [models.dev](https://models.dev) (MIT
//! License) and covering identifiers, pricing, limits, modalities, and
//! capabilities across the supported providers.
//!
//! # Example
//!
//! ```rust
//! use liter_llm::cost;
//!
//! // Returns None for unknown models.
//! assert!(cost::completion_cost("unknown-model", 100, 50).is_none());
//!
//! // Returns Some(cost_in_usd) for known models.
//! let cost = cost::completion_cost("gpt-4o", 1000, 500).expect("gpt-4o is a known model");
//! assert!(cost > 0.0);
//! ```

use std::collections::{BTreeMap, HashMap};
use std::sync::LazyLock;

use serde::{Deserialize, Serialize};

const CATALOG_JSON: &str = include_str!("../schemas/catalog.json");

/// Bare (provider-less) model names resolve only for these providers, with
/// alphabetically-first provider winning on a name collision. Every other
/// provider's models are reachable only via the combined `"{provider}/{model}"`
/// key.
const PRIMARY_PROVIDERS: [&str; 3] = ["anthropic", "google", "openai"];

/// Lazy-initialised registry flattened from the embedded catalog JSON.
/// Stores a `Result` so that parse failures surface at call time rather than
/// panicking the process (mirrors the pattern used in `provider/mod.rs`).
static PRICING: LazyLock<std::result::Result<HashMap<String, ModelPricing>, String>> =
    LazyLock::new(|| registry_from_catalog_str(CATALOG_JSON));

/// Access the flattened pricing registry, returning `None` if the embedded
/// catalog JSON was invalid.
///
/// Invalid embedded JSON is a compile-time defect; callers treat it the same
/// as an unknown model (no pricing available).
fn registry() -> Option<&'static HashMap<String, ModelPricing>> {
    PRICING.as_ref().ok()
}

/// Shape of the embedded `schemas/catalog.json`, ignoring the `$provenance`
/// and `$schema_version` metadata fields (not needed at runtime).
#[derive(Debug, Deserialize)]
struct CatalogFile {
    /// Providers keyed by provider id, in deterministic (sorted) order so
    /// that bare-name collisions resolve consistently.
    providers: BTreeMap<String, CatalogProviderRow>,
}

#[derive(Debug, Deserialize)]
struct CatalogProviderRow {
    /// Models offered by this provider, keyed by model id.
    #[serde(default)]
    models: BTreeMap<String, CatalogModelRow>,
}

#[derive(Debug, Deserialize)]
struct CatalogModelRow {
    /// Pricing, absent for models the catalog has no cost data for.
    #[serde(default)]
    pricing: Option<CatalogPricingRow>,
    /// Context window and per-request token limits.
    limit: CatalogLimitRow,
    /// Best-effort inferred usage mode (`"chat"`, `"image_generation"`, ...).
    #[serde(default)]
    mode: Option<String>,
    /// Boolean capability flags.
    capabilities: CatalogCapabilitiesRow,
}

#[derive(Debug, Deserialize)]
struct CatalogPricingRow {
    input_cost_per_token: f64,
    output_cost_per_token: f64,
    #[serde(default)]
    cache_read_input_token_cost: Option<f64>,
    #[serde(default)]
    cache_creation_input_token_cost: Option<f64>,
    #[serde(default)]
    input_cost_per_audio_token: Option<f64>,
    #[serde(default)]
    output_cost_per_audio_token: Option<f64>,
    #[serde(default)]
    output_cost_per_reasoning_token: Option<f64>,
    #[serde(default)]
    tiers: Vec<CatalogPricingTierRow>,
}

#[derive(Debug, Deserialize)]
struct CatalogPricingTierRow {
    min_context_tokens: u64,
    input_cost_per_token: f64,
    output_cost_per_token: f64,
    #[serde(default)]
    cache_read_input_token_cost: Option<f64>,
    #[serde(default)]
    cache_creation_input_token_cost: Option<f64>,
    #[serde(default)]
    input_cost_per_audio_token: Option<f64>,
    #[serde(default)]
    output_cost_per_audio_token: Option<f64>,
    #[serde(default)]
    output_cost_per_reasoning_token: Option<f64>,
}

#[derive(Debug, Deserialize)]
struct CatalogLimitRow {
    context: u64,
    #[serde(default)]
    input: Option<u64>,
    output: u64,
}

#[derive(Debug, Deserialize)]
struct CatalogCapabilitiesRow {
    vision: bool,
    function_calling: bool,
    reasoning: bool,
    structured_output: bool,
    audio_input: bool,
    audio_output: bool,
    prompt_caching: bool,
}

impl From<&CatalogPricingTierRow> for PricingTier {
    fn from(row: &CatalogPricingTierRow) -> Self {
        PricingTier {
            min_context_tokens: row.min_context_tokens,
            input_cost_per_token: row.input_cost_per_token,
            output_cost_per_token: row.output_cost_per_token,
            cache_read_input_token_cost: row.cache_read_input_token_cost,
            cache_creation_input_token_cost: row.cache_creation_input_token_cost,
            input_cost_per_audio_token: row.input_cost_per_audio_token,
            output_cost_per_audio_token: row.output_cost_per_audio_token,
            output_cost_per_reasoning_token: row.output_cost_per_reasoning_token,
        }
    }
}

/// Flatten one catalog model row into a [`ModelPricing`]. Models without a
/// `pricing` object get the zero-cost [`Default`] rates while keeping their
/// limits, mode, and capability metadata populated.
fn flatten_model(model: &CatalogModelRow) -> ModelPricing {
    let (
        input_cost_per_token,
        output_cost_per_token,
        cache_read_input_token_cost,
        cache_creation_input_token_cost,
        input_cost_per_audio_token,
        output_cost_per_audio_token,
        output_cost_per_reasoning_token,
        tiers,
    ) = match &model.pricing {
        Some(pricing) => (
            pricing.input_cost_per_token,
            pricing.output_cost_per_token,
            pricing.cache_read_input_token_cost,
            pricing.cache_creation_input_token_cost,
            pricing.input_cost_per_audio_token,
            pricing.output_cost_per_audio_token,
            pricing.output_cost_per_reasoning_token,
            pricing.tiers.iter().map(PricingTier::from).collect(),
        ),
        None => (0.0, 0.0, None, None, None, None, None, Vec::new()),
    };

    ModelPricing {
        input_cost_per_token,
        output_cost_per_token,
        cache_read_input_token_cost,
        cache_creation_input_token_cost,
        input_cost_per_audio_token,
        output_cost_per_audio_token,
        output_cost_per_reasoning_token,
        max_tokens: Some(model.limit.context),
        max_input_tokens: Some(model.limit.input.unwrap_or(model.limit.context)),
        max_output_tokens: Some(model.limit.output),
        mode: model.mode.clone(),
        supports_vision: Some(model.capabilities.vision),
        supports_function_calling: Some(model.capabilities.function_calling),
        supports_reasoning: Some(model.capabilities.reasoning),
        supports_structured_output: Some(model.capabilities.structured_output),
        supports_audio_input: Some(model.capabilities.audio_input),
        supports_audio_output: Some(model.capabilities.audio_output),
        supports_prompt_caching: Some(model.capabilities.prompt_caching),
        tiers,
    }
}

/// Parse a catalog JSON document (same shape as the embedded
/// `schemas/catalog.json`) and flatten it into a name-indexed registry.
///
/// Every model is inserted under its combined `"{provider_id}/{model_id}"`
/// key. Models from [`PRIMARY_PROVIDERS`] are additionally inserted under
/// their bare `"{model_id}"` key; since `providers` iterates in sorted
/// (`BTreeMap`) order, `.entry(..).or_insert(..)` guarantees the
/// alphabetically-first provider wins on a bare-name collision.
///
/// Shared by the embedded-catalog [`PRICING`] `LazyLock` and the runtime
/// overlay refresh (`cost::refresh`) — both flatten the same catalog shape
/// with identical logic, so a runtime-downloaded `catalog.json` behaves
/// exactly like the embedded one.
fn registry_from_catalog_str(catalog_json: &str) -> std::result::Result<HashMap<String, ModelPricing>, String> {
    let catalog: CatalogFile = serde_json::from_str(catalog_json).map_err(|e| e.to_string())?;
    let mut registry = HashMap::new();

    for (provider_id, provider) in &catalog.providers {
        for (model_id, model) in &provider.models {
            let pricing = flatten_model(model);
            if PRIMARY_PROVIDERS.contains(&provider_id.as_str()) {
                registry.entry(model_id.clone()).or_insert_with(|| pricing.clone());
            }
            registry.insert(format!("{provider_id}/{model_id}"), pricing);
        }
    }

    Ok(registry)
}

/// Per-token pricing for a single model (USD per token).
///
/// Flattened from a model entry in the embedded `schemas/catalog.json`
/// registry (see [`registry_from_catalog_str`]). Every field beyond the two base costs
/// is optional so that cost-only records (containing only
/// `input_cost_per_token` and `output_cost_per_token`) continue to parse,
/// e.g. via direct deserialization in tests.
#[derive(Debug, Clone, Default, Deserialize)]
#[cfg_attr(alef, alef(skip))]
pub struct ModelPricing {
    /// Cost in USD per input (prompt) token.
    pub input_cost_per_token: f64,
    /// Cost in USD per output (completion) token.  Zero for embedding models.
    pub output_cost_per_token: f64,
    /// Cost in USD per cached input token (cache hit / read). When the model
    /// supports prompt caching the provider serves cached tokens at this
    /// discounted rate; otherwise this is `None` and cached tokens are billed
    /// at `input_cost_per_token`.
    #[serde(default)]
    pub cache_read_input_token_cost: Option<f64>,
    /// Cost in USD per token written to the prompt cache (Anthropic-style
    /// cache-write surcharge). `None` when the provider does not separately
    /// charge for cache writes.
    #[serde(default)]
    pub cache_creation_input_token_cost: Option<f64>,
    /// Cost in USD per input audio token. `None` when the model does not
    /// price audio input separately.
    #[serde(default)]
    pub input_cost_per_audio_token: Option<f64>,
    /// Cost in USD per output audio token. `None` when the model does not
    /// price audio output separately.
    #[serde(default)]
    pub output_cost_per_audio_token: Option<f64>,
    /// Cost in USD per reasoning (extended-thinking) output token. `None`
    /// when the model does not price reasoning tokens separately.
    #[serde(default)]
    pub output_cost_per_reasoning_token: Option<f64>,
    /// Total context window size in tokens (input + output). `None` when
    /// unknown.
    #[serde(default)]
    pub max_tokens: Option<u64>,
    /// Maximum input (prompt) tokens accepted. `None` when unknown.
    #[serde(default)]
    pub max_input_tokens: Option<u64>,
    /// Maximum output (completion) tokens the model can generate. `None`
    /// when unknown.
    #[serde(default)]
    pub max_output_tokens: Option<u64>,
    /// Best-effort operating mode, e.g. `"chat"`, `"embedding"`,
    /// `"image_generation"`, `"audio_speech"`, `"audio_transcription"`.
    /// `None` when the mode could not be derived.
    #[serde(default)]
    pub mode: Option<String>,
    /// The model accepts image input. `None` when unknown (treated as
    /// unsupported).
    #[serde(default)]
    pub supports_vision: Option<bool>,
    /// The model supports tool / function calling. `None` when unknown.
    #[serde(default)]
    pub supports_function_calling: Option<bool>,
    /// The model supports extended-thinking / reasoning tokens. `None` when
    /// unknown.
    #[serde(default)]
    pub supports_reasoning: Option<bool>,
    /// The model supports JSON-mode or `response_format` structured output.
    /// `None` when unknown.
    #[serde(default)]
    pub supports_structured_output: Option<bool>,
    /// The model accepts audio input. `None` when unknown.
    #[serde(default)]
    pub supports_audio_input: Option<bool>,
    /// The model can generate audio output. `None` when unknown.
    #[serde(default)]
    pub supports_audio_output: Option<bool>,
    /// The model supports prompt caching (cache read and/or cache write).
    /// `None` when unknown.
    #[serde(default)]
    pub supports_prompt_caching: Option<bool>,
    /// Context-tiered pricing overrides, sorted by ascending
    /// `min_context_tokens`. Empty when the model has flat (non-tiered)
    /// pricing.
    #[serde(default)]
    pub tiers: Vec<PricingTier>,
}

/// A single context-window pricing tier: rates that apply once the
/// prompt/context token count reaches `min_context_tokens`.
#[derive(Debug, Clone, Default, Deserialize)]
#[cfg_attr(alef, alef(skip))]
pub struct PricingTier {
    /// The tier applies when the prompt/context token count is at least
    /// this value.
    pub min_context_tokens: u64,
    /// Cost in USD per input (prompt) token within this tier.
    pub input_cost_per_token: f64,
    /// Cost in USD per output (completion) token within this tier.
    pub output_cost_per_token: f64,
    /// Cost in USD per cached input token within this tier. `None` falls
    /// back to the base model's `cache_read_input_token_cost`.
    #[serde(default)]
    pub cache_read_input_token_cost: Option<f64>,
    /// Cost in USD per cache-write token within this tier. `None` falls
    /// back to the base model's `cache_creation_input_token_cost`.
    #[serde(default)]
    pub cache_creation_input_token_cost: Option<f64>,
    /// Cost in USD per input audio token within this tier.
    #[serde(default)]
    pub input_cost_per_audio_token: Option<f64>,
    /// Cost in USD per output audio token within this tier.
    #[serde(default)]
    pub output_cost_per_audio_token: Option<f64>,
    /// Cost in USD per reasoning output token within this tier.
    #[serde(default)]
    pub output_cost_per_reasoning_token: Option<f64>,
}

/// Public, FFI-friendly snapshot of a model's pricing and capability
/// metadata, projected from [`ModelPricing`].
///
/// Unlike [`ModelPricing`] (which is excluded from binding generation),
/// `ModelInfo` is an owned plain-data DTO safe to hand across the FFI
/// boundary — see [`model_info`].
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct ModelInfo {
    /// Cost in USD per input (prompt) token.
    pub input_cost_per_token: f64,
    /// Cost in USD per output (completion) token.
    pub output_cost_per_token: f64,
    /// Cost in USD per cached input token (cache hit / read).
    pub cache_read_input_token_cost: Option<f64>,
    /// Cost in USD per token written to the prompt cache.
    pub cache_creation_input_token_cost: Option<f64>,
    /// Cost in USD per input audio token.
    pub input_cost_per_audio_token: Option<f64>,
    /// Cost in USD per output audio token.
    pub output_cost_per_audio_token: Option<f64>,
    /// Cost in USD per reasoning (extended-thinking) output token.
    pub output_cost_per_reasoning_token: Option<f64>,
    /// Total context window size in tokens (input + output).
    pub max_tokens: Option<u64>,
    /// Maximum input (prompt) tokens accepted.
    pub max_input_tokens: Option<u64>,
    /// Maximum output (completion) tokens the model can generate.
    pub max_output_tokens: Option<u64>,
    /// Best-effort operating mode, e.g. `"chat"`, `"embedding"`.
    pub mode: Option<String>,
    /// The model accepts image input.
    pub supports_vision: Option<bool>,
    /// The model supports tool / function calling.
    pub supports_function_calling: Option<bool>,
    /// The model supports extended-thinking / reasoning tokens.
    pub supports_reasoning: Option<bool>,
    /// The model supports JSON-mode or `response_format` structured output.
    pub supports_structured_output: Option<bool>,
    /// The model accepts audio input.
    pub supports_audio_input: Option<bool>,
    /// The model can generate audio output.
    pub supports_audio_output: Option<bool>,
    /// The model supports prompt caching.
    pub supports_prompt_caching: Option<bool>,
    /// Context-tiered pricing overrides, sorted by ascending
    /// `min_context_tokens`. Empty when the model has flat pricing.
    pub tiers: Vec<ModelTier>,
}

/// Public, FFI-friendly snapshot of a single context-window pricing tier,
/// projected from [`PricingTier`].
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct ModelTier {
    /// The tier applies when the prompt/context token count is at least
    /// this value.
    pub min_context_tokens: u64,
    /// Cost in USD per input (prompt) token within this tier.
    pub input_cost_per_token: f64,
    /// Cost in USD per output (completion) token within this tier.
    pub output_cost_per_token: f64,
    /// Cost in USD per cached input token within this tier.
    pub cache_read_input_token_cost: Option<f64>,
    /// Cost in USD per cache-write token within this tier.
    pub cache_creation_input_token_cost: Option<f64>,
    /// Cost in USD per input audio token within this tier.
    pub input_cost_per_audio_token: Option<f64>,
    /// Cost in USD per output audio token within this tier.
    pub output_cost_per_audio_token: Option<f64>,
    /// Cost in USD per reasoning output token within this tier.
    pub output_cost_per_reasoning_token: Option<f64>,
}

impl From<&PricingTier> for ModelTier {
    fn from(tier: &PricingTier) -> Self {
        ModelTier {
            min_context_tokens: tier.min_context_tokens,
            input_cost_per_token: tier.input_cost_per_token,
            output_cost_per_token: tier.output_cost_per_token,
            cache_read_input_token_cost: tier.cache_read_input_token_cost,
            cache_creation_input_token_cost: tier.cache_creation_input_token_cost,
            input_cost_per_audio_token: tier.input_cost_per_audio_token,
            output_cost_per_audio_token: tier.output_cost_per_audio_token,
            output_cost_per_reasoning_token: tier.output_cost_per_reasoning_token,
        }
    }
}

impl From<&ModelPricing> for ModelInfo {
    fn from(pricing: &ModelPricing) -> Self {
        ModelInfo {
            input_cost_per_token: pricing.input_cost_per_token,
            output_cost_per_token: pricing.output_cost_per_token,
            cache_read_input_token_cost: pricing.cache_read_input_token_cost,
            cache_creation_input_token_cost: pricing.cache_creation_input_token_cost,
            input_cost_per_audio_token: pricing.input_cost_per_audio_token,
            output_cost_per_audio_token: pricing.output_cost_per_audio_token,
            output_cost_per_reasoning_token: pricing.output_cost_per_reasoning_token,
            max_tokens: pricing.max_tokens,
            max_input_tokens: pricing.max_input_tokens,
            max_output_tokens: pricing.max_output_tokens,
            mode: pricing.mode.clone(),
            supports_vision: pricing.supports_vision,
            supports_function_calling: pricing.supports_function_calling,
            supports_reasoning: pricing.supports_reasoning,
            supports_structured_output: pricing.supports_structured_output,
            supports_audio_input: pricing.supports_audio_input,
            supports_audio_output: pricing.supports_audio_output,
            supports_prompt_caching: pricing.supports_prompt_caching,
            tiers: pricing.tiers.iter().map(ModelTier::from).collect(),
        }
    }
}

/// Calculate the estimated cost of a completion given a model name and token
/// counts.
///
/// Returns `None` if the model is not present in the embedded pricing registry.
/// Returns `Some(cost_usd)` otherwise, where the value is in US dollars.
///
/// When an exact model name match is not found, progressively shorter prefixes
/// are tried by stripping from the last `-` or `.` separator.  For example,
/// `gpt-4-0613` will match `gpt-4` if no `gpt-4-0613` entry exists.
///
/// # Example
///
/// ```rust
/// use liter_llm::cost;
///
/// let usd = cost::completion_cost("gpt-4o", 1_000, 500).expect("gpt-4o is a known model");
/// // 1000 * 0.0000025 + 500 * 0.00001 = 0.0025 + 0.005 = 0.0075
/// assert!((usd - 0.0075).abs() < 1e-9);
/// ```
#[must_use]
pub fn completion_cost(model: &str, prompt_tokens: u64, completion_tokens: u64) -> Option<f64> {
    completion_cost_with_cache(model, prompt_tokens, 0, completion_tokens)
}

/// Calculate the estimated cost of a completion, accounting for cached
/// (cache-hit) prompt tokens billed at the provider's discounted rate.
///
/// `cached_tokens` is the count of prompt tokens served from the provider's
/// prompt cache. It must be `<= prompt_tokens` (cached tokens are a subset of
/// the prompt). The non-cached portion is billed at `input_cost_per_token`
/// and the cached portion at `cache_read_input_token_cost` when the model
/// has cache pricing; otherwise the entire prompt is billed at the regular
/// input rate.
///
/// Returns `None` if the model is not present in the embedded pricing
/// registry, mirroring [`completion_cost`].
///
/// When the model has [`ModelPricing::tiers`], the tier whose
/// `min_context_tokens` is the highest value `<= prompt_tokens` supplies the
/// input/output/cache rates for the whole call; models without tiers (or
/// when `prompt_tokens` is below every tier threshold) use the base rates
/// unchanged, matching the original flat-rate behaviour.
#[must_use]
pub fn completion_cost_with_cache(
    model: &str,
    prompt_tokens: u64,
    cached_tokens: u64,
    completion_tokens: u64,
) -> Option<f64> {
    with_active_registry(|reg| compute_cost_in(reg, model, prompt_tokens, cached_tokens, completion_tokens))
}

/// [`completion_cost_with_cache`], factored to operate over an explicit
/// registry rather than the module-level embedded/overlay resolution. Shared
/// by the embedded-only and overlay-aware call paths.
fn compute_cost_in(
    reg: &HashMap<String, ModelPricing>,
    model: &str,
    prompt_tokens: u64,
    cached_tokens: u64,
    completion_tokens: u64,
) -> Option<f64> {
    let pricing = lookup_in(reg, model)?;
    Some(compute_cost(pricing, prompt_tokens, cached_tokens, completion_tokens))
}

/// Select the applicable pricing tier for a given prompt/context token
/// count: the tier with the highest `min_context_tokens` that is
/// `<= prompt_tokens`. Returns `None` when the model has no tiers or none of
/// them apply yet, in which case callers fall back to the base rates.
fn select_tier(pricing: &ModelPricing, prompt_tokens: u64) -> Option<&PricingTier> {
    pricing
        .tiers
        .iter()
        .filter(|tier| tier.min_context_tokens <= prompt_tokens)
        .max_by_key(|tier| tier.min_context_tokens)
}

/// Compute the USD cost of a completion from an already-resolved
/// [`ModelPricing`] row, applying tier-aware rate selection.
fn compute_cost(pricing: &ModelPricing, prompt_tokens: u64, cached_tokens: u64, completion_tokens: u64) -> f64 {
    let cached = cached_tokens.min(prompt_tokens);
    let uncached = prompt_tokens - cached;
    let tier = select_tier(pricing, prompt_tokens);
    let input_rate = tier.map_or(pricing.input_cost_per_token, |t| t.input_cost_per_token);
    let output_rate = tier.map_or(pricing.output_cost_per_token, |t| t.output_cost_per_token);
    let cache_rate = tier
        .and_then(|t| t.cache_read_input_token_cost)
        .or(pricing.cache_read_input_token_cost)
        .unwrap_or(input_rate);
    (uncached as f64) * input_rate + (cached as f64) * cache_rate + (completion_tokens as f64) * output_rate
}

/// Resolve pricing for a model name, trying progressively shorter prefixes
/// when an exact match is absent.
///
/// Returns `None` if the model is not present in the embedded pricing registry.
/// The returned reference is valid for the lifetime of the process (`'static`).
///
/// When an exact model name match is not found, progressively shorter prefixes
/// are tried by stripping from the last `-` or `.` separator.  For example,
/// `gpt-4-0613` will try `gpt-4-0613`, then `gpt-4`, then `gpt`.  The first
/// match wins.
fn lookup(model: &str) -> Option<&'static ModelPricing> {
    lookup_in(registry()?, model)
}

/// [`lookup`], factored to resolve against an explicit registry rather than
/// the embedded [`PRICING`] table. Shared by the embedded-only `lookup` and
/// the overlay-aware [`compute_cost_in`] / [`model_info_in`] paths.
fn lookup_in<'a>(models: &'a HashMap<String, ModelPricing>, model: &str) -> Option<&'a ModelPricing> {
    if let Some(p) = models.get(model) {
        return Some(p);
    }

    let mut candidate = model;
    while let Some(pos) = candidate.rfind(['-', '.']) {
        candidate = &candidate[..pos];
        if let Some(p) = models.get(candidate) {
            return Some(p);
        }
    }

    None
}

/// Look up the per-token pricing for a model.
///
/// Returns `None` if the model is not present in the embedded pricing registry.
/// The returned reference is valid for the lifetime of the process (`'static`).
///
/// When an exact model name match is not found, progressively shorter prefixes
/// are tried by stripping from the last `-` or `.` separator.  For example,
/// `gpt-4-0613` will try `gpt-4-0613`, then `gpt-4`, then `gpt`.  The first
/// match wins.
///
/// # Runtime refresh
///
/// This function always reflects the **embedded** catalog and never the
/// runtime overlay, even when a refresh has succeeded: its `'static` return
/// type borrows directly from the embedded [`PRICING`] table, so it cannot
/// borrow from an overlay registry that may be swapped out at any time.
/// Callers that need overlay-aware pricing should use [`completion_cost`],
/// [`completion_cost_with_cache`], or [`model_info`] instead, all of which
/// return owned values and consult the runtime overlay first.
#[cfg_attr(alef, alef(skip))]
#[must_use]
pub fn model_pricing(model: &str) -> Option<&'static ModelPricing> {
    lookup(model)
}

/// Look up FFI-friendly pricing and capability metadata for a model.
///
/// Returns `None` if the model is not present in the active pricing
/// registry. Uses the same exact-match-then-prefix-fallback resolution as
/// [`model_pricing`]; unlike `model_pricing`, the result is an owned
/// [`ModelInfo`] value safe to hand across the FFI boundary.
///
/// When a runtime catalog refresh has succeeded, this reflects the refreshed
/// (overlay) catalog; otherwise it reflects the embedded catalog. See
/// [`model_pricing`] for the embedded-only alternative.
#[must_use]
pub fn model_info(model: &str) -> Option<ModelInfo> {
    with_active_registry(|reg| model_info_in(reg, model))
}

/// [`model_info`], factored to operate over an explicit registry.
fn model_info_in(reg: &HashMap<String, ModelPricing>, model: &str) -> Option<ModelInfo> {
    lookup_in(reg, model).map(ModelInfo::from)
}

/// Resolve the registry that [`completion_cost`], [`completion_cost_with_cache`],
/// and [`model_info`] operate over, and invoke `f` with it.
///
/// The runtime overlay (installed by a successful [`refresh::refresh_catalog`]
/// or [`refresh::install_catalog_overlay_from_str`] call) takes priority when
/// present; otherwise this falls back to the embedded [`PRICING`] table, which
/// keeps air-gapped/offline environments (no overlay ever installed) and
/// networks with a failed refresh (overlay never touched on error) fully
/// functional. Runtime refresh is off by default
/// ([`CatalogRefreshConfig::default`] has `enabled: false`), so absent an
/// explicit, successful refresh this is always the embedded table.
fn with_active_registry<T>(f: impl FnOnce(&HashMap<String, ModelPricing>) -> Option<T>) -> Option<T> {
    if let Some(overlay) = refresh::overlay_registry() {
        return f(&overlay);
    }
    f(registry()?)
}

pub mod refresh;
pub use refresh::{
    CatalogRefreshConfig, CatalogRefreshError, DEFAULT_CATALOG_URL, RefreshOutcome, clear_catalog_overlay,
    install_catalog_overlay_from_str, refresh_catalog,
};

#[cfg(test)]
mod refresh_tests;
#[cfg(test)]
mod tests;