@trazum/cli 1.53.0 → 1.53.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@trazum/cli",
3
- "version": "1.53.0",
3
+ "version": "1.53.2",
4
4
  "description": "Trazum CLI: find where your LLM bill goes, price every finding per month, and enforce token budgets in CI.",
5
5
  "license": "MIT",
6
6
  "author": "David Mu\u00f1oz Rey",
@@ -37,7 +37,7 @@
37
37
  "prepublishOnly": "npm run build && npm test"
38
38
  },
39
39
  "dependencies": {
40
- "@trazum/core": "1.53.0"
40
+ "@trazum/core": "1.53.2"
41
41
  },
42
42
  "devDependencies": {
43
43
  "@types/node": "^26.2.0",
package/src/i18n/en.ts CHANGED
@@ -42,8 +42,9 @@ ${bold('USAGE')}
42
42
  trazum route <log.jsonl> --prompt-file <file> --cases <file> --yes
43
43
  trazum plan <log.jsonl|dir> [options]
44
44
  trazum verify <plan.json> --against <newer.jsonl|dir> [options]
45
+ trazum profile <log.jsonl|dir> [options]
45
46
  trazum history <dir-of-stored-reports> [options]
46
- trazum connect <anthropic|openai> [options]
47
+ trazum connect <provider> [options]
47
48
  trazum store [--prune] [options]
48
49
  trazum watch [--once | --interval 15m] [options]
49
50
  trazum serve [--port <n> | --socket <path>]
@@ -57,7 +58,7 @@ ${bold('USAGE')}
57
58
  trazum conform <file|-> [--contract <name>]
58
59
  trazum models
59
60
  trazum rules
60
- trazum gateway <anthropic|openai> --on-cannot-tell <fail-open|fail-closed>
61
+ trazum gateway <provider> --on-cannot-tell <fail-open|fail-closed>
61
62
  trazum experiment <log> --a <label> --b <label> --min-outcomes <n>
62
63
  trazum quality <log> --label <name> --at <iso> [--gate]
63
64
  trazum semantic <prompt> [--yes]
@@ -206,6 +207,12 @@ ${bold('OPTIONS FOR eval')}
206
207
  for the question agreement cannot answer.
207
208
  -o, --out <file> Where to write it. Defaults to stdout.
208
209
 
210
+ Runs both prompt versions over your cases and reports whether the
211
+ optimisation changed the answers. Costs THREE provider calls per case: the
212
+ original twice, to measure the model's own run-to-run variance, and the
213
+ optimised once. That baseline is the yardstick — without it, a divergence
214
+ figure means nothing. Exits with code 1 when the answers genuinely diverge.
215
+
209
216
  ${bold('OPTIONS FOR rank')}
210
217
  --level <safe|aggressive> Which rules to count as recoverable. Default: safe.
211
218
  --model, --calls, Price the recoverable tokens, as in optimize.
@@ -295,7 +302,8 @@ ${bold('OPTIONS FOR optimize')}
295
302
  order mattered. Refuses on any block that refers
296
303
  backwards ("the text above"), and says which phrase.
297
304
  --llm Add a pass through the LLM configured by environment.
298
- --exact-tokens Count tokens with the official API instead of the heuristic.
305
+ --exact-tokens Count tokens with Anthropic's endpoint, not the heuristic.
306
+ Claude models only: it is Claude's tokenizer.
299
307
  --tokens-only Report the token saving and no money at all. The
300
308
  default inside Claude Code, Codex or Cursor, where
301
309
  a subscription means there is no bill to reduce.
@@ -352,17 +360,21 @@ ${bold('OPTIONS FOR baseline')}
352
360
  "0 failures" from a check that measured nothing is the most misleading
353
361
  thing this tool could tell you.
354
362
 
355
- ${bold('OPTIONS FOR eval')}
356
- --cases <file> Inputs to test, one per line or a JSON array. Required.
357
- --level <safe|aggressive> Level to optimise with before comparing.
358
- --concurrency <n> Cases in flight at once. Default: 3.
359
- --json Result as JSON.
360
-
361
- Runs both prompt versions over your cases and reports whether the
362
- optimisation changed the answers. Costs THREE provider calls per case: the
363
- original twice, to measure the model's own run-to-run variance, and the
364
- optimised once. That baseline is the yardstick — without it, a divergence
365
- figure means nothing. Exits with code 1 when the answers genuinely diverge.
363
+ ${bold('OPTIONS FOR ladder')}
364
+ --since <when> Read only calls in this window. A UTC day
365
+ --until <when> (2026-08-14), a full ISO 8601 timestamp, a
366
+ relative window (7d, 24h) or "now". Calls with no
367
+ "ts" cannot be placed and are left out — counted
368
+ out loud, never dropped silently.
369
+ --label <name> Judge one workload's ladder rather than the whole
370
+ log. A label that matches nothing is an error
371
+ naming the labels that exist.
372
+
373
+ ${bold('OPTIONS FOR owners')}
374
+ --since <when> Read only calls in this window, in the same forms
375
+ --until <when> the other commands take. What no owner claims is
376
+ reported as unallocated and never spread across
377
+ the ones that are known.
366
378
 
367
379
  ${bold('OPTIONS FOR profile')}
368
380
  --against <log.jsonl> Compare this bill to a previous log. Positive
@@ -802,6 +814,21 @@ ${bold('EXAMPLES')}
802
814
  'Set TRAZUM_LLM_BASE_URL and TRAZUM_LLM_MODEL (OpenAI-compatible endpoint),\n' +
803
815
  'or TRAZUM_LLM_PROVIDER=anthropic with TRAZUM_LLM_API_KEY.',
804
816
  exactTokensNeedsKey: () => '--exact-tokens needs ANTHROPIC_API_KEY in the environment.',
817
+ /**
818
+ * Named, and told what it cannot do rather than merely that it will not.
819
+ *
820
+ * The alternative on offer has to be somebody else's tooling, because
821
+ * Trazum has none for this family — saying so is the whole refusal. A
822
+ * refusal never arrives bare.
823
+ */
824
+ exactTokensWrongFamily: (model, provider) =>
825
+ `--exact-tokens counts with Anthropic's endpoint, which counts Claude's tokenizer${
826
+ provider === null
827
+ ? `, and the catalogue records no provider for "${model}" — so which tokenizer it uses is not something Trazum knows`
828
+ : `, and ${model} is a model from ${provider}`
829
+ }. Counting it there would either be refused upstream or return a number for a different tokenizer, and this tool will not label that exact. Drop --exact-tokens for the estimate — which is honest about being one — or count with ${
830
+ provider === null ? "that model's" : provider + "'s"
831
+ } own tooling.`,
805
832
  checkNeedsMaxTokens: () => 'trazum check needs --max-tokens <n>.',
806
833
  evalNeedsCases: () => 'trazum eval needs --cases <file>.',
807
834
  unknownExportFormat: (received, allowed) =>
package/src/i18n/es.ts CHANGED
@@ -29,8 +29,9 @@ ${bold('USO')}
29
29
  trazum route <log.jsonl> --prompt-file <fichero> --cases <fichero> --yes
30
30
  trazum plan <log.jsonl|dir> [opciones]
31
31
  trazum verify <plan.json> --against <nuevo.jsonl|dir> [opciones]
32
+ trazum profile <log.jsonl|dir> [opciones]
32
33
  trazum history <dir-de-informes-guardados> [opciones]
33
- trazum connect <anthropic|openai> [opciones]
34
+ trazum connect <provider> [opciones]
34
35
  trazum store [--prune] [opciones]
35
36
  trazum watch [--once | --interval 15m] [opciones]
36
37
  trazum serve [--port <n> | --socket <ruta>]
@@ -44,7 +45,7 @@ ${bold('USO')}
44
45
  trazum conform <fichero|-> [--contract <nombre>]
45
46
  trazum models
46
47
  trazum rules
47
- trazum gateway <anthropic|openai> --on-cannot-tell <fail-open|fail-closed>
48
+ trazum gateway <provider> --on-cannot-tell <fail-open|fail-closed>
48
49
  trazum experiment <log> --a <label> --b <label> --min-outcomes <n>
49
50
  trazum quality <log> --label <name> --at <iso> [--gate]
50
51
  trazum semantic <prompt> [--yes]
@@ -198,6 +199,12 @@ ${bold('OPCIONES DE eval')}
198
199
  concordancia no puede contestar.
199
200
  -o, --out <fichero> Dónde escribirla. Por defecto, stdout.
200
201
 
202
+ Ejecuta las dos versiones del prompt sobre tus casos y dice si la
203
+ optimización ha cambiado las respuestas. Cuesta TRES llamadas por caso: el
204
+ original dos veces, para medir la varianza propia del modelo, y el optimizado
205
+ una. Esa base es la vara de medir: sin ella, un porcentaje de divergencia no
206
+ significa nada. Sale con código 1 cuando las respuestas divergen de verdad.
207
+
201
208
  ${bold('OPCIONES DE rank')}
202
209
  --level <safe|aggressive> Qué reglas cuentan como recuperables. Por defecto: safe.
203
210
  --model, --calls, Calcula el coste de los tokens recuperables, como
@@ -351,17 +358,21 @@ ${bold('OPCIONES DE baseline')}
351
358
  Nunca falla. Registrar no es un veredicto, y un comando que pudiera fallar
352
359
  mientras escribe aquello con lo que arreglarías el fallo es un bucle.
353
360
 
354
- ${bold('OPCIONES DE eval')}
355
- --cases <fichero> Entradas a probar, una por línea o array JSON. Obligatorio.
356
- --level <safe|aggressive> Nivel con el que optimizar antes de comparar.
357
- --concurrency <n> Casos en paralelo. Por defecto: 3.
358
- --json Resultado en JSON.
359
-
360
- Ejecuta las dos versiones del prompt sobre tus casos y dice si la
361
- optimización ha cambiado las respuestas. Cuesta TRES llamadas por caso: el
362
- original dos veces, para medir la varianza propia del modelo, y el optimizado
363
- una. Esa base es la vara de medir: sin ella, un porcentaje de divergencia no
364
- significa nada. Sale con código 1 cuando las respuestas divergen de verdad.
361
+ ${bold('OPCIONES DE ladder')}
362
+ --since <cuándo> Lee solo las llamadas de esta ventana. Un día UTC
363
+ --until <cuándo> (2026-08-14), una marca ISO 8601 completa, una
364
+ ventana relativa (7d, 24h) o "now". Las llamadas
365
+ sin "ts" no se pueden situar y quedan fuera: se
366
+ cuentan en voz alta, nunca se tiran en silencio.
367
+ --label <nombre> Juzga la escalera de un solo workload en vez de
368
+ todo el registro. Una etiqueta que no casa con
369
+ nada es un error que nombra las que existen.
370
+
371
+ ${bold('OPCIONES DE owners')}
372
+ --since <cuándo> Lee solo las llamadas de esta ventana, en las
373
+ --until <cuándo> mismas formas que aceptan los demás comandos. Lo
374
+ que no reclama ningún dueño se reporta como sin
375
+ asignar y nunca se reparte entre los conocidos.
365
376
 
366
377
  ${bold('OPCIONES DE profile')}
367
378
  --against <log.jsonl> Compara esta factura con un registro anterior.
@@ -829,6 +840,14 @@ ${bold('EJEMPLOS')}
829
840
  'Define TRAZUM_LLM_BASE_URL y TRAZUM_LLM_MODEL (endpoint compatible con OpenAI),\n' +
830
841
  'o TRAZUM_LLM_PROVIDER=anthropic con TRAZUM_LLM_API_KEY.',
831
842
  exactTokensNeedsKey: () => '--exact-tokens necesita ANTHROPIC_API_KEY en el entorno.',
843
+ exactTokensWrongFamily: (model, provider) =>
844
+ `--exact-tokens cuenta con el endpoint de Anthropic, que cuenta el tokenizador de Claude${
845
+ provider === null
846
+ ? `, y el catálogo no registra proveedor para "${model}": qué tokenizador usa no es algo que Trazum sepa`
847
+ : `, y ${model} es un modelo de ${provider}`
848
+ }. Contarlo ahí sería rechazado arriba o devolvería un número de otro tokenizador, y esta herramienta no va a llamar exacto a eso. Quita --exact-tokens y quédate con la estimación —que es honesta sobre serlo— o cuenta con las herramientas de ${
849
+ provider === null ? 'ese modelo' : provider
850
+ }.`,
832
851
  checkNeedsMaxTokens: () => 'trazum check necesita --max-tokens <n>.',
833
852
  evalNeedsCases: () => 'trazum eval necesita --cases <fichero>.',
834
853
  unknownExportFormat: (received, allowed) =>
package/src/i18n/types.ts CHANGED
@@ -52,6 +52,12 @@ export interface CliMessages {
52
52
  llmNotConfigured(): string;
53
53
  applyNeedsSuggest(): string;
54
54
  exactTokensNeedsKey(): string;
55
+ /**
56
+ * `provider` is null when the model is not in the price catalogue at all —
57
+ * a different mistake from asking for an exact count on a family Trazum
58
+ * cannot count, and told as a different sentence.
59
+ */
60
+ exactTokensWrongFamily(model: string, provider: string | null): string;
55
61
  checkNeedsMaxTokens(): string;
56
62
  evalNeedsCases(): string;
57
63
  evalNoCases(path: string): string;
package/src/index.ts CHANGED
@@ -36,6 +36,7 @@ import {
36
36
  comparePrompts,
37
37
  compareToBaseline,
38
38
  computeSavings,
39
+ bandGoverns,
39
40
  countTokensAnthropic,
40
41
  DEFAULT_USAGE,
41
42
  budgetPositions,
@@ -3613,6 +3614,26 @@ async function commandOptimize(
3613
3614
  }
3614
3615
 
3615
3616
  if (boolFlag(args, 'exact-tokens')) {
3617
+ /**
3618
+ * The family check comes **before** the key check, and the order is the
3619
+ * point.
3620
+ *
3621
+ * This branch used to hand `result.usage.model` straight to Anthropic's
3622
+ * `count_tokens`. On a Claude model that is exactly right. On `gpt-5` it
3623
+ * sends somebody else's model id to Anthropic and returns either a
3624
+ * confusing upstream error or a number counted with the wrong tokenizer and
3625
+ * labelled exact — and "exact" is the strongest word this tool uses about a
3626
+ * count.
3627
+ *
3628
+ * Asking for `ANTHROPIC_API_KEY` first would send a reader on another
3629
+ * family to find a credential that could not have helped them.
3630
+ */
3631
+ const priced = pricing.byId.get(result.usage.model);
3632
+ if (!bandGoverns(priced?.provider)) {
3633
+ throw new Error(
3634
+ t.errors.exactTokensWrongFamily(result.usage.model, priced?.provider ?? null),
3635
+ );
3636
+ }
3616
3637
  const apiKey = process.env.ANTHROPIC_API_KEY;
3617
3638
  if (!apiKey) {
3618
3639
  throw new Error(t.errors.exactTokensNeedsKey());