@trazum/cli 1.50.6 → 1.50.7

package/package.json

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

package/src/i18n/en.ts

@@ -58,6 +58,7 @@ ${bold('USAGE')}
   trazum models
   trazum rules
   trazum gateway <anthropic|openai> --on-cannot-tell <fail-open|fail-closed>
+  trazum experiment <log> --a <label> --b <label> --min-outcomes <n>
   trazum ladder <log>
   trazum feedback
   trazum --version
@@ -119,6 +120,18 @@ ${bold('OPTIONS FOR gateway')}
 
   Your credential is forwarded untouched and never read. See docs/gateway.md.
 
+${bold('OPTIONS FOR experiment')}
+  --a <label>, --b <label>    The two workloads to compare.
+  --min-outcomes <n>          Required: how many outcomes each arm must record
+                              before the result may be read. A stopping rule
+                              declared after looking at the numbers is not a
+                              stopping rule, and the report says whether it was
+                              honoured.
+
+  Judges recorded outcomes and cost together. Three-valued: A wins, B wins, or
+  not separable — with the number of outcomes per arm that would settle it, so
+  "run it longer" is an instruction rather than a shrug. Nothing is promoted.
+
 ${bold('OPTIONS FOR prune')}
   --cases <file>              One input per line, or a JSON array. Required.
   --yes                       Actually spend the calls. Without it the estimate is
@@ -964,6 +977,32 @@ ${bold('EXAMPLES')}
       `${path} exists and could not be parsed, so nothing was written over it. Fix or move it first.`,
   },
 
+  experiment: {
+    heading: (a, b) => `Experiment: ${a} against ${b}`,
+    needsTwo: () =>
+      'Name two labels to compare, for example: trazum experiment <log> --a prompt-v1 --b prompt-v2',
+    needsRule: () =>
+      '--min-outcomes is required, and it is the point: a stopping rule declared after looking at the numbers is not a stopping rule. Say how many outcomes each arm must record before the result may be read.',
+    arm: (name, rate, successes, recorded, interval) =>
+      `${name}  ${rate}  (${successes} of ${recorded} recorded)  95% ${interval}`,
+    wins: (name, low, high) =>
+      `${name} wins. The difference is between ${low} and ${high} at 95% confidence \u2014 the whole interval is on one side of zero, which is what "wins" means here.`,
+    notSeparable: (why, needed) =>
+      why === 'no-difference-observed'
+        ? 'Not separable: both arms recorded the same rate. No sample size separates a difference of zero, so there is no "run it longer" to offer \u2014 there is nothing here to find.'
+        : why === 'nothing-recorded'
+          ? 'Not separable: an arm recorded no outcomes at all, so there is no rate to compare.'
+          : `Not separable on this traffic: the 95% interval on the difference includes zero. One number is larger, and that is not a finding. About ${needed} outcomes per arm would settle the difference observed so far.`,
+    peeked: (short, declared, recorded) =>
+      `Read early. The declared rule was ${declared} outcomes per arm and ${short} has ${recorded}. Nothing can stop a number being read early; this line exists so whoever reads the result later can see that it was.`,
+    honoured: (declared) => `Stopping rule honoured: both arms cleared ${declared} recorded outcomes.`,
+    marginalDearer: (better, usd) =>
+      `${better} resolves more and costs more. One extra success costs ${usd} \u2014 that figure, not the rate, is what the decision turns on.`,
+    marginalCheaper: (better) => `${better} resolves more AND costs less per call. Nothing is being traded.`,
+    neverPromotes: () =>
+      'Nothing was changed. A winner is a finding; taking it is a decision with a name attached, and it belongs in the plan like everything else.',
+  },
+
   ladder: {
     heading: () => 'Escalation ladders',
     noLadders: () =>

package/src/i18n/es.ts

@@ -45,6 +45,7 @@ ${bold('USO')}
   trazum models
   trazum rules
   trazum gateway <anthropic|openai> --on-cannot-tell <fail-open|fail-closed>
+  trazum experiment <log> --a <label> --b <label> --min-outcomes <n>
   trazum ladder <log>
   trazum feedback
   trazum --version
@@ -109,6 +110,18 @@ ${bold('OPCIONES DE gateway')}
 
   Tu credencial se reenvía intacta y nunca se lee. Ver docs/gateway.md.
 
+${bold('OPCIONES DE experiment')}
+  --a <etiqueta>, --b <etiqueta>  Las dos cargas a comparar.
+  --min-outcomes <n>          Obligatorio: cuántos resultados debe registrar
+                              cada brazo antes de poder leer el resultado. Una
+                              regla de parada declarada después de mirar los
+                              números no es una regla de parada, y el informe
+                              dice si se respetó.
+
+  Juzga resultados registrados y coste a la vez. Tres valores: gana A, gana B,
+  o no separables — con cuántos resultados por brazo lo zanjarían, para que
+  "déjalo correr más" sea una instrucción y no un encogimiento de hombros.
+
 ${bold('OPCIONES DE prune')}
   --cases <fichero>           Una entrada por línea, o un array JSON. Obligatorio.
   --yes                       Gasta las llamadas de verdad. Sin él se imprime la
@@ -1000,6 +1013,32 @@ ${bold('EJEMPLOS')}
       `${path} existe y no se pudo interpretar, así que no se escribió nada encima. Arréglalo o muévelo primero.`,
   },
 
+  experiment: {
+    heading: (a, b) => `Experimento: ${a} contra ${b}`,
+    needsTwo: () =>
+      'Nombra dos etiquetas a comparar, por ejemplo: trazum experiment <log> --a prompt-v1 --b prompt-v2',
+    needsRule: () =>
+      '--min-outcomes es obligatorio, y ese es justo el punto: una regla de parada declarada despu\u00e9s de mirar los n\u00fameros no es una regla de parada. Di cu\u00e1ntos resultados debe registrar cada brazo antes de poder leer el resultado.',
+    arm: (name, rate, successes, recorded, interval) =>
+      `${name}  ${rate}  (${successes} de ${recorded} registrados)  95% ${interval}`,
+    wins: (name, low, high) =>
+      `Gana ${name}. La diferencia est\u00e1 entre ${low} y ${high} con un 95% de confianza \u2014 el intervalo entero est\u00e1 a un lado del cero, que es lo que significa "gana" aqu\u00ed.`,
+    notSeparable: (why, needed) =>
+      why === 'no-difference-observed'
+        ? 'No separables: los dos brazos registraron la misma tasa. Ning\u00fan tama\u00f1o de muestra separa una diferencia de cero, as\u00ed que no hay ning\u00fan "d\u00e9jalo correr m\u00e1s" que ofrecer \u2014 no hay nada que encontrar.'
+        : why === 'nothing-recorded'
+          ? 'No separables: un brazo no registr\u00f3 ning\u00fan resultado, as\u00ed que no hay tasa que comparar.'
+          : `No separables con este tr\u00e1fico: el intervalo del 95% sobre la diferencia incluye el cero. Un n\u00famero es mayor, y eso no es un hallazgo. Unos ${needed} resultados por brazo zanjar\u00edan la diferencia observada hasta ahora.`,
+    peeked: (short, declared, recorded) =>
+      `Le\u00eddo antes de tiempo. La regla declarada eran ${declared} resultados por brazo y ${short} tiene ${recorded}. Nada puede impedir que se lea un n\u00famero antes de tiempo; esta l\u00ednea existe para que quien lea el resultado despu\u00e9s vea que se hizo.`,
+    honoured: (declared) => `Regla de parada respetada: los dos brazos superaron ${declared} resultados registrados.`,
+    marginalDearer: (better, usd) =>
+      `${better} resuelve m\u00e1s y cuesta m\u00e1s. Un acierto extra cuesta ${usd} \u2014 esa cifra, y no la tasa, es de lo que depende la decisi\u00f3n.`,
+    marginalCheaper: (better) => `${better} resuelve m\u00e1s Y cuesta menos por llamada. No se est\u00e1 cambiando nada por nada.`,
+    neverPromotes: () =>
+      'No se cambi\u00f3 nada. Un ganador es un hallazgo; tomarlo es una decisi\u00f3n con un nombre detr\u00e1s, y va en el plan como todo lo dem\u00e1s.',
+  },
+
   ladder: {
     heading: () => 'Escaleras de escalado',
     noLadders: () =>

package/src/i18n/types.ts

@@ -268,6 +268,20 @@ export interface CliMessages {
    * The ladder. Every line here exists to stop somebody reading "we route to
    * the cheap model first" as a saving without the number that decides it.
    */
+  experiment: {
+    heading(a: string, b: string): string;
+    needsTwo(): string;
+    needsRule(): string;
+    arm(name: string, rate: string, successes: string, recorded: string, interval: string): string;
+    wins(name: string, low: string, high: string): string;
+    notSeparable(why: string, needed: string): string;
+    peeked(short: string, declared: string, recorded: string): string;
+    honoured(declared: string): string;
+    marginalDearer(better: string, usd: string): string;
+    marginalCheaper(better: string): string;
+    neverPromotes(): string;
+  };
+
   ladder: {
     heading(): string;
     noLadders(): string;

package/src/index.ts

@@ -40,6 +40,7 @@ import {
   budgetPositions,
   conform,
   BREAK_EVEN_BAND,
+  runExperiment,
   ladderPosition,
   validateLadder,
   outcomeReport,
@@ -139,6 +140,7 @@ import type {
 import type {
   BudgetReport,
   ContractName,
+  ExperimentArm,
   FailurePolicy,
   GatewayStanding,
   UsageProfileReport,
@@ -245,6 +247,9 @@ interface Args {
 }
 
 const VALUE_FLAGS = new Set([
+  'a',
+  'b',
+  'min-outcomes',
   'against',
   'contract',
   'on-cannot-tell',
@@ -574,6 +579,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   feedback: [],
   gateway: ['on-cannot-tell', 'port', 'socket', 'pricing', 'pricing-live'],
   ladder: ['pricing', 'pricing-live', 'since', 'until', 'label'],
+  experiment: ['a', 'b', 'min-outcomes', 'pricing', 'pricing-live'],
   where: [],
   rules: [],
   blame: ['limit', 'model', 'calls', 'output-tokens', 'batch', 'prompt', 'markdown-out'],
@@ -2324,6 +2330,135 @@ async function commandLadder(
   if (anyProblem) process.exitCode = 1;
 }
 
+/**
+ * `trazum experiment <log> --a <label> --b <label> --min-outcomes <n>`
+ *
+ * Two arms on real traffic, judged on recorded outcomes and cost together.
+ *
+ * `--min-outcomes` is required and that is the entire point of it. A stopping
+ * rule declared after looking at the numbers is not a stopping rule, and
+ * nothing here can stop somebody reading a result early — what it can do is
+ * make the early read **visible to whoever reads the result later**, which is
+ * the part that survives the afternoon.
+ */
+async function commandExperiment(
+  args: Args,
+  config: TrazumConfig,
+  pricing: PricingCatalogue,
+  t: CliMessages,
+): Promise<void> {
+  const path = args.positional[0];
+  if (path === undefined) throw new Error(t.errors.missingInputFile());
+
+  const aName = stringFlag(args, 'a');
+  const bName = stringFlag(args, 'b');
+  if (aName === undefined || bName === undefined) throw new Error(t.experiment.needsTwo());
+
+  const minRaw = stringFlag(args, 'min-outcomes');
+  const minOutcomesPerArm = minRaw === undefined ? Number.NaN : Number(minRaw);
+  if (!Number.isInteger(minOutcomesPerArm) || minOutcomesPerArm < 1) {
+    throw new Error(t.experiment.needsRule());
+  }
+
+  const report = profileUsage(await readUsageLog(path, t), { catalogue: pricing });
+  const n = (value: number): string => value.toLocaleString(t.numberLocale);
+  const pct = (value: number): string => `${(value * 100).toFixed(1)}%`;
+
+  const armOf = (label: string): ExperimentArm => {
+    const slice = report.outcomeTallyByLabel.find((entry) => entry.label === label);
+    return {
+      name: label,
+      totalUsd: slice?.totalUsd ?? 0,
+      tally: slice?.tally ?? { byValue: [], recorded: 0, parsed: 0, unrecordedUsd: 0 },
+    };
+  };
+
+  const result = runExperiment(
+    { arms: [aName, bName], minOutcomesPerArm },
+    { a: armOf(aName), b: armOf(bName) },
+    config.outcomes ?? null,
+  );
+
+  console.log();
+  console.log(c.bold(t.experiment.heading(aName, bName)));
+  console.log();
+  for (const side of [result.a, result.b]) {
+    console.log(
+      `  ${t.experiment.arm(
+        side.name,
+        side.rate === null ? '—' : pct(side.rate),
+        n(side.successes),
+        n(side.recorded),
+        side.interval === null ? '—' : `[${pct(side.interval.low)}, ${pct(side.interval.high)}]`,
+      )}`,
+    );
+  }
+  console.log();
+
+  if (result.separation === 'not-separable') {
+    console.log(
+      `  ${c.dim('·')} ${wrap(
+        t.experiment.notSeparable(
+          result.notSeparable ?? '',
+          result.outcomesNeededPerArm === null ? '—' : n(result.outcomesNeededPerArm),
+        ),
+        74,
+        '    ',
+      )}`,
+    );
+  } else {
+    const winner = result.separation === 'a-wins' ? result.a.name : result.b.name;
+    const d = result.difference as { low: number; high: number };
+    // Reported as a magnitude: the sign is carried by which arm is named, and
+    // printing "-30.0% to -18.0%" beside "b wins" is two ways of saying the
+    // same thing that a reader has to reconcile.
+    const lo = Math.min(Math.abs(d.low), Math.abs(d.high));
+    const hi = Math.max(Math.abs(d.low), Math.abs(d.high));
+    console.log(`  ${c.green('✓')} ${wrap(t.experiment.wins(winner, pct(lo), pct(hi)), 74, '    ')}`);
+  }
+
+  /**
+   * The peek line, printed **whether or not** the arms separated.
+   *
+   * A separable result read too early is still separable and still read too
+   * early. Collapsing the two would hide one of the facts, and it is always
+   * the inconvenient one that goes.
+   */
+  console.log();
+  if (result.stopping.honoured) {
+    console.log(`  ${c.dim(wrap(t.experiment.honoured(n(result.stopping.declared)), 74, '    '))}`);
+  } else {
+    const short = result.stopping.short === result.a.name ? result.a : result.b;
+    console.log(
+      `  ${c.yellow('!')} ${wrap(
+        t.experiment.peeked(short.name, n(result.stopping.declared), n(short.recorded)),
+        74,
+        '    ',
+      )}`,
+    );
+  }
+
+  if (result.marginal !== null) {
+    console.log();
+    console.log(
+      `  ${wrap(
+        result.marginal.usdPerExtraSuccess !== null
+          ? t.experiment.marginalDearer(
+              result.marginal.better,
+              formatUsd(result.marginal.usdPerExtraSuccess),
+            )
+          : t.experiment.marginalCheaper(result.marginal.better),
+        74,
+        '    ',
+      )}`,
+    );
+  }
+
+  console.log();
+  console.log(`  ${c.dim(wrap(t.experiment.neverPromotes(), 74, '    '))}`);
+  console.log();
+}
+
 function commandModels(t: CliMessages, pricing: PricingCatalogue): void {
   const n = (value: number): string => value.toLocaleString(t.numberLocale);
   const col = t.models.columns;
@@ -8524,6 +8659,9 @@ async function main(): Promise<void> {
     case 'models':
       commandModels(t, pricing);
       break;
+    case 'experiment':
+      await commandExperiment(args, config, pricing, t);
+      break;
     case 'ladder':
       await commandLadder(args, config, pricing, t);
       break;