Open History to see the last commit
1import type {
2 UsageCategoryCost,
3 UsageCostSource,
4 UsageModelPriceOverride,
5 UsageTokenTotals,
6} from "@t3tools/contracts";
7
8import type { UsageRecord, UsageSpeed } from "@t3tools/provider-core/server/usage";
9
10export interface TokenRates {
11 readonly inputCostPerToken: number;
12 readonly outputCostPerToken: number;
13 readonly cacheReadCostPerToken: number;
14 readonly cacheCreationCostPerToken: number;
15 /** Cache writes with a 1-hour TTL; the 5-minute rate when unpublished. */
16 readonly cacheCreation1hCostPerToken: number;
17}
18
19interface SpeedRates extends TokenRates {
20 readonly fast: TokenRates | null;
21 readonly ultrafast: TokenRates | null;
22}
23
24/** A request whose prompt exceeds `thresholdTokens` bills every token at this tier. */
25interface ContextTier {
26 readonly thresholdTokens: number;
27 readonly rate: SpeedRates;
28}
29
30/** Omits LiteLLM's flex and batches variants, which transcripts do not record. */
31export interface ModelRate extends SpeedRates {
32 /** Sorted by descending threshold. */
33 readonly contextTiers: readonly ContextTier[];
34}
35
36export type RateTable = ReadonlyMap<string, ModelRate>;
37
38export function createOverrideRateTable(
39 overrides: Readonly<Record<string, UsageModelPriceOverride>>,
40): RateTable {
41 return new Map(
42 Object.entries(overrides).map(([model, prices]) => {
43 const cacheCreationCostPerToken =
44 (prices.cacheWriteCostPerMillionTokens ?? prices.inputCostPerMillionTokens) / 1_000_000;
45 return [
46 model.trim(),
47 {
48 inputCostPerToken: prices.inputCostPerMillionTokens / 1_000_000,
49 outputCostPerToken: prices.outputCostPerMillionTokens / 1_000_000,
50 cacheReadCostPerToken:
51 (prices.cacheReadCostPerMillionTokens ?? prices.inputCostPerMillionTokens) / 1_000_000,
52 cacheCreationCostPerToken,
53 cacheCreation1hCostPerToken: cacheCreationCostPerToken,
54 fast: null,
55 ultrafast: null,
56 contextTiers: [],
57 },
58 ];
59 }),
60 );
61}
62
63type LiteLlmEntry = Readonly<Record<string, unknown>>;
64
65function finiteNumber(value: unknown): number | null {
66 return typeof value === "number" && Number.isFinite(value) ? value : null;
67}
68
69// Missing cache rates fall back to input pricing, and a missing 1-hour write rate to the 5-minute one.
70function readTokenRates(
71 entry: LiteLlmEntry,
72 suffix: string,
73 standard?: TokenRates,
74 outputFallback?: number,
75): TokenRates | null {
76 const input = finiteNumber(entry[`input_cost_per_token${suffix}`]);
77 const output = finiteNumber(entry[`output_cost_per_token${suffix}`]) ?? outputFallback ?? null;
78 if (input === null || output === null) return null;
79 const cacheRate = (
80 name: string,
81 field: "cacheReadCostPerToken" | "cacheCreationCostPerToken" | "cacheCreation1hCostPerToken",
82 fallback = input,
83 ) =>
84 finiteNumber(entry[`${name}${suffix}`]) ??
85 (standard !== undefined && standard.inputCostPerToken > 0
86 ? (standard[field] / standard.inputCostPerToken) * input
87 : fallback);
88 const cacheCreationCostPerToken = cacheRate(
89 "cache_creation_input_token_cost",
90 "cacheCreationCostPerToken",
91 );
92 return {
93 inputCostPerToken: input,
94 outputCostPerToken: output,
95 cacheReadCostPerToken: cacheRate("cache_read_input_token_cost", "cacheReadCostPerToken"),
96 cacheCreationCostPerToken,
97 cacheCreation1hCostPerToken: cacheRate(
98 "cache_creation_input_token_cost_above_1hr",
99 "cacheCreation1hCostPerToken",
100 cacheCreationCostPerToken,
101 ),
102 };
103}
104
105function scaleTokenRates(rates: TokenRates, multiple: number): TokenRates {
106 return {
107 inputCostPerToken: rates.inputCostPerToken * multiple,
108 outputCostPerToken: rates.outputCostPerToken * multiple,
109 cacheReadCostPerToken: rates.cacheReadCostPerToken * multiple,
110 cacheCreationCostPerToken: rates.cacheCreationCostPerToken * multiple,
111 cacheCreation1hCostPerToken: rates.cacheCreation1hCostPerToken * multiple,
112 };
113}
114
115function fastMultiplier(entry: LiteLlmEntry): number | null {
116 const specific = entry["provider_specific_entry"];
117 if (typeof specific !== "object" || specific === null) return null;
118 const fast = finiteNumber((specific as Record<string, unknown>)["fast"]);
119 return fast !== null && fast > 0 ? fast : null;
120}
121
122function readSpeedRates(entry: LiteLlmEntry, standard: TokenRates, suffix = ""): SpeedRates {
123 const multiple = fastMultiplier(entry);
124 return {
125 ...standard,
126 fast:
127 multiple === null
128 ? readTokenRates(entry, `${suffix}_priority`, standard)
129 : scaleTokenRates(standard, multiple),
130 ultrafast: readTokenRates(entry, `${suffix}_ultrafast`, standard),
131 };
132}
133
134const CONTEXT_TIER_INPUT_KEY =
135 /^input_cost_per_token_above_(\d{1,7})k_tokens(?:_priority|_ultrafast)?$/;
136
137// Fields a tier omits fall back to base rates, so a priority-only tier still prices standard requests at base.
138function readContextTiers(entry: LiteLlmEntry, base: TokenRates): ContextTier[] {
139 const thresholds = new Set<string>();
140 for (const key of Object.keys(entry)) {
141 const match = CONTEXT_TIER_INPUT_KEY.exec(key);
142 if (match !== null) thresholds.add(match[1]!);
143 }
144 return [...thresholds]
145 .map((threshold) => {
146 const suffix = `_above_${threshold}k_tokens`;
147 const standard = readTokenRates(entry, suffix, base, base.outputCostPerToken) ?? base;
148 return {
149 thresholdTokens: Number(threshold) * 1_000,
150 rate: readSpeedRates(entry, standard, suffix),
151 };
152 })
153 .toSorted((a, b) => b.thresholdTokens - a.thresholdTokens);
154}
155
156// LiteLLM prefixes for the model makers' own APIs; their price beats a cloud's or reseller's for a bare name.
157const FIRST_PARTY_PROVIDERS = new Set([
158 "anthropic",
159 "deepseek",
160 "gemini",
161 "meta",
162 "mistral",
163 "openai",
164 "xai",
165]);
166
167/** Drops models missing input or output rates to avoid understating cost. */
168export function parseRateTable(document: unknown): RateTable {
169 const table = new Map<string, ModelRate>();
170 if (typeof document !== "object" || document === null) return table;
171
172 for (const [name, raw] of Object.entries(document as Record<string, unknown>)) {
173 if (typeof raw !== "object" || raw === null) continue;
174 const entry = raw as LiteLlmEntry;
175 const standard = readTokenRates(entry, "");
176 if (standard === null) continue;
177
178 const key = normalizeRateKey(name);
179 if (key.length === 0) continue;
180 table.set(key, {
181 ...readSpeedRates(entry, standard),
182 contextTiers: readContextTiers(entry, standard),
183 });
184 }
185
186 const aliasCandidates = new Map<string, { rate: ModelRate | null; firstParty: boolean }>();
187 for (const [key, rate] of table) {
188 const slash = key.indexOf("/");
189 const alias = slash === -1 ? bedrockBaseModelName(key) : bareModelName(key);
190 if (alias.length === 0 || alias === key || table.has(alias)) continue;
191 const firstParty = slash !== -1 && FIRST_PARTY_PROVIDERS.has(key.slice(0, slash));
192 const held = aliasCandidates.get(alias);
193 if (held === undefined || (firstParty && !held.firstParty)) {
194 aliasCandidates.set(alias, { rate, firstParty });
195 } else if (held.rate !== null && firstParty === held.firstParty) {
196 aliasCandidates.set(alias, { rate: mergeAliasRate(held.rate, rate), firstParty });
197 }
198 }
199 for (const [alias, { rate }] of aliasCandidates) {
200 if (rate !== null) table.set(alias, rate);
201 }
202
203 return table;
204}
205
206function sameTokenRates(a: TokenRates | null, b: TokenRates | null): boolean {
207 if (a === null || b === null) return a === b;
208 return (
209 a.inputCostPerToken === b.inputCostPerToken &&
210 a.outputCostPerToken === b.outputCostPerToken &&
211 a.cacheReadCostPerToken === b.cacheReadCostPerToken &&
212 a.cacheCreationCostPerToken === b.cacheCreationCostPerToken &&
213 a.cacheCreation1hCostPerToken === b.cacheCreation1hCostPerToken
214 );
215}
216
217// Resellers often omit speed and context tiers, so a missing tier fills from the other entry instead of conflicting.
218function mergeSpeedRates(a: SpeedRates, b: SpeedRates): SpeedRates | null {
219 const fast = a.fast ?? b.fast;
220 const ultrafast = a.ultrafast ?? b.ultrafast;
221 if (
222 !sameTokenRates(a, b) ||
223 !sameTokenRates(fast, b.fast ?? fast) ||
224 !sameTokenRates(ultrafast, b.ultrafast ?? ultrafast)
225 ) {
226 return null;
227 }
228 return { ...a, fast, ultrafast };
229}
230
231function mergeContextTiers(
232 a: readonly ContextTier[],
233 b: readonly ContextTier[],
234): readonly ContextTier[] | null {
235 if (a.length === 0) return b;
236 if (b.length === 0) return a;
237 if (a.length !== b.length) return null;
238 const merged: ContextTier[] = [];
239 for (const [index, tier] of a.entries()) {
240 const other = b[index]!;
241 const rate = mergeSpeedRates(tier.rate, other.rate);
242 if (tier.thresholdTokens !== other.thresholdTokens || rate === null) return null;
243 merged.push({ thresholdTokens: tier.thresholdTokens, rate });
244 }
245 return merged;
246}
247
248function mergeAliasRate(a: ModelRate, b: ModelRate): ModelRate | null {
249 const speeds = mergeSpeedRates(a, b);
250 const contextTiers = mergeContextTiers(a.contextTiers, b.contextTiers);
251 return speeds === null || contextTiers === null ? null : { ...speeds, contextTiers };
252}
253
254function promptTokens(totals: UsageTokenTotals): number {
255 return totals.uncachedInputTokens + totals.cachedInputTokens + totals.cacheCreationTokens;
256}
257
258// A tier without the requested speed keeps the base tier's rate for that speed.
259function ratesAt(rate: ModelRate, speed: UsageSpeed, totals: UsageTokenTotals): TokenRates {
260 const prompt = promptTokens(totals);
261 const tier = rate.contextTiers.find((tier) => prompt > tier.thresholdTokens)?.rate;
262 if (speed === "standard") return tier ?? rate;
263 return tier?.[speed] ?? rate[speed] ?? tier ?? rate;
264}
265
266function normalizeRateKey(model: string): string {
267 return model.trim().toLowerCase();
268}
269
270function bareModelName(key: string): string {
271 const slash = key.lastIndexOf("/");
272 return slash === -1 ? key : key.slice(slash + 1);
273}
274
275// Only Bedrock's base ID gives a bare alias; its regional (us., eu.) and GovCloud IDs carry markups.
276function bedrockBaseModelName(key: string): string {
277 return key.startsWith("anthropic.") ? key.slice("anthropic.".length) : key;
278}
279
280// Price Claude's bracketed context variants at the base tier, the only name the rate table knows.
281function stripVariantSuffix(key: string): string {
282 const bracket = key.indexOf("[");
283 return bracket === -1 ? key : key.slice(0, bracket);
284}
285
286// Synthetic messages are unbilled; bare family names are generation-ambiguous and remain unpriced.
287const UNPRICEABLE_MODELS = new Set([
288 "<synthetic>",
289 "synthetic",
290 "opus",
291 "sonnet",
292 "haiku",
293 "fable",
294]);
295
296// Immutable tables permit caching rates across twice-per-record pricing lookups.
297const resolvedRates = new WeakMap<RateTable, Map<string, ModelRate | null>>();
298
299export function lookupRate(table: RateTable, model: string): ModelRate | null {
300 let resolved = resolvedRates.get(table);
301 if (resolved === undefined) {
302 resolved = new Map();
303 resolvedRates.set(table, resolved);
304 }
305 let rate = resolved.get(model);
306 if (rate === undefined) {
307 rate = resolveRate(table, model);
308 resolved.set(model, rate);
309 }
310 return rate;
311}
312
313function resolveRate(table: RateTable, model: string): ModelRate | null {
314 const key = stripVariantSuffix(normalizeRateKey(model));
315 const bareName = bareModelName(key);
316 if (bareName.length === 0 || UNPRICEABLE_MODELS.has(bareName)) return null;
317 return table.get(key) ?? null;
318}
319
320export type PricedRecord = Pick<
321 UsageRecord,
322 "model" | "rateModel" | "totals" | "cacheCreation1hTokens" | "speed" | "reportedCostUsd"
323>;
324
325function recordRate(table: RateTable, record: PricedRecord): ModelRate | null {
326 const rate = record.rateModel === undefined ? null : lookupRate(table, record.rateModel);
327 return rate ?? lookupRate(table, record.model);
328}
329
330export interface PricedUsage {
331 readonly costUsd: number;
332 readonly costSource: UsageCostSource;
333 readonly categoryCostUsd: UsageCategoryCost | null;
334 readonly speedPremiumUsd: number;
335}
336
337function costByCategory(record: PricedRecord, rates: TokenRates): UsageCategoryCost {
338 const { totals } = record;
339 const oneHour = Math.min(record.cacheCreation1hTokens ?? 0, totals.cacheCreationTokens);
340 return {
341 input: totals.uncachedInputTokens * rates.inputCostPerToken,
342 cacheRead: totals.cachedInputTokens * rates.cacheReadCostPerToken,
343 cacheWrite:
344 (totals.cacheCreationTokens - oneHour) * rates.cacheCreationCostPerToken +
345 oneHour * rates.cacheCreation1hCostPerToken,
346 output: totals.outputTokens * rates.outputCostPerToken,
347 };
348}
349
350function sumCategories(cost: UsageCategoryCost): number {
351 return cost.input + cost.cacheRead + cost.cacheWrite + cost.output;
352}
353
354/** Reasoning tokens are already included in outputTokens; do not charge twice. */
355export function priceUsage(
356 table: RateTable,
357 record: PricedRecord,
358 overrides?: RateTable,
359): PricedUsage {
360 const { model, totals, reportedCostUsd } = record;
361 const override = overrides?.get(model.trim());
362 const reported =
363 override === undefined && reportedCostUsd !== null && Number.isFinite(reportedCostUsd)
364 ? reportedCostUsd
365 : null;
366 const unsplit = (costUsd: number, costSource: UsageCostSource): PricedUsage => ({
367 costUsd,
368 costSource,
369 categoryCostUsd: null,
370 speedPremiumUsd: 0,
371 });
372 const rate = override ?? recordRate(table, record);
373 if (rate === null) {
374 return reported === null ? unsplit(0, "unpriced") : unsplit(reported, "providerReported");
375 }
376
377 const listCost = costByCategory(record, ratesAt(rate, record.speed, totals));
378 const listCostUsd = sumCategories(listCost);
379 if (reported !== null && listCostUsd <= 0) return unsplit(reported, "providerReported");
380 const premiumUsd =
381 record.speed === "standard"
382 ? 0
383 : listCostUsd - sumCategories(costByCategory(record, ratesAt(rate, "standard", totals)));
384 const scale = reported === null ? 1 : reported / listCostUsd;
385 return {
386 costUsd: reported ?? listCostUsd,
387 costSource: reported === null ? "modelPriced" : "providerReported",
388 categoryCostUsd: {
389 input: listCost.input * scale,
390 cacheRead: listCost.cacheRead * scale,
391 cacheWrite: listCost.cacheWrite * scale,
392 output: listCost.output * scale,
393 },
394 speedPremiumUsd: premiumUsd * scale,
395 };
396}
397
398export function cacheSavingsUsd(
399 table: RateTable,
400 record: PricedRecord,
401 overrides?: RateTable,
402): number {
403 const rate = overrides?.get(record.model.trim()) ?? recordRate(table, record);
404 if (rate === null) return 0;
405 const rates = ratesAt(rate, record.speed, record.totals);
406 return record.totals.cachedInputTokens * (rates.inputCostPerToken - rates.cacheReadCostPerToken);
407}