The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import type { |
| 2 | UsageCategoryCost, |
| 3 | UsageCostSource, |
| 4 | UsageModelPriceOverride, |
| 5 | UsageTokenTotals, |
| 6 | } from "@t3tools/contracts"; |
| 7 | |
| 8 | import type { UsageRecord, UsageSpeed } from "@t3tools/provider-core/server/usage"; |
| 9 | |
| 10 | export 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 | |
| 19 | interface 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. */ |
| 25 | interface ContextTier { |
| 26 | readonly thresholdTokens: number; |
| 27 | readonly rate: SpeedRates; |
| 28 | } |
| 29 | |
| 30 | /** Omits LiteLLM's flex and batches variants, which transcripts do not record. */ |
| 31 | export interface ModelRate extends SpeedRates { |
| 32 | /** Sorted by descending threshold. */ |
| 33 | readonly contextTiers: readonly ContextTier[]; |
| 34 | } |
| 35 | |
| 36 | export type RateTable = ReadonlyMap<string, ModelRate>; |
| 37 | |
| 38 | export 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 | |
| 63 | type LiteLlmEntry = Readonly<Record<string, unknown>>; |
| 64 | |
| 65 | function 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. |
| 70 | function 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 | |
| 105 | function 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 | |
| 115 | function 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 | |
| 122 | function 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 | |
| 134 | const 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. |
| 138 | function 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. |
| 157 | const 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. */ |
| 168 | export 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 | |
| 206 | function 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. |
| 218 | function 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 | |
| 231 | function 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 | |
| 248 | function 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 | |
| 254 | function 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. |
| 259 | function 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 | |
| 266 | function normalizeRateKey(model: string): string { |
| 267 | return model.trim().toLowerCase(); |
| 268 | } |
| 269 | |
| 270 | function 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. |
| 276 | function 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. |
| 281 | function 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. |
| 287 | const 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. |
| 297 | const resolvedRates = new WeakMap<RateTable, Map<string, ModelRate | null>>(); |
| 298 | |
| 299 | export 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 | |
| 313 | /** A priceable model the table has no rate for; a newer table may list it. */ |
| 314 | export function isUnlistedModel(table: RateTable, model: string): boolean { |
| 315 | const bareName = bareModelName(stripVariantSuffix(normalizeRateKey(model))); |
| 316 | return ( |
| 317 | bareName.length > 0 && !UNPRICEABLE_MODELS.has(bareName) && lookupRate(table, model) === null |
| 318 | ); |
| 319 | } |
| 320 | |
| 321 | function resolveRate(table: RateTable, model: string): ModelRate | null { |
| 322 | const key = stripVariantSuffix(normalizeRateKey(model)); |
| 323 | const bareName = bareModelName(key); |
| 324 | if (bareName.length === 0 || UNPRICEABLE_MODELS.has(bareName)) return null; |
| 325 | return table.get(key) ?? null; |
| 326 | } |
| 327 | |
| 328 | export type PricedRecord = Pick< |
| 329 | UsageRecord, |
| 330 | "model" | "rateModel" | "totals" | "cacheCreation1hTokens" | "speed" | "reportedCostUsd" |
| 331 | >; |
| 332 | |
| 333 | function recordRate(table: RateTable, record: PricedRecord): ModelRate | null { |
| 334 | const rate = record.rateModel === undefined ? null : lookupRate(table, record.rateModel); |
| 335 | return rate ?? lookupRate(table, record.model); |
| 336 | } |
| 337 | |
| 338 | export interface PricedUsage { |
| 339 | readonly costUsd: number; |
| 340 | readonly costSource: UsageCostSource; |
| 341 | readonly categoryCostUsd: UsageCategoryCost | null; |
| 342 | readonly speedPremiumUsd: number; |
| 343 | } |
| 344 | |
| 345 | function costByCategory(record: PricedRecord, rates: TokenRates): UsageCategoryCost { |
| 346 | const { totals } = record; |
| 347 | const oneHour = Math.min(record.cacheCreation1hTokens ?? 0, totals.cacheCreationTokens); |
| 348 | return { |
| 349 | input: totals.uncachedInputTokens * rates.inputCostPerToken, |
| 350 | cacheRead: totals.cachedInputTokens * rates.cacheReadCostPerToken, |
| 351 | cacheWrite: |
| 352 | (totals.cacheCreationTokens - oneHour) * rates.cacheCreationCostPerToken + |
| 353 | oneHour * rates.cacheCreation1hCostPerToken, |
| 354 | output: totals.outputTokens * rates.outputCostPerToken, |
| 355 | }; |
| 356 | } |
| 357 | |
| 358 | function sumCategories(cost: UsageCategoryCost): number { |
| 359 | return cost.input + cost.cacheRead + cost.cacheWrite + cost.output; |
| 360 | } |
| 361 | |
| 362 | /** Reasoning tokens are already included in outputTokens; do not charge twice. */ |
| 363 | export function priceUsage( |
| 364 | table: RateTable, |
| 365 | record: PricedRecord, |
| 366 | overrides?: RateTable, |
| 367 | ): PricedUsage { |
| 368 | const { model, totals, reportedCostUsd } = record; |
| 369 | const override = overrides?.get(model.trim()); |
| 370 | const reported = |
| 371 | override === undefined && reportedCostUsd !== null && Number.isFinite(reportedCostUsd) |
| 372 | ? reportedCostUsd |
| 373 | : null; |
| 374 | const unsplit = (costUsd: number, costSource: UsageCostSource): PricedUsage => ({ |
| 375 | costUsd, |
| 376 | costSource, |
| 377 | categoryCostUsd: null, |
| 378 | speedPremiumUsd: 0, |
| 379 | }); |
| 380 | const rate = override ?? recordRate(table, record); |
| 381 | if (rate === null) { |
| 382 | return reported === null ? unsplit(0, "unpriced") : unsplit(reported, "providerReported"); |
| 383 | } |
| 384 | |
| 385 | const listCost = costByCategory(record, ratesAt(rate, record.speed, totals)); |
| 386 | const listCostUsd = sumCategories(listCost); |
| 387 | if (reported !== null && listCostUsd <= 0) return unsplit(reported, "providerReported"); |
| 388 | const premiumUsd = |
| 389 | record.speed === "standard" |
| 390 | ? 0 |
| 391 | : listCostUsd - sumCategories(costByCategory(record, ratesAt(rate, "standard", totals))); |
| 392 | const scale = reported === null ? 1 : reported / listCostUsd; |
| 393 | return { |
| 394 | costUsd: reported ?? listCostUsd, |
| 395 | costSource: reported === null ? "modelPriced" : "providerReported", |
| 396 | categoryCostUsd: { |
| 397 | input: listCost.input * scale, |
| 398 | cacheRead: listCost.cacheRead * scale, |
| 399 | cacheWrite: listCost.cacheWrite * scale, |
| 400 | output: listCost.output * scale, |
| 401 | }, |
| 402 | speedPremiumUsd: premiumUsd * scale, |
| 403 | }; |
| 404 | } |
| 405 | |
| 406 | export function cacheSavingsUsd( |
| 407 | table: RateTable, |
| 408 | record: PricedRecord, |
| 409 | overrides?: RateTable, |
| 410 | ): number { |
| 411 | const rate = overrides?.get(record.model.trim()) ?? recordRate(table, record); |
| 412 | if (rate === null) return 0; |
| 413 | const rates = ratesAt(rate, record.speed, record.totals); |
| 414 | return record.totals.cachedInputTokens * (rates.inputCostPerToken - rates.cacheReadCostPerToken); |
| 415 | } |