@trazum/core 1.8.0 → 1.10.0

package/dist/usage.d.ts

@@ -0,0 +1,219 @@
+import type { PricingCatalogue } from './pricing.js';
+/**
+ * Where the money actually went, from calls that actually happened.
+ *
+ * ## Why this exists
+ *
+ * Everything else in this package reads a **prompt file** and reasons about what
+ * it would cost. That is the smallest line item on most bills, and the gap is not
+ * small enough to argue about: measured on an ordinary support prompt, the
+ * deterministic rules recover about **1%** of the monthly figure, while output
+ * tokens alone were **87%** of it. A tool that reads `prompts/*.txt` cannot see
+ * retrieved context, conversation history, tool results or answers, and on a RAG
+ * or agent workload those are nearly the whole invoice.
+ *
+ * So this reads the other direction: **what the provider actually charged**, per
+ * call, and says where it went. The sentence it is built to produce is "63% of
+ * your bill is retrieved context and nothing is watching it", which is a fact
+ * about a system rather than an estimate about a file.
+ *
+ * ## It reads a file, and that is the design
+ *
+ * Not a proxy, not an SDK wrapper, not a callback. Trazum's whole security
+ * position is that prompts do not leave the machine they are on — asserted by
+ * tests, not promised — and a tool that sits in the request path trades that away
+ * for convenience. A JSON Lines file is something you already have or can produce
+ * in three lines, and it keeps the guarantee intact.
+ *
+ * ## The format is the one the API already gives you
+ *
+ * Nothing is invented here. Every Anthropic response carries a `usage` object
+ * with exactly these fields, so recording a call is:
+ *
+ * ```ts
+ * appendFileSync('usage.jsonl', JSON.stringify({
+ *   model: response.model,
+ *   ...response.usage,
+ * }) + '\n');
+ * ```
+ *
+ * OpenAI's `usage` maps onto the same shape with different names, and
+ * `parseUsageLine` accepts both. Asking somebody to transform their logs into a
+ * bespoke schema before a tool will read them is how a tool goes unused.
+ *
+ * ## What it refuses to do
+ *
+ * **It does not read prompt text and there is nowhere to put it.** The record
+ * shape has no field for content, so a usage log handed to Trazum cannot contain
+ * a prompt even by accident. That is a stronger promise than "we do not look at
+ * it", and it is the reason this takes counts rather than calls.
+ *
+ * **It reports no saving.** Attributing "you could have saved X" to a call that
+ * already happened means guessing what the call should have been, and this module
+ * exists precisely because guessing is what the rest of the package has to do.
+ * It reports what was spent, split by where it went. What to do about it is a
+ * different question and belongs to the advisories.
+ */
+/** One recorded call, after parsing. All counts, no content. */
+export interface UsageRecord {
+    /** Model id as the provider reported it. */
+    model: string;
+    /** Uncached input tokens billed at the full rate. */
+    inputTokens: number;
+    /** Tokens billed at the cache-read rate. Zero when nothing was cached. */
+    cacheReadTokens: number;
+    /** Cache writes at the 5-minute rate — 1.25x input on Anthropic. */
+    cacheWrite5mTokens: number;
+    /** Cache writes at the 1-hour rate, which is **2x** input, not 1.25x. */
+    cacheWrite1hTokens: number;
+    /**
+     * Whether the log said which TTL those writes used.
+     *
+     * `false` when only the flat `cache_creation_input_tokens` was present and it
+     * was non-zero: the writes are then priced at the cheaper 5-minute rate because
+     * one of the two has to be assumed, and the report says so. Choosing the cheaper
+     * rate silently understates a 1-hour workload by 37.5% on its largest line.
+     */
+    writeTtlKnown: boolean;
+    outputTokens: number;
+    /**
+     * Optional label for grouping — an endpoint, a feature, a prompt name.
+     *
+     * The whole value of a profile is answering "which part of the product costs
+     * this", and without a label every call looks alike. Unlabelled records are
+     * grouped under a single bucket rather than dropped, because a profile that
+     * refuses to read a log until it is annotated is a profile nobody runs.
+     */
+    label: string | null;
+}
+/** What a set of calls cost, split by where the money went. */
+export interface UsageBreakdown {
+    calls: number;
+    inputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+    /**
+     * Calls whose cache-write TTL the log did not state, so the cheaper rate was
+     * assumed. Non-zero means this total is a floor on those calls, not a figure.
+     */
+    assumedWriteTtlCalls: number;
+    inputUsd: number;
+    cacheReadUsd: number;
+    cacheWriteUsd: number;
+    outputUsd: number;
+    totalUsd: number;
+}
+export interface UsageProfileReport {
+    /** Everything, combined. */
+    total: UsageBreakdown;
+    /** Per `label`, largest bill first — the order somebody would act in. */
+    byLabel: Array<{
+        label: string;
+        breakdown: UsageBreakdown;
+    }>;
+    /** Per model, largest bill first. */
+    byModel: Array<{
+        model: string;
+        breakdown: UsageBreakdown;
+    }>;
+    /**
+     * Models in the log that the pricing catalogue does not know.
+     *
+     * Named rather than silently costed at zero. A profile that quietly omits a
+     * model reports a total lower than the real bill, which is the flattering
+     * direction and the one this repository refuses.
+     */
+    unpricedModels: string[];
+    /**
+     * What those models used, kept entirely out of `total`.
+     *
+     * The first version added their **tokens** to the totals and their **dollars**
+     * to nothing, because pricing failed after the counts had been accumulated. So
+     * `total.inputTokens` included them and `total.inputUsd` did not, and anybody
+     * dividing one by the other got a cost per token that was wrong by however much
+     * of the log was unpriced — silently, and low.
+     *
+     * They are separated now. `total` is what could be priced, tokens and dollars
+     * describing the same calls. This is what could not, so the size of the gap is
+     * visible instead of being folded into a number that looks complete.
+     */
+    unpriced: UsageBreakdown;
+    /**
+     * Lines that could not be read, with their 1-based position.
+     *
+     * Reported rather than thrown on. A log with three malformed lines out of forty
+     * thousand should still produce a profile, and a parser that dies on the first
+     * one makes the tool unusable on real data — but a parser that skips quietly
+     * produces a total that is wrong by an unknown amount.
+     */
+    skippedLines: number[];
+}
+/** The share of the bill each part accounts for, as fractions of 1. */
+export interface UsageShares {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+}
+/**
+ * One line of a usage log, or `null` when it is not one.
+ *
+ * Accepts the Anthropic shape and the OpenAI one, because those are the two
+ * things people actually have. The alternative — a Trazum-specific schema — asks
+ * for a transformation step before the tool will read anything, and a tool with a
+ * setup cost that exceeds its payoff does not get run twice.
+ *
+ * `null` in three cases, and the third is the one that was wrong:
+ *
+ * 1. Not JSON, or not an object, or no `model`.
+ * 2. **No** token counts at all — counting it would inflate the call count while
+ *    contributing nothing, which lowers every per-call figure.
+ * 3. **Any** count present but unreadable. A field that is there and unusable is
+ *    corruption, and a corrupt line belongs in `skippedLines` where the report
+ *    names it, not in the totals as a silent zero.
+ */
+export declare function parseUsageLine(line: string): UsageRecord | null;
+/** The bucket unlabelled calls land in, named so a report can say so. */
+export declare const UNLABELLED = "unlabelled";
+export interface UsageProfileOptions {
+    catalogue: PricingCatalogue;
+    /** Date the prices are read at, so a promotional rate resolves the same way. */
+    on?: Date;
+}
+/**
+ * Reads a usage log and says where the money went.
+ *
+ * Takes the whole text rather than a stream: a usage log is measured in megabytes
+ * and this package imports no Node builtins, so streaming would mean an interface
+ * the browser build cannot satisfy. `@trazum/core/node` is where file reading
+ * lives, and it can chunk if it ever needs to.
+ */
+export declare function profileUsage(text: string, options: UsageProfileOptions): UsageProfileReport;
+/**
+ * What share of the bill each part is.
+ *
+ * The point of the whole module in one function: a caller can print "output is
+ * 87% of this" without doing arithmetic that would drift from the arithmetic
+ * here.
+ *
+ * All zeroes when nothing was spent, rather than `NaN`. A profile of an empty log
+ * is a legitimate result — no calls yet — and a report full of `NaN%` is a bug
+ * report from somebody who did nothing wrong.
+ */
+export declare function sharesOf(breakdown: UsageBreakdown): UsageShares;
+/**
+ * How much of the input that could have been cached was.
+ *
+ * `null` when nothing was cacheable-looking at all — no reads and no writes —
+ * because a hit rate over zero attempts is not zero, it is undefined, and
+ * printing "0% cache hit rate" for somebody who never turned caching on is a
+ * finding about nothing.
+ *
+ * Reads against reads-plus-full-price-input, deliberately. Cache *writes* are
+ * excluded from the denominator: a write is the cost of establishing an entry,
+ * not a missed read, and counting it as a miss makes a healthy cache look broken
+ * on the day it warms.
+ */
+export declare function cacheHitRate(breakdown: UsageBreakdown): number | null;
+//# sourceMappingURL=usage.d.ts.map

package/dist/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../src/usage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,gEAAgE;AAChE,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,eAAe,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,yEAAyE;IACzE,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,4BAA4B;IAC5B,KAAK,EAAE,cAAc,CAAC;IACtB,yEAAyE;IACzE,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;IAC7D,qCAAqC;IACrC,OAAO,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;IAC7D;;;;;;OAMG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB;;;;;;;;;;;;OAYG;IACH,QAAQ,EAAE,cAAc,CAAC;IACzB;;;;;;;OAOG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,uEAAuE;AACvE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAoDD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAuF/D;AAED,yEAAyE;AACzE,eAAO,MAAM,UAAU,eAAe,CAAC;AAiDvC,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,gBAAgB,CAAC;IAC5B,gFAAgF;IAChF,EAAE,CAAC,EAAE,IAAI,CAAC;CACX;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAyD3F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,SAAS,EAAE,cAAc,GAAG,WAAW,CAS/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,cAAc,GAAG,MAAM,GAAG,IAAI,CAKrE"}

package/dist/usage.js

@@ -0,0 +1,274 @@
+import { effectivePricing, multipliersFor } from './pricing.js';
+const EMPTY = () => ({
+    calls: 0,
+    inputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    outputTokens: 0,
+    assumedWriteTtlCalls: 0,
+    inputUsd: 0,
+    cacheReadUsd: 0,
+    cacheWriteUsd: 0,
+    outputUsd: 0,
+    totalUsd: 0,
+});
+const OK = (value) => ({ kind: 'ok', value });
+function readCount(...candidates) {
+    let sawCorrupt = false;
+    for (const value of candidates) {
+        if (value === undefined)
+            continue;
+        if (typeof value === 'number' && Number.isFinite(value) && value >= 0)
+            return OK(value);
+        // Present and unusable: a string, a null, a negative, a NaN.
+        sawCorrupt = true;
+    }
+    return sawCorrupt ? { kind: 'corrupt' } : { kind: 'absent' };
+}
+/** Zero for an absent count. Callers reject corrupt ones before reaching this. */
+const valueOf = (count) => (count.kind === 'ok' ? count.value : 0);
+/**
+ * One line of a usage log, or `null` when it is not one.
+ *
+ * Accepts the Anthropic shape and the OpenAI one, because those are the two
+ * things people actually have. The alternative — a Trazum-specific schema — asks
+ * for a transformation step before the tool will read anything, and a tool with a
+ * setup cost that exceeds its payoff does not get run twice.
+ *
+ * `null` in three cases, and the third is the one that was wrong:
+ *
+ * 1. Not JSON, or not an object, or no `model`.
+ * 2. **No** token counts at all — counting it would inflate the call count while
+ *    contributing nothing, which lowers every per-call figure.
+ * 3. **Any** count present but unreadable. A field that is there and unusable is
+ *    corruption, and a corrupt line belongs in `skippedLines` where the report
+ *    names it, not in the totals as a silent zero.
+ */
+export function parseUsageLine(line) {
+    let raw;
+    try {
+        raw = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return null;
+    const record = raw;
+    // Anthropic nests usage on a response; a hand-rolled log usually flattens it.
+    const usage = typeof record.usage === 'object' && record.usage !== null
+        ? record.usage
+        : record;
+    const model = typeof record.model === 'string' ? record.model : null;
+    if (!model)
+        return null;
+    /**
+     * OpenAI reports cached tokens inside `prompt_tokens_details` **and counts them
+     * 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.
+     */
+    const details = typeof usage.prompt_tokens_details === 'object' && usage.prompt_tokens_details !== null
+        ? usage.prompt_tokens_details
+        : null;
+    const openAiCached = details ? readCount(details.cached_tokens) : { kind: 'absent' };
+    /**
+     * Anthropic splits cache writes by time-to-live, and the two cost different
+     * amounts: 1.25x input for the 5-minute entry, **2x** for the 1-hour one.
+     *
+     * Reading only the flat `cache_creation_input_tokens` threw that distinction
+     * away and then priced everything at the cheaper rate — a 1-hour workload
+     * reported 37.5% under, silently, on its largest line. The split is in the log
+     * whenever the recording recipe in the README is followed, because it is part of
+     * the `usage` object the API returns.
+     */
+    const creation = typeof usage.cache_creation === 'object' && usage.cache_creation !== null
+        ? usage.cache_creation
+        : null;
+    const write5m = creation ? readCount(creation.ephemeral_5m_input_tokens) : { kind: 'absent' };
+    const write1h = creation ? readCount(creation.ephemeral_1h_input_tokens) : { kind: 'absent' };
+    const counts = {
+        input: readCount(usage.input_tokens, usage.inputTokens, usage.prompt_tokens),
+        output: readCount(usage.output_tokens, usage.outputTokens, usage.completion_tokens),
+        cacheRead: readCount(usage.cache_read_input_tokens, usage.cacheReadTokens),
+        cacheWrite: readCount(usage.cache_creation_input_tokens, usage.cacheWriteTokens),
+        openAiCached,
+        write5m,
+        write1h,
+    };
+    // Any field present and unreadable rejects the line. See `readCount`.
+    if (Object.values(counts).some((c) => c.kind === 'corrupt'))
+        return null;
+    // Nothing to count at all.
+    if (Object.values(counts).every((c) => c.kind === 'absent'))
+        return null;
+    const cached = valueOf(counts.openAiCached);
+    const flatWrite = valueOf(counts.cacheWrite);
+    const split5m = valueOf(counts.write5m);
+    const split1h = valueOf(counts.write1h);
+    const hasSplit = counts.write5m.kind === 'ok' || counts.write1h.kind === 'ok';
+    return {
+        model,
+        inputTokens: Math.max(0, valueOf(counts.input) - cached),
+        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,
+        cacheWrite1hTokens: hasSplit ? split1h : 0,
+        writeTtlKnown: hasSplit || flatWrite === 0,
+        outputTokens: valueOf(counts.output),
+        label: typeof record.label === 'string' && record.label.trim() !== ''
+            ? record.label.trim()
+            : null,
+    };
+}
+/** The bucket unlabelled calls land in, named so a report can say so. */
+export const UNLABELLED = 'unlabelled';
+/** Token counts only. Used for both halves, because both need them. */
+function countInto(into, record) {
+    into.calls += 1;
+    into.inputTokens += record.inputTokens;
+    into.cacheReadTokens += record.cacheReadTokens;
+    into.cacheWriteTokens += record.cacheWrite5mTokens + record.cacheWrite1hTokens;
+    if (!record.writeTtlKnown)
+        into.assumedWriteTtlCalls += 1;
+    into.outputTokens += record.outputTokens;
+}
+function add(into, record, catalogue, on) {
+    /**
+     * Looked up directly rather than through `modelFrom`, which **throws** on an id
+     * it does not know. A usage log is somebody's production traffic and will
+     * contain models this catalogue has never heard of — a fine-tune, a preview, a
+     * competitor. Throwing means one unfamiliar id destroys the whole profile;
+     * naming it separately means the report is honest about what it could not price
+     * and useful about everything else.
+     *
+     * **Priced first, counted second.** The other order was the bug: counts landed
+     * before the lookup could fail, so an unpriced call contributed tokens to a
+     * total whose dollars excluded it.
+     */
+    const model = catalogue.byId.get(record.model);
+    if (!model)
+        return false;
+    countInto(into, record);
+    const { inputPerMTok, outputPerMTok } = effectivePricing(model, on);
+    const rates = multipliersFor(model);
+    const per = (tokens, rate) => (tokens / 1_000_000) * rate;
+    into.inputUsd += per(record.inputTokens, inputPerMTok);
+    into.cacheReadUsd += per(record.cacheReadTokens, inputPerMTok * rates.cacheRead);
+    /**
+     * Each TTL at its own rate. Anthropic charges 1.25x input for a 5-minute entry
+     * and 2x for a 1-hour one, and the first version applied 1.25x to both — 37.5%
+     * under on a 1-hour workload, on the largest line, with nothing on screen
+     * saying a rate had been chosen.
+     */
+    into.cacheWriteUsd += per(record.cacheWrite5mTokens, inputPerMTok * rates.cacheWrite5m);
+    into.cacheWriteUsd += per(record.cacheWrite1hTokens, inputPerMTok * rates.cacheWrite1h);
+    into.outputUsd += per(record.outputTokens, outputPerMTok);
+    into.totalUsd =
+        into.inputUsd + into.cacheReadUsd + into.cacheWriteUsd + into.outputUsd;
+    return true;
+}
+/**
+ * Reads a usage log and says where the money went.
+ *
+ * Takes the whole text rather than a stream: a usage log is measured in megabytes
+ * and this package imports no Node builtins, so streaming would mean an interface
+ * the browser build cannot satisfy. `@trazum/core/node` is where file reading
+ * lives, and it can chunk if it ever needs to.
+ */
+export function profileUsage(text, options) {
+    const { catalogue, on = new Date() } = options;
+    const total = EMPTY();
+    const unpriced = EMPTY();
+    const byLabel = new Map();
+    const byModel = new Map();
+    const unpricedModels = new Set();
+    const skippedLines = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i].trim();
+        if (line === '')
+            continue;
+        const record = parseUsageLine(line);
+        if (!record) {
+            skippedLines.push(i + 1);
+            continue;
+        }
+        if (!add(total, record, catalogue, on)) {
+            unpricedModels.add(record.model);
+            countInto(unpriced, record);
+            // Still grouped by model, so the reader can see which unknown id is costing
+            // them attention — but with zero dollars, which the grouping makes obvious.
+            if (!byModel.has(record.model))
+                byModel.set(record.model, EMPTY());
+            countInto(byModel.get(record.model), record);
+            continue;
+        }
+        const labelKey = record.label ?? UNLABELLED;
+        if (!byLabel.has(labelKey))
+            byLabel.set(labelKey, EMPTY());
+        add(byLabel.get(labelKey), record, catalogue, on);
+        if (!byModel.has(record.model))
+            byModel.set(record.model, EMPTY());
+        add(byModel.get(record.model), record, catalogue, on);
+    }
+    const sorted = (map, key) => [...map.entries()]
+        .sort((a, b) => b[1].totalUsd - a[1].totalUsd || a[0].localeCompare(b[0]))
+        .map(([name, breakdown]) => ({ [key]: name, breakdown }));
+    return {
+        total,
+        byLabel: sorted(byLabel, 'label'),
+        byModel: sorted(byModel, 'model'),
+        unpricedModels: [...unpricedModels].sort(),
+        unpriced,
+        skippedLines,
+    };
+}
+/**
+ * What share of the bill each part is.
+ *
+ * The point of the whole module in one function: a caller can print "output is
+ * 87% of this" without doing arithmetic that would drift from the arithmetic
+ * here.
+ *
+ * All zeroes when nothing was spent, rather than `NaN`. A profile of an empty log
+ * is a legitimate result — no calls yet — and a report full of `NaN%` is a bug
+ * report from somebody who did nothing wrong.
+ */
+export function sharesOf(breakdown) {
+    const { totalUsd } = breakdown;
+    if (totalUsd <= 0)
+        return { input: 0, cacheRead: 0, cacheWrite: 0, output: 0 };
+    return {
+        input: breakdown.inputUsd / totalUsd,
+        cacheRead: breakdown.cacheReadUsd / totalUsd,
+        cacheWrite: breakdown.cacheWriteUsd / totalUsd,
+        output: breakdown.outputUsd / totalUsd,
+    };
+}
+/**
+ * How much of the input that could have been cached was.
+ *
+ * `null` when nothing was cacheable-looking at all — no reads and no writes —
+ * because a hit rate over zero attempts is not zero, it is undefined, and
+ * printing "0% cache hit rate" for somebody who never turned caching on is a
+ * finding about nothing.
+ *
+ * Reads against reads-plus-full-price-input, deliberately. Cache *writes* are
+ * excluded from the denominator: a write is the cost of establishing an entry,
+ * not a missed read, and counting it as a miss makes a healthy cache look broken
+ * on the day it warms.
+ */
+export function cacheHitRate(breakdown) {
+    const attempts = breakdown.cacheReadTokens + breakdown.inputTokens;
+    if (breakdown.cacheReadTokens === 0 && breakdown.cacheWriteTokens === 0)
+        return null;
+    if (attempts === 0)
+        return null;
+    return breakdown.cacheReadTokens / attempts;
+}
+//# sourceMappingURL=usage.js.map

package/dist/usage.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/core",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Trazum core: priced advisories for LLM prompts (caching, model tier, batching, schemas), plus deterministic trimming, token counting and pricing.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",