@trazum/cli 1.50.8 → 1.50.9

package/package.json

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

package/src/i18n/en.ts

@@ -60,6 +60,7 @@ ${bold('USAGE')}
   trazum gateway <anthropic|openai> --on-cannot-tell <fail-open|fail-closed>
   trazum experiment <log> --a <label> --b <label> --min-outcomes <n>
   trazum quality <log> --label <name> --at <iso> [--gate]
+  trazum semantic <prompt> [--yes]
   trazum ladder <log>
   trazum feedback
   trazum --version
@@ -147,6 +148,17 @@ ${bold('OPTIONS FOR quality')}
   whenever the model mix, the call volume or the outcome coverage moved across
   the boundary — the prompt is not the only variable and it says so.
 
+${bold('OPTIONS FOR semantic')}
+  --yes                       Required to send anything. Without it the command
+                              prints what the call would cost and stops.
+  --model <id>                Which model to ask. Priced from the catalogue.
+
+  Finds what a dictionary cannot: the same rule taught twice in different
+  words, an instruction restated far away, a policy a later clause contradicts.
+  Every quoted passage is checked character for character against the prompt,
+  pairs the rules engine already catches are dropped, and every token figure is
+  counted rather than believed. Optional, and always will be.
+
 ${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
@@ -992,6 +1004,36 @@ ${bold('EXAMPLES')}
       `${path} exists and could not be parsed, so nothing was written over it. Fix or move it first.`,
   },
 
+  semantic: {
+    heading: (path) => `Semantic pass on ${path}`,
+    willCost: (usd, input, output, model) =>
+      `This will send the prompt to ${model}: about ${input} tokens in and ${output} out, roughly ${usd}. Estimated, not measured \u2014 a tool that spends your money to tell you how to spend less should be the first thing audited by its own arithmetic. Pass --yes to run it.`,
+    needsYes: () => 'Nothing was sent. Add --yes once you have read the price above.',
+    finding: (kind, because) =>
+      `${kind === 'contradiction' ? 'Contradiction' : kind === 'restated-instruction' ? 'Restated' : 'Same thing, different words'}: ${because}`,
+    span: (line, text) => `line ${line}: ${text}`,
+    ceiling: (tokens) =>
+      `At most ${tokens} tokens \u2014 a ceiling, not a saving. Merging these two means writing one passage that does the work of both, and nobody knows yet how long that is.`,
+    noCeiling: () =>
+      'No tokens attached. A contradiction is worth fixing because the prompt is wrong, not because it is long, and putting a figure on it would sell the wrong reason.',
+    nothingFound: () => 'Nothing survived checking. That is a real answer.',
+    rejected: (count) => `${count} proposals did not survive checking against the prompt.`,
+    rejectedLine: (reason, span) =>
+      reason === 'span-not-found'
+        ? `paraphrased its own evidence: ${span}`
+        : reason === 'already-detected'
+          ? `already found without a model: ${span}`
+          : reason === 'contradiction-of-a-copy'
+            ? `called a near-copy a contradiction: ${span}`
+            : reason === 'spans-identical' || reason === 'spans-overlap'
+              ? `quoted the same passage twice: ${span}`
+              : `covers ground an accepted finding covers: ${span}`,
+    disposes: () =>
+      'The model proposes and the deterministic layer disposes: every quoted passage is checked character for character against the prompt, pairs the rules engine already catches are dropped, and every token figure is counted here rather than believed.',
+    optIn: () =>
+      'This pass is optional and always will be. Trazum works with no key, no network and no model \u2014 that has been true since 0.1.0 and this does not change it.',
+  },
+
   quality: {
     heading: (label) => `Quality across the change: ${label}`,
     needsLabel: () => 'Name the workload with --label: this compares one label before and after a change, and a mixture of workloads would average a regression away.',

package/src/i18n/es.ts

@@ -47,6 +47,7 @@ ${bold('USO')}
   trazum gateway <anthropic|openai> --on-cannot-tell <fail-open|fail-closed>
   trazum experiment <log> --a <label> --b <label> --min-outcomes <n>
   trazum quality <log> --label <name> --at <iso> [--gate]
+  trazum semantic <prompt> [--yes]
   trazum ladder <log>
   trazum feedback
   trazum --version
@@ -137,6 +138,17 @@ ${bold('OPCIONES DE quality')}
   siempre que la mezcla de modelos, el volumen o la cobertura se movieran a
   través de la frontera — el prompt no es la única variable y lo dice.
 
+${bold('OPCIONES DE semantic')}
+  --yes                       Obligatorio para enviar nada. Sin él, el comando
+                              imprime lo que costaría la llamada y para.
+  --model <id>                Qué modelo preguntar. Se tarifa del catálogo.
+
+  Encuentra lo que un diccionario no puede: la misma regla enseñada dos veces
+  con otras palabras, una instrucción repetida lejos, una política que una
+  cláusula posterior contradice. Cada pasaje citado se comprueba carácter a
+  carácter contra el prompt, los pares que el motor de reglas ya caza se
+  descartan, y toda cifra de tokens se cuenta en vez de creérsela.
+
 ${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
@@ -1028,6 +1040,36 @@ ${bold('EJEMPLOS')}
       `${path} existe y no se pudo interpretar, así que no se escribió nada encima. Arréglalo o muévelo primero.`,
   },
 
+  semantic: {
+    heading: (path) => `Pase sem\u00e1ntico sobre ${path}`,
+    willCost: (usd, input, output, model) =>
+      `Esto enviar\u00e1 el prompt a ${model}: unos ${input} tokens de entrada y ${output} de salida, aproximadamente ${usd}. Estimado, no medido \u2014 una herramienta que gasta tu dinero para decirte c\u00f3mo gastar menos deber\u00eda ser lo primero que audite su propia aritm\u00e9tica. Pasa --yes para ejecutarlo.`,
+    needsYes: () => 'No se envi\u00f3 nada. A\u00f1ade --yes cuando hayas le\u00eddo el precio de arriba.',
+    finding: (kind, because) =>
+      `${kind === 'contradiction' ? 'Contradicci\u00f3n' : kind === 'restated-instruction' ? 'Repetido' : 'Lo mismo con otras palabras'}: ${because}`,
+    span: (line, text) => `l\u00ednea ${line}: ${text}`,
+    ceiling: (tokens) =>
+      `Como mucho ${tokens} tokens \u2014 un techo, no un ahorro. Fundir los dos significa escribir un pasaje que haga el trabajo de ambos, y nadie sabe todav\u00eda cu\u00e1nto ocupa.`,
+    noCeiling: () =>
+      'Sin tokens asociados. Una contradicci\u00f3n merece arreglarse porque el prompt est\u00e1 mal, no porque sea largo, y ponerle una cifra vender\u00eda el motivo equivocado.',
+    nothingFound: () => 'Nada sobrevivi\u00f3 a la comprobaci\u00f3n. Esa es una respuesta real.',
+    rejected: (count) => `${count} propuestas no sobrevivieron a la comprobaci\u00f3n contra el prompt.`,
+    rejectedLine: (reason, span) =>
+      reason === 'span-not-found'
+        ? `parafrase\u00f3 su propia evidencia: ${span}`
+        : reason === 'already-detected'
+          ? `ya se encuentra sin modelo: ${span}`
+          : reason === 'contradiction-of-a-copy'
+            ? `llam\u00f3 contradicci\u00f3n a una casi copia: ${span}`
+            : reason === 'spans-identical' || reason === 'spans-overlap'
+              ? `cit\u00f3 el mismo pasaje dos veces: ${span}`
+              : `cubre terreno que ya cubre un hallazgo aceptado: ${span}`,
+    disposes: () =>
+      'El modelo propone y la capa determinista dispone: cada pasaje citado se comprueba car\u00e1cter a car\u00e1cter contra el prompt, los pares que el motor de reglas ya caza se descartan, y toda cifra de tokens se cuenta aqu\u00ed en vez de cre\u00e9rsela.',
+    optIn: () =>
+      'Este pase es opcional y siempre lo ser\u00e1. Trazum funciona sin clave, sin red y sin modelo \u2014 eso es cierto desde 0.1.0 y esto no lo cambia.',
+  },
+
   quality: {
     heading: (label) => `Calidad a trav\u00e9s del cambio: ${label}`,
     needsLabel: () => 'Nombra la carga con --label: esto compara una etiqueta antes y despu\u00e9s de un cambio, y una mezcla de cargas promediar\u00eda una regresi\u00f3n hasta hacerla desaparecer.',

package/src/i18n/types.ts

@@ -268,6 +268,21 @@ 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.
    */
+  semantic: {
+    heading(path: string): string;
+    willCost(usd: string, input: string, output: string, model: string): string;
+    needsYes(): string;
+    finding(kind: string, because: string): string;
+    span(line: string, text: string): string;
+    ceiling(tokens: string): string;
+    noCeiling(): string;
+    nothingFound(): string;
+    rejected(count: string): string;
+    rejectedLine(reason: string, span: string): string;
+    disposes(): string;
+    optIn(): string;
+  };
+
   quality: {
     heading(label: string): string;
     needsLabel(): string;

package/src/index.ts

@@ -42,6 +42,9 @@ import {
   BREAK_EVEN_BAND,
   runExperiment,
   qualityGate,
+  semanticPassCost,
+  verifySemanticProposals,
+  SEMANTIC_SYSTEM_PROMPT,
   ladderPosition,
   validateLadder,
   outcomeReport,
@@ -143,6 +146,7 @@ import type {
   ContractName,
   ExperimentArm,
   GateSide,
+  SemanticProposal,
   FailurePolicy,
   GatewayStanding,
   UsageProfileReport,
@@ -584,6 +588,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
   ladder: ['pricing', 'pricing-live', 'since', 'until', 'label'],
   experiment: ['a', 'b', 'min-outcomes', 'pricing', 'pricing-live'],
   quality: ['label', 'at', 'gate', 'pricing', 'pricing-live'],
+  semantic: ['yes', 'model', 'pricing', 'pricing-live'],
   where: [],
   rules: [],
   blame: ['limit', 'model', 'calls', 'output-tokens', 'batch', 'prompt', 'markdown-out'],
@@ -2609,6 +2614,126 @@ async function commandQuality(
   console.log();
 }
 
+/**
+ * `trazum semantic <prompt> [--yes]` — the findings a dictionary cannot see.
+ *
+ * The rules engine has deferred these since 0.1.0 for one honest reason: a
+ * dictionary cannot see meaning, and a model that hallucinates a finding is
+ * worse than a rule that misses one.
+ *
+ * **The price is printed before anything is sent, and `--yes` is required.** A
+ * tool that spends somebody's money to tell them how to spend less has to be
+ * the first thing audited by its own arithmetic, and it has to ask.
+ */
+async function commandSemantic(
+  args: Args,
+  config: TrazumConfig,
+  pricing: PricingCatalogue,
+  t: CliMessages,
+): Promise<void> {
+  const prompt = await readInput(args.positional[0], t);
+  const modelId = stringFlag(args, 'model') ?? config.usage?.model ?? DEFAULT_USAGE.model;
+  const model = pricing.byId.get(modelId) ?? getModel(DEFAULT_USAGE.model);
+  const rates = { inputPerMTok: model.inputPerMTok, outputPerMTok: model.outputPerMTok };
+  const cost = semanticPassCost(prompt, rates);
+  const n = (value: number): string => value.toLocaleString(t.numberLocale);
+
+  console.log();
+  console.log(c.bold(t.semantic.heading(args.positional[0] ?? '-')));
+  console.log();
+  console.log(
+    `  ${wrap(
+      t.semantic.willCost(formatUsd(cost.usd), n(cost.inputTokens), n(cost.outputTokens), model.displayName),
+      74,
+      '  ',
+    )}`,
+  );
+
+  if (!boolFlag(args, 'yes')) {
+    // Nothing has been sent at this point, and nothing will be. The price
+    // above is the whole output of a run without --yes.
+    console.log();
+    console.log(`  ${c.dim(t.semantic.needsYes())}`);
+    console.log();
+    return;
+  }
+
+  const provider = providerFromEnv();
+  if (!provider) throw new Error(t.errors.llmNotConfigured());
+
+  const answer = await provider.complete({ system: SEMANTIC_SYSTEM_PROMPT, user: prompt });
+  let proposals: SemanticProposal[] = [];
+  try {
+    const parsed: unknown = JSON.parse(
+      /^(?:```|~~~)[a-zA-Z]*\n([\s\S]*?)\n?(?:```|~~~)$/.exec(answer.trim())?.[1] ?? answer.trim(),
+    );
+    /**
+     * A response that is not the shape asked for is **no proposals**, never a
+     * crash and never a partial read. The model was told exactly what to
+     * return; anything else is a response this layer cannot check, and an
+     * unchecked finding is the one thing this whole module exists to prevent.
+     */
+    if (Array.isArray(parsed)) {
+      proposals = parsed.filter(
+        (entry): entry is SemanticProposal =>
+          typeof entry === 'object' &&
+          entry !== null &&
+          Array.isArray((entry as SemanticProposal).spans) &&
+          (entry as SemanticProposal).spans.length === 2 &&
+          (entry as SemanticProposal).spans.every((span) => typeof span === 'string'),
+      );
+    }
+  } catch {
+    proposals = [];
+  }
+
+  const result = verifySemanticProposals(prompt, proposals);
+  const lineOf = (offset: number): number => prompt.slice(0, offset).split('\n').length;
+
+  console.log();
+  if (result.findings.length === 0) {
+    console.log(`  ${c.dim(t.semantic.nothingFound())}`);
+  }
+  for (const finding of result.findings) {
+    console.log(`  ${c.bold(t.semantic.finding(finding.kind, finding.because))}`);
+    finding.spans.forEach((span, index) => {
+      const shown = span.length > 90 ? `${span.slice(0, 87)}…` : span;
+      console.log(`    ${c.dim(t.semantic.span(String(lineOf(finding.offsets[index] ?? 0)), shown))}`);
+    });
+    console.log(
+      `    ${c.dim(
+        wrap(
+          finding.ceilingTokens > 0 ? t.semantic.ceiling(n(finding.ceilingTokens)) : t.semantic.noCeiling(),
+          70,
+          '    ',
+        ),
+      )}`,
+    );
+    console.log();
+  }
+
+  /**
+   * What did **not** survive, counted and reasoned.
+   *
+   * A pass that showed only its accepted findings would hide its own hit
+   * rate, and the hit rate is the most useful thing a reader can know about
+   * whether to run it again.
+   */
+  if (result.rejected.length > 0) {
+    console.log(`  ${c.dim(t.semantic.rejected(n(result.rejected.length)))}`);
+    for (const { proposal, reason } of result.rejected.slice(0, 5)) {
+      const span = proposal.spans[0];
+      const shown = span.length > 50 ? `${span.slice(0, 47)}…` : span;
+      console.log(`    ${c.dim(t.semantic.rejectedLine(reason, shown))}`);
+    }
+    console.log();
+  }
+
+  console.log(`  ${c.dim(wrap(t.semantic.disposes(), 74, '  '))}`);
+  console.log(`  ${c.dim(wrap(t.semantic.optIn(), 74, '  '))}`);
+  console.log();
+}
+
 function commandModels(t: CliMessages, pricing: PricingCatalogue): void {
   const n = (value: number): string => value.toLocaleString(t.numberLocale);
   const col = t.models.columns;
@@ -8809,6 +8934,9 @@ async function main(): Promise<void> {
     case 'models':
       commandModels(t, pricing);
       break;
+    case 'semantic':
+      await commandSemantic(args, config, pricing, t);
+      break;
     case 'quality':
       await commandQuality(args, config, pricing, t);
       break;