Skip to main content

firstpass_core/
cost.rs

1//! Cost model: per-model token pricing and the counterfactual baseline (SPEC §9.1).
2//!
3//! The whole product claim is "cheapest model that passes," so cost math is load-bearing.
4//! Two numbers matter per trace: what the escalation ladder actually spent, and the
5//! **counterfactual baseline** — what always calling the top rung would have cost. Their
6//! difference is the savings Firstpass proves.
7
8use crate::error::{Error, Result};
9use serde::{Deserialize, Serialize};
10use std::collections::HashMap;
11
12/// Published price of a model, in USD per 1,000,000 tokens.
13#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
14pub struct ModelPrice {
15    /// USD per 1M input (prompt) tokens.
16    pub input_per_mtok: f64,
17    /// USD per 1M output (completion) tokens.
18    pub output_per_mtok: f64,
19}
20
21impl ModelPrice {
22    /// Cost in USD of `input`/`output` tokens at this price.
23    #[must_use]
24    pub fn cost(&self, input: u64, output: u64) -> f64 {
25        (input as f64 / 1e6) * self.input_per_mtok + (output as f64 / 1e6) * self.output_per_mtok
26    }
27
28    /// Cost in USD including prompt-cache traffic, which bills at different rates than plain input.
29    ///
30    /// Cached prompt tokens are **not** free and **not** priced like ordinary input:
31    /// - writing to the cache costs a premium ([`CACHE_WRITE_MULTIPLIER`]), because the provider
32    ///   stores the prefix;
33    /// - reading from it is heavily discounted ([`CACHE_READ_MULTIPLIER`]).
34    ///
35    /// Ignoring both — which is what counting `input_tokens` alone does — understates a cached
36    /// request by orders of magnitude. A 190k-token cached prefix reports an `input_tokens` of
37    /// about 20, so the receipt reads a fraction of a cent for a call that cost most of a dollar,
38    /// and `[budget]` caps fed by that total never trip.
39    #[must_use]
40    pub fn cost_with_cache(
41        &self,
42        input: u64,
43        cache_write: u64,
44        cache_read: u64,
45        output: u64,
46    ) -> f64 {
47        self.cost(input, output)
48            + (cache_write as f64 / 1e6) * self.input_per_mtok * CACHE_WRITE_MULTIPLIER
49            + (cache_read as f64 / 1e6) * self.input_per_mtok * CACHE_READ_MULTIPLIER
50    }
51}
52
53/// Premium on input rate for tokens written to the provider's prompt cache.
54///
55/// Anthropic's published 5-minute-TTL rate. ponytail: one constant rather than a per-model column —
56/// every provider that offers prompt caching currently prices it as a fixed multiple of its own
57/// input rate, so a column would be the same number repeated. Move it into [`ModelPrice`] the day
58/// one of them diverges.
59pub const CACHE_WRITE_MULTIPLIER: f64 = 1.25;
60
61/// Discount on input rate for tokens served from the provider's prompt cache (Anthropic: 0.1×).
62pub const CACHE_READ_MULTIPLIER: f64 = 0.1;
63
64/// A lookup from `provider/model` to [`ModelPrice`].
65///
66/// ponytail: the embedded [`PriceTable::defaults`] are a calibration knob, not gospel —
67/// list prices drift and enterprise contracts differ. In prod, load overrides from config
68/// via [`PriceTable::with_override`]; the defaults just make the common case work out of the box.
69#[derive(Debug, Clone, Default)]
70pub struct PriceTable {
71    prices: HashMap<String, ModelPrice>,
72}
73
74impl PriceTable {
75    /// An empty table.
76    #[must_use]
77    pub fn new() -> Self {
78        Self::default()
79    }
80
81    /// Built-in prices for the common frontier models (USD / 1M tokens, approximate list
82    /// prices — a starting point to be overridden per deployment).
83    #[must_use]
84    pub fn defaults() -> Self {
85        let mut prices = HashMap::new();
86        let mut put = |k: &str, i: f64, o: f64| {
87            prices.insert(
88                k.to_owned(),
89                ModelPrice {
90                    input_per_mtok: i,
91                    output_per_mtok: o,
92                },
93            );
94        };
95        // Anthropic
96        put("anthropic/claude-haiku-4-5", 1.0, 5.0);
97        put("anthropic/claude-sonnet-5", 3.0, 15.0);
98        put("anthropic/claude-opus-4-8", 15.0, 75.0);
99        // OpenAI
100        put("openai/gpt-4.1-mini", 0.4, 1.6);
101        put("openai/gpt-5.5", 5.0, 15.0);
102        // Google. `gemini-3.1-flash`/`-pro` were priced here but never existed on the API —
103        // `generateContent` 404s them — so the shipped Google ladder failed on its first call.
104        // These two are GA per Google's model + pricing docs.
105        // ponytail: Google prices Pro in tiers (>200k-token prompts cost more) and this table
106        // is flat; these are the ≤200k rates. Pin your own with `[[price]]` if you run long
107        // prompts on Pro.
108        put("google/gemini-3.5-flash-lite", 0.3, 2.5);
109        put("google/gemini-3.6-flash", 1.5, 7.5);
110        put("google/gemini-2.5-pro", 1.25, 10.0);
111        Self { prices }
112    }
113
114    /// Insert or replace a model's price, returning `self` for chaining.
115    #[must_use]
116    pub fn with_override(mut self, model: impl Into<String>, price: ModelPrice) -> Self {
117        self.prices.insert(model.into(), price);
118        self
119    }
120
121    /// Look up a model's price by its `provider/model` key.
122    #[must_use]
123    pub fn get(&self, model: &str) -> Option<ModelPrice> {
124        self.prices.get(model).copied()
125    }
126
127    /// Cost in USD of a call to `model` with the given token counts.
128    ///
129    /// **Only correct for a response with no prompt-cache traffic.** Any path pricing a real
130    /// provider response should call [`PriceTable::cost_usd_with_cache`] instead and pass the
131    /// cache counters — this one silently prices a cached call at a small fraction of what it
132    /// cost, which is how a ~$0.72 request once banked a $0.0001 receipt. Reserved for
133    /// counterfactuals and synthetic token counts, where there is no cache traffic by
134    /// construction.
135    ///
136    /// # Errors
137    /// Returns [`Error::UnknownModel`] if the model has no price entry.
138    pub fn cost_usd(&self, model: &str, input: u64, output: u64) -> Result<f64> {
139        self.cost_usd_with_cache(model, input, 0, 0, output)
140    }
141
142    /// As [`PriceTable::cost_usd`], including prompt-cache traffic at its own rates.
143    ///
144    /// # Errors
145    /// Returns [`Error::UnknownModel`] if the model has no price entry.
146    pub fn cost_usd_with_cache(
147        &self,
148        model: &str,
149        input: u64,
150        cache_write: u64,
151        cache_read: u64,
152        output: u64,
153    ) -> Result<f64> {
154        self.get(model)
155            .map(|p| p.cost_with_cache(input, cache_write, cache_read, output))
156            .ok_or_else(|| Error::UnknownModel(model.to_owned()))
157    }
158
159    /// The counterfactual baseline: what the request would have cost had it gone straight to
160    /// `top_model` (the ladder's top rung) with the served token counts.
161    ///
162    /// This is an estimate — the top model might have emitted a different number of tokens —
163    /// but token counts of served output are the fair, auditable proxy the trace records.
164    ///
165    /// # Errors
166    /// Returns [`Error::UnknownModel`] if `top_model` has no price entry.
167    pub fn baseline_usd(&self, top_model: &str, input: u64, output: u64) -> Result<f64> {
168        self.cost_usd(top_model, input, output)
169    }
170}
171
172#[cfg(test)]
173mod tests {
174    /// A cached request must not be billed as if the cached prompt were free.
175    ///
176    /// This is the regression that mattered: usage was read as `input_tokens` alone, and a caller
177    /// using prompt caching reports the bulk of its prompt in the cache counters. A 190k-token
178    /// cached prefix arrives as an `input_tokens` of ~20, so the receipt recorded a fraction of a
179    /// cent for a call that cost most of a dollar — in a product whose claim is a tamper-evident
180    /// cost record, and with `[budget]` caps fed by that same total.
181    #[test]
182    fn a_cached_prompt_is_billed_not_ignored() {
183        // sonnet-5: $3/1M input, $15/1M output.
184        let p = super::ModelPrice {
185            input_per_mtok: 3.0,
186            output_per_mtok: 15.0,
187        };
188
189        // What a real cached Claude Code turn looks like: tiny uncached remainder, huge cache write.
190        let naive = p.cost(20, 400);
191        let real = p.cost_with_cache(20, 190_000, 0, 400);
192
193        assert!(
194            real > naive * 50.0,
195            "cache-aware cost {real} must dwarf the naive {naive}; that gap is the bug"
196        );
197        // 20 in + 400 out + 190k written at 1.25x: 0.00006 + 0.006 + 0.7125
198        assert!((real - 0.71856).abs() < 1e-5, "got {real}");
199    }
200
201    #[test]
202    fn a_cache_read_is_cheap_but_never_free() {
203        let p = super::ModelPrice {
204            input_per_mtok: 3.0,
205            output_per_mtok: 15.0,
206        };
207        // 190k read from cache at 0.1x = $0.057, versus $0.57 had it been uncached input.
208        let read = p.cost_with_cache(0, 0, 190_000, 0);
209        assert!((read - 0.057).abs() < 1e-6, "got {read}");
210        assert!(read > 0.0, "a cache read is discounted, not free");
211        let uncached = p.cost(190_000, 0);
212        assert!(read < uncached, "{read} should undercut {uncached}");
213    }
214
215    #[test]
216    fn zero_cache_traffic_bills_exactly_as_before() {
217        // Every existing receipt and test must be unaffected: no cache traffic, no change.
218        let p = super::ModelPrice {
219            input_per_mtok: 3.0,
220            output_per_mtok: 15.0,
221        };
222        assert!((p.cost_with_cache(1000, 0, 0, 500) - p.cost(1000, 500)).abs() < f64::EPSILON);
223    }
224
225    use super::*;
226
227    #[test]
228    fn cost_math_is_correct() {
229        let p = ModelPrice {
230            input_per_mtok: 3.0,
231            output_per_mtok: 15.0,
232        };
233        // 1000 in * $3/M + 500 out * $15/M = 0.003 + 0.0075 = 0.0105
234        assert!((p.cost(1000, 500) - 0.0105).abs() < 1e-12);
235        assert_eq!(p.cost(0, 0), 0.0);
236    }
237
238    #[test]
239    fn table_lookup_and_unknown_model() {
240        let t = PriceTable::defaults();
241        assert!(t.cost_usd("anthropic/claude-haiku-4-5", 1000, 1000).is_ok());
242        match t.cost_usd("acme/nope", 1, 1) {
243            Err(Error::UnknownModel(m)) => assert_eq!(m, "acme/nope"),
244            other => panic!("expected UnknownModel, got {other:?}"),
245        }
246    }
247
248    #[test]
249    fn baseline_exceeds_cheap_rung_for_same_tokens() {
250        // The core value prop, as a math invariant: top rung costs more than the cheap rung.
251        let t = PriceTable::defaults();
252        let (i, o) = (2000, 800);
253        let cheap = t.cost_usd("anthropic/claude-haiku-4-5", i, o).unwrap();
254        let baseline = t.baseline_usd("anthropic/claude-opus-4-8", i, o).unwrap();
255        assert!(baseline > cheap);
256        assert!(baseline - cheap > 0.0); // there are savings to prove
257    }
258
259    #[test]
260    fn overrides_win() {
261        let t = PriceTable::new().with_override(
262            "x/y",
263            ModelPrice {
264                input_per_mtok: 2.0,
265                output_per_mtok: 2.0,
266            },
267        );
268        assert_eq!(t.cost_usd("x/y", 1_000_000, 0).unwrap(), 2.0);
269    }
270}