@trazum/core 1.80.1 → 1.82.0

package/src/conform.ts

@@ -54,6 +54,11 @@ export const CONTRACT_NAMES = [
   'bench',
   'prompt-draft',
   'position',
+  'routing-measurement',
+  'example-pruning',
+  'store-inventory',
+  'conformance',
+  'watch-cycle',
 ] as const;
 
 export type ContractName = (typeof CONTRACT_NAMES)[number];
@@ -394,6 +399,62 @@ const DOCUMENT_RULES: Record<Exclude<ContractName, 'usage-log'>, FieldRule[]> =
     rule('cannotSay', 'an array of sentences — what is deliberately not answered', isArray),
     rule('unpricedRecords', 'a count of records the catalogue cannot price', isNumber),
   ],
+  'routing-measurement': [
+    rule('slice', 'the workload object — the calls this measured', isObject),
+    rule('evaluation', 'the measurement object — verdict and agreement rates', isObject),
+  ],
+  'store-inventory': [
+    rule('providers', 'an array — one entry per provider held', isArray),
+    rule('totalRecords', 'records the store resolves to', isNumber),
+    rule(
+      'span',
+      'an object, or null when the store holds nothing',
+      (v) => v === null || isObject(v),
+    ),
+    rule('possiblyDouble', 'records the store could not tell apart', isNumber),
+    rule('unknownVersion', 'records written by a newer schema', isNumber),
+    rule('totalUsd', 'what the held records priced to', isNumber),
+    rule('unreadable', 'an array — files the store could not parse', isArray),
+  ],
+  conformance: [
+    rule(
+      'contract',
+      'the contract the input looked like, or null when nothing did',
+      (v) => v === null || typeof v === 'string',
+    ),
+    rule(
+      'because',
+      'why nothing matched, or null when something did — never a bare refusal',
+      (v) => v === null || typeof v === 'string',
+    ),
+    rule(
+      'records',
+      'records examined for a log, or null for a single document',
+      (v) => v === null || isNumber(v),
+    ),
+    rule('problems', 'an array — one entry per fault found', isArray),
+    rule('unavailable', 'an array — findings this shape cannot support', isArray),
+    rule('conforms', 'a boolean — the verdict', (v) => typeof v === 'boolean'),
+  ],
+  'watch-cycle': [
+    rule('firedAtMs', 'the instant the cycle ran', isNumber),
+    rule('crossings', 'an array — gates over their limit, news this cycle', isArray),
+    rule('suppressed', 'an array — still over, already reported', isArray),
+    rule('abstentions', 'an array — gates that could not be judged', isArray),
+    rule(
+      'gap',
+      'an object, or null when this cycle watched the whole stretch',
+      (v) => v === null || isObject(v),
+    ),
+  ],
+  'example-pruning': [
+    rule('provider', 'the provider the calls went to', (v) => typeof v === 'string'),
+    rule('model', 'the model that answered', (v) => typeof v === 'string'),
+    rule('selfAgreement', 'the model’s agreement with itself, the yardstick every removal is judged against', isNumber),
+    rule('recoverableTokens', 'tokens held by examples whose removal changed nothing measurable', isNumber),
+    rule('callsMade', 'calls actually spent', isNumber),
+    rule('contributions', 'an array — one entry per example', isArray),
+  ],
   pulse: [
     rule('beats', 'an array — one per kind', isArray),
     rule('nowMs', 'the instant the ages were taken against', isNumber),
@@ -554,6 +615,44 @@ function contractOf(doc: Record<string, unknown>): Exclude<ContractName, 'usage-
   if (Array.isArray(doc.actions) && typeof doc.arrived === 'number') return 'verification';
   if (Array.isArray(doc.actions)) return 'plan';
   if (typeof doc.verdict === 'string' && 'restsOn' in doc) return 'cost-answer';
+  /*
+    Two the inference could never reach, found by the guard that demands every
+    contract be recognisable from a document of its own shape.
+
+    The cost answer's branch above tested `restsOn`, which its contract does
+    not require: the required set is verdict, call and budget, so a conforming
+    answer that omitted the optional field was recognised as nothing at all.
+    The prompt draft had no branch of any kind — its schema has been published
+    since 1.68 and `trazum conform draft.json` has never known what it was.
+  */
+  if (typeof doc.verdict === 'string' && 'call' in doc && 'budget' in doc) return 'cost-answer';
+  if (typeof doc.prompt === 'string' && Array.isArray(doc.sections) && Array.isArray(doc.missing)) {
+    return 'prompt-draft';
+  }
+  /*
+    The five the JSON sweep contracted, and the reason they are here.
+
+    All five arrived with rules, a schema, a row in the interchange table and
+    a parity test, and none of them arrived with a branch in this function —
+    so `trazum conform verdict.json` read a real routing measurement as a
+    usage log and answered with advice about `stop_reason`. A contract that
+    cannot be recognised is a contract only reachable by somebody who already
+    knows its name, which is the opposite of what this page is for. Found by
+    running the command against its own output; `contract-coverage.test.js`
+    now requires every name to be inferable from a document.
+
+    Conformance sits before the connected report deliberately: both carry an
+    `unavailable` array, and only the conformance verdict carries `conforms`.
+  */
+  if (Array.isArray(doc.problems) && Array.isArray(doc.unavailable) && typeof doc.conforms === 'boolean') {
+    return 'conformance';
+  }
+  if (isObject(doc.evaluation) && 'slice' in doc) return 'routing-measurement';
+  if (Array.isArray(doc.contributions) && typeof doc.recoverableTokens === 'number') {
+    return 'example-pruning';
+  }
+  if (Array.isArray(doc.providers) && typeof doc.totalRecords === 'number') return 'store-inventory';
+  if (Array.isArray(doc.crossings) && Array.isArray(doc.abstentions)) return 'watch-cycle';
   if (typeof doc.provider === 'string' && Array.isArray(doc.unavailable)) return 'connected';
   return null;
 }
@@ -650,7 +749,7 @@ export function conform(text: string, options: ConformOptions = {}): Conformance
       schemaVersion: 1,
       contract: null,
       because:
-        'no contract recognised it — a roll-up has contributors and notMerged, a profile has byLabelAndModel, a plan has actions, a verification adds arrived, a history has periods and runs, a connected report has provider and unavailable, a cost answer has verdict and restsOn',
+        'no contract recognised it — a roll-up has contributors and notMerged, a profile has byLabelAndModel, a plan has actions, a verification adds arrived, a history has periods and runs, a connected report has provider and unavailable, a cost answer has verdict with call and budget, a prompt draft has prompt, sections and missing, a routing measurement has slice and evaluation, an example pruning has contributions and recoverableTokens, a store inventory has providers and totalRecords, a conformance verdict has problems and conforms, a watch cycle has crossings and abstentions',
       problems: [],
       unavailable: [],
       records: null,

package/src/helicone.ts

@@ -0,0 +1,227 @@
+/**
+ * Helicone's request export, read as a usage log.
+ *
+ * The third converter in the pattern `from-claude-code` started: a pure
+ * function turns one tool's export into Trazum's usage-log records, and every
+ * door prices it from there. Helicone sits as a proxy in front of the provider
+ * and keeps every request it saw, so a team using it already has the export.
+ *
+ * **The format is derived, not guessed.** The columns below are the SELECT
+ * that builds Helicone's own request table — `web/lib/api/request/request.ts`
+ * in Helicone/helicone — and the response shape its `POST /v1/request/query`
+ * endpoint documents. A converter written from memory of an API is a converter
+ * that silently mis-reads somebody's bill.
+ *
+ * ## The model, and why it takes three columns to answer
+ *
+ * Helicone carries `request_model`, `model_override` and `response_model`, and
+ * they can disagree: the override exists precisely because a proxy can send a
+ * different model than the caller asked for, and the response says what
+ * actually answered. **The response wins**, then the override, then the
+ * request — the bill is about what was billed, not what was intended — and
+ * `modelDisagreements` counts the rows where they differed so a reader can see
+ * the substitution happened rather than discover it in a total.
+ *
+ * ## What deliberately does not cross
+ *
+ * A Helicone row carries the request body and the response body — the prompt
+ * and the completion — and `request_user_id`, which is an email address in
+ * Helicone's own documented example. **None of it is read.** The converter
+ * names the fields it takes and takes nothing else, and a fixture plants a
+ * marker in each and greps the whole output.
+ *
+ * ## What it refuses to invent
+ *
+ * There is no cache-token split anywhere on the row: `cache_enabled` is a flag
+ * on the analytics table. A converted record therefore carries no cache fields
+ * and the caching questions come back `cannot-tell` rather than answered from
+ * a guess — the same refusal `from-otel` and `from-litellm` make.
+ *
+ * There is no conversation identity either. `request_id` is one call, so the
+ * records carry no `session` and the conversation-shaped findings stay
+ * unavailable. A custom property can carry one, and then it is there because
+ * the operator put it there — never because this file inferred it.
+ */
+
+/** One converted record, shaped exactly as `parseUsageLine` reads it. */
+export interface HeliconeRecord {
+  model: string;
+  ts?: string;
+  label?: string;
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+  };
+}
+
+export interface HeliconeConversion {
+  records: HeliconeRecord[];
+  /** Rows that were requests and converted. */
+  rows: number;
+  /** Rows naming no model in any of the three columns: counted, never guessed. */
+  unnamedModel: number;
+  /**
+   * Rows where the model that answered was not the model that was asked for.
+   *
+   * The response's model is what the bill rests on, and a proxy substituting
+   * one model for another is a fact worth seeing rather than a difference
+   * that only shows up as an unexplained total.
+   */
+  modelDisagreements: number;
+  /** Rows carrying no token counts at all — a logged request nobody can price. */
+  noTokens: number;
+  /** Rows Helicone served from its cache, with no token split behind the flag. */
+  cacheFlagged: number;
+  /** Lines or documents that did not parse as JSON at all. */
+  unparseable: number;
+}
+
+const asObject = (value: unknown): Record<string, unknown> | null =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+
+const tryParse = (text: string): unknown => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+};
+
+const asCount = (value: unknown): number | undefined => {
+  const n = typeof value === 'string' ? Number(value) : value;
+  return typeof n === 'number' && Number.isFinite(n) && n >= 0 ? n : undefined;
+};
+
+const asName = (value: unknown): string | null =>
+  typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
+
+/**
+ * The label, from Helicone's custom properties.
+ *
+ * `request_properties` is the documented place for whatever a team tags its
+ * calls with, and the keys are theirs. Trazum looks for the ones a workload
+ * would plausibly be named by, in order, and takes the first — never joins
+ * several, because a workload has one name in a bill.
+ */
+function labelOf(row: Record<string, unknown>): string | undefined {
+  const properties = asObject(row.request_properties) ?? asObject(row.properties);
+  if (properties === null) return undefined;
+  for (const key of ['Helicone-Property-Label', 'label', 'workload', 'app', 'environment']) {
+    const found = asName(properties[key]);
+    if (found !== null) return found;
+  }
+  return undefined;
+}
+
+/** The request's creation time as an ISO instant, or undefined. */
+function timeOf(row: Record<string, unknown>): string | undefined {
+  const raw = row.request_created_at ?? row.created_at ?? row.response_created_at;
+  if (typeof raw !== 'string' && typeof raw !== 'number') return undefined;
+  const ms = typeof raw === 'number' ? raw : Date.parse(raw);
+  if (!Number.isFinite(ms)) return undefined;
+  return new Date(ms).toISOString();
+}
+
+/**
+ * Convert a Helicone request export.
+ *
+ * Accepts a JSON array of rows, a single row, `{ data: [...] }` as the query
+ * endpoint returns it, or newline-delimited rows. Pure over its input.
+ */
+export function heliconeRecords(text: string): HeliconeConversion {
+  const out: HeliconeConversion = {
+    records: [],
+    rows: 0,
+    unnamedModel: 0,
+    modelDisagreements: 0,
+    noTokens: 0,
+    cacheFlagged: 0,
+    unparseable: 0,
+  };
+
+  const rows: unknown[] = [];
+  const whole = tryParse(text);
+  if (whole !== undefined) {
+    if (Array.isArray(whole)) rows.push(...whole);
+    else {
+      const doc = asObject(whole);
+      if (doc !== null && Array.isArray(doc.data)) rows.push(...doc.data);
+      else if (doc !== null) rows.push(doc);
+    }
+  } else {
+    for (const line of text.split('\n')) {
+      if (line.trim() === '') continue;
+      const parsed = tryParse(line);
+      if (parsed === undefined) out.unparseable += 1;
+      else if (Array.isArray(parsed)) rows.push(...parsed);
+      else rows.push(parsed);
+    }
+  }
+
+  for (const raw of rows) {
+    const row = asObject(raw);
+    if (row === null) continue;
+    const input = asCount(row.prompt_tokens);
+    const output = asCount(row.completion_tokens);
+    // A request row is one carrying at least one token column. Anything else
+    // in the same file is not a call and is skipped rather than recorded as a
+    // zero, which would be a call nobody made.
+    if (input === undefined && output === undefined) continue;
+
+    out.rows += 1;
+    if (input === 0 && output === 0) out.noTokens += 1;
+    if (row.cache_enabled === true || row.cache_enabled === 1 || row.cache_enabled === '1') {
+      out.cacheFlagged += 1;
+    }
+
+    /*
+      The response first, and this order is the whole point of counting the
+      disagreement. A proxy that substituted a model billed for the model that
+      answered, so that is what a bill has to price; taking the requested one
+      would report the intention and call it the cost.
+    */
+    const answered = asName(row.response_model);
+    const overridden = asName(row.model_override);
+    const requested = asName(row.request_model);
+    const model = answered ?? overridden ?? requested;
+    if (model === null) {
+      out.unnamedModel += 1;
+      continue;
+    }
+    if (requested !== null && answered !== null && requested !== answered) {
+      out.modelDisagreements += 1;
+    }
+
+    const ts = timeOf(row);
+    const label = labelOf(row);
+    out.records.push({
+      model,
+      ...(ts !== undefined ? { ts } : {}),
+      ...(label !== undefined ? { label } : {}),
+      usage: { input_tokens: input ?? 0, output_tokens: output ?? 0 },
+    });
+  }
+
+  return out;
+}
+
+/**
+ * Whether a file looks like a Helicone request export, by shape.
+ *
+ * Deliberately narrow: a token column beside one of the names only Helicone's
+ * own SELECT produces. A looser test would claim an OpenAI usage response or a
+ * LiteLLM spend log — both of which also carry `prompt_tokens` — and refuse it
+ * in this file's words instead of letting the code that can read it try.
+ */
+export function looksLikeHelicone(text: string, prefixBytes = 8192): boolean {
+  const head = text.slice(0, prefixBytes);
+  if (!head.includes('prompt_tokens') && !head.includes('completion_tokens')) return false;
+  return (
+    head.includes('"request_created_at"') ||
+    head.includes('"request_model"') ||
+    head.includes('"response_model"') ||
+    head.includes('"request_properties"')
+  );
+}

package/src/i18n/en.ts

@@ -82,7 +82,7 @@ export const en: CoreMessages = {
 
   suggest: {
     'not-found': () =>
-      'the quoted phrase is not in the prompt — the model paraphrased what it was copying',
+      'the quoted phrase is not in the prompt: the model paraphrased what it was copying',
     'touches-protected': () =>
       'it would edit code, a URL, a placeholder or a tag, which are copied verbatim',
     'introduces-protected': () => 'the replacement adds a placeholder or URL that was not there',
@@ -95,10 +95,10 @@ export const en: CoreMessages = {
      * Three shapes, not two, because *"how wrong might this estimate be"* has
      * three answers and only two were written down.
      *
-     * The count is exact — then the window verdict is a fact. The count is an
-     * estimate on the family the estimator was measured against — then the
+     * The count is exact, and then the window verdict is a fact. The count is an
+     * estimate on the family the estimator was measured against, and then the
      * margin is known and the verdict is a probability. Or the count is an
-     * estimate on a family nobody has measured — and then the margin itself is
+     * estimate on a family nobody has measured, and then the margin itself is
      * the unknown, which is neither of the first two and used to be told as the
      * second.
      *
@@ -116,15 +116,15 @@ export const en: CoreMessages = {
       detail: !uncertain
         ? `The optimised prompt is ~${n(tokens)} tokens and ${modelName} accepts ${n(contextWindow)}. The call will fail: split the content or move to a model with a larger window.`
         : bandApplies
-          ? `The optimised prompt is ~${n(tokens)} tokens against ${modelName}'s ${n(contextWindow)}. That count is an estimate and it is close to the line, so the call will probably fail but might not — settle it with --exact-tokens before rewriting anything. The counting endpoint is free. If it does exceed the window, split the content or move to a model with a larger one.`
-          : `The optimised prompt is ~${n(tokens)} tokens against ${modelName}'s ${n(contextWindow)}, which is over. That count is an estimate, and the estimator's error was measured against Claude's tokenizer — not ${modelName}'s — so how far over it really is cannot be said from here. Trazum will not tell you the call fails on a number it has not measured for this family. Count with your provider's own tooling before rewriting anything.`,
+          ? `The optimised prompt is ~${n(tokens)} tokens against ${modelName}'s ${n(contextWindow)}. That count is an estimate and it is close to the line, so the call will probably fail but might not. Settle it with --exact-tokens before rewriting anything. The counting endpoint is free. If it does exceed the window, split the content or move to a model with a larger one.`
+          : `The optimised prompt is ~${n(tokens)} tokens against ${modelName}'s ${n(contextWindow)}, which is over. That count is an estimate, and the estimator's error was measured against Claude's tokenizer rather than ${modelName}'s, so how far over it really is cannot be said from here. Trazum will not tell you the call fails on a number it has not measured for this family. Count with your provider's own tooling before rewriting anything.`,
     }),
 
     contextNearLimit: ({ tokens, modelName, contextWindow, bandApplies }) => ({
       title: 'The prompt may not fit in the context window',
       detail: bandApplies
-        ? `The optimised prompt is ~${n(tokens)} tokens against ${modelName}'s ${n(contextWindow)}, which fits — but that count is an estimate and its error range reaches past the window, so the real prompt may not. A call that exceeds the window fails outright rather than degrading, and nothing else here warns about it. Confirm with --exact-tokens; the counting endpoint is free.`
-        : `The optimised prompt is ~${n(tokens)} tokens against ${modelName}'s ${n(contextWindow)}, which fits on the estimate. This warning is raised because the estimator's measured error — against Claude's tokenizer, not ${modelName}'s — would reach past the window, and nobody has measured what that error is on this family. A call that exceeds the window fails outright rather than degrading. Count with your provider's own tooling before relying on the margin.`,
+        ? `The optimised prompt is ~${n(tokens)} tokens against ${modelName}'s ${n(contextWindow)}, which fits, but that count is an estimate and its error range reaches past the window, so the real prompt may not. A call that exceeds the window fails outright rather than degrading, and nothing else here warns about it. Confirm with --exact-tokens; the counting endpoint is free.`
+        : `The optimised prompt is ~${n(tokens)} tokens against ${modelName}'s ${n(contextWindow)}, which fits on the estimate. This warning is raised because the estimator's measured error, against Claude's tokenizer rather than ${modelName}'s, would reach past the window, and nobody has measured what that error is on this family. A call that exceeds the window fails outright rather than degrading. Count with your provider's own tooling before relying on the margin.`,
     }),
 
     promptCaching: ({
@@ -140,13 +140,13 @@ export const en: CoreMessages = {
       nearMinimum,
     }) => {
       const scope = placeholder
-        ? `The stable prefix — everything before the first placeholder ${placeholder} — is ~${n(prefixTokens)} of the prompt's ${n(totalTokens)} tokens, and clears ${modelName}'s ${n(minTokens)}-token cacheable minimum.`
+        ? `The stable prefix (everything before the first placeholder ${placeholder}) is ~${n(prefixTokens)} of the prompt's ${n(totalTokens)} tokens, and clears ${modelName}'s ${n(minTokens)}-token cacheable minimum.`
         : `The prompt has no variable placeholders, so the whole thing is a cacheable prefix and it clears ${modelName}'s ${n(minTokens)}-token minimum.`;
       const how = explicit
         ? 'Put the cache marker at the end of the stable prefix: any byte that changes before the cut invalidates everything after it.'
-        : `${modelName} caches automatically above its minimum, so there is nothing to set — but the same rule applies: any byte that changes before the cut invalidates everything after it.`;
+        : `${modelName} caches automatically above its minimum, so there is nothing to set, but the same rule applies: any byte that changes before the cut invalidates everything after it.`;
       const hedge = nearMinimum
-        ? ` One caveat on the figure: that prefix count is an estimate and it is close to the line, so the real one may be below the ${n(minTokens)}-token minimum — in which case nothing caches and this saving is not there. Settle it with --exact-tokens before budgeting from it. The counting endpoint is free.`
+        ? ` One caveat on the figure: that prefix count is an estimate and it is close to the line, so the real one may be below the ${n(minTokens)}-token minimum, in which case nothing caches and this saving is not there. Settle it with --exact-tokens before budgeting from it. The counting endpoint is free.`
         : '';
       return {
         title: 'Turn on prompt caching for the stable prefix',
@@ -154,10 +154,12 @@ export const en: CoreMessages = {
       };
     },
 
-    promptCachingNotWorthIt: () => ({
+    promptCachingNotWorthIt: ({ readPct, writePct, breakEvenPct }) => ({
       title: 'At that hit rate, caching does not pay off',
       detail:
-        'A cache write costs 125% of the input price and a read costs 10%. Below roughly a 28% hit rate you pay more than you save. Either raise prefix reuse or leave caching off.',
+        breakEvenPct === null
+          ? `A cache write costs ${writePct}% of the input price on this model, the same as not caching, and a read costs ${readPct}%. So caching cannot lose you money here: at this hit rate it simply buys nothing. Raise prefix reuse and it starts paying immediately.`
+          : `A cache write costs ${writePct}% of the input price on this model and a read costs ${readPct}%. Below a ${breakEvenPct}% hit rate you pay more than you save. Either raise prefix reuse or leave caching off.`,
     }),
 
     belowCacheMinimum: ({
@@ -180,14 +182,14 @@ export const en: CoreMessages = {
             ? ' Claude Opus 5 lowers that minimum to 512 tokens, so short prompts that miss here would cache there.'
             : '') +
           (couldReachMinimum
-            ? ' That prefix count is an estimate and it is close to the line, so the real one may already be above it — check with --exact-tokens before deciding this is not available to you. The counting endpoint is free.'
+            ? ' That prefix count is an estimate and it is close to the line, so the real one may already be above it. Check with --exact-tokens before deciding this is not available to you. The counting endpoint is free.'
             : ''),
       };
     },
 
     cachePrefixReorder: ({ staticTokensAfter, sharePct, placeholder, command }) => ({
       title: 'Move the stable instructions ahead of the first placeholder',
-      detail: `About ~${n(staticTokensAfter)} tokens of stable content (${sharePct}% of the prompt) sit after the first variable placeholder ${placeholder}, so today they never get cached. Fixed instructions and context first, placeholders last, and that content starts being read from cache at 10% of the price. Run \`${command}\` to attempt it: whole blocks only, and it refuses to move anything that refers back to earlier text. Read the diff — order carries meaning, and "summarise the text above" is nonsense in front of the text it points at.`,
+      detail: `About ~${n(staticTokensAfter)} tokens of stable content (${sharePct}% of the prompt) sit after the first variable placeholder ${placeholder}, so today they never get cached. Fixed instructions and context first, placeholders last, and that content starts being read from cache at 10% of the price. Run \`${command}\` to attempt it: whole blocks only, and it refuses to move anything that refers back to earlier text. Read the diff: order carries meaning, and "summarise the text above" is nonsense in front of the text it points at.`,
     }),
 
     batchApi: () => ({
@@ -198,7 +200,12 @@ export const en: CoreMessages = {
 
     modelDowngrade: ({ modelName, tier, candidateName, currentUsd, candidateUsd }) => ({
       title: `This task may not need ${modelName}`,
-      detail: `By length and vocabulary the prompt looks like "${tier}" complexity. On ${candidateName} you would go from ${currentUsd} to ${candidateUsd} per month. This is a keyword heuristic, not a judgement about answer quality: measure the difference with your own evaluations before switching in production.`,
+      detail: `By length and vocabulary the prompt looks like "${tier}" complexity. On ${candidateName} you would go from ${currentUsd} to ${candidateUsd} per month. This is a keyword heuristic, not a judgement about answer quality. Measure it before switching in production: \`trazum route <log.jsonl> --prompt-file <prompt> --cases <cases> --yes\` sends the same cases to both models and reports whether the cheaper one still does the job.`,
+    }),
+
+    tierSignalsConflict: ({ complexSignals, simpleSignals }) => ({
+      title: 'The prompt asks for depth and for brevity at once',
+      detail: `It carries ${complexSignals} signal${complexSignals === 1 ? '' : 's'} of a hard task and ${simpleSignals} of an easy one, and this heuristic scores those against each other, so they cancel. No tier is recommended here: a number produced by two opposite readings cancelling out looks exactly like a prompt with no signals at all, and they are not the same thing. Decide it by measurement rather than by vocabulary: \`trazum route <log.jsonl> --prompt-file <prompt> --cases <cases> --yes\`.`,
     }),
 
     outputDominated: ({ outputUsd, inputUsd }) => ({
@@ -222,7 +229,7 @@ export const en: CoreMessages = {
       title: `Two instructions disagree about ${axis}`,
       detail:
         `One says ${firstValue} ("${firstSnippet}") and another says ${secondValue} ("${secondSnippet}"). ` +
-        'The model has to pick one, and which one it picks can change between calls — so this is a correctness problem before it is a cost one. ' +
+        'The model has to pick one, and which one it picks can change between calls, so this is a correctness problem before it is a cost one. ' +
         'Deleting the instruction you did not mean also shortens the prompt.' +
         (otherCount > 0
           ? ` ${otherCount} other ${otherCount === 1 ? 'pair' : 'pairs'} of instructions disagree too.`
@@ -241,8 +248,8 @@ export const en: CoreMessages = {
       title: 'The output schema could travel in the request instead of the prompt',
       detail:
         `${blocks === 1 ? 'A schema block' : `${blocks} schema blocks`} introduced by "${cue}" defines ${keyList}, costing about ${n(tokens)} tokens on every call. ` +
-        'Every major API now takes a response schema as a request parameter — output_config.format, response_format, responseSchema — and moving it there is the rare change that is both cheaper and stricter: prose asks the model to comply, a parameter makes the decoder comply. ' +
-        'Trazum cannot make this edit, because it changes the call rather than the prompt, and it does not check whether your provider offers the parameter — if it does not, this is not available to you.',
+        'Every major API now takes a response schema as a request parameter (output_config.format, response_format, responseSchema), and moving it there is the rare change that is both cheaper and stricter: prose asks the model to comply, a parameter makes the decoder comply. ' +
+        'Trazum cannot make this edit, because it changes the call rather than the prompt, and it does not check whether your provider offers the parameter; if it does not, this is not available to you.',
     }),
 
     restatedOutputFormat: ({ restatedCount, totalCount, restatedTokens, keyList }) => ({
@@ -250,7 +257,7 @@ export const en: CoreMessages = {
       detail:
         `The prose describes ${restatedCount} of the ${totalCount} fields your schema already defines (${keyList}), costing about ${n(restatedTokens)} tokens on every call. ` +
         'The code block is the version worth keeping: it is unambiguous, and Trazum never edits it. ' +
-        'Check the two agree before deleting either — when a prompt says one thing in prose and another in its schema, the prose is usually the one that went stale.',
+        'Check the two agree before deleting either: when a prompt says one thing in prose and another in its schema, the prose is usually the one that went stale.',
     }),
   },
 

package/src/i18n/es.ts

@@ -138,10 +138,12 @@ export const es: CoreMessages = {
       };
     },
 
-    promptCachingNotWorthIt: () => ({
+    promptCachingNotWorthIt: ({ readPct, writePct, breakEvenPct }) => ({
       title: 'Con esa tasa de acierto, la caché no compensa',
       detail:
-        'Escribir en caché cuesta un 125% del precio de entrada y leer un 10%. Por debajo de un ~28% de aciertos pagas más de lo que ahorras. Sube la reutilización del prefijo o deja la caché desactivada.',
+        breakEvenPct === null
+          ? `En este modelo escribir en caché cuesta un ${writePct}% del precio de entrada, lo mismo que no usarla, y leer un ${readPct}%. Así que aquí la caché no puede costarte dinero: con esta tasa de acierto simplemente no te aporta nada. En cuanto subas la reutilización del prefijo, empieza a compensar.`
+          : `En este modelo escribir en caché cuesta un ${writePct}% del precio de entrada y leer un ${readPct}%. Por debajo de un ${breakEvenPct}% de aciertos pagas más de lo que ahorras. Sube la reutilización del prefijo o deja la caché desactivada.`,
     }),
 
     belowCacheMinimum: ({
@@ -182,7 +184,12 @@ export const es: CoreMessages = {
 
     modelDowngrade: ({ modelName, tier, candidateName, currentUsd, candidateUsd }) => ({
       title: `Esta tarea quizá no necesite ${modelName}`,
-      detail: `Por longitud y vocabulario, el prompt parece de complejidad "${tier}". Con ${candidateName} pasarías de ${currentUsd} a ${candidateUsd} al mes. Es una heurística por palabras clave, no un juicio de calidad: mide la diferencia con tus propias evaluaciones antes de cambiar en producción.`,
+      detail: `Por longitud y vocabulario, el prompt parece de complejidad "${tier}". Con ${candidateName} pasarías de ${currentUsd} a ${candidateUsd} al mes. Es una heurística por palabras clave, no un juicio de calidad. Mídelo antes de cambiar en producción: \`trazum route <log.jsonl> --prompt-file <prompt> --cases <casos> --yes\` envía los mismos casos a ambos modelos y dice si el barato sigue haciendo el trabajo.`,
+    }),
+
+    tierSignalsConflict: ({ complexSignals, simpleSignals }) => ({
+      title: 'El prompt pide profundidad y brevedad a la vez',
+      detail: `Lleva ${complexSignals} señal${complexSignals === 1 ? '' : 'es'} de tarea difícil y ${simpleSignals} de tarea fácil, y esta heurística las resta entre sí, así que se anulan. Aquí no se recomienda ningún nivel: un número que sale de dos lecturas opuestas cancelándose se parece exactamente a un prompt sin ninguna señal, y no son lo mismo. Decídelo midiendo y no por vocabulario: \`trazum route <log.jsonl> --prompt-file <prompt> --cases <casos> --yes\`.`,
     }),
 
     outputDominated: ({ outputUsd, inputUsd }) => ({

package/src/i18n/types.ts

@@ -215,6 +215,49 @@ export interface LlmMessages {
   suspiciousShrink(retainedPct: number): string;
 }
 
+/**
+ * What the caching-does-not-pay advisory needs to state a threshold that is
+ * true about **this** model.
+ *
+ * It used to take nothing and print one sentence for every model: *"a cache
+ * write costs 125% of the input price and a read costs 10%. Below roughly a 28%
+ * hit rate you pay more than you save."* Two of those three numbers were the
+ * Anthropic multipliers stated as universal, and the third was not derivable
+ * from any model in the catalogue: at 125% and 10% the break-even is 21.74%,
+ * not 28%.
+ *
+ * The multipliers were already in hand at the call site and already passed to
+ * the advisory next door. Only this message invented its own.
+ */
+export interface PromptCachingNotWorthItParams {
+  /** The model's cache read multiplier as a percentage of the input price. */
+  readPct: number;
+  /** Its 5-minute cache write multiplier, likewise. */
+  writePct: number;
+  /**
+   * The hit rate at which caching stops costing money, derived rather than
+   * quoted: `(1 - write) / (read - write)`.
+   *
+   * `null` when the write multiplier is 1, which is not a smaller threshold but
+   * a different situation: writing costs exactly what not caching costs, so
+   * caching can never lose money and there is no rate below which it does. Eight
+   * of the eighteen models in the catalogue are that shape, and the old sentence
+   * told all eight to consider turning caching off.
+   */
+  breakEvenPct: number | null;
+}
+
+/**
+ * What the tier heuristic saw when it declined to answer.
+ *
+ * Both counts, because "three of each" and "one of each" are different degrees
+ * of the same refusal and the reader can act on the difference.
+ */
+export interface TierSignalsConflictParams {
+  complexSignals: number;
+  simpleSignals: number;
+}
+
 /** Why a proposed rewrite did not survive checking against the prompt. */
 export interface SuggestMessages {
   'not-found'(): string;
@@ -236,11 +279,12 @@ export interface CoreMessages {
     contextOverflow(p: ContextOverflowParams): LocalizedMessage;
     contextNearLimit(p: ContextNearLimitParams): LocalizedMessage;
     promptCaching(p: PromptCachingParams): LocalizedMessage;
-    promptCachingNotWorthIt(): LocalizedMessage;
+    promptCachingNotWorthIt(p: PromptCachingNotWorthItParams): LocalizedMessage;
     belowCacheMinimum(p: BelowCacheMinimumParams): LocalizedMessage;
     cachePrefixReorder(p: CachePrefixReorderParams): LocalizedMessage;
     batchApi(): LocalizedMessage;
     modelDowngrade(p: ModelDowngradeParams): LocalizedMessage;
+    tierSignalsConflict(p: TierSignalsConflictParams): LocalizedMessage;
     outputDominated(p: OutputDominatedParams): LocalizedMessage;
     promoPricing(p: PromoPricingParams): LocalizedMessage;
     contradictoryInstructions(p: ContradictoryInstructionsParams): LocalizedMessage;

package/src/index.ts

@@ -166,7 +166,18 @@ export type {
   GatewayStanding,
   RefuseReason,
 } from './gateway.js';
+export {
+  BANDS,
+  MEASURED_FOREIGN_ERROR_PCT,
+  bandFor,
+  bucketFor,
+  foreignTokenizer,
+  measuredForeignError,
+} from './band.js';
+export type { BandBucket } from './band.js';
 export { conform, CONTRACT_NAMES, requiredFieldsOf } from './conform.js';
+export { readDroppedVerdict, verdictMatchesSlice } from './verdict-bridge.js';
+export type { DroppedVerdict, BridgeReading } from './verdict-bridge.js';
 export { CONTRACT_SCHEMAS, contractSchema } from './schemas.js';
 export type {
   ConformOptions,
@@ -203,6 +214,10 @@ export type { MeasuredIndex } from './position.js';
 export { claudeCodeRecords, looksLikeClaudeCodeTranscript } from './claude-code.js';
 export { otelRecords, looksLikeOtel } from './otel.js';
 export type { OtelConversion, OtelRecord } from './otel.js';
+export { litellmRecords, looksLikeLiteLlm } from './litellm.js';
+export type { LiteLlmConversion, LiteLlmRecord } from './litellm.js';
+export { heliconeRecords, looksLikeHelicone } from './helicone.js';
+export type { HeliconeConversion, HeliconeRecord } from './helicone.js';
 export type { ClaudeCodeConversion, ClaudeCodeRecord } from './claude-code.js';
 export { positionReport } from './position-report.js';
 export type {
@@ -424,7 +439,8 @@ export type {
 export { RULES, getRule } from './rules.js';
 export { segment, join, protectedTexts } from './segment.js';
 export { computeSavings, costOfCall, formatUsd, formatSignedUsd } from './savings.js';
-export { buildAdvisories, recommendTier } from './advisories.js';
+export { buildAdvisories, recommendTier, recommendTierDetailed } from './advisories.js';
+export type { TierRecommendation } from './advisories.js';
 export type { AdvisoryOptions } from './advisories.js';
 export { analyzeCachePrefix } from './cache.js';