@trazum/core 1.10.0 → 1.26.0

package/dist/input-shape.js

@@ -0,0 +1,132 @@
+import { effectivePricing, multipliersFor } from './pricing.js';
+import { UNLABELLED } from './usage.js';
+/**
+ * Bucket edges sized for requests rather than answers.
+ *
+ * 512 tokens up to 65,536 is finer than any decision about a prompt, and past
+ * that the buckets widen to 8,192: the difference between a 400,000-token
+ * request and a 404,000-token one changes nothing. The last bucket is
+ * open-ended so a call larger than the widest edge still lands somewhere,
+ * counted rather than dropped.
+ */
+const SMALL_STEP = 512;
+const SMALL_LIMIT = 65_536;
+const LARGE_STEP = 8_192;
+const LARGE_LIMIT = 1_048_576;
+const EDGES = (() => {
+    const edges = [];
+    for (let t = 0; t < SMALL_LIMIT; t += SMALL_STEP)
+        edges.push(t);
+    for (let t = SMALL_LIMIT; t < LARGE_LIMIT; t += LARGE_STEP)
+        edges.push(t);
+    return edges;
+})();
+const SMALL_BUCKETS = SMALL_LIMIT / SMALL_STEP;
+/** Index of the bucket a count falls in. The last bucket is open-ended. */
+function bucketOf(tokens) {
+    if (tokens >= EDGES[EDGES.length - 1])
+        return EDGES.length - 1;
+    if (tokens < SMALL_LIMIT)
+        return Math.floor(tokens / SMALL_STEP);
+    return SMALL_BUCKETS + Math.floor((tokens - SMALL_LIMIT) / LARGE_STEP);
+}
+/** A bucket's upper edge, or `null` for the open-ended last one. */
+function upperEdgeOf(bucket) {
+    if (bucket >= EDGES.length - 1)
+        return null;
+    return EDGES[bucket + 1];
+}
+/**
+ * The bucket ceiling covering `share` of the calls, walking up from the
+ * smallest requests. Exact over the histogram: every call at or below the
+ * returned ceiling is counted, none is interpolated.
+ */
+function ceilingFor(buckets, totalCalls, share) {
+    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);
+        if (covered >= target)
+            return upperEdgeOf(b);
+    }
+    return upperEdgeOf(ascending[ascending.length - 1]);
+}
+/** An accumulator, fed in the pass a profile already makes. */
+export function createInputShapeTracker(options) {
+    const { catalogue, on = new Date(), minShare = 0.05, minCalls = 20 } = options;
+    const slices = new Map();
+    const add = (record) => {
+        const model = catalogue.byId.get(record.model);
+        // An unpriced model contributes no dollars anywhere else; a shape drawn
+        // from one would describe a bill that was never computed.
+        if (!model)
+            return;
+        const tokens = record.inputTokens +
+            record.cacheReadTokens +
+            record.cacheWrite5mTokens +
+            record.cacheWrite1hTokens;
+        if (tokens <= 0)
+            return;
+        const key = `${record.label ?? UNLABELLED}\n${record.model}`;
+        let slice = slices.get(key);
+        if (!slice) {
+            slice = { calls: 0, inputTokens: 0, cachedTokens: 0, inputUsd: 0, buckets: new Map() };
+            slices.set(key, slice);
+        }
+        const { inputPerMTok } = effectivePricing(model, on);
+        const rates = multipliersFor(model);
+        const per = (count, rate) => (count / 1_000_000) * rate;
+        slice.calls += 1;
+        slice.inputTokens += tokens;
+        slice.cachedTokens += record.cacheReadTokens;
+        slice.inputUsd +=
+            per(record.inputTokens, inputPerMTok) +
+                per(record.cacheReadTokens, inputPerMTok * rates.cacheRead) +
+                per(record.cacheWrite5mTokens, inputPerMTok * rates.cacheWrite5m) +
+                per(record.cacheWrite1hTokens, inputPerMTok * rates.cacheWrite1h);
+        const b = bucketOf(tokens);
+        slice.buckets.set(b, (slice.buckets.get(b) ?? 0) + 1);
+    };
+    const finish = (totalUsd) => {
+        const out = [];
+        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.calls < minCalls)
+                continue;
+            const shareOfBill = totalUsd > 0 ? slice.inputUsd / totalUsd : 0;
+            if (shareOfBill < minShare)
+                continue;
+            const medianWithinTokens = ceilingFor(slice.buckets, slice.calls, 0.5);
+            const p95WithinTokens = ceilingFor(slice.buckets, slice.calls, 0.95);
+            out.push({
+                label,
+                model: modelId,
+                modelName: model.displayName,
+                calls: slice.calls,
+                inputTokens: slice.inputTokens,
+                inputUsd: slice.inputUsd,
+                shareOfBill,
+                medianWithinTokens,
+                p95WithinTokens,
+                p95OverMedian: medianWithinTokens !== null && p95WithinTokens !== null && medianWithinTokens > 0
+                    ? p95WithinTokens / medianWithinTokens
+                    : null,
+                cachedShare: slice.inputTokens > 0 ? slice.cachedTokens / slice.inputTokens : 0,
+            });
+        }
+        return out.sort((a, b) => b.inputUsd - a.inputUsd);
+    };
+    return { add, finish };
+}
+/** The same measurement over a list of records, for a caller holding one. */
+export function inputShapes(records, totalUsd, options) {
+    const tracker = createInputShapeTracker(options);
+    for (const record of records)
+        tracker.add(record);
+    return tracker.finish(totalUsd);
+}
+//# sourceMappingURL=input-shape.js.map

package/dist/input-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-shape.js","sourceRoot":"","sources":["../src/input-shape.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAoGxC;;;;;;;;GAQG;AACH,MAAM,UAAU,GAAG,GAAG,CAAC;AACvB,MAAM,WAAW,GAAG,MAAM,CAAC;AAC3B,MAAM,UAAU,GAAG,KAAK,CAAC;AACzB,MAAM,WAAW,GAAG,SAAS,CAAC;AAE9B,MAAM,KAAK,GAAa,CAAC,GAAG,EAAE;IAC5B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,IAAI,UAAU;QAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAChE,KAAK,IAAI,CAAC,GAAG,WAAW,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,IAAI,UAAU;QAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1E,OAAO,KAAK,CAAC;AACf,CAAC,CAAC,EAAE,CAAC;AAEL,MAAM,aAAa,GAAG,WAAW,GAAG,UAAU,CAAC;AAE/C,2EAA2E;AAC3E,SAAS,QAAQ,CAAC,MAAc;IAC9B,IAAI,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE;QAAE,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;IAChE,IAAI,MAAM,GAAG,WAAW;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC;IACjE,OAAO,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,WAAW,CAAC,GAAG,UAAU,CAAC,CAAC;AACzE,CAAC;AAED,oEAAoE;AACpE,SAAS,WAAW,CAAC,MAAc;IACjC,IAAI,MAAM,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,OAA4B,EAAE,UAAkB,EAAE,KAAa;IACjF,MAAM,SAAS,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5D,MAAM,MAAM,GAAG,UAAU,GAAG,KAAK,CAAC;IAClC,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC;QAC3B,IAAI,OAAO,IAAI,MAAM;YAAE,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,WAAW,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,CAAC;AACvD,CAAC;AAgBD,+DAA+D;AAC/D,MAAM,UAAU,uBAAuB,CAAC,OAA0B;IAChE,MAAM,EAAE,SAAS,EAAE,EAAE,GAAG,IAAI,IAAI,EAAE,EAAE,QAAQ,GAAG,IAAI,EAAE,QAAQ,GAAG,EAAE,EAAE,GAAG,OAAO,CAAC;IAC/E,MAAM,MAAM,GAAG,IAAI,GAAG,EAAiB,CAAC;IAExC,MAAM,GAAG,GAAG,CAAC,MAAmB,EAAQ,EAAE;QACxC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC/C,wEAAwE;QACxE,0DAA0D;QAC1D,IAAI,CAAC,KAAK;YAAE,OAAO;QAEnB,MAAM,MAAM,GACV,MAAM,CAAC,WAAW;YAClB,MAAM,CAAC,eAAe;YACtB,MAAM,CAAC,kBAAkB;YACzB,MAAM,CAAC,kBAAkB,CAAC;QAC5B,IAAI,MAAM,IAAI,CAAC;YAAE,OAAO;QAExB,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,KAAK,IAAI,UAAU,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC;QAC7D,IAAI,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;YACvF,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACzB,CAAC;QAED,MAAM,EAAE,YAAY,EAAE,GAAG,gBAAgB,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACrD,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;QACpC,MAAM,GAAG,GAAG,CAAC,KAAa,EAAE,IAAY,EAAU,EAAE,CAAC,CAAC,KAAK,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC;QAEhF,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;QACjB,KAAK,CAAC,WAAW,IAAI,MAAM,CAAC;QAC5B,KAAK,CAAC,YAAY,IAAI,MAAM,CAAC,eAAe,CAAC;QAC7C,KAAK,CAAC,QAAQ;YACZ,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,YAAY,CAAC;gBACrC,GAAG,CAAC,MAAM,CAAC,eAAe,EAAE,YAAY,GAAG,KAAK,CAAC,SAAS,CAAC;gBAC3D,GAAG,CAAC,MAAM,CAAC,kBAAkB,EAAE,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;gBACjE,GAAG,CAAC,MAAM,CAAC,kBAAkB,EAAE,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;QAEpE,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC3B,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,CAAC,CAAC;IAEF,MAAM,MAAM,GAAG,CAAC,QAAgB,EAAgB,EAAE;QAChD,MAAM,GAAG,GAAiB,EAAE,CAAC;QAE7B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAChC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YAClC,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;YACrC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAC1C,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,GAAG,QAAQ;gBAAE,SAAS;YAE/C,MAAM,WAAW,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;YACjE,IAAI,WAAW,GAAG,QAAQ;gBAAE,SAAS;YAErC,MAAM,kBAAkB,GAAG,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YACvE,MAAM,eAAe,GAAG,UAAU,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;YAErE,GAAG,CAAC,IAAI,CAAC;gBACP,KAAK;gBACL,KAAK,EAAE,OAAO;gBACd,SAAS,EAAE,KAAK,CAAC,WAAW;gBAC5B,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,WAAW;gBACX,kBAAkB;gBAClB,eAAe;gBACf,aAAa,EACX,kBAAkB,KAAK,IAAI,IAAI,eAAe,KAAK,IAAI,IAAI,kBAAkB,GAAG,CAAC;oBAC/E,CAAC,CAAC,eAAe,GAAG,kBAAkB;oBACtC,CAAC,CAAC,IAAI;gBACV,WAAW,EAAE,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;aAChF,CAAC,CAAC;QACL,CAAC;QAED,OAAO,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;IACrD,CAAC,CAAC;IAEF,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;AACzB,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,WAAW,CACzB,OAA+B,EAC/B,QAAgB,EAChB,OAA0B;IAE1B,MAAM,OAAO,GAAG,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjD,KAAK,MAAM,MAAM,IAAI,OAAO;QAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAClD,OAAO,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AAClC,CAAC"}

package/dist/levers.d.ts

@@ -0,0 +1,151 @@
+import { UNLABELLED } from './usage.js';
+import type { PricingCatalogue } from './pricing.js';
+import type { UsageProfileReport } from './usage.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;
+}
+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 declare function billLevers(report: UsageProfileReport, options: BillLeverOptions): BillLevers;
+/** Named so a report can say "unlabelled" in the reader's language. */
+export { UNLABELLED };
+//# sourceMappingURL=levers.d.ts.map

package/dist/levers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"levers.d.ts","sourceRoot":"","sources":["../src/levers.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAkB,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,uBAAuB;AACvB,MAAM,MAAM,OAAO;AACjB,8DAA8D;AAC5D,OAAO;AACT,8CAA8C;GAC5C,OAAO,CAAC;AAEZ;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,KAAK,EAAE;QAAE,SAAS,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,WAAW,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACpF,mDAAmD;IACnD,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACpC;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;CAClB;AA8FD,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,gFAAgF;IAChF,EAAE,CAAC,EAAE,IAAI,CAAC;IACV;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,kBAAkB,EAC1B,OAAO,EAAE,gBAAgB,GACxB,UAAU,CAqFZ;AAED,uEAAuE;AACvE,OAAO,EAAE,UAAU,EAAE,CAAC"}

package/dist/levers.js

@@ -0,0 +1,160 @@
+import { effectivePricing, multipliersFor } from './pricing.js';
+import { UNLABELLED } from './usage.js';
+/**
+ * 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 = ['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) {
+    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, model, on) {
+    const { inputPerMTok, outputPerMTok } = effectivePricing(model, on);
+    const rates = multipliersFor(model);
+    const per = (tokens, rate) => (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, breakdown, catalogue, on) {
+    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);
+}
+/**
+ * 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, options) {
+    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 = [];
+    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 };
+//# sourceMappingURL=levers.js.map

package/dist/levers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"levers.js","sourceRoot":"","sources":["../src/levers.ts"],"names":[],"mappings":"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"}

package/dist/node.d.ts

@@ -17,7 +17,7 @@
 export { loadConfig } from './config.js';
 export type { LoadConfigOptions, LoadedConfig } from './config.js';
 export { CONFIG_FILENAME, CONFIG_KEYS, CONFIG_USAGE_KEYS, ConfigError, DEFAULT_EXTENSIONS, MAX_CONFIG_BYTES, MAX_CONFIG_SEARCH_DEPTH, budgetFor, parseConfig, validateConfigModel, } from './config-schema.js';
-export type { ResolvedBudget, TrazumConfig } from './config-schema.js';
+export type { ResolvedBudget, SpendConfig, TrazumConfig } from './config-schema.js';
 export { MAX_PRICING_BYTES, PricingOverlayError, applyPricingOverlay, catalogueFromOverlay, parsePricingOverlay, } from './pricing-overlay.js';
 export type { PricingOverlay } from './pricing-overlay.js';
 export { openrouterOverlay } from './openrouter.js';

package/dist/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAInE,OAAO,EACL,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,SAAS,EACT,WAAW,EACX,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvE,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGxD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAInE,OAAO,EACL,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,SAAS,EACT,WAAW,EACX,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIpF,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGxD,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC"}

package/dist/output-shape.d.ts

@@ -0,0 +1,96 @@
+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;
+}
+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 declare function createOutputShapeTracker(options: OutputShapeOptions): OutputShapeTracker;
+/** The same measurement over a list of records, for a caller holding one. */
+export declare function outputShapes(records: readonly UsageRecord[], totalUsd: number, options: OutputShapeOptions): OutputShape[];
+//# sourceMappingURL=output-shape.d.ts.map

package/dist/output-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-shape.d.ts","sourceRoot":"","sources":["../src/output-shape.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,wEAAwE;AACxE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;IACvB,mFAAmF;IACnF,eAAe,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;;OAQG;IACH,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC;;;;OAIG;IACH,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,gBAAgB,CAAC;IAC5B,EAAE,CAAC,EAAE,IAAI,CAAC;IACV,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA2DD,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC/B,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;CACzC;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,kBAAkB,GAAG,kBAAkB,CAsFxF;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAC1B,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,kBAAkB,GAC1B,WAAW,EAAE,CAIf"}