@trazum/core 2.4.3 → 2.5.0

package/src/connector.ts

@@ -379,20 +379,23 @@ export function normalizeOpenAIUsage(payload: unknown): ConnectorPull {
       }
       const cached = num(r.input_cached_tokens) ?? 0;
       const input = num(r.input_tokens) ?? 0;
+      // The 30-minute write GPT-5.6 and later bill at 1.25x. The 12-hour write
+      // has no published price and stays in the input total, a floor.
+      const written = num(r.input_cache_write_tokens) ?? 0;
       buckets.push({
         fromMs,
         toMs,
         model,
         calls: num(r.num_model_requests),
-        // OpenAI reports cached tokens *inside* the input total, so the
-        // uncached half is the subtraction. Reporting both at face value
-        // would bill the cached tokens twice, at the dearer rate.
-        inputTokens: Math.max(0, input - cached),
+        // OpenAI reports cached tokens and writes *inside* the input total, so
+        // the uncached part is the subtraction. Reporting them at face value
+        // would bill them twice.
+        inputTokens: Math.max(0, input - cached - written),
         cacheReadTokens: cached,
-        cacheWrite5mTokens: 0,
+        cacheWrite5mTokens: written,
         cacheWrite1hTokens: 0,
-        // Nothing was assumed: this API reports no cache writes at all, and an
-        // absent field is not an assumed TTL.
+        // Nothing was assumed: an OpenAI write has one TTL, which the model
+        // states (`cacheTtl`), and an absent field is not an assumed TTL.
         writeTtlKnown: true,
         outputTokens: num(r.output_tokens) ?? 0,
         group: groupOf(r, ['project_id', 'api_key_id', 'batch']),
@@ -444,6 +447,18 @@ export interface BucketedSlice {
   /** Writes priced at the 1-hour rate, when the source did not state the TTL. */
   cacheWriteUsdIfAssumed1h: number;
   writeTtlKnown: boolean;
+  /**
+   * Buckets billed at the dearer of two rates, and what they cost each way.
+   *
+   * A model priced by prompt length bills each request on its own prompt; a
+   * bucket sums requests and says none of their lengths. Unless the bucket's
+   * whole prompt total is at or under the line, it is billed at the dearer
+   * rate, so `totalUsd` is a ceiling on it: `tierCeilingUsd` is its share of
+   * that total and `tierFloorUsd` the same tokens at the cheaper rate.
+   */
+  tierCeilingBuckets: number;
+  tierCeilingUsd: number;
+  tierFloorUsd: number;
 }
 
 export interface BucketedReport {
@@ -480,9 +495,15 @@ export interface BucketedReport {
  */
 export function bucketedProfile(
   pull: ConnectorPull,
+  /**
+   * `on` is accepted and no longer read. Each bucket is billed at its own
+   * start, as `profile` bills each call at its own moment: priced at the
+   * report's date, a pull spanning a published price change came out entirely
+   * at whichever price applied the day it ran.
+   */
   options: { catalogue: PricingCatalogue; on?: Date },
 ): BucketedReport {
-  const { catalogue, on = new Date() } = options;
+  const { catalogue } = options;
 
   const slices = new Map<string, BucketedSlice>();
   const days = new Map<string, { usd: number; calls: number | null }>();
@@ -498,9 +519,28 @@ export function bucketedProfile(
       continue;
     }
 
-    const { inputPerMTok, outputPerMTok } = effectivePricing(model, on);
-    const rates = multipliersFor(model);
+    const at = new Date(bucket.fromMs);
+    /*
+     * A bucket of exactly one request says that request's prompt; any other
+     * bucket only bounds it. See `PromptSize`.
+     */
+    const prompt =
+      bucket.inputTokens + bucket.cacheReadTokens + bucket.cacheWrite5mTokens + bucket.cacheWrite1hTokens;
+    const priced = effectivePricing(
+      model,
+      at,
+      bucket.calls === 1 ? { inputTokens: prompt } : { inputTokensAtMost: prompt },
+    );
+    const { inputPerMTok, outputPerMTok } = priced;
+    const rates = multipliersFor(model, at);
     const per = (count: number, rate: number): number => (count / 1_000_000) * rate;
+    const costAt = (input: number, output: number): number =>
+      per(bucket.inputTokens, input) +
+      per(bucket.cacheReadTokens, input * rates.cacheRead) +
+      per(bucket.cacheWrite5mTokens, input * rates.cacheWrite5m) +
+      per(bucket.cacheWrite1hTokens, input * rates.cacheWrite1h) +
+      per(bucket.outputTokens, output);
+    const floor = priced.tier?.decided === false ? priced.tier.floor : undefined;
 
     const inputUsd = per(bucket.inputTokens, inputPerMTok);
     const cacheReadUsd = per(bucket.cacheReadTokens, inputPerMTok * rates.cacheRead);
@@ -529,6 +569,9 @@ export function bucketedProfile(
       cachedTokensAtInputRateUsd: 0,
       cacheWriteUsdIfAssumed1h: 0,
       writeTtlKnown: true,
+      tierCeilingBuckets: 0,
+      tierCeilingUsd: 0,
+      tierFloorUsd: 0,
     };
     slice.calls = slice.calls === null || bucket.calls === null ? null : slice.calls + bucket.calls;
     slice.inputTokens += bucket.inputTokens;
@@ -543,6 +586,11 @@ export function bucketedProfile(
     slice.cachedTokensAtInputRateUsd += atInputRate;
     slice.cacheWriteUsdIfAssumed1h += ifAssumed1h;
     slice.writeTtlKnown = slice.writeTtlKnown && bucket.writeTtlKnown;
+    if (floor !== undefined) {
+      slice.tierCeilingBuckets += 1;
+      slice.tierCeilingUsd += costAt(inputPerMTok, outputPerMTok);
+      slice.tierFloorUsd += costAt(floor.inputPerMTok, floor.outputPerMTok);
+    }
     slices.set(bucket.model, slice);
 
     const day = new Date(bucket.fromMs).toISOString().slice(0, 10);

package/src/conversation.ts

@@ -1,4 +1,5 @@
 import { effectivePricing, multipliersFor } from './pricing.js';
+import { billedAt, promptSizeOf } from './billing.js';
 import { UNLABELLED } from './usage.js';
 import type { PricingCatalogue } from './pricing.js';
 import type { UsageRecord } from './usage.js';
@@ -95,8 +96,9 @@ export interface ConversationOptions {
 function inputCostOf(record: UsageRecord, catalogue: PricingCatalogue, on: Date): number | null {
   const model = catalogue.byId.get(record.model);
   if (!model) return null;
-  const { inputPerMTok } = effectivePricing(model, on);
-  const rates = multipliersFor(model);
+  const at = billedAt(record, on);
+  const { inputPerMTok } = effectivePricing(model, at, promptSizeOf(record));
+  const rates = multipliersFor(model, at);
   const per = (tokens: number, rate: number): number => (tokens / 1_000_000) * rate;
   return (
     per(record.inputTokens, inputPerMTok) +

package/src/gateway.ts

@@ -216,7 +216,8 @@ function priceCall(
   on: Date,
 ): number | null {
   if (model === undefined || call.inputTokens === null) return null;
-  const rates = effectivePricing(model, on);
+  // The call's own prompt decides a model priced by prompt length.
+  const rates = effectivePricing(model, on, { inputTokens: call.inputTokens });
   const output = call.maxOutputTokens ?? 0;
   return (call.inputTokens / 1_000_000) * rates.inputPerMTok + (output / 1_000_000) * rates.outputPerMTok;
 }
@@ -236,11 +237,12 @@ function alternativesFor(
   const mine = priceCall(model, call, on);
   if (mine === null) return [];
   const out: GatewayAlternative[] = [];
-  const here = effectivePricing(model, on);
+  const size = call.inputTokens === null ? {} : { inputTokens: call.inputTokens };
+  const here = effectivePricing(model, on, size);
 
   for (const candidate of catalogue.byId.values()) {
     if (candidate.id === model.id || candidate.provider !== model.provider) continue;
-    const there = effectivePricing(candidate, on);
+    const there = effectivePricing(candidate, on, size);
     if (there.inputPerMTok >= here.inputPerMTok) continue;
     if (call.inputTokens !== null && candidate.contextWindow < call.inputTokens) continue;
     const routed = priceCall(candidate, call, on);

package/src/guard.ts

@@ -91,18 +91,20 @@ function cheaperThan(
   inputTokens: number,
   on: Date,
 ): ModelPricing[] {
-  const here = effectivePricing(model, on);
+  // At this call's prompt, so a model priced by prompt length is ranked at its real band.
+  const size = { inputTokens };
+  const here = effectivePricing(model, on, size);
   return [...catalogue.byId.values()]
     .filter((candidate) => {
       if (candidate.id === model.id) return false;
       if (candidate.provider !== model.provider) return false;
-      const there = effectivePricing(candidate, on);
+      const there = effectivePricing(candidate, on, size);
       if (there.inputPerMTok >= here.inputPerMTok) return false;
       // A model the prompt does not fit in is not a cheaper way to make this
       // call; it is a way not to make it.
       return candidate.contextWindow >= inputTokens;
     })
-    .sort((a, b) => effectivePricing(b, on).inputPerMTok - effectivePricing(a, on).inputPerMTok);
+    .sort((a, b) => effectivePricing(b, on, size).inputPerMTok - effectivePricing(a, on, size).inputPerMTok);
 }
 
 export interface GuardRequest extends AnswerRequest {
@@ -133,9 +135,9 @@ export function guardSpend(
   if (model !== undefined && cost.call !== null) {
     const inputTokens = cost.call.inputTokens;
     const outputTokens = cost.call.outputTokens;
-    const here = effectivePricing(model, on);
+    const here = effectivePricing(model, on, { inputTokens });
     const priceOf = (candidate: ModelPricing): number => {
-      const rates = effectivePricing(candidate, on);
+      const rates = effectivePricing(candidate, on, { inputTokens });
       return (inputTokens / 1_000_000) * rates.inputPerMTok + (outputTokens / 1_000_000) * rates.outputPerMTok;
     };
     const mine = (inputTokens / 1_000_000) * here.inputPerMTok + (outputTokens / 1_000_000) * here.outputPerMTok;

package/src/index.ts

@@ -435,7 +435,7 @@ export {
   multipliersFor,
   isOffered,
 } from './pricing.js';
-export type { PricingCatalogue } from './pricing.js';
+export type { PricingCatalogue, PromptSize } from './pricing.js';
 export type { CachingMode, Capability, CostMultipliers } from './types.js';
 
 // Local price corrections, so a price change needs no library upgrade.

package/src/input-shape.ts

@@ -1,4 +1,5 @@
 import { effectivePricing, multipliersFor } from './pricing.js';
+import { billedAt, promptSizeOf } from './billing.js';
 import { UNLABELLED } from './usage.js';
 import type { PricingCatalogue } from './pricing.js';
 import type { UsageRecord } from './usage.js';
@@ -190,8 +191,9 @@ export function createInputShapeTracker(options: InputShapeOptions): InputShapeT
       slices.set(key, slice);
     }
 
-    const { inputPerMTok } = effectivePricing(model, on);
-    const rates = multipliersFor(model);
+    const at = billedAt(record, on);
+    const { inputPerMTok } = effectivePricing(model, at, promptSizeOf(record));
+    const rates = multipliersFor(model, at);
     const per = (count: number, rate: number): number => (count / 1_000_000) * rate;
 
     slice.calls += 1;

package/src/ladder.ts

@@ -151,7 +151,8 @@ export function ladderArithmetic(
     if (id === undefined) return null;
     const model = catalogue.byId.get(id);
     if (model === undefined) return null;
-    const rates = effectivePricing(model, on);
+    // The shape's own prompt decides a model priced by prompt length.
+    const rates = effectivePricing(model, on, { inputTokens: shape.inputTokens });
     return (
       (shape.inputTokens / 1_000_000) * rates.inputPerMTok +
       (shape.outputTokens / 1_000_000) * rates.outputPerMTok

package/src/levers.ts

@@ -150,8 +150,11 @@ function repriceAt(
   model: ModelPricing,
   on: Date,
 ): { inputUsd: number; outputUsd: number; cacheUsd: number; totalUsd: number } {
-  const { inputPerMTok, outputPerMTok } = effectivePricing(model, on);
-  const rates = multipliersFor(model);
+  // The breakdown's largest call bounds every prompt in it: see `PromptSize`.
+  const { inputPerMTok, outputPerMTok } = effectivePricing(model, on, {
+    inputTokensAtMost: breakdown.maxCallInputTokens,
+  });
+  const rates = multipliersFor(model, on);
   const per = (tokens: number, rate: number): number => (tokens / 1_000_000) * rate;
 
   const inputUsd = per(breakdown.inputTokens, inputPerMTok);

package/src/openai-usage.ts

@@ -95,10 +95,21 @@ export interface OpenaiUsageRecord {
   model: string;
   ts: string;
   label?: string;
+  /**
+   * `num_model_requests` when the bucket sums more than one, `null` when the
+   * row does not carry a usable count, and absent when it is exactly one
+   * request, which is then a call like any other. See `UsageRecord.requests`.
+   */
+  requests?: number | null;
   usage: {
     prompt_tokens: number;
     completion_tokens: number;
-    prompt_tokens_details?: { cached_tokens: number };
+    /**
+     * Both inside `prompt_tokens`, as OpenAI counts them, and both taken out of
+     * it by `parseUsageLine`. `cache_write_tokens` is the 30-minute write
+     * GPT-5.6 and later bill at 1.25x input.
+     */
+    prompt_tokens_details?: { cached_tokens: number; cache_write_tokens?: number };
   };
 }
 
@@ -128,6 +139,12 @@ export interface OpenaiUsageConversion {
   nonTextTokens: number;
   /** Cache-write tokens on mixed rows, left out because the schema gives them no modality. */
   cacheWriteUnplaced: number;
+  /**
+   * Tokens written to the 12-hour cache. No price for that write is published
+   * anywhere this table can read, so they stay in the prompt total and are
+   * priced as plain input, a floor, and named rather than guessed at.
+   */
+  cacheWrite12hTokens: number;
   /** Mixed rows the report gave no text split for, refused whole. */
   unsplitRows: number;
   /** `has_more`: this is one page and the bill from it is understated. */
@@ -182,6 +199,7 @@ export function openaiUsageRecords(
     mixedRows: 0,
     nonTextTokens: 0,
     cacheWriteUnplaced: 0,
+    cacheWrite12hTokens: 0,
     unsplitRows: 0,
     truncated: false,
     labelledByProject: 0,
@@ -213,6 +231,7 @@ export function openaiUsageRecords(
   let mixedRows = 0;
   let nonTextTokens = 0;
   let cacheWriteUnplaced = 0;
+  let cacheWrite12hTokens = 0;
   let unsplitRows = 0;
   let labelledByProject = 0;
   let unruledProject = 0;
@@ -279,10 +298,18 @@ export function openaiUsageRecords(
       const nonText = NON_TEXT.reduce((sum, field) => sum + count(result[field]), 0);
       let prompt: number;
       let cached: number;
+      let written = 0;
       let completion: number;
       if (nonText === 0) {
         prompt = count(result.input_tokens);
         cached = count(result.input_cached_tokens);
+        /*
+          `input_tokens` is uncached + cached + both writes, by the schema's own
+          example. The 30-minute write has a price and goes where the parser
+          prices it; the 12-hour write has none here and stays in the total.
+        */
+        written = count(result.input_cache_write_tokens);
+        cacheWrite12hTokens += count(result.input_cache_write_12h_tokens);
         completion = count(result.output_tokens);
       } else {
         const split =
@@ -306,10 +333,18 @@ export function openaiUsageRecords(
         model: result.model,
         ts,
         ...(label === undefined ? {} : { label }),
+        ...requestsField(result.num_model_requests),
         usage: {
           prompt_tokens: prompt,
           completion_tokens: completion,
-          ...(cached > 0 ? { prompt_tokens_details: { cached_tokens: cached } } : {}),
+          ...(cached > 0 || written > 0
+            ? {
+                prompt_tokens_details: {
+                  cached_tokens: cached,
+                  ...(written > 0 ? { cache_write_tokens: written } : {}),
+                },
+              }
+            : {}),
         },
       });
       rows += 1;
@@ -330,6 +365,7 @@ export function openaiUsageRecords(
     mixedRows,
     nonTextTokens,
     cacheWriteUnplaced,
+    cacheWrite12hTokens,
     unsplitRows,
     truncated: report.has_more === true,
     labelledByProject,
@@ -351,3 +387,9 @@ export function looksLikeOpenaiUsage(text: string, prefixBytes = 8192): boolean
   if (head.includes('"organization.usage.completions.result"')) return true;
   return head.includes('"num_model_requests"') && head.includes('"start_time"');
 }
+
+/** A bucket's request count as `UsageRecord.requests` reads it: one is a call. */
+function requestsField(value: unknown): { requests?: number | null } {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) return { requests: null };
+  return value === 1 ? {} : { requests: value };
+}

package/src/openrouter-activity.ts

@@ -63,6 +63,12 @@ export interface OpenrouterActivityRecord {
   model: string;
   ts: string;
   label?: string;
+  /**
+   * The day's `requests` when it is more than one, `null` when the row does
+   * not carry a usable count, absent when it is exactly one request. See
+   * `UsageRecord.requests`.
+   */
+  requests?: number | null;
   usage: { prompt_tokens: number; completion_tokens: number };
 }
 
@@ -186,6 +192,7 @@ export function openrouterActivityRecords(
       model: row.model,
       ts: `${row.date}T00:00:00.000Z`,
       ...(label === undefined ? {} : { label }),
+      ...requestsField(row.requests),
       usage: {
         prompt_tokens: count(row.prompt_tokens),
         completion_tokens: count(row.completion_tokens),
@@ -219,3 +226,9 @@ export function looksLikeOpenrouterActivity(text: string, prefixBytes = 8192): b
   const head = text.slice(0, prefixBytes);
   return head.includes('"model_permaslug"') || head.includes('"byok_usage_inference"');
 }
+
+/** A day's request count as `UsageRecord.requests` reads it: one is a call. */
+function requestsField(value: unknown): { requests?: number | null } {
+  if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) return { requests: null };
+  return value === 1 ? {} : { requests: value };
+}

package/src/output-shape.ts

@@ -1,4 +1,5 @@
 import { effectivePricing } from './pricing.js';
+import { billedAt, promptSizeOf } from './billing.js';
 import { UNLABELLED } from './usage.js';
 import type { PricingCatalogue } from './pricing.js';
 import type { UsageRecord } from './usage.js';
@@ -172,7 +173,7 @@ export function createOutputShapeTracker(options: OutputShapeOptions): OutputSha
       slices.set(key, slice);
     }
 
-    const { outputPerMTok } = effectivePricing(model, on);
+    const { outputPerMTok } = effectivePricing(model, billedAt(record, on), promptSizeOf(record));
     slice.calls += 1;
     slice.outputTokens += record.outputTokens;
     slice.outputUsd += (record.outputTokens / 1_000_000) * outputPerMTok;