@trazum/core 2.4.2 → 2.5.0

package/src/usage.ts

@@ -1,4 +1,5 @@
-import { effectivePricing, multipliersFor } from './pricing.js';
+import { cacheTtlOf, effectivePricing, multipliersFor } from './pricing.js';
+import { billedAt, promptSizeOf } from './billing.js';
 import { createConversationTracker } from './conversation.js';
 import { createOutputShapeTracker } from './output-shape.js';
 import { createInputShapeTracker } from './input-shape.js';
@@ -159,6 +160,22 @@ export interface UsageRecord {
    * must not congratulate a log that never measured.
    */
   truncated: boolean | null;
+  /**
+   * How many requests this record sums, when it sums more than one.
+   *
+   * Absent on a record that is one call, which is every record a per-call log
+   * holds. A number above one, or `null` for "a sum, count not given", is a
+   * row out of a usage report: an Anthropic or OpenAI bucket, an OpenRouter
+   * day. It matters to a model priced by prompt length, because a request is
+   * priced on its own prompt and a row of many requests does not say any one
+   * of them. Such a row is priced at the dearer rate unless its whole prompt
+   * total is at or under the line, and the report says so.
+   *
+   * Read from `requests` when it is a positive integer or `null`; anything
+   * else is not this field, because a log that already uses the name for
+   * something of its own should not lose its records to it.
+   */
+  requests?: number | null;
 }
 
 /** What a set of calls cost, split by where the money went. */
@@ -239,6 +256,21 @@ export interface UsageBreakdown {
   truncatedOutputUsd: number;
   /** Calls that recorded a stop reason at all, truncated or not. */
   stopReasonCalls: number;
+  /**
+   * Records billed at the dearer of two rates because which one applied could
+   * not be decided, and what they cost each way.
+   *
+   * A model priced by prompt length bills each request on its own prompt, and
+   * a row that sums requests does not say any one prompt's length. Those rows
+   * are billed at the dearer rate, so `totalUsd` is a ceiling on them and never
+   * a figure that flatters; `tierCeilingUsd` is what they contribute to it and
+   * `tierFloorUsd` what the same tokens come to at the cheaper rate. The true
+   * bill for them is between the two, and a report that printed only the
+   * ceiling would be right and useless.
+   */
+  tierCeilingCalls: number;
+  tierCeilingUsd: number;
+  tierFloorUsd: number;
 }
 
 /**
@@ -597,6 +629,9 @@ const EMPTY = (): UsageBreakdown => ({
   truncatedCalls: 0,
   truncatedOutputUsd: 0,
   stopReasonCalls: 0,
+  tierCeilingCalls: 0,
+  tierCeilingUsd: 0,
+  tierFloorUsd: 0,
 });
 
 /**
@@ -713,12 +748,24 @@ export function parseUsageLine(line: string): UsageRecord | null {
    * in `prompt_tokens`**, while Anthropic reports them separately and does not.
    * Subtracting in one case and not the other is the difference between a correct
    * bill and one that charges the cached half twice.
+   *
+   * **And the Responses API spells it `input_tokens_details`**, under an
+   * `input_tokens` that likewise includes the cached tokens. Only the Chat
+   * Completions spelling was read, so a Responses log, OpenAI's default API,
+   * billed every cached token at the full input rate: a call that read 90,000
+   * of its 100,000 tokens from the cache came out four times its price, and the
+   * cache verdict said caching was never used.
+   *
+   * GPT-5.6 and later also report `cache_write_tokens` in the same object,
+   * inside the same total, and bill them at 1.25x input. They are subtracted
+   * with the cached tokens and land in the write bucket, whose TTL the model
+   * states (`cacheTtl`): one kind of entry, so nothing about it is assumed.
    */
+  const detailsRaw = usage.prompt_tokens_details ?? usage.input_tokens_details;
   const details =
-    typeof usage.prompt_tokens_details === 'object' && usage.prompt_tokens_details !== null
-      ? (usage.prompt_tokens_details as Record<string, unknown>)
-      : null;
+    typeof detailsRaw === 'object' && detailsRaw !== null ? (detailsRaw as Record<string, unknown>) : null;
   const openAiCached = details ? readCount(details.cached_tokens) : ({ kind: 'absent' } as Count);
+  const openAiWrite = details ? readCount(details.cache_write_tokens) : ({ kind: 'absent' } as Count);
 
   /**
    * Anthropic splits cache writes by time-to-live, and the two cost different
@@ -769,6 +816,7 @@ export function parseUsageLine(line: string): UsageRecord | null {
     cacheRead: readCount(usage.cache_read_input_tokens, usage.cacheReadTokens),
     cacheWrite: readCount(usage.cache_creation_input_tokens, usage.cacheWriteTokens),
     openAiCached,
+    openAiWrite,
     geminiCached,
     write5m,
     write1h,
@@ -791,6 +839,8 @@ export function parseUsageLine(line: string): UsageRecord | null {
   // Both providers that fold cached tokens into the prompt count, one
   // subtraction. They cannot coexist on a record: the shapes share no field.
   const cached = valueOf(counts.openAiCached!) + valueOf(counts.geminiCached!);
+  // Inside the OpenAI total like the cached tokens, and taken out of it the same way.
+  const openAiWritten = valueOf(counts.openAiWrite!);
   const flatWrite = valueOf(counts.cacheWrite!);
   const split5m = valueOf(counts.write5m!);
   const split1h = valueOf(counts.write1h!);
@@ -798,16 +848,17 @@ export function parseUsageLine(line: string): UsageRecord | null {
 
   return {
     model,
-    inputTokens: Math.max(0, valueOf(counts.input!) - cached),
+    inputTokens: Math.max(0, valueOf(counts.input!) - cached - openAiWritten),
     cacheReadTokens: counts.cacheRead!.kind === 'ok' ? counts.cacheRead!.value : cached,
     /**
      * The split when the log carries it, the flat number otherwise — and
      * `writeTtlKnown` says which, so the report can admit that a rate was assumed
      * rather than quietly choosing the cheaper one.
      */
-    cacheWrite5mTokens: hasSplit ? split5m : flatWrite,
+    cacheWrite5mTokens: (hasSplit ? split5m : flatWrite) + openAiWritten,
     cacheWrite1hTokens: hasSplit ? split1h : 0,
-    writeTtlKnown: hasSplit || flatWrite === 0,
+    // `cache_write_tokens` names no TTL either; see the note in `profileUsage`.
+    writeTtlKnown: hasSplit || (flatWrite === 0 && openAiWritten === 0),
     outputTokens: valueOf(counts.output!),
     /**
      * Trimmed and internally normalised: any whitespace run becomes one space.
@@ -846,9 +897,22 @@ export function parseUsageLine(line: string): UsageRecord | null {
       if (typeof reason !== 'string') return null;
       return reason === 'max_tokens' || reason === 'length' || reason === 'MAX_TOKENS';
     })(),
+    ...requestsOf(record.requests),
   };
 }
 
+/**
+ * `requests`, when it is this field: a positive integer or `null`.
+ *
+ * One is the same as absent, so it is left absent and a per-call record stays
+ * the shape it always was.
+ */
+function requestsOf(value: unknown): { requests?: number | null } {
+  if (value === null) return { requests: null };
+  if (typeof value === 'number' && Number.isInteger(value) && value > 1) return { requests: value };
+  return {};
+}
+
 /**
  * One slice's outcome tally, in the same shape as the whole log's.
  *
@@ -944,9 +1008,40 @@ function add(into: UsageBreakdown, record: UsageRecord, catalogue: PricingCatalo
   if (!model) return false;
 
   countInto(into, record);
-  const { inputPerMTok, outputPerMTok } = effectivePricing(model, on);
-  const rates = multipliersFor(model);
+  /**
+   * **Each call at the price of its own moment.** A bill is history: a call
+   * made inside a promotion was billed at the promotional rate, a DeepSeek
+   * call at 03:00 UTC on a weekday was billed at peak, and a call before a
+   * published price change was billed at the old price. Priced at the report's
+   * date instead, every one of those came out at whatever applied the day the
+   * report ran: a clock-priced log read during peak hours was all peak, and an
+   * August log read in October lost its August promotion. `on` is the date for
+   * a record that carries no clock, which is the only thing it can mean here.
+   */
+  const at = billedAt(record, on);
+  /**
+   * **Each request on its own prompt.** A model priced by prompt length counts
+   * every input token a request carried, cache reads and writes included, and
+   * a record that is one call says exactly that. A record that sums requests
+   * gives only a bound: no request in it was larger than the whole row.
+   */
+  const priced = effectivePricing(model, at, promptSizeOf(record));
+  const { inputPerMTok, outputPerMTok } = priced;
+  // Dated, like the rate above: a repriced cache read is part of the reprice.
+  const rates = multipliersFor(model, at);
   const per = (tokens: number, rate: number): number => (tokens / 1_000_000) * rate;
+  const recordUsd = (input: number, output: number): number =>
+    per(record.inputTokens, input) +
+    per(record.cacheReadTokens, input * rates.cacheRead) +
+    per(record.cacheWrite5mTokens, input * rates.cacheWrite5m) +
+    per(record.cacheWrite1hTokens, input * rates.cacheWrite1h) +
+    per(record.outputTokens, output);
+  const floor = priced.tier?.decided === false ? priced.tier.floor : undefined;
+  if (floor !== undefined) {
+    into.tierCeilingCalls += 1;
+    into.tierCeilingUsd += recordUsd(inputPerMTok, outputPerMTok);
+    into.tierFloorUsd += recordUsd(floor.inputPerMTok, floor.outputPerMTok);
+  }
 
   into.inputUsd += per(record.inputTokens, inputPerMTok);
   into.cacheReadUsd += per(record.cacheReadTokens, inputPerMTok * rates.cacheRead);
@@ -991,7 +1086,11 @@ function add(into: UsageBreakdown, record: UsageRecord, catalogue: PricingCatalo
 
 export interface UsageProfileOptions {
   catalogue: PricingCatalogue;
-  /** Date the prices are read at, so a promotional rate resolves the same way. */
+  /**
+   * The date a record with no timestamp is priced at, and the date the
+   * forward-looking findings (levers, what-ifs) are priced at. A record that
+   * carries its own `ts` is billed at its own moment: see `add`.
+   */
   on?: Date;
   /**
    * Profile only the records carrying this label — the drill-down, once the
@@ -1089,11 +1188,30 @@ export function profileUsage(text: string, options: UsageProfileOptions): UsageP
     const line = lines[i]!.trim();
     if (line === '') continue;
 
-    const record = parseUsageLine(line);
+    let record = parseUsageLine(line);
     if (!record) {
       skippedLines.push(i + 1);
       continue;
     }
+    /**
+     * A write whose TTL the line did not state is an assumption only where
+     * there was a choice. `cache_write_tokens` carries no TTL: on Kimi K3,
+     * which sells a 5-minute and a 1-hour entry, the cheaper is assumed and
+     * the report says so; on OpenAI's GPT-5.6 and later, which sell one, and
+     * on its earlier models, whose writes cost what input costs whatever they
+     * last, there is nothing to assume and nothing is said.
+     */
+    if (!record.writeTtlKnown) {
+      const priced = catalogue.byId.get(record.model);
+      // One kind of entry, or two at one price: an assumption that cannot move the bill is not one.
+      if (
+        priced !== undefined
+        && (cacheTtlOf(priced).longerMs === null
+          || multipliersFor(priced).cacheWrite1h === multipliersFor(priced).cacheWrite5m)
+      ) {
+        record = { ...record, writeTtlKnown: true };
+      }
+    }
 
     // The drill-down: after the skip accounting, so a corrupt line is reported
     // whatever it might have been labelled.