@trazum/cli 1.37.0 → 1.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.37.0",
+  "version": "1.38.0",
   "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",
@@ -37,7 +37,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@trazum/core": "1.37.0"
+    "@trazum/core": "1.38.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -39,6 +39,7 @@ ${bold('USAGE')}
   trazum eval <file> --cases <file> [options]
   trazum eval <file> --cases <file> --export promptfoo -o suite.json
   trazum route <log.jsonl> --prompt-file <file> --cases <file> --yes
+  trazum plan <log.jsonl|dir> [options]
   trazum diff <before> <after> [options]
   trazum diff --all <dir> <dir> [options]
   trazum rank <dir> [options]
@@ -299,6 +300,23 @@ ${bold('OPTIONS FOR profile')}
   "label" (which workload), "session" (which conversation — grouped by, never
   printed), "stop_reason"/"finish_reason" (answers cut off at max_tokens).
 
+${bold('OPTIONS FOR plan')}
+  --min-usd <n>               Leave out actions worth less than n dollars. How
+                              many were left out is stated, never silent.
+  -o, --out <file>            Save the plan as dated JSON — the file
+                              "trazum verify" will later hold it to.
+  --markdown-out <file>       Also write the plan as Markdown, for a CI job
+                              summary or a pull request comment.
+  --pricing <file>            Local price overlay, as everywhere else.
+  --json                      The plan as data.
+
+  Reads a usage log and turns the report's findings into a ranked plan: route
+  this, batch that, fix the truncation pair, look at the cache. The money is
+  composed correctly — route and batch on the same slice arrive combined,
+  never summed — and every action names what the log cannot confirm, because
+  a plan that hides its assumptions is advice pretending to be arithmetic.
+  Projected savings and money already spent are separate totals throughout.
+
 ${bold('OPTIONS FOR route')}
   --prompt-file <file>        The prompt those calls send. Not --prompt, which
                               names a marked prompt inside a source file.
@@ -1345,6 +1363,55 @@ ${bold('EXAMPLES')}
       `${label} on ${model}: ${single} of ${sessions} conversations ended after their first turn and spent ${usd} writing a cache that nothing in this log ever read. Within the conversation, across conversations — no read anywhere, so those writes bought nothing. Caching a one-shot call is pure write premium; stop marking these calls with cache_control.`,
   },
 
+  plan: {
+    noTarget: () =>
+      'Point this at a usage log or a directory of them: trazum plan usage.jsonl. It turns the report into a ranked plan — what to do first, what each action is worth, and what the log cannot confirm about it.',
+    nothingPriced: () =>
+      'This log priced nothing — no call in it matched a model in the catalogue. A plan over zero dollars would be advice about nothing; check the log with "trazum profile" first.',
+    heading: (actions, total) => `The plan: ${actions} actions against a ${total} bill`,
+    totals: (projected, staked) =>
+      `${projected} projected savings, on assumptions listed below. ${staked} already spent on problems this plan names — measured, not projected.`,
+    noClock: () =>
+      'No timestamps in this log, so every figure is per this log, not per any period.',
+    projected: (usd) => `${usd} projected`,
+    staked: (usd) => `${usd} already spent`,
+    action: (kind, label, model) => {
+      const verb =
+        kind === 'route'
+          ? 'Route'
+          : kind === 'batch'
+            ? 'Batch'
+            : kind === 'route+batch'
+              ? 'Route and batch'
+              : kind === 'fix-truncation'
+                ? 'Fix the truncation retries on'
+                : 'Look at the cache on';
+      return `${verb} ${label} (${model})`;
+    },
+    routeTo: (model) => `to ${model} — combined with batching where both apply, never summed`,
+    assume: (assumption) => {
+      switch (assumption.kind) {
+        case 'model-capability':
+          return `assumes ${assumption.model} can do this work — the log prices the move, it cannot judge the answers`;
+        case 'batch-window':
+          return 'assumes these calls can wait for a batch window';
+        case 'retry-pattern-real':
+          return 'assumes the retry pattern is real — the log sees shapes, not content';
+        case 'max-tokens-fits':
+          return 'assumes a max_tokens the answers fit in removes the pair';
+        case 'traffic-pattern-holds':
+          return 'assumes the traffic pattern holds — a cache that lost money on this log may pay on different traffic';
+      }
+    },
+    check: (command) => `check it: ${command}`,
+    filtered: (count, minUsd, worth) =>
+      `${count} actions under ${minUsd}, worth ${worth} together, left out by --min-usd — left out of this document entirely, not disproved.`,
+    footer: () =>
+      'Ranked by money, projected or already spent alike. The assumptions are yours to answer: this plan is arithmetic over the log, not knowledge of your product.',
+    wrote: (path) =>
+      `Plan written to ${path}, dated. Keep it: a prediction nobody wrote down is a prediction nobody can be held to.`,
+  },
+
   route: {
     noTarget: () =>
       'Point this at a usage log and a prompt: trazum route usage.jsonl --prompt-file prompts/support.txt --cases cases.txt --yes. It finds the slice worth the most, then measures whether the cheaper model still does the job. The flag is --prompt-file and not --prompt, because --prompt names a marked prompt inside a source file everywhere else in this tool.',

package/src/i18n/es.ts

@@ -26,6 +26,7 @@ ${bold('USO')}
   trazum eval <fichero> --cases <fichero> [opciones]
   trazum eval <fichero> --cases <fichero> --export promptfoo -o suite.json
   trazum route <log.jsonl> --prompt-file <fichero> --cases <fichero> --yes
+  trazum plan <log.jsonl|dir> [opciones]
   trazum diff <antes> <después> [opciones]
   trazum diff --all <dir> <dir> [opciones]
   trazum rank <dir> [opciones]
@@ -304,6 +305,25 @@ ${bold('OPCIONES DE profile')}
   nunca se imprime), "stop_reason"/"finish_reason" (respuestas cortadas en
   max_tokens).
 
+${bold('OPCIONES DE plan')}
+  --min-usd <n>               Deja fuera las acciones que valen menos de n
+                              dólares. Cuántas quedaron fuera se dice, nunca
+                              en silencio.
+  -o, --out <fichero>         Guarda el plan como JSON fechado — el fichero al
+                              que "trazum verify" lo atará después.
+  --markdown-out <fichero>    Escribe además el plan como Markdown, para un
+                              resumen de CI o un comentario de pull request.
+  --pricing <fichero>         Tarifas locales superpuestas, como en el resto.
+  --json                      El plan como datos.
+
+  Lee un registro de uso y convierte los hallazgos del informe en un plan
+  ordenado: enruta esto, agrupa aquello, arregla el par de truncados, mira la
+  caché. El dinero está compuesto correctamente — ruta y batch sobre la misma
+  porción llegan combinados, nunca sumados — y cada acción nombra lo que el
+  registro no puede confirmar, porque un plan que esconde sus supuestos es un
+  consejo haciéndose pasar por aritmética. El ahorro proyectado y el dinero ya
+  gastado son totales separados en todas partes.
+
 ${bold('OPCIONES DE route')}
   --prompt-file <fichero>     El prompt que mandan esas llamadas. No --prompt,
                               que nombra un prompt marcado dentro de un fuente.
@@ -1363,6 +1383,55 @@ ${bold('EJEMPLOS')}
       `${label} en ${model}: ${single} de ${sessions} conversaciones terminaron tras su primer turno y gastaron ${usd} escribiendo una caché que nada en este registro leyó jamás. Dentro de la conversación, entre conversaciones — ninguna lectura en ningún sitio, así que esas escrituras no compraron nada. Cachear una llamada de un solo uso es puro sobreprecio de escritura; deja de marcar estas llamadas con cache_control.`,
   },
 
+  plan: {
+    noTarget: () =>
+      'Apunta esto a un registro de uso o a un directorio de ellos: trazum plan usage.jsonl. Convierte el informe en un plan ordenado — qué hacer primero, cuánto vale cada acción y qué no puede confirmar el registro sobre ella.',
+    nothingPriced: () =>
+      'Este registro no tasó nada — ninguna llamada coincide con un modelo del catálogo. Un plan sobre cero dólares sería un consejo sobre nada; revisa el registro primero con "trazum profile".',
+    heading: (actions, total) => `El plan: ${actions} acciones contra una factura de ${total}`,
+    totals: (projected, staked) =>
+      `${projected} de ahorro proyectado, sobre los supuestos listados abajo. ${staked} ya gastados en problemas que este plan nombra — medido, no proyectado.`,
+    noClock: () =>
+      'Este registro no tiene marcas de tiempo, así que cada cifra es por este registro, no por ningún período.',
+    projected: (usd) => `${usd} proyectados`,
+    staked: (usd) => `${usd} ya gastados`,
+    action: (kind, label, model) => {
+      const verb =
+        kind === 'route'
+          ? 'Enruta'
+          : kind === 'batch'
+            ? 'Agrupa en batch'
+            : kind === 'route+batch'
+              ? 'Enruta y agrupa'
+              : kind === 'fix-truncation'
+                ? 'Arregla los reintentos por truncado de'
+                : 'Mira la caché de';
+      return `${verb} ${label} (${model})`;
+    },
+    routeTo: (model) => `a ${model} — combinado con el batch donde aplican los dos, nunca sumado`,
+    assume: (assumption) => {
+      switch (assumption.kind) {
+        case 'model-capability':
+          return `supone que ${assumption.model} puede hacer este trabajo — el registro tasa el cambio, no puede juzgar las respuestas`;
+        case 'batch-window':
+          return 'supone que estas llamadas pueden esperar una ventana de batch';
+        case 'retry-pattern-real':
+          return 'supone que el patrón de reintentos es real — el registro ve formas, no contenido';
+        case 'max-tokens-fits':
+          return 'supone que un max_tokens en el que quepan las respuestas elimina el par';
+        case 'traffic-pattern-holds':
+          return 'supone que el patrón de tráfico se mantiene — una caché que perdió dinero en este registro puede rendir con otro tráfico';
+      }
+    },
+    check: (command) => `compruébalo: ${command}`,
+    filtered: (count, minUsd, worth) =>
+      `${count} acciones por debajo de ${minUsd}, que juntas valen ${worth}, quedaron fuera por --min-usd — fuera de este documento por completo, no refutadas.`,
+    footer: () =>
+      'Ordenado por dinero, proyectado o ya gastado por igual. Los supuestos los respondes tú: este plan es aritmética sobre el registro, no conocimiento de tu producto.',
+    wrote: (path) =>
+      `Plan escrito en ${path}, con fecha. Guárdalo: una predicción que nadie apuntó es una predicción que no se le puede exigir a nadie.`,
+  },
+
   route: {
     noTarget: () =>
       'Apunta esto a un registro de uso y a un prompt: trazum route usage.jsonl --prompt-file prompts/soporte.txt --cases casos.txt --yes. Busca la porción que más vale y mide si el modelo más barato sigue haciendo el trabajo. El flag es --prompt-file y no --prompt, porque en el resto de la herramienta --prompt nombra un prompt marcado dentro de un fichero fuente.',

package/src/i18n/types.ts

@@ -1,4 +1,4 @@
-import type { EvalVerdict, Locale, RuleLevel } from '@trazum/core';
+import type { EvalVerdict, Locale, PlanActionKind, PlanAssumption, RuleLevel } from '@trazum/core';
 
 /**
  * The CLI's own message catalogue.
@@ -1038,6 +1038,40 @@ export interface CliMessages {
     singleTurnCeiling(label: string, model: string, single: string, sessions: string, usd: string): string;
     singleTurnConfirmed(label: string, model: string, single: string, sessions: string, usd: string): string;
   };
+  /**
+   * `trazum plan <log>` — not a list of findings, a ranked plan of what to do.
+   *
+   * The report names what it found; the plan ranks what to do about it, with
+   * the money composed correctly (route and batch on one slice combined,
+   * never summed) and every action carrying what the log cannot confirm.
+   * Projected savings and measured stakes are separate columns throughout:
+   * "what you would save" and "what you already paid" merged into one number
+   * is a number that is neither.
+   */
+  plan: {
+    noTarget(): string;
+    /** The log priced nothing — a plan over zero calls would be advice about nothing. */
+    nothingPriced(): string;
+    heading(actions: string, total: string): string;
+    totals(projected: string, staked: string): string;
+    /** No timestamps: the figures are per this log, not per any period. */
+    noClock(): string;
+    projected(usd: string): string;
+    staked(usd: string): string;
+    /** One action line: what to do, to which workload, on which model. */
+    action(kind: PlanActionKind, label: string, model: string): string;
+    routeTo(model: string): string;
+    /** One assumption the log cannot confirm, localized from its typed form. */
+    assume(assumption: PlanAssumption): string;
+    /** The command that can check the assumption, when one exists. */
+    check(command: string): string;
+    /** Actions below --min-usd, counted out loud rather than dropped silently. */
+    filtered(count: string, minUsd: string, worth: string): string;
+    footer(): string;
+    /** The plan saved as dated JSON — what 1.39's verify will hold it to. */
+    wrote(path: string): string;
+  };
+
   /**
    * `trazum route` — the loop the levers section could only point at.
    *

package/src/index.ts

@@ -11,6 +11,7 @@ import {
   cacheableMinimum,
   analyzeCachePrefix,
   billLevers,
+  buildPlan,
   cacheEconomics,
   cacheHitRate,
   contextPressure,
@@ -172,6 +173,7 @@ interface Args {
 const VALUE_FLAGS = new Set([
   'against',
   'from-log',
+  'min-usd',
   // `route` takes a path here, and the flag is deliberately not `--prompt`:
   // everywhere else in this tool `--prompt` names a marked prompt *inside* a
   // source file, and reusing it for a path would be a trap laid for the reader.
@@ -312,6 +314,13 @@ function levelFlag(args: Args, config: TrazumConfig, t: CliMessages): RuleLevel
  * model id. It beats the default because reading the code is better than
  * assuming, and loses to config because being told is better than reading.
  */
+/**
+ * The file names a usage log answers to, shared by every command that reads a
+ * directory of them. One list, because two commands disagreeing on what counts
+ * as a log would be the same directory billing differently by verb.
+ */
+const LOG_EXTENSIONS = ['.jsonl', '.ndjson', '.log', '.json'];
+
 /**
  * One usage log, gzip included, shared by every command that reads one.
  *
@@ -465,6 +474,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   check: ['max-tokens', 'level', 'exact-tokens', 'markdown-out', 'baseline'],
   baseline: ['model', 'calls', 'output-tokens', 'cache-hit-rate', 'batch', 'exact-tokens', 'out', 'o'],
   profile: ['json', 'pricing', 'pricing-live', 'against', 'what-if', 'markdown-out', 'csv-out', 'csv-shape', 'max-usd', 'max-growth-usd', 'max-cache-loss-usd', 'max-day-usd', 'max-session-usd', 'label', 'since', 'until', 'dry-run', 'markdown-summary', 'by-source'],
+  plan: ['json', 'out', 'markdown-out', 'min-usd', 'pricing', 'pricing-live'],
   route: ['prompt-file', 'cases', 'label', 'concurrency', 'json', 'yes', 'pricing', 'pricing-live'],
   eval: ['cases', 'level', 'concurrency', 'export', 'out', 'o', 'model'],
   prune: ['cases', 'concurrency', 'json', 'yes'],
@@ -2204,6 +2214,140 @@ function isoDate(): string {
  * metered API calls somebody was actually billed for — the bill exists wherever
  * Trazum happens to be running, so the host has no bearing on it.
  */
+/**
+ * `trazum plan <log>` — not a list of findings, a ranked plan of what to do.
+ *
+ * The composition (route and batch on one slice never summed) happens in
+ * core's `buildPlan`; this command owns the I/O and the rendering. The plan
+ * saves as a dated JSON file on request, which is what makes verifying it
+ * against a later log possible at all — a prediction nobody wrote down is a
+ * prediction nobody can be held to.
+ */
+async function commandPlan(
+  args: Args,
+  pricing: PricingCatalogue,
+  t: CliMessages,
+): Promise<void> {
+  const path = args.positional[0];
+  if (path === undefined) throw new Error(t.plan.noTarget());
+
+  const GZ = LOG_EXTENSIONS.map((ext) => `${ext}.gz`);
+  const READABLE = [...LOG_EXTENSIONS, ...GZ];
+  const target = await stat(path).catch(() => null);
+  let files: string[] = [path];
+  if (target?.isDirectory()) {
+    const entries = await readdir(path, { withFileTypes: true });
+    files = entries
+      .filter((entry) => entry.isFile() && READABLE.some((ext) => entry.name.endsWith(ext)))
+      .map((entry) => join(path, entry.name))
+      .sort((a, b) => a.localeCompare(b));
+    if (files.length === 0) throw new Error(t.profile.noLogsInDirectory(path, READABLE.join(', ')));
+  }
+  const texts = await Promise.all(files.map((file) => readUsageLog(file, t)));
+  const raw = texts.map((text) => (text.endsWith('\n') ? text : `${text}\n`)).join('');
+
+  const report = profileUsage(raw, { catalogue: pricing });
+  if (report.total.calls === 0) throw new Error(t.plan.nothingPriced());
+  const levers = billLevers(report, { catalogue: pricing });
+  const plan = buildPlan(report, levers, pricing.lastReviewed);
+
+  const minUsd = typeof args.flags.get('min-usd') === 'string' ? numberFlag(args, 'min-usd', 0, t) : 0;
+  const actions = plan.actions.filter((a) => (a.savingUsd ?? a.stakeUsd ?? 0) >= minUsd);
+  const filtered = plan.actions.length - actions.length;
+  const droppedUsd = plan.actions
+    .filter((a) => (a.savingUsd ?? a.stakeUsd ?? 0) < minUsd)
+    .reduce((sum, a) => sum + (a.savingUsd ?? a.stakeUsd ?? 0), 0);
+
+  const n = (value: number): string => value.toLocaleString(t.numberLocale);
+  /**
+   * The document's totals cover the actions the document holds — a filtered
+   * plan whose totals still counted the filtered actions would be a file
+   * that contradicts itself, and 1.39's verify would hold it to money it
+   * cannot see. What --min-usd dropped is stated with its worth, never
+   * silently.
+   */
+  const stamped = {
+    ...plan,
+    actions,
+    projectedSavingUsd: actions.reduce((sum, a) => sum + (a.savingUsd ?? 0), 0),
+    measuredStakeUsd: actions.reduce((sum, a) => sum + (a.stakeUsd ?? 0), 0),
+    createdAt: new Date().toISOString(),
+  };
+
+  const outPath = stringFlag(args, 'out');
+  if (outPath !== undefined) {
+    await writeFile(outPath, `${JSON.stringify(stamped, null, 2)}\n`);
+  }
+
+  await writeMarkdown(args, () => {
+    const lines: string[] = [];
+    lines.push(`## ${t.plan.heading(n(actions.length), formatUsd(plan.totalUsd))}`);
+    lines.push('');
+    lines.push(t.plan.totals(formatUsd(stamped.projectedSavingUsd), formatUsd(stamped.measuredStakeUsd)));
+    if (plan.span === null) {
+      lines.push('');
+      lines.push(`_${t.plan.noClock()}_`);
+    }
+    for (const action of actions) {
+      const name = action.label === UNLABELLED ? t.profile.unlabelled() : action.label;
+      const money =
+        action.savingUsd !== null
+          ? t.plan.projected(formatUsd(action.savingUsd))
+          : t.plan.staked(formatUsd(action.stakeUsd ?? 0));
+      lines.push('');
+      lines.push(`### ${t.plan.action(action.kind, name, action.model)} — ${money}`);
+      if (action.detail.routeTo !== undefined) lines.push(`- ${t.plan.routeTo(action.detail.routeTo.displayName)}`);
+      for (const assumption of action.assumes) lines.push(`- ${t.plan.assume(assumption)}`);
+      if (action.check !== null) lines.push(`- ${t.plan.check(action.check)}`);
+    }
+    if (filtered > 0) {
+      lines.push('');
+      lines.push(`_${t.plan.filtered(n(filtered), formatUsd(minUsd), formatUsd(droppedUsd))}_`);
+    }
+    lines.push('');
+    lines.push(`_${t.plan.footer()}_`);
+    return lines.join('\n');
+  });
+
+  if (boolFlag(args, 'json')) {
+    console.log(JSON.stringify(stamped, null, 2));
+    return;
+  }
+
+  console.log(c.bold(t.plan.heading(n(actions.length), formatUsd(plan.totalUsd))));
+  console.log(
+    `  ${wrap(t.plan.totals(formatUsd(stamped.projectedSavingUsd), formatUsd(stamped.measuredStakeUsd)), 74, '  ')}`,
+  );
+  if (plan.span === null) {
+    console.log(`  ${c.dim(wrap(t.plan.noClock(), 74, '  '))}`);
+  }
+  for (const action of actions) {
+    const name = action.label === UNLABELLED ? t.profile.unlabelled() : action.label;
+    const money =
+      action.savingUsd !== null
+        ? t.plan.projected(formatUsd(action.savingUsd))
+        : t.plan.staked(formatUsd(action.stakeUsd ?? 0));
+    console.log();
+    console.log(`  ${c.green('→')} ${c.bold(t.plan.action(action.kind, name, action.model))}  ${money}`);
+    if (action.detail.routeTo !== undefined) {
+      console.log(`    ${c.dim(t.plan.routeTo(action.detail.routeTo.displayName))}`);
+    }
+    for (const assumption of action.assumes) {
+      console.log(`    ${c.yellow('?')} ${c.dim(wrap(t.plan.assume(assumption), 72, '      '))}`);
+    }
+    if (action.check !== null) {
+      console.log(`    ${c.dim(wrap(t.plan.check(action.check), 72, '      '))}`);
+    }
+  }
+  if (filtered > 0) {
+    console.log();
+    console.log(`  ${c.dim(wrap(t.plan.filtered(n(filtered), formatUsd(minUsd), formatUsd(droppedUsd)), 74, '  '))}`);
+  }
+  console.log();
+  console.log(`  ${c.dim(wrap(t.plan.footer(), 74, '  '))}`);
+  if (outPath !== undefined) console.log(c.dim(wrap(t.plan.wrote(outPath), 74, '')));
+}
+
 async function commandProfile(args: Args, config: TrazumConfig, pricing: PricingCatalogue, t: CliMessages): Promise<void> {
   const path = args.positional[0];
   if (path === undefined) {
@@ -2227,7 +2371,6 @@ async function commandProfile(args: Args, config: TrazumConfig, pricing: Pricing
    * directory holding nothing readable is an error naming what it looked for,
    * not an empty report.
    */
-  const LOG_EXTENSIONS = ['.jsonl', '.ndjson', '.log', '.json'];
   /**
    * The same names, gzipped — which is what a rotated log actually looks like
    * a day after it rotates.
@@ -6015,6 +6158,9 @@ async function main(): Promise<void> {
     case 'profile':
       await commandProfile(args, config, pricing, t);
       break;
+    case 'plan':
+      await commandPlan(args, pricing, t);
+      break;
     case 'route':
       await commandRoute(args, pricing, t);
       break;