@trazum/core 1.10.0 → 1.26.0

package/src/levers.ts

@@ -0,0 +1,331 @@
+import { effectivePricing, multipliersFor } from './pricing.js';
+import { UNLABELLED } from './usage.js';
+import type { PricingCatalogue } from './pricing.js';
+import type { UsageBreakdown, UsageProfileReport } from './usage.js';
+import type { Capability, ModelPricing } from './types.js';
+
+/**
+ * What would actually move this bill.
+ *
+ * ## The number this exists to answer
+ *
+ * Trazum's rules recover about **1%** of a bill. Measured, on an ordinary support
+ * prompt: three tokens out of three hundred and six. On a company spending twenty
+ * thousand a month that is two hundred, and nobody installs a tool for two
+ * hundred. The complaint is correct and it is the most important thing anybody has
+ * said about this product.
+ *
+ * The rest of the package reads a prompt file and shortens it. This reads what was
+ * charged and prices the levers that are **not** the prompt, from the same log, at
+ * the same arithmetic:
+ *
+ * | lever | what it moves |
+ * |---|---|
+ * | which model the call goes to | Opus 5 → Sonnet 5 is 40% off; → Haiku 4.5 is 80% |
+ * | the Batch API | 50% flat, on input and output |
+ * | prompt caching | 3–4x the rules |
+ * | shortening the prompt | ~1% |
+ *
+ * So the honest headline is that **the money is in what you call, not in how long
+ * the prompt is** — and the tool that only did the last row should say so, in the
+ * reader's own figures, rather than reporting a 1% win as a success.
+ *
+ * ## Every figure here is arithmetic on tokens that were billed
+ *
+ * Nothing is modelled and nothing is extrapolated. A route lever is the same token
+ * counts at another model's published rate. A batch lever is the same tokens at the
+ * provider's batch multiplier. There is no assumed traffic, no assumed prompt, no
+ * assumed anything — which is the whole reason this reads a usage log instead of a
+ * directory.
+ *
+ * ## What it refuses to do
+ *
+ * **It never says a lever is safe to take.** Routing a workload to a cheaper model
+ * is a quality question that arithmetic cannot answer, and this module has never
+ * seen the prompt or a single answer. So a route carries its dollar figure *and*
+ * the command that measures whether it holds, and it is described as worth testing
+ * rather than worth doing. The same posture the `model-downgrade` advisory has
+ * always had, for the same reason.
+ *
+ * **It never says "per month".** A usage log covers whatever period somebody
+ * happened to record, and this module is not told which. Every figure is "on this
+ * bill" — over exactly the calls in the file. Multiplying an unknown period into a
+ * monthly headline is how a tool ends up quoting a saving four times the real one.
+ *
+ * **It never crosses a vendor.** A cheaper model at another provider is a
+ * migration, not a routing change, and pricing one as though it were a switch you
+ * could make on Tuesday is a saving nobody can take.
+ */
+
+/** What a lever is. */
+export type LeverId =
+  /** Send these calls to a cheaper model of the same family. */
+  | 'route'
+  /** Send these calls through the Batch API. */
+  | 'batch';
+
+/**
+ * Everything available on one label-and-model slice, and what it comes to.
+ *
+ * **Grouped by slice rather than listed as separate levers, because the levers
+ * are not additive and a list invites adding them.** The first version printed
+ * "route support-rag: $12.60" and "batch support-rag: $10.50" as two rows against
+ * a slice that had only spent $21.00 — a reader who added them got $23.10, a
+ * saving larger than the bill it came from. Impossible, and in the flattering
+ * direction.
+ *
+ * They do combine, just not by addition: batching a routed call saves half of the
+ * *cheaper* model's price, not half of the one you left. `combinedUsd` is that
+ * figure, computed rather than summed.
+ */
+export interface SliceLevers {
+  /** The label these calls carry, or `UNLABELLED`. */
+  label: string;
+  /** The model they go to now. */
+  model: string;
+  modelName: string;
+  /** Calls affected — the reader's own judgement of whether it is worth a day. */
+  calls: number;
+  /** What these exact calls cost. */
+  spentUsd: number;
+  /** A cheaper model one capability step down, if the catalogue has one. */
+  route: { candidate: { id: string; displayName: string }; savingUsd: number } | null;
+  /** The Batch API, where the provider sells one. */
+  batch: { savingUsd: number } | null;
+  /**
+   * Both together, **computed and never summed**. Equal to the single available
+   * lever when only one is.
+   */
+  combinedUsd: number;
+  /** `combinedUsd` as a fraction of the whole bill in the log, not of this slice. */
+  shareOfBill: number;
+}
+
+export interface BillLevers {
+  /** Ranked by what the whole slice could save, largest first. */
+  slices: SliceLevers[];
+  /**
+   * The most that shortening prompt text could ever be worth on this bill.
+   *
+   * Everything that is not output: plain input, cache reads, cache writes. It is a
+   * **ceiling and not an estimate** — deliberately generous, because it counts
+   * retrieved context, conversation history and tool results, none of which live in
+   * a prompt file and none of which a rules pass can touch. The real figure is
+   * below it, usually far below.
+   *
+   * It is here so the levers above have something to be compared against. A tool
+   * that reports a 1% win without saying 1% of what is not being useful.
+   */
+  promptCeilingUsd: number;
+  promptCeilingShare: number;
+  /** The bill the shares are taken against. */
+  totalUsd: number;
+}
+
+/**
+ * Weakest first. A step *down* this ladder is what a route offers.
+ *
+ * `unknown` is absent on purpose rather than placed at one end: a model whose
+ * capability nobody recorded cannot be ranked against one whose capability is
+ * known, and guessing puts a real workload on a model chosen by a default value.
+ */
+const CAPABILITY_LADDER: Capability[] = ['small', 'mid', 'large', 'frontier'];
+
+/**
+ * The next step down, or `null` at the bottom and for `unknown`.
+ *
+ * One step, not the cheapest available. Frontier to small is an 80% saving and a
+ * different product, and offering it as the headline would be the arithmetic
+ * leading the advice — exactly the failure this file is written against. The
+ * reader who wants the bigger jump can ask for it once the first one holds.
+ */
+function stepDown(capability: Capability): Capability | null {
+  const at = CAPABILITY_LADDER.indexOf(capability);
+  return at <= 0 ? null : CAPABILITY_LADDER[at - 1]!;
+}
+
+/** What a breakdown's tokens would cost at a model's rates, split so batch can apply. */
+function repriceAt(
+  breakdown: UsageBreakdown,
+  model: ModelPricing,
+  on: Date,
+): { inputUsd: number; outputUsd: number; cacheUsd: number; totalUsd: number } {
+  const { inputPerMTok, outputPerMTok } = effectivePricing(model, on);
+  const rates = multipliersFor(model);
+  const per = (tokens: number, rate: number): number => (tokens / 1_000_000) * rate;
+
+  const inputUsd = per(breakdown.inputTokens, inputPerMTok);
+  const outputUsd = per(breakdown.outputTokens, outputPerMTok);
+  /**
+   * Cache writes at the 5-minute rate. The breakdown does not carry the recorded
+   * TTL split per class, so one has to be chosen — and the same choice sits on
+   * both sides of every subtraction here, so it cancels out of the saving. Worth
+   * stating rather than papering over: it would not cancel if the two models had
+   * different write multipliers, which is why a route never crosses a vendor.
+   */
+  const cacheUsd =
+    per(breakdown.cacheReadTokens, inputPerMTok * rates.cacheRead) +
+    per(breakdown.cacheWriteTokens, inputPerMTok * rates.cacheWrite5m);
+
+  return { inputUsd, outputUsd, cacheUsd, totalUsd: inputUsd + outputUsd + cacheUsd };
+}
+
+/**
+ * The cheapest recommendable model one capability step below, same provider.
+ *
+ * Same provider because switching vendor is a migration rather than a routing
+ * change, and the context window has to hold what these calls already sent — a
+ * cheaper model that cannot fit the prompt is not cheaper, it is broken.
+ */
+function candidateFor(
+  model: ModelPricing,
+  breakdown: UsageBreakdown,
+  catalogue: PricingCatalogue,
+  on: Date,
+): ModelPricing | null {
+  const target = stepDown(model.capability);
+  if (target === null) return null;
+
+  /**
+   * The largest single call cannot be recovered from a total, so this uses the
+   * **average** input per call and refuses any candidate that could not hold it.
+   * An average understates the peak, so this is the permissive direction — stated
+   * rather than hidden, because the reader will check the window properly when
+   * they run the evaluation this points them at.
+   */
+  const avgInput =
+    breakdown.calls === 0
+      ? 0
+      : (breakdown.inputTokens + breakdown.cacheReadTokens + breakdown.cacheWriteTokens) /
+        breakdown.calls;
+
+  const candidates = catalogue.models.filter(
+    (m) =>
+      m.id !== model.id &&
+      m.capability === target &&
+      m.provider === model.provider &&
+      m.recommendable !== false &&
+      m.contextWindow >= avgInput,
+  );
+  if (candidates.length === 0) return null;
+
+  return candidates.reduce((best, m) =>
+    repriceAt(breakdown, m, on).totalUsd < repriceAt(breakdown, best, on).totalUsd ? m : best,
+  );
+}
+
+export interface BillLeverOptions {
+  catalogue: PricingCatalogue;
+  /** Date the prices are read at, so a promotional rate resolves the same way. */
+  on?: Date;
+  /**
+   * Slices worth less than this share of the bill are dropped.
+   *
+   * Not a judgement about small money — a judgement about attention. Thirty rows
+   * worth a tenth of a percent each bury the two worth twenty, and a report nobody
+   * finishes reading is a report that changed nothing. Default 1%.
+   */
+  minShare?: number;
+}
+
+/**
+ * Prices the levers that are not the prompt, from a profile of real calls.
+ *
+ * Returns them ranked by money, with the ceiling on prompt shortening beside them
+ * so the comparison is unavoidable. Empty when nothing clears `minShare`, which is
+ * a legitimate answer: a bill already on the cheapest model of its family, with no
+ * batch API to reach for, has no lever here, and saying so is more useful than
+ * manufacturing one.
+ */
+export function billLevers(
+  report: UsageProfileReport,
+  options: BillLeverOptions,
+): BillLevers {
+  const { catalogue, on = new Date(), minShare = 0.01 } = options;
+  const totalUsd = report.total.totalUsd;
+
+  const promptCeilingUsd =
+    report.total.inputUsd + report.total.cacheReadUsd + report.total.cacheWriteUsd;
+
+  if (totalUsd <= 0) {
+    return { slices: [], promptCeilingUsd, promptCeilingShare: 0, totalUsd };
+  }
+
+  const slices: SliceLevers[] = [];
+
+  for (const { label, model: modelId, breakdown } of report.byLabelAndModel) {
+    const model = catalogue.byId.get(modelId);
+    // An unpriced model never reaches this list with dollars on it, and a lever
+    // computed from a zero bill is a saving invented out of nothing.
+    if (!model || breakdown.totalUsd <= 0) continue;
+
+    const candidate = candidateFor(model, breakdown, catalogue, on);
+    const routed = candidate ? repriceAt(breakdown, candidate, on) : null;
+    const route =
+      candidate && routed && breakdown.totalUsd - routed.totalUsd > 0
+        ? {
+            candidate: { id: candidate.id, displayName: candidate.displayName },
+            savingUsd: breakdown.totalUsd - routed.totalUsd,
+          }
+        : null;
+
+    /**
+     * `null` means the provider has no batch API, which is different from an
+     * unstated one — offering a discount nobody sells is worse than staying quiet.
+     *
+     * Applied to input and output only. The published discount covers those two
+     * lines; whether it also reaches cache reads and writes is not something this
+     * catalogue records, so they stay at full price. That understates the saving,
+     * which is the direction to be wrong in.
+     */
+    const batchRate = multipliersFor(model).batch;
+    const batchable = batchRate !== null && batchRate < 1;
+    const batch = batchable
+      ? { savingUsd: (breakdown.inputUsd + breakdown.outputUsd) * (1 - batchRate!) }
+      : null;
+
+    /**
+     * Both together — **computed, never summed.**
+     *
+     * Batching a routed call discounts the cheaper model's price, not the one you
+     * left behind. Adding the two figures produced a saving larger than the slice
+     * had ever cost: $12.60 and $10.50 against $21.00 spent.
+     */
+    const afterBoth = routed ?? {
+      inputUsd: breakdown.inputUsd,
+      outputUsd: breakdown.outputUsd,
+      cacheUsd: breakdown.cacheReadUsd + breakdown.cacheWriteUsd,
+      totalUsd: breakdown.totalUsd,
+    };
+    const combinedCost = batchable
+      ? afterBoth.totalUsd - (afterBoth.inputUsd + afterBoth.outputUsd) * (1 - batchRate!)
+      : afterBoth.totalUsd;
+    const combinedUsd = breakdown.totalUsd - combinedCost;
+
+    if (combinedUsd <= 0) continue;
+    const shareOfBill = combinedUsd / totalUsd;
+    if (shareOfBill < minShare) continue;
+
+    slices.push({
+      label,
+      model: modelId,
+      modelName: model.displayName,
+      calls: breakdown.calls,
+      spentUsd: breakdown.totalUsd,
+      route,
+      batch,
+      combinedUsd,
+      shareOfBill,
+    });
+  }
+
+  return {
+    slices: slices.sort((a, b) => b.combinedUsd - a.combinedUsd),
+    promptCeilingUsd,
+    promptCeilingShare: promptCeilingUsd / totalUsd,
+    totalUsd,
+  };
+}
+
+/** Named so a report can say "unlabelled" in the reader's language. */
+export { UNLABELLED };

package/src/node.ts

@@ -32,7 +32,7 @@ export {
   parseConfig,
   validateConfigModel,
 } from './config-schema.js';
-export type { ResolvedBudget, TrazumConfig } from './config-schema.js';
+export type { ResolvedBudget, SpendConfig, TrazumConfig } from './config-schema.js';
 
 // Local price corrections. Pure, so also on the main entry point; re-exported
 // here so the CLI has one import for everything it needs to resolve a run.

package/src/output-shape.ts

@@ -0,0 +1,254 @@
+import { effectivePricing } from './pricing.js';
+import { UNLABELLED } from './usage.js';
+import type { PricingCatalogue } from './pricing.js';
+import type { UsageRecord } from './usage.js';
+
+/**
+ * Where the output spend concentrates.
+ *
+ * ## The biggest line, and nothing said anything actionable about it
+ *
+ * Output is over half of many real bills — **87%** on the support prompt this
+ * repository measures itself against. `profile` could say that much and then
+ * stopped, because the advice that follows from "output dominates" is about
+ * answers rather than prompts, and the rules engine has nothing to offer there.
+ *
+ * But a total hides the shape, and the shape is the actionable part. Two bills
+ * with identical output spend want opposite responses:
+ *
+ * - **A tail.** Six per cent of calls hold half the output spend. Those calls are
+ *   doing something the other ninety-four are not — a different path through the
+ *   prompt, a runaway with no `max_tokens`, a retrieval that returned a book. They
+ *   are a morning's work and they are worth finding.
+ * - **Flat.** Forty-five per cent of calls hold half of it, which is what "evenly
+ *   spread" looks like. There is no tail to hunt; the answer length is inherent to
+ *   the task, and the only lever is asking every answer to be shorter.
+ *
+ * ## The split is derived, not chosen
+ *
+ * The figure reported is **the smallest group of calls that holds at least half the
+ * output spend**. Half is the point that divides the spend in two — a median over
+ * money rather than a threshold somebody picked — and the group is found by walking
+ * the distribution down from the longest answers until half the spend is covered.
+ *
+ * "At least half" is meant literally. The walk stops on a bucket boundary, so the
+ * group it names is a whole number of buckets and can overshoot; saying "half"
+ * flat would be claiming a precision the histogram does not have.
+ *
+ * ## Bounded memory, exact statement
+ *
+ * The counts live in fixed buckets rather than a list of every call, because a
+ * usage log is measured in megabytes. Every call inside an included bucket is at or
+ * above that bucket's lower edge, so **"calls producing more than N tokens" is
+ * exact** for the N this reports — it is only ever a bucket edge.
+ */
+
+/** How the output spend of one label-and-model slice is distributed. */
+export interface OutputShape {
+  label: string;
+  model: string;
+  modelName: string;
+  calls: number;
+  outputTokens: number;
+  outputUsd: number;
+  /** The bucket edge the heaviest group sits above. Always a bucket boundary. */
+  aboveTokens: number;
+  /** How many calls are in that group. */
+  heavyCalls: number;
+  /** Their share of the calls in this slice. */
+  heavyCallShare: number;
+  /** Their share of this slice's output spend — at least a half, by construction. */
+  heavySpendShare: number;
+  /** This slice's output spend as a fraction of the whole bill. */
+  shareOfBill: number;
+  /**
+   * The bucket ceiling that at least half the measured answers fit within.
+   *
+   * A ceiling by construction, never an interpolation: the histogram knows
+   * which bucket the median call landed in, and the honest sentence is "half
+   * the answers fit within N tokens" where N is that bucket's upper edge.
+   * `null` only when the covering bucket is the open-ended last one, which has
+   * no ceiling to name.
+   */
+  medianWithinTokens: number | null;
+  /**
+   * The same ceiling for 95% of the measured answers — the number somebody
+   * setting `max_tokens` actually wants. Measured on these calls, promised for
+   * nothing.
+   */
+  p95WithinTokens: number | null;
+}
+
+export interface OutputShapeOptions {
+  catalogue: PricingCatalogue;
+  on?: Date;
+  /** Slices whose output is below this share of the bill are dropped. Default 5%. */
+  minShare?: number;
+}
+
+/**
+ * Bucket edges, fine where answers actually land and coarse in the tail.
+ *
+ * 64 tokens up to 8,192 covers ordinary answers at a resolution finer than anybody
+ * would act on; past that the buckets widen, because the difference between a
+ * 40,000-token answer and a 41,000-token one changes no decision. The last bucket is
+ * open-ended so nothing falls off the end — an answer longer than the largest edge
+ * still counts, in the group where it belongs.
+ */
+const EDGES: number[] = (() => {
+  const edges: number[] = [];
+  for (let t = 0; t < 8192; t += 64) edges.push(t);
+  for (let t = 8192; t < 131_072; t += 1024) edges.push(t);
+  return edges;
+})();
+
+/** Index of the bucket a count falls in. The last bucket is open-ended. */
+function bucketOf(tokens: number): number {
+  if (tokens >= EDGES[EDGES.length - 1]!) return EDGES.length - 1;
+  if (tokens < 8192) return Math.floor(tokens / 64);
+  return 128 + Math.floor((tokens - 8192) / 1024);
+}
+
+/** A bucket's upper edge, or `null` for the open-ended last one. */
+function upperEdgeOf(bucket: number): number | null {
+  if (bucket >= EDGES.length - 1) return null;
+  return EDGES[bucket + 1]!;
+}
+
+/**
+ * The bucket ceiling covering `share` of the calls, walking up from the
+ * shortest answers. Exact over the histogram: every call at or below the
+ * returned ceiling is counted, none is interpolated.
+ */
+function ceilingFor(
+  buckets: Map<number, { calls: number; tokens: number }>,
+  totalCalls: number,
+  share: number,
+): number | null {
+  const ascending = [...buckets.keys()].sort((a, b) => a - b);
+  const target = totalCalls * share;
+  let covered = 0;
+  for (const b of ascending) {
+    covered += buckets.get(b)!.calls;
+    if (covered >= target) return upperEdgeOf(b);
+  }
+  return upperEdgeOf(ascending[ascending.length - 1]!);
+}
+
+interface Slice {
+  calls: number;
+  outputTokens: number;
+  outputUsd: number;
+  /** Calls and output tokens per bucket, sparse. */
+  buckets: Map<number, { calls: number; tokens: number }>;
+}
+
+export interface OutputShapeTracker {
+  add(record: UsageRecord): void;
+  finish(totalUsd: number): OutputShape[];
+}
+
+/**
+ * An accumulator, fed in the pass a profile already makes.
+ *
+ * What it holds is bounded by the number of slices times the number of buckets any
+ * of them actually touches, not by the size of the log.
+ */
+export function createOutputShapeTracker(options: OutputShapeOptions): OutputShapeTracker {
+  const { catalogue, on = new Date(), minShare = 0.05 } = options;
+  const slices = new Map<string, Slice>();
+
+  const add = (record: UsageRecord): void => {
+    const model = catalogue.byId.get(record.model);
+    // An unpriced model contributes no dollars anywhere else; a shape drawn from
+    // one would be a distribution of a bill that was never computed.
+    if (!model) return;
+    if (record.outputTokens <= 0) return;
+
+    const key = `${record.label ?? UNLABELLED}\n${record.model}`;
+    let slice = slices.get(key);
+    if (!slice) {
+      slice = { calls: 0, outputTokens: 0, outputUsd: 0, buckets: new Map() };
+      slices.set(key, slice);
+    }
+
+    const { outputPerMTok } = effectivePricing(model, on);
+    slice.calls += 1;
+    slice.outputTokens += record.outputTokens;
+    slice.outputUsd += (record.outputTokens / 1_000_000) * outputPerMTok;
+
+    const b = bucketOf(record.outputTokens);
+    const cell = slice.buckets.get(b);
+    if (cell) {
+      cell.calls += 1;
+      cell.tokens += record.outputTokens;
+    } else {
+      slice.buckets.set(b, { calls: 1, tokens: record.outputTokens });
+    }
+  };
+
+  const finish = (totalUsd: number): OutputShape[] => {
+    const out: OutputShape[] = [];
+
+    for (const [key, slice] of slices) {
+      const split = key.indexOf('\n');
+      const label = key.slice(0, split);
+      const modelId = key.slice(split + 1);
+      const model = catalogue.byId.get(modelId);
+      if (!model || slice.outputTokens === 0) continue;
+
+      const shareOfBill = totalUsd > 0 ? slice.outputUsd / totalUsd : 0;
+      if (shareOfBill < minShare) continue;
+
+      /**
+       * Walk down from the longest answers until half the output spend is
+       * covered. Spend is proportional to tokens inside one slice — one model,
+       * one rate — so the tokens are the money here and no second accumulator is
+       * needed.
+       */
+      const target = slice.outputTokens / 2;
+      const descending = [...slice.buckets.keys()].sort((a, b) => b - a);
+      let tokens = 0;
+      let heavyCalls = 0;
+      let lastBucket = descending[0]!;
+      for (const b of descending) {
+        const cell = slice.buckets.get(b)!;
+        tokens += cell.tokens;
+        heavyCalls += cell.calls;
+        lastBucket = b;
+        if (tokens >= target) break;
+      }
+
+      out.push({
+        label,
+        model: modelId,
+        modelName: model.displayName,
+        calls: slice.calls,
+        outputTokens: slice.outputTokens,
+        outputUsd: slice.outputUsd,
+        aboveTokens: EDGES[lastBucket]!,
+        heavyCalls,
+        heavyCallShare: heavyCalls / slice.calls,
+        heavySpendShare: tokens / slice.outputTokens,
+        shareOfBill,
+        medianWithinTokens: ceilingFor(slice.buckets, slice.calls, 0.5),
+        p95WithinTokens: ceilingFor(slice.buckets, slice.calls, 0.95),
+      });
+    }
+
+    return out.sort((a, b) => b.outputUsd - a.outputUsd);
+  };
+
+  return { add, finish };
+}
+
+/** The same measurement over a list of records, for a caller holding one. */
+export function outputShapes(
+  records: readonly UsageRecord[],
+  totalUsd: number,
+  options: OutputShapeOptions,
+): OutputShape[] {
+  const tracker = createOutputShapeTracker(options);
+  for (const record of records) tracker.add(record);
+  return tracker.finish(totalUsd);
+}

package/src/pricing-overlay.ts

@@ -1,7 +1,7 @@
 import { BUNDLED_CATALOGUE } from './pricing.js';
 import { nearestName } from './nearest.js';
 import type { PricingCatalogue } from './pricing.js';
-import type { Capability, CachingMode, ModelPricing } from './types.js';
+import type { Capability, CachingMode, CostMultipliers, ModelPricing } from './types.js';
 
 /**
  * Local price corrections, so a price change does not require a library upgrade.
@@ -34,10 +34,28 @@ export const PRICING_MODEL_KEYS = [
   'caching',
   'notes',
   'promo',
+  'multipliers',
 ] as const;
 
 const PROMO_KEYS = ['inputPerMTok', 'outputPerMTok', 'until'] as const;
 
+/**
+ * Cache and batch rates, which an overlay had no way to state — and had to.
+ *
+ * Without this, a model added through `--pricing` silently inherited Anthropic's
+ * multipliers: a cache write at 1.25x input, or 2x at the long TTL. Most
+ * providers charge plain input for a write, so `trazum profile` computed a
+ * premium that model never charged, accused the workload of a caching loss it
+ * could not have, and told the reader to turn caching off. Three documents
+ * claimed that could not happen to a provider whose writes cost what input costs,
+ * and for an overlay model it was exactly what happened.
+ *
+ * `batch` accepts `null`, which is not the same as leaving it out: "this provider
+ * has no batch API" should stop the advisory offering a discount nobody sells,
+ * while "nobody has said" should fall back to the default.
+ */
+const MULTIPLIER_KEYS = ['cacheRead', 'cacheWrite5m', 'cacheWrite1h', 'batch'] as const;
+
 const TIERS: ModelPricing['tier'][] = ['frontier', 'opus', 'sonnet', 'haiku', 'unknown'];
 const CAPABILITIES: Capability[] = ['small', 'mid', 'large', 'frontier', 'unknown'];
 const CACHING_MODES: CachingMode[] = ['explicit', 'automatic', 'none', 'unknown'];
@@ -129,6 +147,36 @@ function parsePromo(raw: unknown, label: string, source: string): ModelPricing['
   };
 }
 
+function parseMultipliers(raw: unknown, label: string, source: string): CostMultipliers {
+  if (!isPlainObject(raw)) {
+    throw new PricingOverlayError(`"${label}" must be an object`, source);
+  }
+  rejectUnknownKeys(raw, MULTIPLIER_KEYS, source, `${label}.`);
+  if (Object.keys(raw).length === 0) {
+    throw new PricingOverlayError(
+      `"${label}" is empty — remove it, or say which rate it changes`,
+      source,
+    );
+  }
+
+  const multipliers: CostMultipliers = {};
+  for (const key of ['cacheRead', 'cacheWrite5m', 'cacheWrite1h'] as const) {
+    if (raw[key] === undefined) continue;
+    /**
+     * Zero is refused along with the negatives. A free cache read is not a price
+     * anybody publishes, and admitting one would let an overlay typo turn a real
+     * cost into no cost — the flattering direction, and the one this whole file
+     * exists to keep out of a report.
+     */
+    multipliers[key] = positiveNumber(raw[key], `${label}.${key}`, source);
+  }
+  if (raw.batch !== undefined) {
+    multipliers.batch =
+      raw.batch === null ? null : positiveNumber(raw.batch, `${label}.batch`, source);
+  }
+  return multipliers;
+}
+
 function parseModel(
   raw: unknown,
   id: string,
@@ -209,6 +257,9 @@ function parseModel(
     // `null` is how you cancel a bundled promotion that has been withdrawn.
     model.promo = raw.promo === null ? undefined : parsePromo(raw.promo, `models.${id}.promo`, source);
   }
+  if (raw.multipliers !== undefined) {
+    model.multipliers = parseMultipliers(raw.multipliers, `models.${id}.multipliers`, source);
+  }
 
   return model;
 }