@trazum/cli 1.36.0 → 1.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.36.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.36.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]
@@ -78,6 +79,16 @@ ${bold('OPTIONS FOR rank')}
   --model, --calls,           Price the recoverable tokens, as in optimize.
   --output-tokens, --batch
   --prompt <name>             Which marked prompt to take from each source file.
+  --by-source                 The fleet: one summary per service from the
+                              config's "sources" block (name → glob patterns
+                              over log paths), plus a rollup naming the source
+                              where the money is. Shares compare totals, and
+                              when the sources' logs cover different periods
+                              the report says so rather than letting a 3-day
+                              log look cheap beside a 30-day one. Budgets per
+                              service live in spend.bySource and fail the run
+                              naming the service. Files matching no pattern
+                              are named, never silently dropped.
   --markdown-out <file>       Also write the ranking as Markdown, for a CI job
                               summary or a pull request comment.
   --json                      The ranking as data.
@@ -289,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.
@@ -1227,6 +1255,31 @@ ${bold('EXAMPLES')}
       'A ✗ is not a defect in the log; it is a finding this log cannot support yet. The README\'s recording recipe carries every field above.',
     dryRunNoGates: () =>
       '--dry-run produces no bill, so a gate beside it would exit green having judged nothing. Run the gates without --dry-run.',
+    bySourceNeedsConfig: () =>
+      '--by-source reads the "sources" block in trazum.config.json — a name per service, each with glob patterns over log paths — and this config has none. Name at least one source.',
+    bySourceNothingMatched: (sources) =>
+      'No log file matched any source pattern. The sources configured: ${sources}. Patterns match the paths as given on the command line.'.replace('${sources}', sources),
+    fleetHeading: (count, total, calls) => `The fleet: ${count} sources · ${total} · ${calls}`,
+    fleetRow: (name, usd, share, calls, span) => `${name}  ${usd}  ${share} of the fleet · ${calls} · ${span}`,
+    fleetSpan: (days) => `${days} days`,
+    fleetNoClock: () => 'no clock',
+    fleetWorst: (name, usd, share) =>
+      `${name} is where the money is: ${usd}, ${share} of the fleet's total.`,
+    fleetMismatchedSpans: () =>
+      'These sources cover different periods, so the shares above compare totals, not rates — a 3-day log looks cheap next to a 30-day one for reasons that have nothing to do with cost. Each row states its own span.',
+    fleetSplitBrain: (label, detail) =>
+      `The same workload runs on different models in different sources — ${label}: ${detail}. Same job, different rate cards; whether that is a decision or an accident is not in the logs.`,
+    fleetCacheUnderwater: (name, usd) =>
+      `Caching pays for the fleet overall but loses ${usd} in ${name} — the aggregate verdict was hiding it.`,
+    fleetUnmatched: (file) =>
+      `${file} matched no source pattern, so it is in no report above — spend missing from every bill until a pattern covers it.`,
+    fleetFooter: () =>
+      'Summaries per source; the full report for one service is "trazum profile <its logs>". Same thresholds, same findings, one source at a time.',
+    fleetBudgetOk: (name, usd, max) => `Within budget: ${name} spent ${usd} against its ${max} in spend.bySource.`,
+    fleetBudgetFailed: (name, usd, max) =>
+      `FAILED — ${name} spent ${usd} against its budget of ${max} in spend.bySource. The fleet total can be fine while one service bleeds; this gate names which.`,
+    fleetBudgetMissing: (name) =>
+      `${name} has a budget in spend.bySource and no logs matched it in this run, so nothing was measured for it. Not a pass: a service that did not appear is not a service under budget.`,
     coverageHeading: () => 'What this log cannot answer yet',
     needsLabel: (seen) =>
       `"label" on ${seen} records: without it every workload is one row, so no per-workload spend, no drill-down, and the levers describe a mixture rather than a decision.`,
@@ -1310,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]
@@ -66,6 +67,18 @@ ${bold('OPCIONES DE rank')}
   --model, --calls,           Calcula el coste de los tokens recuperables, como
   --output-tokens, --batch    en optimize.
   --prompt <nombre>           Qué prompt marcado tomar de cada fichero de código.
+  --by-source                 La flota: un resumen por servicio desde el
+                              bloque "sources" de la config (nombre → patrones
+                              glob sobre rutas de registros), más un rollup
+                              que nombra la fuente donde está el dinero. Los
+                              porcentajes comparan totales, y cuando los
+                              registros cubren periodos distintos el informe
+                              lo dice en vez de dejar que un registro de 3
+                              días parezca barato junto a uno de 30. Los
+                              presupuestos por servicio viven en
+                              spend.bySource y hacen fallar la ejecución
+                              nombrando el servicio. Los ficheros sin patrón
+                              se nombran, nunca se descartan en silencio.
   --markdown-out <fichero>    Escribe además el ranking en Markdown, para el
                               resumen de un job de CI o un comentario de PR.
   --json                      El ranking como datos.
@@ -292,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.
@@ -1243,6 +1275,31 @@ ${bold('EJEMPLOS')}
       'Una ✗ no es un defecto del registro; es un hallazgo que este registro aún no puede sostener. La receta de registro del README lleva todos los campos de arriba.',
     dryRunNoGates: () =>
       '--dry-run no produce factura, así que un gate a su lado saldría en verde sin haber juzgado nada. Corre los gates sin --dry-run.',
+    bySourceNeedsConfig: () =>
+      '--by-source lee el bloque "sources" de trazum.config.json — un nombre por servicio, cada uno con patrones glob sobre rutas de registros — y esta config no tiene ninguno. Nombra al menos una fuente.',
+    bySourceNothingMatched: (sources) =>
+      'Ningún fichero de registro coincidió con ningún patrón de fuente. Las fuentes configuradas: ${sources}. Los patrones casan con las rutas tal como se dan en la línea de comandos.'.replace('${sources}', sources),
+    fleetHeading: (count, total, calls) => `La flota: ${count} fuentes · ${total} · ${calls}`,
+    fleetRow: (name, usd, share, calls, span) => `${name}  ${usd}  ${share} de la flota · ${calls} · ${span}`,
+    fleetSpan: (days) => `${days} días`,
+    fleetNoClock: () => 'sin reloj',
+    fleetWorst: (name, usd, share) =>
+      `${name} es donde está el dinero: ${usd}, el ${share} del total de la flota.`,
+    fleetMismatchedSpans: () =>
+      'Estas fuentes cubren periodos distintos, así que los porcentajes de arriba comparan totales, no ritmos — un registro de 3 días parece barato junto a uno de 30 por motivos que nada tienen que ver con el coste. Cada fila indica su propio periodo.',
+    fleetSplitBrain: (label, detail) =>
+      `La misma carga corre en modelos distintos en fuentes distintas — ${label}: ${detail}. Mismo trabajo, tarifas distintas; si es una decisión o un accidente no está en los registros.`,
+    fleetCacheUnderwater: (name, usd) =>
+      `La caché es rentable para la flota en conjunto pero pierde ${usd} en ${name} — el veredicto agregado lo escondía.`,
+    fleetUnmatched: (file) =>
+      `${file} no coincidió con ningún patrón de fuente, así que no está en ningún informe de arriba — gasto ausente de todas las facturas hasta que un patrón lo cubra.`,
+    fleetFooter: () =>
+      'Resúmenes por fuente; el informe completo de un servicio es "trazum profile <sus registros>". Mismos umbrales, mismos hallazgos, una fuente cada vez.',
+    fleetBudgetOk: (name, usd, max) => `Dentro de presupuesto: ${name} gastó ${usd} contra su ${max} en spend.bySource.`,
+    fleetBudgetFailed: (name, usd, max) =>
+      `FALLÓ — ${name} gastó ${usd} contra su presupuesto de ${max} en spend.bySource. El total de la flota puede estar bien mientras un servicio sangra; este gate nombra cuál.`,
+    fleetBudgetMissing: (name) =>
+      `${name} tiene presupuesto en spend.bySource y ningún registro coincidió con él en esta ejecución, así que no se midió nada. No es un aprobado: un servicio que no apareció no es un servicio dentro de presupuesto.`,
     coverageHeading: () => 'Lo que este registro todavía no puede responder',
     needsLabel: (seen) =>
       `"label" en ${seen} registros: sin él todas las cargas son una sola fila, así que no hay gasto por carga, ni zoom, y las palancas describen una mezcla en vez de una decisión.`,
@@ -1326,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.
@@ -975,6 +975,26 @@ export interface CliMessages {
     dryRunNoCacheTraffic(): string;
     dryRunFooter(): string;
     dryRunNoGates(): string;
+    /**
+     * `--by-source`: the fleet. One summary per service, the rollup naming
+     * the worst offender, cross-source findings a merged bill cannot make,
+     * and per-source budgets that fail naming the service.
+     */
+    bySourceNeedsConfig(): string;
+    bySourceNothingMatched(sources: string): string;
+    fleetHeading(count: string, total: string, calls: string): string;
+    fleetRow(name: string, usd: string, share: string, calls: string, span: string): string;
+    fleetSpan(days: string): string;
+    fleetNoClock(): string;
+    fleetWorst(name: string, usd: string, share: string): string;
+    fleetMismatchedSpans(): string;
+    fleetSplitBrain(label: string, detail: string): string;
+    fleetCacheUnderwater(name: string, usd: string): string;
+    fleetUnmatched(file: string): string;
+    fleetFooter(): string;
+    fleetBudgetOk(name: string, usd: string, max: string): string;
+    fleetBudgetFailed(name: string, usd: string, max: string): string;
+    fleetBudgetMissing(name: string): string;
     coverageHeading(): string;
     needsLabel(seen: string): string;
     needsSession(seen: string): string;
@@ -1018,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.
    *