Skip to main content

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}