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}