Skip to content
Source
Sign inSign up
pingdotgg/t3code
Open History to see the last commit

usageAggregation.ts

407 lines14.1 KB

1// @effect-diagnostics globalDate:off
2import type {
3 UsageBucket,
4 UsageCategoryCost,
5 UsageDay,
6 UsageModelFilter,
7 UsageModelSelector,
8 UsageResolution,
9 UsageTokenTotals,
10} from "@t3tools/contracts";
11​
12import { EMPTY_TOTALS, type UsageRecord } from "@t3tools/provider-core/server/usage";
13import { cacheSavingsUsd, priceUsage, type RateTable } from "./usagePricing.ts";
14​
15// en-CA gives ISO-ordered parts in the requested zone; Date getters are host-local.
16function makeDayFormatter(timeZone: string): (timestampMs: number) => string {
17 let format: Intl.DateTimeFormat;
18 try {
19 format = new Intl.DateTimeFormat("en-CA", {
20 timeZone,
21 year: "numeric",
22 month: "2-digit",
23 day: "2-digit",
24 });
25 } catch {
26 format = new Intl.DateTimeFormat("en-CA", {
27 timeZone: "UTC",
28 year: "numeric",
29 month: "2-digit",
30 day: "2-digit",
31 });
32 }
33 // Cache quarter-hour slots to avoid per-record Intl calls; fixed-offset midnight can split slots and needs exact formatting.
34 const days = new Map<number, string | null>();
35 return (timestampMs) => {
36 const slot = Math.floor(timestampMs / QUARTER_HOUR_MS);
37 let day = days.get(slot);
38 if (day === undefined) {
39 const first = format.format(new Date(slot * QUARTER_HOUR_MS));
40 const last = format.format(new Date((slot + 1) * QUARTER_HOUR_MS - 1));
41 day = first === last ? first : null;
42 days.set(slot, day);
43 }
44 return day ?? format.format(new Date(timestampMs));
45 };
47​
48const QUARTER_HOUR_MS = 15 * 60 * 1000;
49const HOUR_MS = 60 * 60 * 1000;
50​
51interface MutableBucket {
52 totals: { -readonly [K in keyof UsageTokenTotals]: number };
53 costUsd: number;
54 cacheSavingsUsd: number;
55 categoryCostUsd: UsageCategoryCost | null;
56 fastCostUsd: number;
57 ultrafastCostUsd: number;
58 speedPremiumUsd: number;
59 records: number;
60 unpricedRecords: number;
61 providerReportedRecords: number;
62 sessions: Set<string>;
64​
65export interface AggregateOptions {
66 readonly timeZone: string;
67 readonly sinceDay: string;
68 readonly untilDay: string;
69 readonly rates: RateTable;
70 readonly priceOverrides?: RateTable;
71 readonly modelAliases?: ReadonlyMap<string, string>;
72 readonly modelFilter?: UsageModelFilter;
73 readonly resolution?: UsageResolution;
74 readonly sinceTimeMs?: number;
75 readonly untilTimeMs?: number;
77​
78export function resolveModelAliases(
79 aliases: Readonly<Record<string, string>>,
80): ReadonlyMap<string, string> {
81 const resolved = new Map<string, string>();
82 for (const model of Object.keys(aliases)) {
83 const seen = new Set([model]);
84 let target = aliases[model]!;
85 while (Object.hasOwn(aliases, target) && !seen.has(target)) {
86 seen.add(target);
87 target = aliases[target]!;
88 }
89 if (!Object.hasOwn(aliases, target)) resolved.set(model, target);
90 }
91 return resolved;
93​
94/** Matches original IDs, so an alias cannot pull excluded usage into a kept model. */
95function keepsUsageRecord(filter: UsageModelFilter | undefined, record: UsageRecord): boolean {
96 if (filter === undefined) return true;
97 const model = record.model.trim();
98 const matches = (selector: UsageModelSelector) =>
99 selector.model === model &&
100 (selector.provider === undefined || selector.provider === record.provider);
101 return (filter.include?.some(matches) ?? true) && !(filter.exclude?.some(matches) ?? false);
103​
104const selectorKey = (selector: UsageModelSelector) =>
105 JSON.stringify([selector.provider ?? null, selector.model]);
106​
107const canonicalSelectors = (selectors: readonly UsageModelSelector[]) =>
108 [...new Map(selectors.map((selector) => [selectorKey(selector), selector]))]
109 // Code-unit order, so servers in different locales echo the same form.
110 .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
111 .map(([, selector]) => selector);
112​
113/** Equal filters get one form, so they share scans and clients can compare echoed filters. */
114export function canonicalModelFilter(
115 filter: UsageModelFilter | undefined,
116): UsageModelFilter | undefined {
117 if (filter === undefined) return undefined;
118 const exclude = filter.exclude?.length ? canonicalSelectors(filter.exclude) : undefined;
119 if (filter.include === undefined && exclude === undefined) return undefined;
120 return {
121 ...(filter.include === undefined ? {} : { include: canonicalSelectors(filter.include) }),
122 ...(exclude === undefined ? {} : { exclude }),
123 };
125​
126export interface AggregateResult {
127 readonly buckets: readonly UsageBucket[];
128 readonly duplicatesDropped: number;
129 readonly outOfWindow: number;
131​
132/**
133 * Partial copies share a billed message's key: keep each token channel's maximum and the larger
134 * reported cost, and the first copy's time, model, session and speed so it stays in its bucket.
135 */
136export function mergeUsageCopies(held: UsageRecord, copy: UsageRecord): UsageRecord {
137 const a = held.totals;
138 const b = copy.totals;
139 const reportedCostUsd =
140 held.reportedCostUsd === null || copy.reportedCostUsd === null
141 ? (held.reportedCostUsd ?? copy.reportedCostUsd)
142 : Math.max(held.reportedCostUsd, copy.reportedCostUsd);
143 if (
144 b.uncachedInputTokens <= a.uncachedInputTokens &&
145 b.cachedInputTokens <= a.cachedInputTokens &&
146 b.cacheCreationTokens <= a.cacheCreationTokens &&
147 b.outputTokens <= a.outputTokens &&
148 b.reasoningTokens <= a.reasoningTokens &&
149 reportedCostUsd === held.reportedCostUsd
150 ) {
151 return held;
152 }
153 return {
154 ...held,
155 totals: {
156 uncachedInputTokens: Math.max(a.uncachedInputTokens, b.uncachedInputTokens),
157 cachedInputTokens: Math.max(a.cachedInputTokens, b.cachedInputTokens),
158 cacheCreationTokens: Math.max(a.cacheCreationTokens, b.cacheCreationTokens),
159 outputTokens: Math.max(a.outputTokens, b.outputTokens),
160 reasoningTokens: Math.max(a.reasoningTokens, b.reasoningTokens),
161 },
162 reportedCostUsd,
163 };
165​
166interface Contribution {
167 record: UsageRecord;
168 /** Null when the first copy fell outside the window. */
169 readonly bucket: MutableBucket | null;
171​
172/** Deduplicates across the whole scan; Claude copies records into resumed/forked transcripts. */
173export class UsageAggregator {
174 readonly #buckets = new Map<string, MutableBucket>();
175 readonly #seen = new Map<string, Contribution>();
176 readonly #toDay: (timestampMs: number) => string;
177 readonly #hourlyWindow: { readonly sinceTimeMs: number; readonly untilTimeMs: number } | null;
178 readonly #options: AggregateOptions;
179 #lastBucket: {
180 readonly day: string;
181 readonly hourIndex: number;
182 readonly provider: string;
183 readonly model: string;
184 readonly source: string;
185 readonly bucket: MutableBucket;
186 } | null = null;
187 #duplicatesDropped = 0;
188 #outOfWindow = 0;
189​
190 constructor(options: AggregateOptions) {
191 this.#options = options;
192 this.#toDay = makeDayFormatter(options.timeZone);
193 if (options.resolution === "hour") {
194 if (options.sinceTimeMs === undefined || options.untilTimeMs === undefined) {
195 throw new Error("Hourly usage aggregation requires exact time bounds");
196 }
197 this.#hourlyWindow = {
198 sinceTimeMs: options.sinceTimeMs,
199 untilTimeMs: options.untilTimeMs,
200 };
201 } else {
202 this.#hourlyWindow = null;
203 }
204 }
205​
206 add(input: UsageRecord, sourcePath?: string): boolean {
207 if (!keepsUsageRecord(this.#options.modelFilter, input)) return false;
208 const record = this.#mapModel(input);
209 if (record.dedupeKey !== null) {
210 const held = this.#seen.get(record.dedupeKey);
211 if (held !== undefined) {
212 this.#duplicatesDropped += 1;
213 if (held.bucket !== null) held.record = mergeUsageCopies(held.record, record);
214 return false;
215 }
216 }
217​
218 const bucket = this.#placeInWindow(record, sourcePath ?? "");
219 if (record.dedupeKey !== null) this.#seen.set(record.dedupeKey, { record, bucket });
220 if (bucket === null) {
221 this.#outOfWindow += 1;
222 return false;
223 }
224 // Keyed usage is counted in finish(), once all its copies are merged.
225 if (record.dedupeKey === null) this.#accumulate(bucket, record);
226 if (record.sessionId.length > 0) bucket.sessions.add(record.sessionId);
227 return true;
228 }
229​
230 #placeInWindow(record: UsageRecord, source: string): MutableBucket | null {
231 if (
232 this.#hourlyWindow !== null &&
233 (record.timestampMs < this.#hourlyWindow.sinceTimeMs ||
234 record.timestampMs >= this.#hourlyWindow.untilTimeMs)
235 ) {
236 return null;
237 }
238​
239 const day = this.#toDay(record.timestampMs);
240 if (
241 this.#hourlyWindow === null &&
242 (day < this.#options.sinceDay || day > this.#options.untilDay)
243 ) {
244 return null;
245 }
246​
247 const hourIndex =
248 this.#hourlyWindow === null
249 ? -1
250 : Math.floor((record.timestampMs - this.#hourlyWindow.sinceTimeMs) / HOUR_MS);
251 return this.#bucketFor(day, hourIndex, record.provider, record.model, source);
252 }
253​
254 #accumulate(bucket: MutableBucket, record: UsageRecord): void {
255 const priced = priceUsage(this.#options.rates, record, this.#options.priceOverrides);
256​
257 const totals = bucket.totals;
258 totals.uncachedInputTokens += record.totals.uncachedInputTokens;
259 totals.cachedInputTokens += record.totals.cachedInputTokens;
260 totals.cacheCreationTokens += record.totals.cacheCreationTokens;
261 totals.outputTokens += record.totals.outputTokens;
262 totals.reasoningTokens += record.totals.reasoningTokens;
263 bucket.costUsd += priced.costUsd;
264 if (priced.categoryCostUsd !== null) {
265 const sum = bucket.categoryCostUsd;
266 const add = priced.categoryCostUsd;
267 bucket.categoryCostUsd =
268 sum === null
269 ? add
270 : {
271 input: sum.input + add.input,
272 cacheRead: sum.cacheRead + add.cacheRead,
273 cacheWrite: sum.cacheWrite + add.cacheWrite,
274 output: sum.output + add.output,
275 };
276 }
277 if (record.speed === "fast") bucket.fastCostUsd += priced.costUsd;
278 if (record.speed === "ultrafast") bucket.ultrafastCostUsd += priced.costUsd;
279 bucket.speedPremiumUsd += priced.speedPremiumUsd;
280 bucket.cacheSavingsUsd += cacheSavingsUsd(
281 this.#options.rates,
282 record,
283 this.#options.priceOverrides,
284 );
285 bucket.records += 1;
286 if (priced.costSource === "unpriced") bucket.unpricedRecords += 1;
287 if (priced.costSource === "providerReported") bucket.providerReportedRecords += 1;
288 }
289​
290 // Aliases use the target's rate, replacing provider-specific rateModel.
291 #mapModel(record: UsageRecord): UsageRecord {
292 const model = this.#options.modelAliases?.get(record.model);
293 if (model === undefined) return record;
294 const { rateModel: _rateModel, ...rest } = record;
295 return { ...rest, model };
296 }
297​
298 // Time-ordered records usually reuse the previous bucket; avoid rebuilding its key.
299 #bucketFor(
300 day: string,
301 hourIndex: number,
302 provider: string,
303 model: string,
304 source: string,
305 ): MutableBucket {
306 const last = this.#lastBucket;
307 if (
308 last !== null &&
309 last.day === day &&
310 last.hourIndex === hourIndex &&
311 last.provider === provider &&
312 last.model === model &&
313 last.source === source
314 ) {
315 return last.bucket;
316 }
317 const window = this.#hourlyWindow;
318 const hourStart =
319 window === null ? "" : new Date(window.sinceTimeMs + hourIndex * HOUR_MS).toISOString();
320 const key = `${day}\u0000${hourStart}\u0000${provider}\u0000${model}\u0000${source}`;
321 let bucket = this.#buckets.get(key);
322 if (bucket === undefined) {
323 bucket = {
324 totals: { ...EMPTY_TOTALS },
325 costUsd: 0,
326 cacheSavingsUsd: 0,
327 categoryCostUsd: null,
328 fastCostUsd: 0,
329 ultrafastCostUsd: 0,
330 speedPremiumUsd: 0,
331 records: 0,
332 unpricedRecords: 0,
333 providerReportedRecords: 0,
334 sessions: new Set<string>(),
335 };
336 this.#buckets.set(key, bucket);
337 }
338 this.#lastBucket = { day, hourIndex, provider, model, source, bucket };
339 return bucket;
340 }
341​
342 finish(): AggregateResult {
343 for (const { record, bucket } of this.#seen.values()) {
344 if (bucket !== null) this.#accumulate(bucket, record);
345 }
346 this.#seen.clear();
347 const buckets: UsageBucket[] = [];
348 for (const [key, bucket] of this.#buckets) {
349 const [day = "", hourStart = "", provider = "", model = "", sourcePath = ""] =
350 key.split("\u0000");
351 const category = bucket.categoryCostUsd;
352 const fastCostUsd = roundUsd(bucket.fastCostUsd);
353 const ultrafastCostUsd = roundUsd(bucket.ultrafastCostUsd);
354 const speedPremiumUsd = roundUsd(bucket.speedPremiumUsd);
355 buckets.push({
356 day: day as UsageDay,
357 ...(hourStart === "" ? {} : { hourStart }),
358 provider: provider as UsageBucket["provider"],
359 model,
360 ...(sourcePath === "" ? {} : { sourcePath }),
361 totals: { ...bucket.totals },
362 costUsd: bucket.costUsd,
363 cacheSavingsUsd: bucket.cacheSavingsUsd,
364 ...(category === null
365 ? {}
366 : {
367 categoryCostUsd: {
368 input: roundUsd(category.input),
369 cacheRead: roundUsd(category.cacheRead),
370 cacheWrite: roundUsd(category.cacheWrite),
371 output: roundUsd(category.output),
372 },
373 }),
374 ...(fastCostUsd === 0 ? {} : { fastCostUsd }),
375 ...(ultrafastCostUsd === 0 ? {} : { ultrafastCostUsd }),
376 ...(speedPremiumUsd === 0 ? {} : { speedPremiumUsd }),
377 costSource: resolveCostSource(bucket),
378 records: bucket.records,
379 unpricedRecords: bucket.unpricedRecords,
380 sessions: bucket.sessions.size,
381 });
382 }
383 buckets.sort(
384 (a, b) =>
385 a.day.localeCompare(b.day) ||
386 (a.hourStart ?? "").localeCompare(b.hourStart ?? "") ||
387 a.provider.localeCompare(b.provider) ||
388 a.model.localeCompare(b.model),
389 );
390​
391 return {
392 buckets,
393 duplicatesDropped: this.#duplicatesDropped,
394 outOfWindow: this.#outOfWindow,
395 };
396 }
398​
399function roundUsd(value: number): number {
400 return Math.round(value * 1e6) / 1e6;
402​
403function resolveCostSource(bucket: MutableBucket): UsageBucket["costSource"] {
404 if (bucket.unpricedRecords === bucket.records) return "unpriced";
405 if (bucket.providerReportedRecords === bucket.records) return "providerReported";
406 return "modelPriced";