model_router/cost.rs
1//! USD cost tracking with budget enforcement.
2
3#[cfg(feature = "serde")]
4use serde::{Deserialize, Serialize};
5use std::collections::BTreeMap;
6use std::sync::atomic::{AtomicU64, Ordering};
7use std::sync::{Arc, Mutex};
8
9use crate::error::RouterError;
10use crate::pricing::ModelPricing;
11
12/// Fixed-point scale for stored costs: units of $0.0001 (i.e. USD * 10,000).
13const COST_SCALE: f64 = 10_000.0;
14
15/// Accumulates token usage and USD spend, optionally against a budget.
16///
17/// * Totals are stored in fixed point (units of $0.0001) in atomics, so
18/// [`CostTracker::total_usd`], [`CostTracker::total_input_tokens`] and
19/// [`CostTracker::total_output_tokens`] are lock-free and `Send + Sync`.
20/// * The per-model breakdown is guarded by a [`std::sync::Mutex`].
21/// * Cloning a tracker shares the same underlying state (all fields are
22/// `Arc`-backed), so all clones observe the same spend.
23///
24/// # Budget semantics
25///
26/// [`CostTracker::record`] checks the budget *before* mutating any state. A
27/// record that would push total spend past the limit is rejected with
28/// [`RouterError::BudgetExceeded`] and nothing is accumulated. Therefore, as
29/// long as every call is gated through `record`, tracked spend can never
30/// exceed the limit.
31///
32/// # Example
33///
34/// ```
35/// use model_router::{CostTracker, ModelPricing};
36///
37/// let tracker = CostTracker::new(Some(0.01)); // $0.01 budget
38/// let pricing = ModelPricing::new(3.0, 15.0); // Claude Sonnet class
39///
40/// tracker.record("claude-sonnet-4", 100, 50, &pricing).unwrap();
41/// assert!(tracker.total_usd() < 0.01);
42/// assert!(!tracker.is_over_budget());
43/// ```
44#[derive(Debug, Clone)]
45pub struct CostTracker {
46 /// Total cost, stored as USD * [`COST_SCALE`] in fixed point.
47 total_cost: Arc<AtomicU64>,
48 /// Total input tokens observed.
49 total_input_tokens: Arc<AtomicU64>,
50 /// Total output tokens observed.
51 total_output_tokens: Arc<AtomicU64>,
52 /// Per-model cost breakdown.
53 per_model: Arc<Mutex<BTreeMap<String, ModelCostRecord>>>,
54 /// Budget limit in USD (`None` = unlimited).
55 budget_limit_usd: Option<f64>,
56}
57
58/// Internal per-model accumulation record (fixed point, see [`COST_SCALE`]).
59#[derive(Debug, Clone, Default)]
60struct ModelCostRecord {
61 input_tokens: u64,
62 output_tokens: u64,
63 cost_fixed: u64,
64 request_count: u64,
65}
66
67/// Per-model cost breakdown for reporting.
68#[derive(Debug, Clone, PartialEq)]
69#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
70pub struct ModelCostBreakdown {
71 /// Total input tokens attributed to this model.
72 pub input_tokens: u64,
73 /// Total output tokens attributed to this model.
74 pub output_tokens: u64,
75 /// Total attributed cost in USD.
76 pub cost_usd: f64,
77 /// Number of `record` calls accepted for this model.
78 pub request_count: u64,
79}
80
81/// Snapshot of all tracked usage, including budget status.
82#[derive(Debug, Clone, PartialEq)]
83#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
84pub struct CostReport {
85 /// Total recorded spend in USD.
86 pub total_cost_usd: f64,
87 /// Total input tokens recorded.
88 pub total_input_tokens: u64,
89 /// Total output tokens recorded.
90 pub total_output_tokens: u64,
91 /// Spend broken down per model, keyed by model name.
92 pub per_model: BTreeMap<String, ModelCostBreakdown>,
93 /// Configured budget limit, if any.
94 pub budget_limit_usd: Option<f64>,
95 /// Whether total spend has reached or exceeded the budget.
96 pub is_over_budget: bool,
97}
98
99impl CostTracker {
100 /// Create a new cost tracker, optionally with a USD budget limit.
101 pub fn new(budget_limit_usd: Option<f64>) -> Self {
102 Self {
103 total_cost: Arc::new(AtomicU64::new(0)),
104 total_input_tokens: Arc::new(AtomicU64::new(0)),
105 total_output_tokens: Arc::new(AtomicU64::new(0)),
106 per_model: Arc::new(Mutex::new(BTreeMap::new())),
107 budget_limit_usd,
108 }
109 }
110
111 /// The configured budget limit in USD, if any.
112 pub fn budget_limit_usd(&self) -> Option<f64> {
113 self.budget_limit_usd
114 }
115
116 /// Record token usage for `model`, priced with `pricing`.
117 ///
118 /// Fails with [`RouterError::BudgetExceeded`] (without mutating any
119 /// state) if the record would push total spend past the budget limit.
120 ///
121 /// # Precision
122 ///
123 /// Costs are accumulated in fixed point at $0.0001 granularity and
124 /// *truncated* into that grid, so a recorded delta never exceeds the
125 /// true cost and tracked totals err slightly low. Costs under $0.0001
126 /// (a hundredth of a cent) truncate to zero. The budget pre-check itself
127 /// runs in `f64`, so enforcement precision is unaffected.
128 pub fn record(
129 &self,
130 model: &str,
131 input_tokens: usize,
132 output_tokens: usize,
133 pricing: &ModelPricing,
134 ) -> Result<(), RouterError> {
135 let cost_usd = pricing.cost(input_tokens, output_tokens);
136 let cost_fixed = (cost_usd * COST_SCALE) as u64;
137
138 if let Some(limit) = self.budget_limit_usd {
139 let current = self.total_usd();
140 if current + cost_usd > limit {
141 return Err(RouterError::BudgetExceeded {
142 current,
143 attempted: cost_usd,
144 limit,
145 });
146 }
147 }
148
149 self.total_cost.fetch_add(cost_fixed, Ordering::Relaxed);
150 self.total_input_tokens
151 .fetch_add(input_tokens as u64, Ordering::Relaxed);
152 self.total_output_tokens
153 .fetch_add(output_tokens as u64, Ordering::Relaxed);
154
155 // Justified: poisoning implies a panic mid-update; tracker is best-effort.
156 #[allow(clippy::expect_used)]
157 let mut per_model = self.per_model.lock().expect("cost tracker mutex poisoned");
158 let record = per_model.entry(model.to_string()).or_default();
159 record.input_tokens += input_tokens as u64;
160 record.output_tokens += output_tokens as u64;
161 record.cost_fixed += cost_fixed;
162 record.request_count += 1;
163
164 Ok(())
165 }
166
167 /// Total recorded cost in USD.
168 pub fn total_usd(&self) -> f64 {
169 self.total_cost.load(Ordering::Relaxed) as f64 / COST_SCALE
170 }
171
172 /// Total input tokens recorded across all models.
173 pub fn total_input_tokens(&self) -> u64 {
174 self.total_input_tokens.load(Ordering::Relaxed)
175 }
176
177 /// Total output tokens recorded across all models.
178 pub fn total_output_tokens(&self) -> u64 {
179 self.total_output_tokens.load(Ordering::Relaxed)
180 }
181
182 /// Unspent budget in USD (`None` when no budget is configured). Never
183 /// negative; zero once the budget is exhausted.
184 pub fn remaining_usd(&self) -> Option<f64> {
185 self.budget_limit_usd
186 .map(|limit| (limit - self.total_usd()).max(0.0))
187 }
188
189 /// Per-model cost breakdown.
190 pub fn per_model_breakdown(&self) -> BTreeMap<String, ModelCostBreakdown> {
191 #[allow(clippy::expect_used)]
192 let per_model = self.per_model.lock().expect("cost tracker mutex poisoned");
193 per_model
194 .iter()
195 .map(|(model, record)| {
196 (
197 model.clone(),
198 ModelCostBreakdown {
199 input_tokens: record.input_tokens,
200 output_tokens: record.output_tokens,
201 cost_usd: record.cost_fixed as f64 / COST_SCALE,
202 request_count: record.request_count,
203 },
204 )
205 })
206 .collect()
207 }
208
209 /// Whether total spend has reached or exceeded the budget limit.
210 ///
211 /// Always `false` when no budget is configured.
212 pub fn is_over_budget(&self) -> bool {
213 match self.budget_limit_usd {
214 Some(limit) => self.total_usd() >= limit,
215 None => false,
216 }
217 }
218
219 /// Build a [`CostReport`] snapshot of the current state.
220 pub fn report(&self) -> CostReport {
221 CostReport {
222 total_cost_usd: self.total_usd(),
223 total_input_tokens: self.total_input_tokens(),
224 total_output_tokens: self.total_output_tokens(),
225 per_model: self.per_model_breakdown(),
226 budget_limit_usd: self.budget_limit_usd,
227 is_over_budget: self.is_over_budget(),
228 }
229 }
230}