Skip to main content

model_router/
pricing.rs

1//! Per-model pricing data and a built-in table for popular models.
2//!
3//! Price tables go stale. [`ModelPricing`] carries an optional
4//! `updated_at_unix` stamp and [`PricingTable`] can [`PricingTable::merge`]
5//! fresher entries over older ones and load JSON snapshots
6//! ([`PricingTable::from_json`], feature `json`), so rates can be refreshed
7//! at runtime from a URL or file without a crate release.
8
9#[cfg(feature = "json")]
10use crate::error::RouterError;
11#[cfg(feature = "serde")]
12use serde::{Deserialize, Serialize};
13use std::collections::BTreeMap;
14
15/// Per-model pricing information.
16///
17/// Rates are expressed in USD per **1M tokens**, matching the convention used
18/// by most provider pricing pages.
19#[derive(Debug, Clone, PartialEq)]
20#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
21pub struct ModelPricing {
22    /// Cost per 1M input tokens in USD.
23    pub input_per_1m: f64,
24    /// Cost per 1M output tokens in USD.
25    pub output_per_1m: f64,
26    /// Maximum context window in tokens.
27    pub context_window: usize,
28    /// Maximum output tokens.
29    pub max_output_tokens: usize,
30    /// Quality tier (1-5, 5 = highest). Used by
31    /// [`crate::Router::select_by_complexity`] and [`ModelPricing::efficiency`].
32    pub quality_tier: u8,
33    /// Unix-seconds timestamp of when this entry was last refreshed from an
34    /// external source (`None` = freshness unknown, e.g. built-in defaults).
35    /// Used by [`PricingTable::merge`] conflict resolution. Deserialized as
36    /// `None` when absent, so pre-0.1.1 JSON snapshots still load.
37    #[cfg_attr(feature = "serde", serde(default))]
38    updated_at_unix: Option<u64>,
39}
40
41impl ModelPricing {
42    /// Create pricing from just the USD rates, filling the remaining fields
43    /// with the same defaults as [`ModelPricing::default`] (128k context,
44    /// 4,096 max output, quality tier 3).
45    pub fn new(input_per_1m: f64, output_per_1m: f64) -> Self {
46        Self {
47            input_per_1m,
48            output_per_1m,
49            ..ModelPricing::default()
50        }
51    }
52
53    /// Set the context window (builder style).
54    pub fn with_context_window(mut self, context_window: usize) -> Self {
55        self.context_window = context_window;
56        self
57    }
58
59    /// Set the maximum output tokens (builder style).
60    pub fn with_max_output_tokens(mut self, max_output_tokens: usize) -> Self {
61        self.max_output_tokens = max_output_tokens;
62        self
63    }
64
65    /// Set the quality tier, 1-5 (builder style).
66    pub fn with_quality_tier(mut self, quality_tier: u8) -> Self {
67        self.quality_tier = quality_tier;
68        self
69    }
70
71    /// Stamp the entry with an explicit refresh time, as Unix seconds
72    /// (builder style). See [`ModelPricing::updated_at_unix`].
73    pub fn with_updated_at_unix(mut self, updated_at_unix: u64) -> Self {
74        self.updated_at_unix = Some(updated_at_unix);
75        self
76    }
77
78    /// Stamp the entry with the current wall-clock time as Unix seconds
79    /// (builder style). Convenience for code that builds refresh snapshots.
80    pub fn with_updated_at_now(self) -> Self {
81        let now = std::time::SystemTime::now()
82            .duration_since(std::time::UNIX_EPOCH)
83            .map(|d| d.as_secs())
84            .unwrap_or(0);
85        self.with_updated_at_unix(now)
86    }
87
88    /// Unix-seconds timestamp of the last refresh from an external source,
89    /// if known (`None` = freshness unknown).
90    pub fn updated_at_unix(&self) -> Option<u64> {
91        self.updated_at_unix
92    }
93
94    /// Whether `self` should replace `other` in a [`PricingTable::merge`]:
95    /// true when `self` carries a strictly newer `updated_at_unix` stamp, or
96    /// any stamp at all while `other` carries none. Two unstamped entries
97    /// (or an older stamp) never win.
98    pub fn is_newer_than(&self, other: &Self) -> bool {
99        match (self.updated_at_unix, other.updated_at_unix) {
100            (Some(mine), Some(theirs)) => mine > theirs,
101            (Some(_), None) => true,
102            (None, _) => false,
103        }
104    }
105
106    /// Calculate the cost in USD for a given number of input/output tokens.
107    pub fn cost(&self, input_tokens: usize, output_tokens: usize) -> f64 {
108        (input_tokens as f64 * self.input_per_1m / 1_000_000.0)
109            + (output_tokens as f64 * self.output_per_1m / 1_000_000.0)
110    }
111
112    /// Cost efficiency: quality tier per average-USD cost.
113    ///
114    /// Higher is better. Free models (both rates zero) return [`f64::MAX`].
115    pub fn efficiency(&self) -> f64 {
116        let avg_cost = (self.input_per_1m + self.output_per_1m) / 2.0;
117        if avg_cost > 0.0 {
118            self.quality_tier as f64 / avg_cost
119        } else {
120            f64::MAX
121        }
122    }
123}
124
125impl Default for ModelPricing {
126    /// Placeholder pricing used to *estimate* cost for models that are not in
127    /// the table ($1.00/1M input, $3.00/1M output, 128k context, 4,096 max
128    /// output, tier 3, no freshness stamp).
129    fn default() -> Self {
130        Self {
131            input_per_1m: 1.0,
132            output_per_1m: 3.0,
133            context_window: 128_000,
134            max_output_tokens: 4_096,
135            quality_tier: 3,
136            updated_at_unix: None,
137        }
138    }
139}
140
141/// Built-in pricing table for popular models.
142///
143/// Rates reflect publicly listed prices at the time of extraction (May 2025)
144/// and can be overridden at runtime with
145/// [`crate::Router::add_pricing`]. Keys are plain model identifiers; namespaced
146/// keys such as `openrouter/google/gemma-3-4b-it:free` are kept verbatim.
147///
148/// The table is a [`BTreeMap`], so iteration — and therefore
149/// [`crate::Router::select_by_complexity`] tie-breaking — is deterministic.
150pub fn default_pricing_table() -> BTreeMap<String, ModelPricing> {
151    let mut table = BTreeMap::new();
152
153    let mut insert = |key: &str, pricing: ModelPricing| {
154        table.insert(key.to_string(), pricing);
155    };
156
157    // Claude models (Anthropic)
158    insert(
159        "claude-sonnet-4-20250514",
160        ModelPricing::new(3.0, 15.0)
161            .with_context_window(200_000)
162            .with_max_output_tokens(16_384)
163            .with_quality_tier(5),
164    );
165    insert(
166        "claude-3-5-sonnet-20241022",
167        ModelPricing::new(3.0, 15.0)
168            .with_context_window(200_000)
169            .with_max_output_tokens(8_192)
170            .with_quality_tier(4),
171    );
172    insert(
173        "claude-3-5-haiku-20241022",
174        ModelPricing::new(0.8, 4.0)
175            .with_context_window(200_000)
176            .with_max_output_tokens(8_192)
177            .with_quality_tier(3),
178    );
179    insert(
180        "claude-3-opus-20240229",
181        ModelPricing::new(15.0, 75.0)
182            .with_context_window(200_000)
183            .with_max_output_tokens(4_096)
184            .with_quality_tier(5),
185    );
186
187    // GPT models (OpenAI)
188    insert(
189        "gpt-4o",
190        ModelPricing::new(2.5, 10.0)
191            .with_context_window(128_000)
192            .with_max_output_tokens(16_384)
193            .with_quality_tier(4),
194    );
195    insert(
196        "gpt-4o-mini",
197        ModelPricing::new(0.15, 0.6)
198            .with_context_window(128_000)
199            .with_max_output_tokens(16_384)
200            .with_quality_tier(3),
201    );
202    insert(
203        "gpt-4-turbo",
204        ModelPricing::new(10.0, 30.0)
205            .with_context_window(128_000)
206            .with_max_output_tokens(4_096)
207            .with_quality_tier(5),
208    );
209
210    // Gemini models (Google)
211    insert(
212        "gemini-2.0-flash",
213        ModelPricing::new(0.1, 0.4)
214            .with_context_window(1_000_000)
215            .with_max_output_tokens(8_192)
216            .with_quality_tier(3),
217    );
218    insert(
219        "gemini-1.5-pro",
220        ModelPricing::new(1.25, 5.0)
221            .with_context_window(2_000_000)
222            .with_max_output_tokens(8_192)
223            .with_quality_tier(4),
224    );
225
226    // GLM models (ZAI)
227    insert(
228        "glm-4.6",
229        ModelPricing::new(0.5, 0.5)
230            .with_context_window(128_000)
231            .with_max_output_tokens(4_096)
232            .with_quality_tier(3),
233    );
234    insert(
235        "glm-5-turbo",
236        ModelPricing::new(0.5, 0.5)
237            .with_context_window(128_000)
238            .with_max_output_tokens(4_096)
239            .with_quality_tier(3),
240    );
241
242    // DeepSeek
243    insert(
244        "deepseek-chat",
245        ModelPricing::new(0.14, 0.28)
246            .with_context_window(64_000)
247            .with_max_output_tokens(8_192)
248            .with_quality_tier(3),
249    );
250    insert(
251        "deepseek-coder",
252        ModelPricing::new(0.14, 0.28)
253            .with_context_window(64_000)
254            .with_max_output_tokens(8_192)
255            .with_quality_tier(3),
256    );
257
258    // OpenRouter prefixed models
259    insert(
260        "anthropic/claude-3.5-sonnet",
261        ModelPricing::new(3.0, 15.0)
262            .with_context_window(200_000)
263            .with_max_output_tokens(8_192)
264            .with_quality_tier(4),
265    );
266    insert(
267        "openai/gpt-4o",
268        ModelPricing::new(2.5, 10.0)
269            .with_context_window(128_000)
270            .with_max_output_tokens(16_384)
271            .with_quality_tier(4),
272    );
273    insert(
274        "google/gemma-3-4b-it:free",
275        ModelPricing::new(0.0, 0.0)
276            .with_context_window(32_000)
277            .with_max_output_tokens(4_096)
278            .with_quality_tier(2),
279    );
280    insert(
281        "openai/gpt-oss-20b:free",
282        ModelPricing::new(0.0, 0.0)
283            .with_context_window(32_000)
284            .with_max_output_tokens(4_096)
285            .with_quality_tier(2),
286    );
287
288    table
289}
290
291/// A refreshable set of [`ModelPricing`] entries keyed by model identifier.
292///
293/// The built-in rates returned by [`default_pricing_table`] inevitably go
294/// stale. [`PricingTable`] exists so callers can refresh them at runtime
295/// (from a file, an HTTP JSON endpoint, etc.) without waiting for a crate
296/// release:
297///
298/// 1. Serialize a table with the `serde`/`json` features and host the JSON
299///    (the shape is a plain object mapping model id to pricing fields).
300/// 2. Load it with `PricingTable::from_json` (feature `json`).
301/// 3. [`PricingTable::merge`] it over your current table — entries that are
302///    missing or stamped newer (see [`ModelPricing::is_newer_than`]) win;
303///    everything else is left untouched.
304///
305/// The built-in defaults are *unstamped* (`updated_at_unix == None`), so any
306/// timestamped refresh entry wins over them.
307///
308/// With the `serde` feature the table (de)serializes transparently as a
309/// plain `{ "model-id": {...} }` JSON object.
310#[derive(Debug, Clone, Default, PartialEq)]
311#[cfg_attr(feature = "serde", derive(Serialize, Deserialize), serde(transparent))]
312pub struct PricingTable {
313    entries: BTreeMap<String, ModelPricing>,
314}
315
316impl PricingTable {
317    /// An empty table.
318    pub fn new() -> Self {
319        Self::default()
320    }
321
322    /// A table seeded with the built-in rates (see [`default_pricing_table`]).
323    pub fn with_defaults() -> Self {
324        Self {
325            entries: default_pricing_table(),
326        }
327    }
328
329    /// Insert (or replace) pricing for a model key, returning the previous
330    /// entry if any. Insertions are not timestamp-checked; use
331    /// [`PricingTable::merge`] for freshness-aware upserts.
332    pub fn insert(
333        &mut self,
334        model: impl Into<String>,
335        pricing: ModelPricing,
336    ) -> Option<ModelPricing> {
337        self.entries.insert(model.into(), pricing)
338    }
339
340    /// Pricing for a model key, if present.
341    pub fn get(&self, model: &str) -> Option<&ModelPricing> {
342        self.entries.get(model)
343    }
344
345    /// Number of entries.
346    pub fn len(&self) -> usize {
347        self.entries.len()
348    }
349
350    /// Whether the table has no entries.
351    pub fn is_empty(&self) -> bool {
352        self.entries.is_empty()
353    }
354
355    /// Iterate `(model id, pricing)` pairs in deterministic (sorted) order.
356    pub fn iter(&self) -> impl Iterator<Item = (&str, &ModelPricing)> {
357        self.entries
358            .iter()
359            .map(|(model, pricing)| (model.as_str(), pricing))
360    }
361
362    /// Upsert every entry of `other` into `self`, keeping `self`'s entry
363    /// unless `other`'s is missing from `self` or carries a strictly newer
364    /// [`ModelPricing::updated_at_unix`] stamp.
365    ///
366    /// Semantics:
367    ///
368    /// - key only in `other` → added;
369    /// - key in both, `other` newer (or `self` unstamped, `other` stamped) →
370    ///   `other`'s entry replaces `self`'s;
371    /// - key in both, `self` equal-or-newer (or both unstamped) → `self`'s
372    ///   entry is preserved.
373    pub fn merge(&mut self, other: &PricingTable) {
374        merge_into(&mut self.entries, other);
375    }
376
377    /// Parse a table from JSON (feature `json`).
378    ///
379    /// Accepts the same shape [`PricingTable::to_json`] emits: a plain object
380    /// mapping model id to a pricing object. The `updated_at_unix` field is
381    /// optional (`None` when absent), so snapshots produced before 0.1.1 —
382    /// or by external tooling — still load.
383    ///
384    /// # Examples
385    ///
386    /// ```
387    /// use model_router::PricingTable;
388    ///
389    /// let json = r#"{
390    ///     "gpt-4o": {
391    ///         "input_per_1m": 2.5,
392    ///         "output_per_1m": 10.0,
393    ///         "context_window": 128000,
394    ///         "max_output_tokens": 16384,
395    ///         "quality_tier": 4,
396    ///         "updated_at_unix": 1757289600
397    ///     }
398    /// }"#;
399    /// let table = PricingTable::from_json(json).expect("valid table JSON");
400    /// assert_eq!(table.get("gpt-4o").expect("entry").updated_at_unix(), Some(1_757_289_600));
401    /// ```
402    #[cfg(feature = "json")]
403    pub fn from_json(json: &str) -> Result<Self, RouterError> {
404        serde_json::from_str(json).map_err(|e| RouterError::Json(e.to_string()))
405    }
406
407    /// Serialize the table to JSON (feature `json`).
408    ///
409    /// The output is a plain object mapping model id to pricing object, with
410    /// `updated_at_unix` present when stamped — the exact shape
411    /// [`PricingTable::from_json`] accepts, suitable for hosting at a URL or
412    /// writing to a file for the refresh workflow.
413    #[cfg(feature = "json")]
414    pub fn to_json(&self) -> Result<String, RouterError> {
415        serde_json::to_string(self).map_err(|e| RouterError::Json(e.to_string()))
416    }
417}
418
419/// Shared upsert used by [`PricingTable::merge`] and
420/// [`crate::Router::merge_pricing`].
421pub(crate) fn merge_into(entries: &mut BTreeMap<String, ModelPricing>, other: &PricingTable) {
422    for (model, incoming) in other.iter() {
423        match entries.get(model) {
424            Some(existing) if !incoming.is_newer_than(existing) => {}
425            _ => {
426                entries.insert(model.to_string(), incoming.clone());
427            }
428        }
429    }
430}