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}