@trazum/core 2.7.2 → 2.7.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/dist/anthropic-usage.d.ts +66 -1
  2. package/dist/anthropic-usage.d.ts.map +1 -1
  3. package/dist/anthropic-usage.js +114 -3
  4. package/dist/anthropic-usage.js.map +1 -1
  5. package/dist/batch-results.d.ts +77 -0
  6. package/dist/batch-results.d.ts.map +1 -0
  7. package/dist/batch-results.js +145 -0
  8. package/dist/batch-results.js.map +1 -0
  9. package/dist/billing.d.ts.map +1 -1
  10. package/dist/billing.js +2 -0
  11. package/dist/billing.js.map +1 -1
  12. package/dist/claude-code.d.ts +2 -0
  13. package/dist/claude-code.d.ts.map +1 -1
  14. package/dist/claude-code.js +9 -0
  15. package/dist/claude-code.js.map +1 -1
  16. package/dist/connector.d.ts +3 -1
  17. package/dist/connector.d.ts.map +1 -1
  18. package/dist/connector.js +72 -5
  19. package/dist/connector.js.map +1 -1
  20. package/dist/gateway.d.ts +10 -0
  21. package/dist/gateway.d.ts.map +1 -1
  22. package/dist/gateway.js +7 -1
  23. package/dist/gateway.js.map +1 -1
  24. package/dist/index.d.ts +3 -1
  25. package/dist/index.d.ts.map +1 -1
  26. package/dist/index.js +2 -1
  27. package/dist/index.js.map +1 -1
  28. package/dist/openai-usage.d.ts +43 -7
  29. package/dist/openai-usage.d.ts.map +1 -1
  30. package/dist/openai-usage.js +63 -11
  31. package/dist/openai-usage.js.map +1 -1
  32. package/dist/pricing-overlay.d.ts +1 -1
  33. package/dist/pricing-overlay.d.ts.map +1 -1
  34. package/dist/pricing-overlay.js +21 -0
  35. package/dist/pricing-overlay.js.map +1 -1
  36. package/dist/pricing.d.ts +24 -1
  37. package/dist/pricing.d.ts.map +1 -1
  38. package/dist/pricing.js +87 -0
  39. package/dist/pricing.js.map +1 -1
  40. package/dist/store.d.ts +4 -0
  41. package/dist/store.d.ts.map +1 -1
  42. package/dist/store.js +22 -1
  43. package/dist/store.js.map +1 -1
  44. package/dist/types.d.ts +17 -0
  45. package/dist/types.d.ts.map +1 -1
  46. package/dist/usage.d.ts +16 -0
  47. package/dist/usage.d.ts.map +1 -1
  48. package/dist/usage.js +16 -0
  49. package/dist/usage.js.map +1 -1
  50. package/package.json +1 -1
  51. package/src/anthropic-usage.ts +163 -5
  52. package/src/batch-results.ts +174 -0
  53. package/src/billing.ts +2 -0
  54. package/src/claude-code.ts +11 -0
  55. package/src/connector.ts +76 -6
  56. package/src/gateway.ts +16 -2
  57. package/src/index.ts +3 -0
  58. package/src/openai-usage.ts +95 -14
  59. package/src/pricing-overlay.ts +21 -0
  60. package/src/pricing.ts +105 -1
  61. package/src/store.ts +24 -3
  62. package/src/types.ts +18 -0
  63. package/src/usage.ts +32 -0
@@ -0,0 +1,174 @@
1
+ /**
2
+ * A provider's Batch API results file, read as a usage log.
3
+ *
4
+ * Both providers return a batch's results as JSON Lines, one per request, and
5
+ * bill every one that ran at half the standard price. Neither shape is a usage
6
+ * line: the model and usage sit one or two objects down, so `parseUsageLine`
7
+ * read a whole results file as nothing at all. This converter takes each line
8
+ * that was billed, keeps its model, usage and end reason, marks it `batch`, and
9
+ * drops everything else, the generated text first among it.
10
+ *
11
+ * ## The two shapes, each from its provider's own page
12
+ *
13
+ * **Anthropic** (platform.claude.com/docs/en/build-with-claude/batch-processing,
14
+ * read 2026-11-05): `{"custom_id", "result": {"type", "message"}}`. `type` is
15
+ * `succeeded`, `errored`, `canceled` or `expired`, and the page says of the
16
+ * last three "You will not be billed for these requests". A succeeded result's
17
+ * `message` is a Messages response, `usage` and all.
18
+ *
19
+ * **OpenAI** (developers.openai.com/api/docs/guides/batch, read 2026-11-05):
20
+ * `{"id", "custom_id", "response": {"status_code", "request_id", "body"},
21
+ * "error"}`. `body` is the endpoint's own response, a Responses or Chat
22
+ * Completions object. An expired request is written with `"response": null`
23
+ * and an `error`; the page says "You will be charged for tokens consumed from
24
+ * any completed requests", so a line is billed only when it carries a 200 and
25
+ * a body with usage.
26
+ *
27
+ * ## What it does not invent
28
+ *
29
+ * **No time.** An Anthropic result carries none; it is counted as undated, the
30
+ * way `bill` already names an undated call, rather than stamped with the day
31
+ * the file was read. An OpenAI body's `created` is Unix seconds and is kept.
32
+ *
33
+ * **No price.** The record says `batch: true` and the model; the batch ratio is
34
+ * the catalogue's, applied where every other call is priced.
35
+ *
36
+ * **No content.** The message's `content`, the body's `output` and `choices`,
37
+ * the `custom_id` (which a caller may have filled with anything) and every id
38
+ * are dropped. A test plants a marker in each and greps the output.
39
+ */
40
+
41
+ /** One converted record, in the shape `parseUsageLine` reads. */
42
+ export interface BatchResultRecord {
43
+ model: string;
44
+ ts?: string;
45
+ label?: string;
46
+ /** Always true: every line here ran on the Batch API. */
47
+ batch: true;
48
+ stop_reason?: string;
49
+ usage: Record<string, unknown>;
50
+ }
51
+
52
+ export interface BatchResultConversion {
53
+ records: BatchResultRecord[];
54
+ /** Which provider's shape the file was, or null when no line was either. */
55
+ provider: 'anthropic' | 'openai' | null;
56
+ /** Non-blank lines read. */
57
+ lines: number;
58
+ /** Results the provider says it did not bill: errored, canceled, expired, or not a 200. */
59
+ notBilled: number;
60
+ /** Billed results with no model or usage to price them by. */
61
+ unpriceable: number;
62
+ /** Lines that were not JSON, or neither shape. */
63
+ unparseable: number;
64
+ }
65
+
66
+ const asObject = (value: unknown): Record<string, unknown> | null =>
67
+ typeof value === 'object' && value !== null && !Array.isArray(value)
68
+ ? (value as Record<string, unknown>)
69
+ : null;
70
+
71
+ /** Usage as the response gave it, minus nothing it bills by and plus nothing. */
72
+ const usageOf = (value: unknown): Record<string, unknown> | null => asObject(value);
73
+
74
+ /**
75
+ * @param label the project these results belong to, chosen by the operator.
76
+ */
77
+ export function batchResultRecords(text: string, options: { label?: string } = {}): BatchResultConversion {
78
+ const records: BatchResultRecord[] = [];
79
+ let provider: BatchResultConversion['provider'] = null;
80
+ let lines = 0;
81
+ let notBilled = 0;
82
+ let unpriceable = 0;
83
+ let unparseable = 0;
84
+
85
+ for (const raw of text.split('\n')) {
86
+ if (raw.trim() === '') continue;
87
+ lines += 1;
88
+ let parsed: unknown;
89
+ try {
90
+ parsed = JSON.parse(raw);
91
+ } catch {
92
+ unparseable += 1;
93
+ continue;
94
+ }
95
+ const line = asObject(parsed);
96
+ if (line === null || typeof line.custom_id !== 'string') {
97
+ unparseable += 1;
98
+ continue;
99
+ }
100
+
101
+ const result = asObject(line.result);
102
+ if (result !== null && typeof result.type === 'string') {
103
+ provider ??= 'anthropic';
104
+ if (result.type !== 'succeeded') {
105
+ notBilled += 1;
106
+ continue;
107
+ }
108
+ const message = asObject(result.message);
109
+ const usage = usageOf(message?.usage);
110
+ if (message === null || typeof message.model !== 'string' || usage === null) {
111
+ unpriceable += 1;
112
+ continue;
113
+ }
114
+ records.push({
115
+ model: message.model,
116
+ ...(options.label === undefined ? {} : { label: options.label }),
117
+ batch: true,
118
+ ...(typeof message.stop_reason === 'string' ? { stop_reason: message.stop_reason } : {}),
119
+ usage,
120
+ });
121
+ continue;
122
+ }
123
+
124
+ if ('response' in line) {
125
+ provider ??= 'openai';
126
+ const response = asObject(line.response);
127
+ if (response === null || response.status_code !== 200) {
128
+ notBilled += 1;
129
+ continue;
130
+ }
131
+ const body = asObject(response.body);
132
+ const usage = usageOf(body?.usage);
133
+ if (body === null || typeof body.model !== 'string' || usage === null) {
134
+ unpriceable += 1;
135
+ continue;
136
+ }
137
+ const created =
138
+ typeof body.created_at === 'number' ? body.created_at : typeof body.created === 'number' ? body.created : null;
139
+ records.push({
140
+ model: body.model,
141
+ ...(created !== null && Number.isFinite(created) ? { ts: new Date(created * 1000).toISOString() } : {}),
142
+ ...(options.label === undefined ? {} : { label: options.label }),
143
+ batch: true,
144
+ usage,
145
+ });
146
+ continue;
147
+ }
148
+
149
+ unparseable += 1;
150
+ }
151
+
152
+ return { records, provider, lines, notBilled, unpriceable, unparseable };
153
+ }
154
+
155
+ /**
156
+ * Whether this text is a Batch API results file.
157
+ *
158
+ * Every line carries a `custom_id`, which no other log here does, beside
159
+ * either Anthropic's `result` with a `type` or OpenAI's `response` with a
160
+ * `status_code`. The first line decides; one that is neither is not this.
161
+ */
162
+ export function looksLikeBatchResults(text: string, prefixBytes = 8192): boolean {
163
+ const first = text.slice(0, prefixBytes).split('\n').find((line) => line.trim() !== '');
164
+ if (first === undefined || !first.includes('"custom_id"')) return false;
165
+ try {
166
+ const line = asObject(JSON.parse(first));
167
+ if (line === null || typeof line.custom_id !== 'string') return false;
168
+ const result = asObject(line.result);
169
+ if (result !== null && typeof result.type === 'string') return true;
170
+ return 'response' in line && ('error' in line || asObject(line.response)?.status_code !== undefined);
171
+ } catch {
172
+ return false;
173
+ }
174
+ }
package/src/billing.ts CHANGED
@@ -36,6 +36,8 @@ export function promptSizeOf(record: UsageRecord): PromptSize {
36
36
  const how = {
37
37
  ...(record.speed === undefined ? {} : { speed: record.speed }),
38
38
  ...(record.serviceTier === undefined ? {} : { serviceTier: record.serviceTier }),
39
+ ...(record.inferenceGeo === undefined ? {} : { inferenceGeo: record.inferenceGeo }),
40
+ ...(record.batch === true ? { batch: true } : {}),
39
41
  };
40
42
  return record.requests === undefined ? { inputTokens: prompt, ...how } : { inputTokensAtMost: prompt, ...how };
41
43
  }
@@ -76,6 +76,8 @@ export interface ClaudeCodeRecord {
76
76
  cache_creation?: { ephemeral_5m_input_tokens?: number; ephemeral_1h_input_tokens?: number };
77
77
  /** The response's `usage.speed`, kept because fast mode bills at a multiple of standard. */
78
78
  speed?: string;
79
+ /** The response's `usage.inference_geo`, kept because US-only inference bills 1.1x on Claude 4.6 and later. */
80
+ inference_geo?: string;
79
81
  };
80
82
  }
81
83
 
@@ -280,6 +282,15 @@ export function claudeCodeRecords(
280
282
  * priced every fast call at the standard rate: half its cost.
281
283
  */
282
284
  ...(typeof usage.speed === 'string' && usage.speed !== '' ? { speed: usage.speed } : {}),
285
+ /*
286
+ * And the geography that ran: US-only inference bills 1.1x on Claude
287
+ * 4.6 and later, on every token category. Every Claude Code line
288
+ * carries it, "global" or "not_available" unless the workspace pins
289
+ * "us"; dropping it priced every US-only call at a tenth under its cost.
290
+ */
291
+ ...(typeof usage.inference_geo === 'string' && usage.inference_geo !== ''
292
+ ? { inference_geo: usage.inference_geo }
293
+ : {}),
283
294
  },
284
295
  };
285
296
 
package/src/connector.ts CHANGED
@@ -28,7 +28,7 @@
28
28
  * recorded is not not-happened, at the level of the type system.
29
29
  */
30
30
 
31
- import { effectivePricing, multipliersFor } from './pricing.js';
31
+ import { effectivePricing, multipliersFor, serviceTierOf } from './pricing.js';
32
32
  import type { PricingCatalogue } from './pricing.js';
33
33
 
34
34
  // --------------------------------------------------------------------------
@@ -196,7 +196,9 @@ export interface PullGap {
196
196
  | 'cursor-expired'
197
197
  | 'page-limit'
198
198
  | 'unreadable-entry'
199
- | 'unreadable-field';
199
+ | 'unreadable-field'
200
+ /** Usage at a tier no catalogue rate prices, left out and named. */
201
+ | 'unpriced-tier';
200
202
  detail: string;
201
203
  }
202
204
 
@@ -318,7 +320,7 @@ export function normalizeAnthropicUsage(payload: unknown): ConnectorPull {
318
320
  cacheWrite1hTokens: ttlKnown ? write1h : 0,
319
321
  writeTtlKnown: ttlKnown,
320
322
  outputTokens: num(r.output_tokens) ?? 0,
321
- group: groupOf(r, ['workspace_id', 'api_key_id', 'service_tier', 'context_window']),
323
+ group: groupOf(r, ['workspace_id', 'api_key_id', 'service_tier', 'context_window', 'speed', 'inference_geo']),
322
324
  });
323
325
  }
324
326
  }
@@ -398,7 +400,7 @@ export function normalizeOpenAIUsage(payload: unknown): ConnectorPull {
398
400
  // states (`cacheTtl`), and an absent field is not an assumed TTL.
399
401
  writeTtlKnown: true,
400
402
  outputTokens: num(r.output_tokens) ?? 0,
401
- group: groupOf(r, ['project_id', 'api_key_id', 'batch']),
403
+ group: groupOf(r, ['project_id', 'api_key_id', 'batch', 'service_tier']),
402
404
  });
403
405
  }
404
406
  }
@@ -508,6 +510,17 @@ export function bucketedProfile(
508
510
  const slices = new Map<string, BucketedSlice>();
509
511
  const days = new Map<string, { usd: number; calls: number | null }>();
510
512
  const unpriced = new Map<string, { inputTokens: number; outputTokens: number }>();
513
+ /* Usage at a tier no rate here prices, summed per model and tier so the gap names both. */
514
+ const leftOut = new Map<string, { model: string; tier: string; buckets: number; tokens: number }>();
515
+ const leave = (bucket: UsageBucket, tier: string): void => {
516
+ const key = `${bucket.model}\n${tier}`;
517
+ const seen = leftOut.get(key) ?? { model: bucket.model, tier, buckets: 0, tokens: 0 };
518
+ seen.buckets += 1;
519
+ seen.tokens +=
520
+ bucket.inputTokens + bucket.cacheReadTokens + bucket.cacheWrite5mTokens + bucket.cacheWrite1hTokens
521
+ + bucket.outputTokens;
522
+ leftOut.set(key, seen);
523
+ };
511
524
 
512
525
  for (const bucket of pull.buckets) {
513
526
  const model = catalogue.byId.get(bucket.model);
@@ -519,6 +532,53 @@ export function bucketedProfile(
519
532
  continue;
520
533
  }
521
534
 
535
+ /*
536
+ * What the row says about how its tokens ran, where that changes the
537
+ * price. A tier a catalogue rate is the rate for is priced from it; any
538
+ * other is left out and named, never priced at the standard rate. The
539
+ * groupings are the ones `trazum connect` asks for; a payload without
540
+ * them reads as standard, as it always did.
541
+ */
542
+ const group = bucket.group;
543
+ const how: { speed?: string; serviceTier?: string; inferenceGeo?: string; batch?: boolean } = {};
544
+ /* The Batch API at the row's batch ratio, where the row has one. */
545
+ const batchRate = multipliersFor(model).batch !== null;
546
+ if (pull.provider === 'anthropic') {
547
+ const tier = group.service_tier;
548
+ if (tier === 'batch' && batchRate) {
549
+ how.batch = true;
550
+ } else if (tier !== undefined && tier !== 'standard') {
551
+ leave(bucket, tier);
552
+ continue;
553
+ }
554
+ if (group.speed === 'fast') {
555
+ const fastRate = model.tiers?.some((t) => t.when.kind === 'speed' && t.when.speed === 'fast') ?? false;
556
+ if (!fastRate) {
557
+ leave(bucket, 'fast mode');
558
+ continue;
559
+ }
560
+ how.speed = 'fast';
561
+ }
562
+ if (group.inference_geo !== undefined) how.inferenceGeo = group.inference_geo;
563
+ } else if (pull.provider === 'openai') {
564
+ if (group.batch === 'true') {
565
+ if (!batchRate) {
566
+ leave(bucket, 'batch');
567
+ continue;
568
+ }
569
+ how.batch = true;
570
+ }
571
+ const tier = group.service_tier;
572
+ if (tier !== undefined && tier !== 'default' && !(how.batch === true && tier === 'batch')) {
573
+ const named = serviceTierOf(tier);
574
+ if (named === undefined || model.serviceTiers?.[named] === undefined) {
575
+ leave(bucket, tier);
576
+ continue;
577
+ }
578
+ how.serviceTier = tier;
579
+ }
580
+ }
581
+
522
582
  const at = new Date(bucket.fromMs);
523
583
  /*
524
584
  * A bucket of exactly one request says that request's prompt; any other
@@ -529,7 +589,7 @@ export function bucketedProfile(
529
589
  const priced = effectivePricing(
530
590
  model,
531
591
  at,
532
- bucket.calls === 1 ? { inputTokens: prompt } : { inputTokensAtMost: prompt },
592
+ bucket.calls === 1 ? { inputTokens: prompt, ...how } : { inputTokensAtMost: prompt, ...how },
533
593
  );
534
594
  const { inputPerMTok, outputPerMTok } = priced;
535
595
  const rates = multipliersFor(model, at);
@@ -623,7 +683,17 @@ export function bucketedProfile(
623
683
  unpricedModels: [...unpriced.entries()]
624
684
  .map(([model, tokens]) => ({ model, ...tokens }))
625
685
  .sort((a, b) => b.inputTokens + b.outputTokens - (a.inputTokens + a.outputTokens)),
626
- gaps: pull.gaps,
686
+ gaps: [
687
+ ...pull.gaps,
688
+ ...[...leftOut.values()].map(
689
+ (left): PullGap => ({
690
+ kind: 'unpriced-tier',
691
+ detail:
692
+ `${left.buckets} row(s) of ${left.model} ran at ${left.tier}, which no catalogue rate here is the rate for, `
693
+ + `and ${left.tokens.toLocaleString('en-US')} token(s) were left out rather than priced at the standard rate`,
694
+ }),
695
+ ),
696
+ ],
627
697
  unavailable: pull.unavailable,
628
698
  };
629
699
  }
package/src/gateway.ts CHANGED
@@ -101,6 +101,14 @@ export interface GatewayCall {
101
101
  * `"fast"` at up to twice, `"ultrafast"`. A setting, not content.
102
102
  */
103
103
  serviceTier?: string | null;
104
+ /**
105
+ * The geography the request pinned, when it named one: Anthropic's
106
+ * `inference_geo: "us"`, billed at 1.1x on Claude 4.6 and later. A setting,
107
+ * not content. A request that names none may still run in the workspace's
108
+ * default geography; the response says which ran, and the spend is
109
+ * recorded from that.
110
+ */
111
+ inferenceGeo?: string | null;
104
112
  }
105
113
 
106
114
  /** Where the budget stands, as the gateway was told at the last refresh. */
@@ -222,10 +230,11 @@ export interface GatewayOptions {
222
230
  waivers?: readonly WaiveEntry[];
223
231
  }
224
232
 
225
- /** How the call asked to be run, where that changes its price: speed and service tier. */
226
- const speedOf = (call: GatewayCall): { speed?: string; serviceTier?: string } => ({
233
+ /** How the call asked to be run, where that changes its price: speed, service tier and geography. */
234
+ const speedOf = (call: GatewayCall): { speed?: string; serviceTier?: string; inferenceGeo?: string } => ({
227
235
  ...(typeof call.speed === 'string' && call.speed !== '' ? { speed: call.speed } : {}),
228
236
  ...(typeof call.serviceTier === 'string' && call.serviceTier !== '' ? { serviceTier: call.serviceTier } : {}),
237
+ ...(typeof call.inferenceGeo === 'string' && call.inferenceGeo !== '' ? { inferenceGeo: call.inferenceGeo } : {}),
229
238
  });
230
239
 
231
240
  /** What this call costs at a model's rates, or null when it cannot be priced. */
@@ -512,6 +521,8 @@ export interface GatewayUsage {
512
521
  speed?: string;
513
522
  /** OpenAI's `service_tier`, the tier that actually answered: each has its own table. */
514
523
  serviceTier?: string;
524
+ /** Anthropic's `usage.inference_geo`, the geography that ran: "us" bills 1.1x on Claude 4.6 and later. */
525
+ inferenceGeo?: string;
515
526
  }
516
527
 
517
528
  /**
@@ -681,6 +692,7 @@ export function streamingUsageReader(
681
692
  // that ends before any delta still reports what it reported.
682
693
  usage.outputTokens = num(start.output_tokens);
683
694
  if (typeof start.speed === 'string' && start.speed !== '') usage.speed = start.speed;
695
+ if (typeof start.inference_geo === 'string' && start.inference_geo !== '') usage.inferenceGeo = start.inference_geo;
684
696
  seen = true;
685
697
  }
686
698
  }
@@ -698,6 +710,7 @@ export function streamingUsageReader(
698
710
  if (typeof d.output_tokens === 'number') usage.outputTokens = num(d.output_tokens);
699
711
  if (typeof d.input_tokens === 'number') usage.inputTokens = num(d.input_tokens);
700
712
  if (typeof d.speed === 'string' && d.speed !== '') usage.speed = d.speed;
713
+ if (typeof d.inference_geo === 'string' && d.inference_geo !== '') usage.inferenceGeo = d.inference_geo;
701
714
  seen = true;
702
715
  }
703
716
  return;
@@ -800,6 +813,7 @@ export function usageFromResponse(
800
813
  cacheWriteTokens: num(u.cache_creation_input_tokens),
801
814
  ...cacheWriteBreakdown(u),
802
815
  ...(typeof u.speed === 'string' && u.speed !== '' ? { speed: u.speed } : {}),
816
+ ...(typeof u.inference_geo === 'string' && u.inference_geo !== '' ? { inferenceGeo: u.inference_geo } : {}),
803
817
  };
804
818
  }
805
819
  if (shape === 'openai') {
package/src/index.ts CHANGED
@@ -242,6 +242,8 @@ export type { AnthropicCostReading, BilledReading, Reconciliation } from './anth
242
242
  export { openaiCostReport, looksLikeOpenaiCost } from './openai-cost.js';
243
243
  export type { OpenaiCostReading } from './openai-cost.js';
244
244
  export { openaiUsageRecords, looksLikeOpenaiUsage } from './openai-usage.js';
245
+ export { batchResultRecords, looksLikeBatchResults } from './batch-results.js';
246
+ export type { BatchResultConversion, BatchResultRecord } from './batch-results.js';
245
247
  export { openrouterActivityRecords, looksLikeOpenrouterActivity } from './openrouter-activity.js';
246
248
  export type {
247
249
  OpenrouterActivityConversion,
@@ -444,6 +446,7 @@ export {
444
446
  multipliersFor,
445
447
  isOffered,
446
448
  serviceTierOf,
449
+ inferenceGeoOf,
447
450
  } from './pricing.js';
448
451
  export type { PricingCatalogue, PromptSize } from './pricing.js';
449
452
  export type { CachingMode, Capability, CostMultipliers } from './types.js';
@@ -51,11 +51,21 @@
51
51
  * conversion says the question was not asked, because the alternative is a
52
52
  * reader assuming it was answered.
53
53
  *
54
- * **A service tier that is not `default`.** The schema does not enumerate
55
- * the values, so this does not either: any string but `default` is left out,
56
- * counted, and *named* in the conversion, so the operator sees `flex` or
57
- * `priority` or whatever the report said rather than a number. Refusing
58
- * by name is the honest version of not knowing the list.
54
+ * **A service tier with no table of its own.** OpenAI sells Flex, Fast
55
+ * (Priority until 2026-07-30) and Ultrafast from tables of their own, and the
56
+ * catalogue writes each model's row of each one out in `serviceTiers`. A row
57
+ * at one of those tiers, on a model whose catalogue row has that tier's table,
58
+ * is carried into the record as `service_tier` and priced from that table,
59
+ * exactly as a logged response naming the same tier is: the published rate
60
+ * for the tier that ran, not a multiple of another.
61
+ *
62
+ * Anything else is still left out, counted, and *named*: a tier the
63
+ * catalogue has no table for on that model (GPT-4o has no Flex), and any
64
+ * value `serviceTierOf` does not know, because the schema does not enumerate
65
+ * the tiers and so this does not either. Pricing such a row at the standard
66
+ * rate would put a Flex bill at twice its cost and look right doing it; the
67
+ * operator sees `flex` or `scale` or whatever the report said, never a
68
+ * number standing in for it.
59
69
  *
60
70
  * **Audio and image tokens.** `input_tokens` folds text, audio and image
61
71
  * tokens together, and a text rate is not the rate for the other two. A row
@@ -84,6 +94,9 @@
84
94
  * absence and no second reading to derive.
85
95
  */
86
96
 
97
+ import { BUNDLED_CATALOGUE, multipliersFor, serviceTierOf } from './pricing.js';
98
+ import type { PricingCatalogue } from './pricing.js';
99
+
87
100
  /** One project, and the label the operator gives it. Matched exactly. */
88
101
  export interface ProjectLabel {
89
102
  project: string;
@@ -101,6 +114,15 @@ export interface OpenaiUsageRecord {
101
114
  * request, which is then a call like any other. See `UsageRecord.requests`.
102
115
  */
103
116
  requests?: number | null;
117
+ /**
118
+ * The report's own tier, as it spelled it, when it is one the catalogue
119
+ * prices this model from: `parseUsageLine` reads it as a response's
120
+ * `service_tier` and the call is priced from that tier's table. Absent for
121
+ * the default tier.
122
+ */
123
+ service_tier?: string;
124
+ /** True when the row ran on the Batch API: billed at the row's batch ratio. */
125
+ batch?: true;
104
126
  usage: {
105
127
  prompt_tokens: number;
106
128
  completion_tokens: number;
@@ -123,14 +145,24 @@ export interface OpenaiUsageConversion {
123
145
  requests: number;
124
146
  /** Results with `model: null`, which nothing can price. */
125
147
  unnamedModel: number;
126
- /** Results with `batch: true`, billed at a discount no catalogue rate is. */
148
+ /** Results with `batch: true` on a model with no batch rate, left out. */
127
149
  batch: number;
150
+ /** Results with `batch: true` that became records priced at the row's batch ratio. */
151
+ batchRows: number;
128
152
  /** Whether any result said whether it was batch at all. */
129
153
  batchNamed: boolean;
130
- /** Results at a service tier other than `default`, left out. */
154
+ /**
155
+ * Results at a service tier other than `default` that no table prices, left
156
+ * out: a tier the model's catalogue row has no table for, or a value
157
+ * `serviceTierOf` does not know.
158
+ */
131
159
  nonDefaultTier: number;
132
160
  /** The tiers those results named, so the refusal has a name. */
133
161
  tiersRefused: string[];
162
+ /** Results at Flex, Fast or Ultrafast that became records priced from that tier's own table. */
163
+ serviceTierRows: number;
164
+ /** The tiers those results named, as the report spelled them. */
165
+ tiersPriced: string[];
134
166
  /** Whether any result named a tier at all. */
135
167
  tierNamed: boolean;
136
168
  /** Results that carried audio or image tokens and were reduced to text. */
@@ -183,7 +215,16 @@ const NON_TEXT = [
183
215
  */
184
216
  export function openaiUsageRecords(
185
217
  text: string,
186
- options: { label?: string; labelByProject?: readonly ProjectLabel[] } = {},
218
+ options: {
219
+ label?: string;
220
+ labelByProject?: readonly ProjectLabel[];
221
+ /**
222
+ * Where a tier's table is looked for. The bundled catalogue unless a
223
+ * caller prices with another; a row whose model this catalogue has no
224
+ * table for at that tier is refused, never priced at the standard rate.
225
+ */
226
+ catalogue?: PricingCatalogue;
227
+ } = {},
187
228
  ): OpenaiUsageConversion {
188
229
  const empty: OpenaiUsageConversion = {
189
230
  records: [],
@@ -192,9 +233,12 @@ export function openaiUsageRecords(
192
233
  requests: 0,
193
234
  unnamedModel: 0,
194
235
  batch: 0,
236
+ batchRows: 0,
195
237
  batchNamed: false,
196
238
  nonDefaultTier: 0,
197
239
  tiersRefused: [],
240
+ serviceTierRows: 0,
241
+ tiersPriced: [],
198
242
  tierNamed: false,
199
243
  mixedRows: 0,
200
244
  nonTextTokens: 0,
@@ -219,14 +263,18 @@ export function openaiUsageRecords(
219
263
 
220
264
  const rules = options.labelByProject;
221
265
  const records: OpenaiUsageRecord[] = [];
266
+ const catalogue = options.catalogue ?? BUNDLED_CATALOGUE;
222
267
  const tiersRefused = new Set<string>();
268
+ const tiersPriced = new Set<string>();
223
269
  let buckets = 0;
224
270
  let rows = 0;
225
271
  let requests = 0;
226
272
  let unnamedModel = 0;
227
273
  let batch = 0;
228
274
  let batchNamed = false;
275
+ let batchRows = 0;
229
276
  let nonDefaultTier = 0;
277
+ let serviceTierRows = 0;
230
278
  let tierNamed = false;
231
279
  let mixedRows = 0;
232
280
  let nonTextTokens = 0;
@@ -253,20 +301,43 @@ export function openaiUsageRecords(
253
301
  if (result === null) continue;
254
302
  requests += count(result.num_model_requests);
255
303
 
304
+ /*
305
+ A batch job is billed at the row's batch ratio, half the standard rate,
306
+ which the pricing page publishes as its own table and `price-drift.mjs`
307
+ checks weekly. A batch row on a model with no batch rate is left out.
308
+ */
309
+ let batchRow = false;
256
310
  if (typeof result.batch === 'boolean') {
257
311
  batchNamed = true;
258
312
  if (result.batch) {
259
- batch += 1;
260
- continue;
313
+ const row = typeof result.model === 'string' ? catalogue.byId.get(result.model) : undefined;
314
+ if (row === undefined || multipliersFor(row).batch === null) {
315
+ batch += 1;
316
+ continue;
317
+ }
318
+ batchRow = true;
261
319
  }
262
320
  }
263
321
 
322
+ let serviceTier: string | undefined;
264
323
  if (typeof result.service_tier === 'string') {
265
324
  tierNamed = true;
266
- if (result.service_tier !== 'default') {
267
- nonDefaultTier += 1;
268
- tiersRefused.add(result.service_tier);
269
- continue;
325
+ if (result.service_tier !== 'default' && !(batchRow && result.service_tier === 'batch')) {
326
+ /*
327
+ Priced only from a table that exists for this model at this tier.
328
+ The response path falls back to the standard rate for a tier with
329
+ no table, because a response is one call the provider really ran;
330
+ a report row is the sum of many, and a Flex row priced at the
331
+ standard rate is twice its cost.
332
+ */
333
+ const named = serviceTierOf(result.service_tier);
334
+ const row = typeof result.model === 'string' ? catalogue.byId.get(result.model) : undefined;
335
+ if (named === undefined || row?.serviceTiers?.[named] === undefined) {
336
+ nonDefaultTier += 1;
337
+ tiersRefused.add(result.service_tier);
338
+ continue;
339
+ }
340
+ serviceTier = result.service_tier;
270
341
  }
271
342
  }
272
343
 
@@ -334,6 +405,8 @@ export function openaiUsageRecords(
334
405
  ts,
335
406
  ...(label === undefined ? {} : { label }),
336
407
  ...requestsField(result.num_model_requests),
408
+ ...(serviceTier === undefined ? {} : { service_tier: serviceTier }),
409
+ ...(batchRow ? { batch: true as const } : {}),
337
410
  usage: {
338
411
  prompt_tokens: prompt,
339
412
  completion_tokens: completion,
@@ -348,6 +421,11 @@ export function openaiUsageRecords(
348
421
  },
349
422
  });
350
423
  rows += 1;
424
+ if (batchRow) batchRows += 1;
425
+ if (serviceTier !== undefined) {
426
+ serviceTierRows += 1;
427
+ tiersPriced.add(serviceTier);
428
+ }
351
429
  }
352
430
  }
353
431
 
@@ -359,8 +437,11 @@ export function openaiUsageRecords(
359
437
  unnamedModel,
360
438
  batch,
361
439
  batchNamed,
440
+ batchRows,
362
441
  nonDefaultTier,
363
442
  tiersRefused: [...tiersRefused],
443
+ serviceTierRows,
444
+ tiersPriced: [...tiersPriced],
364
445
  tierNamed,
365
446
  mixedRows,
366
447
  nonTextTokens,
@@ -35,8 +35,12 @@ export const PRICING_MODEL_KEYS = [
35
35
  'notes',
36
36
  'promo',
37
37
  'multipliers',
38
+ 'inferenceGeoMultipliers',
38
39
  ] as const;
39
40
 
41
+ /** The geographies a provider prices differently, as `InferenceGeo` names them. */
42
+ const INFERENCE_GEO_KEYS = ['us'] as const;
43
+
40
44
  const PROMO_KEYS = ['inputPerMTok', 'outputPerMTok', 'until'] as const;
41
45
 
42
46
  /**
@@ -260,6 +264,23 @@ function parseModel(
260
264
  if (raw.multipliers !== undefined) {
261
265
  model.multipliers = parseMultipliers(raw.multipliers, `models.${id}.multipliers`, source);
262
266
  }
267
+ /*
268
+ * The multiplier a provider publishes for one geography, as the catalogue
269
+ * carries it on Claude 4.6 and later. Accepted so a catalogue row copied into
270
+ * an overlay is still a valid overlay row, and so a model added there can say
271
+ * what US-only inference costs on it. Zero and negatives are refused, as for
272
+ * every other rate here.
273
+ */
274
+ if (raw.inferenceGeoMultipliers !== undefined) {
275
+ const label = `models.${id}.inferenceGeoMultipliers`;
276
+ const geo = raw.inferenceGeoMultipliers;
277
+ if (!isPlainObject(geo)) {
278
+ throw new PricingOverlayError(`"${label}" must be an object such as {"us": 1.1}`, source);
279
+ }
280
+ rejectUnknownKeys(geo, INFERENCE_GEO_KEYS, source, `${label}.`);
281
+ model.inferenceGeoMultipliers = {};
282
+ if (geo.us !== undefined) model.inferenceGeoMultipliers.us = positiveNumber(geo.us, `${label}.us`, source);
283
+ }
263
284
 
264
285
  return model;
265
286
  }