@trazum/cli 1.35.0 → 1.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/cli",
-  "version": "1.35.0",
+  "version": "1.37.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.35.0"
+    "@trazum/core": "1.37.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/src/i18n/en.ts

@@ -78,6 +78,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.
@@ -119,6 +129,20 @@ ${bold('OPTIONS FOR optimize')}
   --calls <n>                 Calls per month. Default: ${d.callsPerMonth}.
   --output-tokens <n>         Average output tokens. Default: ${d.avgOutputTokens}.
   --cache-hit-rate <0-1>      Estimated cache hit rate. Default: ${d.cacheHitRate}.
+  --all-labels                With --from-log: every prompt in the config's
+                              "labels" map, optimised and priced against its
+                              own measured traffic, ranked by what the change
+                              is worth — plus the mismatches in both
+                              directions (mapped prompts with no traffic,
+                              traffic with no mapped prompt).
+  --from-log <usage.jsonl>    Measure the three figures above from a usage log
+                              instead of typing them: real call count, real
+                              output size, real cache share, and the model the
+                              calls actually went to. Refuses the typed flags
+                              beside it, scales to a month only past a full
+                              week of data, and says which figures are
+                              measured. Pair with --label, or map the prompt
+                              under "labels" in trazum.config.json.
   --batch                     The work tolerates latency (Batch API, 50% off).
   --disable <id,id>           Turn off specific rules (see "trazum rules").
   --suggest                   Ask the LLM for phrase-level rewrites and list them
@@ -444,6 +468,18 @@ ${bold('EXAMPLES')}
     mustBeNonNegative: (name, raw) =>
       `--${name} must be a non-negative number (received: "${raw}").`,
     badLevel: (received) => `--level must be "safe" or "aggressive" (received: "${received}").`,
+    allLabelsNeedsLog: () =>
+      '--all-labels ranks prompts by measured traffic, so it needs --from-log <usage.jsonl>. Without a log every saving would be multiplied by the same typed guess, which ranks prompts by length and calls it a priority.',
+    allLabelsNeedsMap: () =>
+      '--all-labels reads the "labels" map in trazum.config.json — label to prompt file — and this config has none. Map at least one workload to its prompt.',
+    fromLogConflict: (flag) =>
+      `--from-log measures the figure --${flag} types, and merging a measurement with a guess produces a number that is neither. Pass one or the other.`,
+    fromLogNeedsLabel: (available) =>
+      `--from-log needs to know which workload this prompt is: pass --label, or map the prompt file under "labels" in trazum.config.json. Labels with traffic in this log: ${available}.`,
+    fromLogAmbiguousLabel: (target, labels) =>
+      `${target} is mapped to more than one label in trazum.config.json (${labels}), so --from-log cannot pick one silently. Pass --label.`,
+    fromLogLabelEmpty: (label, available) =>
+      `No priced call in this log carries the label "${label}", so there is nothing to measure — a zero-call profile would price this change as worthless rather than as unmeasured. Labels with traffic: ${available}.`,
     unknownRuleInDisable: (id) => `Unknown rule in --disable: "${id}". Full list: trazum rules`,
     unknownCommand: (command) => `Unknown command: "${command}". Try "trazum --help".`,
     missingInputFile: () => 'Missing input file. Use "-" to read from standard input.',
@@ -510,6 +546,30 @@ ${bold('EXAMPLES')}
     costWith: (modelName) => `Cost with ${modelName}`,
     usageLine: (calls, outputTokens, batch) =>
       `${calls} calls/month · ${outputTokens} output tokens per call${batch ? ' · Batch API' : ''}`,
+    allLabelsHeading: (count) => `Every mapped prompt against its own measured traffic — ${count} ranked by what the change is worth`,
+    allLabelsRow: (saving) => `${saving}/month if optimised`,
+    allLabelsRowPeriod: (saving) => `${saving} over the measured period if optimised`,
+    allLabelsFooter: () =>
+      'Ranked by measured traffic, not by prompt length: a big prompt on a dead workload is worth less than a small one on a busy one. Each figure is this prompt\'s token delta at its own label\'s measured rate.',
+    allLabelsUnmapped: (label, usd) =>
+      `${label} carries ${usd} of measured spend and no prompt file is mapped to it — the workload nobody can optimise because nobody said where it lives. Map it under "labels" in trazum.config.json.`,
+    allLabelsDead: (label, path) =>
+      `${label} is mapped to ${path} and has no traffic in this log — a retired workload, a renamed label, or a typo that has been silently doing nothing.`,
+    allLabelsUnreadable: (label, path) =>
+      `${label} is mapped to ${path}, which could not be read. The mapping exists; the file does not.`,
+    usageLineMeasured: (calls, days, scaled, outputTokens, batch) =>
+      `${calls} calls measured over ${days} days — ${scaled}/month at that rate · ${outputTokens} output tokens per call, measured${batch ? ' · Batch API' : ''}`,
+    usageLineMeasuredPeriod: (calls, days, outputTokens, batch) =>
+      `${calls} calls measured${days === null ? ' (the log carries no clock)' : ` over ${days} days`} · ${outputTokens} output tokens per call, measured${batch ? ' · Batch API' : ''}`,
+    measuredModelShare: (model, share, count) =>
+      `This label ran on ${count} models; the figures use ${model}, which carried ${share} of its spend.`,
+    measuredNoOutput: () =>
+      'No call in this slice recorded output tokens, so the output half of every figure below is $0 measured — not $0 assumed.',
+    perPeriodSaving: (saving, pct) => `saving ${saving} over the measured period (${pct}%)`,
+    periodNotScaled: (days) =>
+      days === null
+        ? 'Not scaled to a month: the log carries no clock, so there is no rate to scale. These figures cover exactly the calls measured.'
+        : `Not scaled to a month: ${days} days is under the week a scaling needs — shorter than one weekly cycle multiplies whichever part of the cycle it caught. These figures cover exactly the period measured.`,
     perMonthSaving: (saving, pct) => `saving ${saving}/month (${pct}%)`,
     beyondShortening: () => 'Beyond shortening the prompt',
     biggestLever: () => 'Start here:',
@@ -1177,6 +1237,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.`,

package/src/i18n/es.ts

@@ -66,6 +66,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.
@@ -109,6 +121,20 @@ ${bold('OPCIONES DE optimize')}
   --calls <n>                 Llamadas al mes. Por defecto: ${d.callsPerMonth}.
   --output-tokens <n>         Tokens de salida medios. Por defecto: ${d.avgOutputTokens}.
   --cache-hit-rate <0-1>      Tasa de acierto de caché estimada. Por defecto: ${d.cacheHitRate}.
+  --all-labels                Con --from-log: cada prompt del mapa "labels"
+                              de la config, optimizado y valorado contra su
+                              propio tráfico medido, ordenado por lo que vale
+                              el cambio — más los desajustes en ambos sentidos
+                              (prompts mapeados sin tráfico, tráfico sin
+                              prompt mapeado).
+  --from-log <usage.jsonl>    Mide las tres cifras de arriba desde un registro
+                              de uso en vez de teclearlas: llamadas reales,
+                              tamaño de salida real, cuota de caché real y el
+                              modelo al que fueron las llamadas. Rechaza los
+                              flags tecleados a su lado, escala a un mes solo
+                              con una semana completa de datos, y dice qué
+                              cifras están medidas. Combínalo con --label, o
+                              mapea el prompt en "labels" de trazum.config.json.
   --batch                     El trabajo tolera latencia (Batch API, 50% menos).
   --disable <id,id>           Desactiva reglas concretas (ver "trazum rules").
   --suggest                   Pide al LLM reescrituras a nivel de frase y las lista
@@ -451,6 +477,18 @@ ${bold('EJEMPLOS')}
     mustBeNonNegative: (name, raw) =>
       `--${name} debe ser un número no negativo (recibido: "${raw}").`,
     badLevel: (received) => `--level debe ser "safe" o "aggressive" (recibido: "${received}").`,
+    allLabelsNeedsLog: () =>
+      '--all-labels ordena los prompts por tráfico medido, así que necesita --from-log <usage.jsonl>. Sin registro cada ahorro se multiplicaría por la misma suposición tecleada, lo que ordena los prompts por longitud y lo llama prioridad.',
+    allLabelsNeedsMap: () =>
+      '--all-labels lee el mapa "labels" de trazum.config.json — etiqueta a fichero de prompt — y esta config no tiene ninguno. Mapea al menos una carga a su prompt.',
+    fromLogConflict: (flag) =>
+      `--from-log mide la cifra que --${flag} teclea, y mezclar una medición con una suposición produce un número que no es ninguna de las dos. Pasa una u otra.`,
+    fromLogNeedsLabel: (available) =>
+      `--from-log necesita saber qué carga es este prompt: pasa --label, o mapea el fichero bajo "labels" en trazum.config.json. Etiquetas con tráfico en este registro: ${available}.`,
+    fromLogAmbiguousLabel: (target, labels) =>
+      `${target} está mapeado a más de una etiqueta en trazum.config.json (${labels}), así que --from-log no puede elegir una en silencio. Pasa --label.`,
+    fromLogLabelEmpty: (label, available) =>
+      `Ninguna llamada valorada de este registro lleva la etiqueta "${label}", así que no hay nada que medir — un perfil de cero llamadas valoraría este cambio como inútil en vez de como no medido. Etiquetas con tráfico: ${available}.`,
     unknownRuleInDisable: (id) =>
       `Regla desconocida en --disable: "${id}". Lista completa: trazum rules`,
     unknownCommand: (command) => `Comando desconocido: "${command}". Prueba con "trazum --help".`,
@@ -519,6 +557,30 @@ ${bold('EJEMPLOS')}
       `${calls} llamadas/mes · ${outputTokens} tokens de salida por llamada${
         batch ? ' · Batch API' : ''
       }`,
+    allLabelsHeading: (count) => `Cada prompt mapeado contra su propio tráfico medido — ${count} ordenados por lo que vale el cambio`,
+    allLabelsRow: (saving) => `${saving}/mes si se optimiza`,
+    allLabelsRowPeriod: (saving) => `${saving} en el periodo medido si se optimiza`,
+    allLabelsFooter: () =>
+      'Ordenado por tráfico medido, no por longitud del prompt: un prompt grande en una carga muerta vale menos que uno pequeño en una ocupada. Cada cifra es el delta de tokens de este prompt al ritmo medido de su propia etiqueta.',
+    allLabelsUnmapped: (label, usd) =>
+      `${label} lleva ${usd} de gasto medido y ningún fichero de prompt está mapeado a ella — la carga que nadie puede optimizar porque nadie dijo dónde vive. Mapéala en "labels" de trazum.config.json.`,
+    allLabelsDead: (label, path) =>
+      `${label} está mapeada a ${path} y no tiene tráfico en este registro — una carga retirada, una etiqueta renombrada, o una errata que lleva sin hacer nada en silencio.`,
+    allLabelsUnreadable: (label, path) =>
+      `${label} está mapeada a ${path}, que no se pudo leer. El mapeo existe; el fichero no.`,
+    usageLineMeasured: (calls, days, scaled, outputTokens, batch) =>
+      `${calls} llamadas medidas en ${days} días — ${scaled}/mes a ese ritmo · ${outputTokens} tokens de salida por llamada, medidos${batch ? ' · Batch API' : ''}`,
+    usageLineMeasuredPeriod: (calls, days, outputTokens, batch) =>
+      `${calls} llamadas medidas${days === null ? ' (el registro no tiene reloj)' : ` en ${days} días`} · ${outputTokens} tokens de salida por llamada, medidos${batch ? ' · Batch API' : ''}`,
+    measuredModelShare: (model, share, count) =>
+      `Esta etiqueta corrió en ${count} modelos; las cifras usan ${model}, que llevó el ${share} de su gasto.`,
+    measuredNoOutput: () =>
+      'Ninguna llamada de este corte registró tokens de salida, así que la mitad de salida de cada cifra de abajo es $0 medido — no $0 supuesto.',
+    perPeriodSaving: (saving, pct) => `ahorro de ${saving} en el periodo medido (${pct}%)`,
+    periodNotScaled: (days) =>
+      days === null
+        ? 'Sin escalar a un mes: el registro no tiene reloj, así que no hay ritmo que escalar. Estas cifras cubren exactamente las llamadas medidas.'
+        : `Sin escalar a un mes: ${days} días queda por debajo de la semana que un escalado necesita — menos de un ciclo semanal multiplica la parte del ciclo que pilló. Estas cifras cubren exactamente el periodo medido.`,
     perMonthSaving: (saving, pct) => `ahorro ${saving}/mes (${pct}%)`,
     beyondShortening: () => 'Además de acortar el prompt',
     biggestLever: () => 'Empieza por aquí:',
@@ -1193,6 +1255,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.`,

package/src/i18n/types.ts

@@ -37,6 +37,13 @@ export interface CliMessages {
     optionNeedsValue(name: string): string;
     mustBeNonNegative(name: string, raw: string): string;
     badLevel(received: string): string;
+    /** `--from-log`'s refusals: contradiction, missing label, ambiguity, emptiness. */
+    allLabelsNeedsLog(): string;
+    allLabelsNeedsMap(): string;
+    fromLogConflict(flag: string): string;
+    fromLogNeedsLabel(available: string): string;
+    fromLogAmbiguousLabel(target: string, labels: string): string;
+    fromLogLabelEmpty(label: string, available: string): string;
     unknownRuleInDisable(id: string): string;
     unknownCommand(command: string): string;
     unknownFlag(name: string, allowed: string): string;
@@ -82,6 +89,28 @@ export interface CliMessages {
     llmRejected(reason: string): string;
     costWith(modelName: string): string;
     usageLine(calls: string, outputTokens: number, batch: boolean): string;
+    /**
+     * `--from-log`: the usage line names its provenance. Measured and typed
+     * are different claims about the same multiplication, and under the week
+     * floor nothing says "month".
+     */
+    /**
+     * `--all-labels`: every mapped prompt against its own measured traffic,
+     * ranked by what the change is worth, with both coverage mismatches named.
+     */
+    allLabelsHeading(count: string): string;
+    allLabelsRow(saving: string): string;
+    allLabelsRowPeriod(saving: string): string;
+    allLabelsFooter(): string;
+    allLabelsUnmapped(label: string, usd: string): string;
+    allLabelsDead(label: string, path: string): string;
+    allLabelsUnreadable(label: string, path: string): string;
+    usageLineMeasured(calls: string, days: string, scaled: string, outputTokens: number, batch: boolean): string;
+    usageLineMeasuredPeriod(calls: string, days: string | null, outputTokens: number, batch: boolean): string;
+    measuredModelShare(model: string, share: string, count: string): string;
+    measuredNoOutput(): string;
+    perPeriodSaving(saving: string, pct: string): string;
+    periodNotScaled(days: string | null): string;
     perMonthSaving(saving: string, pct: string): string;
     beyondShortening(): string;
     biggestLever(): string;
@@ -946,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;