@trazum/core 2.7.3 → 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.
@@ -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
@@ -37,6 +37,7 @@ export function promptSizeOf(record: UsageRecord): PromptSize {
37
37
  ...(record.speed === undefined ? {} : { speed: record.speed }),
38
38
  ...(record.serviceTier === undefined ? {} : { serviceTier: record.serviceTier }),
39
39
  ...(record.inferenceGeo === undefined ? {} : { inferenceGeo: record.inferenceGeo }),
40
+ ...(record.batch === true ? { batch: true } : {}),
40
41
  };
41
42
  return record.requests === undefined ? { inputTokens: prompt, ...how } : { inputTokensAtMost: prompt, ...how };
42
43
  }
package/src/connector.ts CHANGED
@@ -540,10 +540,14 @@ export function bucketedProfile(
540
540
  * them reads as standard, as it always did.
541
541
  */
542
542
  const group = bucket.group;
543
- const how: { speed?: string; serviceTier?: string; inferenceGeo?: string } = {};
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;
544
546
  if (pull.provider === 'anthropic') {
545
547
  const tier = group.service_tier;
546
- if (tier !== undefined && tier !== 'standard') {
548
+ if (tier === 'batch' && batchRate) {
549
+ how.batch = true;
550
+ } else if (tier !== undefined && tier !== 'standard') {
547
551
  leave(bucket, tier);
548
552
  continue;
549
553
  }
@@ -558,11 +562,14 @@ export function bucketedProfile(
558
562
  if (group.inference_geo !== undefined) how.inferenceGeo = group.inference_geo;
559
563
  } else if (pull.provider === 'openai') {
560
564
  if (group.batch === 'true') {
561
- leave(bucket, 'batch');
562
- continue;
565
+ if (!batchRate) {
566
+ leave(bucket, 'batch');
567
+ continue;
568
+ }
569
+ how.batch = true;
563
570
  }
564
571
  const tier = group.service_tier;
565
- if (tier !== undefined && tier !== 'default') {
572
+ if (tier !== undefined && tier !== 'default' && !(how.batch === true && tier === 'batch')) {
566
573
  const named = serviceTierOf(tier);
567
574
  if (named === undefined || model.serviceTiers?.[named] === undefined) {
568
575
  leave(bucket, tier);
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,
@@ -94,7 +94,7 @@
94
94
  * absence and no second reading to derive.
95
95
  */
96
96
 
97
- import { BUNDLED_CATALOGUE, serviceTierOf } from './pricing.js';
97
+ import { BUNDLED_CATALOGUE, multipliersFor, serviceTierOf } from './pricing.js';
98
98
  import type { PricingCatalogue } from './pricing.js';
99
99
 
100
100
  /** One project, and the label the operator gives it. Matched exactly. */
@@ -121,6 +121,8 @@ export interface OpenaiUsageRecord {
121
121
  * the default tier.
122
122
  */
123
123
  service_tier?: string;
124
+ /** True when the row ran on the Batch API: billed at the row's batch ratio. */
125
+ batch?: true;
124
126
  usage: {
125
127
  prompt_tokens: number;
126
128
  completion_tokens: number;
@@ -143,8 +145,10 @@ export interface OpenaiUsageConversion {
143
145
  requests: number;
144
146
  /** Results with `model: null`, which nothing can price. */
145
147
  unnamedModel: number;
146
- /** 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. */
147
149
  batch: number;
150
+ /** Results with `batch: true` that became records priced at the row's batch ratio. */
151
+ batchRows: number;
148
152
  /** Whether any result said whether it was batch at all. */
149
153
  batchNamed: boolean;
150
154
  /**
@@ -229,6 +233,7 @@ export function openaiUsageRecords(
229
233
  requests: 0,
230
234
  unnamedModel: 0,
231
235
  batch: 0,
236
+ batchRows: 0,
232
237
  batchNamed: false,
233
238
  nonDefaultTier: 0,
234
239
  tiersRefused: [],
@@ -267,6 +272,7 @@ export function openaiUsageRecords(
267
272
  let unnamedModel = 0;
268
273
  let batch = 0;
269
274
  let batchNamed = false;
275
+ let batchRows = 0;
270
276
  let nonDefaultTier = 0;
271
277
  let serviceTierRows = 0;
272
278
  let tierNamed = false;
@@ -295,18 +301,28 @@ export function openaiUsageRecords(
295
301
  if (result === null) continue;
296
302
  requests += count(result.num_model_requests);
297
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;
298
310
  if (typeof result.batch === 'boolean') {
299
311
  batchNamed = true;
300
312
  if (result.batch) {
301
- batch += 1;
302
- 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;
303
319
  }
304
320
  }
305
321
 
306
322
  let serviceTier: string | undefined;
307
323
  if (typeof result.service_tier === 'string') {
308
324
  tierNamed = true;
309
- if (result.service_tier !== 'default') {
325
+ if (result.service_tier !== 'default' && !(batchRow && result.service_tier === 'batch')) {
310
326
  /*
311
327
  Priced only from a table that exists for this model at this tier.
312
328
  The response path falls back to the standard rate for a tier with
@@ -390,6 +406,7 @@ export function openaiUsageRecords(
390
406
  ...(label === undefined ? {} : { label }),
391
407
  ...requestsField(result.num_model_requests),
392
408
  ...(serviceTier === undefined ? {} : { service_tier: serviceTier }),
409
+ ...(batchRow ? { batch: true as const } : {}),
393
410
  usage: {
394
411
  prompt_tokens: prompt,
395
412
  completion_tokens: completion,
@@ -404,6 +421,7 @@ export function openaiUsageRecords(
404
421
  },
405
422
  });
406
423
  rows += 1;
424
+ if (batchRow) batchRows += 1;
407
425
  if (serviceTier !== undefined) {
408
426
  serviceTierRows += 1;
409
427
  tiersPriced.add(serviceTier);
@@ -419,6 +437,7 @@ export function openaiUsageRecords(
419
437
  unnamedModel,
420
438
  batch,
421
439
  batchNamed,
440
+ batchRows,
422
441
  nonDefaultTier,
423
442
  tiersRefused: [...tiersRefused],
424
443
  serviceTierRows,
package/src/pricing.ts CHANGED
@@ -2467,6 +2467,8 @@ interface Rates {
2467
2467
  serviceTier?: ServiceTier;
2468
2468
  /** The geography whose published multiplier priced the call, when it was not global. */
2469
2469
  inferenceGeo?: InferenceGeo;
2470
+ /** True when the call was billed at the row's batch ratio. */
2471
+ batch?: true;
2470
2472
  }
2471
2473
 
2472
2474
  /**
@@ -2501,6 +2503,12 @@ export interface PromptSize {
2501
2503
  * only a geography the row publishes a multiplier for changes the price.
2502
2504
  */
2503
2505
  inferenceGeo?: string;
2506
+ /**
2507
+ * The call ran on the provider's Batch API: Anthropic's `usage.service_tier`
2508
+ * `"batch"`, a batch result file's line, or a usage report's batch row.
2509
+ * Billed at the row's batch ratio.
2510
+ */
2511
+ batch?: boolean;
2504
2512
  }
2505
2513
 
2506
2514
  /**
@@ -2517,6 +2525,26 @@ export function inferenceGeoOf(value: unknown): InferenceGeo | undefined {
2517
2525
  /** Rounded to a billionth of a dollar per million tokens, so 1.1x of $5 is $5.5 and not $5.500000000000001. */
2518
2526
  const scaled = (rate: number, factor: number): number => Math.round(rate * factor * 1e9) / 1e9;
2519
2527
 
2528
+ /** Every rate a call is billed at, multiplied by one published factor: the floor of an undecided band too. */
2529
+ function scaleRates(rates: Rates, factor: number): Rates {
2530
+ return {
2531
+ ...rates,
2532
+ inputPerMTok: scaled(rates.inputPerMTok, factor),
2533
+ outputPerMTok: scaled(rates.outputPerMTok, factor),
2534
+ ...(rates.tier?.floor !== undefined
2535
+ ? {
2536
+ tier: {
2537
+ ...rates.tier,
2538
+ floor: {
2539
+ inputPerMTok: scaled(rates.tier.floor.inputPerMTok, factor),
2540
+ outputPerMTok: scaled(rates.tier.floor.outputPerMTok, factor),
2541
+ },
2542
+ },
2543
+ }
2544
+ : {}),
2545
+ };
2546
+ }
2547
+
2520
2548
  /**
2521
2549
  * A response's `service_tier` as the tier whose table prices it, or
2522
2550
  * `undefined` for the standard one.
@@ -2688,23 +2716,22 @@ export function effectivePricing(
2688
2716
  const geo = inferenceGeoOf(inferenceGeo);
2689
2717
  const factor = geo === undefined ? undefined : model.inferenceGeoMultipliers?.[geo];
2690
2718
  if (geo === undefined || factor === undefined) return rates;
2691
- return {
2692
- ...rates,
2693
- inputPerMTok: scaled(rates.inputPerMTok, factor),
2694
- outputPerMTok: scaled(rates.outputPerMTok, factor),
2695
- ...(rates.tier?.floor !== undefined
2696
- ? {
2697
- tier: {
2698
- ...rates.tier,
2699
- floor: {
2700
- inputPerMTok: scaled(rates.tier.floor.inputPerMTok, factor),
2701
- outputPerMTok: scaled(rates.tier.floor.outputPerMTok, factor),
2702
- },
2703
- },
2704
- }
2705
- : {}),
2706
- inferenceGeo: geo,
2707
- };
2719
+ return { ...scaleRates(rates, factor), inferenceGeo: geo };
2720
+ }
2721
+ /*
2722
+ * A call the provider ran on its Batch API is billed at the row's batch
2723
+ * ratio, on input and output alike, and the cache multipliers apply on top
2724
+ * of the batch input rate, as both providers' pages say. The ratio is the
2725
+ * one the batch advisory quotes and `price-drift.mjs` checks against each
2726
+ * batch table every week. A row with no batch API (`batch: null`) cannot
2727
+ * have run one, so such a call keeps the standard price: a ceiling.
2728
+ */
2729
+ if (context.batch === true) {
2730
+ const { batch: _batch, ...rest } = context;
2731
+ const rates = effectivePricing(model, on, rest);
2732
+ const ratio = multipliersFor(model, on).batch;
2733
+ if (ratio === null) return rates;
2734
+ return { ...scaleRates(rates, ratio), batch: true };
2708
2735
  }
2709
2736
  /* A call before a published price change is priced as it was billed then. */
2710
2737
  if (model.history !== undefined) {
package/src/usage.ts CHANGED
@@ -201,6 +201,14 @@ export interface UsageRecord {
201
201
  * not-available are the row's own price.
202
202
  */
203
203
  inferenceGeo?: string;
204
+ /**
205
+ * True when the call ran on the provider's Batch API, which bills it at the
206
+ * row's batch ratio (half the standard rate at Anthropic and OpenAI). Read
207
+ * from Anthropic's `usage.service_tier: "batch"`, which every Messages
208
+ * response carries, or from a record-level `batch: true`, which the usage
209
+ * report converters write for a batch row. Absent is not batch.
210
+ */
211
+ batch?: true;
204
212
  /**
205
213
  * Set when an OpenAI-shaped line split its cache writes by lifetime and the
206
214
  * parts did not add up to the total. The lifetime is then unknown even on a
@@ -999,6 +1007,14 @@ export function parseUsageLine(line: string): UsageRecord | null {
999
1007
  ...(typeof usage.inference_geo === 'string' && usage.inference_geo !== ''
1000
1008
  ? { inferenceGeo: usage.inference_geo }
1001
1009
  : {}),
1010
+ /*
1011
+ * The Batch API, billed at half the standard rate by both providers.
1012
+ * Anthropic names it in `usage.service_tier` ("standard", "priority" or
1013
+ * "batch"); a converted usage report row says `batch: true`. OpenAI's
1014
+ * response-level `service_tier` never says "batch", so the two readings
1015
+ * cannot collide on a flat record.
1016
+ */
1017
+ ...(record.batch === true || usage.service_tier === 'batch' ? { batch: true as const } : {}),
1002
1018
  ...(openAiSplitGiven && !openAiSplitAgrees ? { writeSplitContradicted: true as const } : {}),
1003
1019
  };
1004
1020
  }