@trazum/cli 1.50.10 → 1.50.11

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.50.10",
3
+ "version": "1.50.11",
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.50.10"
40
+ "@trazum/core": "1.50.11"
41
41
  },
42
42
  "devDependencies": {
43
43
  "@types/node": "^26.2.0",
package/src/i18n/en.ts CHANGED
@@ -61,6 +61,7 @@ ${bold('USAGE')}
61
61
  trazum experiment <log> --a <label> --b <label> --min-outcomes <n>
62
62
  trazum quality <log> --label <name> --at <iso> [--gate]
63
63
  trazum semantic <prompt> [--yes]
64
+ trazum commitment <log> --floor <usd> --discount <pct> [--months 12]
64
65
  trazum owners <log>
65
66
  trazum ladder <log>
66
67
  trazum feedback
@@ -160,6 +161,17 @@ ${bold('OPTIONS FOR semantic')}
160
161
  pairs the rules engine already catches are dropped, and every token figure is
161
162
  counted rather than believed. Optional, and always will be.
162
163
 
164
+ ${bold('OPTIONS FOR commitment')}
165
+ --floor <usd> What you commit to spending each month, after
166
+ the discount. Required.
167
+ --discount <pct> What you get off list. 20 and 0.2 both work.
168
+ --months <n> How long the deal runs. Defaults to 12.
169
+
170
+ Replays measured whole months against the deal's terms. Both directions are
171
+ priced: the months that cleared the floor, and what the floor cost in the
172
+ months that fell short — kept as its own figure, because netted into the
173
+ saving it disappears. An as-if calculation about the past, never a forecast.
174
+
163
175
  ${bold('OPTIONS FOR prune')}
164
176
  --cases <file> One input per line, or a JSON array. Required.
165
177
  --yes Actually spend the calls. Without it the estimate is
@@ -1011,6 +1023,33 @@ ${bold('EXAMPLES')}
1011
1023
  `${path} exists and could not be parsed, so nothing was written over it. Fix or move it first.`,
1012
1024
  },
1013
1025
 
1026
+ commitment: {
1027
+ heading: (floor, discount, months) =>
1028
+ `A ${months}-month commitment: ${floor} a month at ${discount} off`,
1029
+ needsTerms: () =>
1030
+ '--floor and --discount are required, and --months defaults to 12. Take them from the contract the provider is offering you: the floor is what you commit to spending each month after the discount, and the discount is what you get off list.',
1031
+ asIf: () =>
1032
+ 'This is what the deal WOULD HAVE done on the traffic you actually had. It is a measurement of the past, not a prediction \u2014 every month below happened.',
1033
+ columns: { month: 'month', list: 'list', paid: 'would pay', saving: 'saving' },
1034
+ net: (usd, months) => `Net over ${months} measured months: ${usd}.`,
1035
+ good: (usd) => `The months that cleared the floor saved ${usd}.`,
1036
+ lost: (usd, months) =>
1037
+ `${months} of them fell short, and the floor you would have paid for capacity nobody used comes to ${usd}. That figure is kept separate on purpose: netted into the line above it disappears, and the disappearing is what a vendor\u2019s slide relies on.`,
1038
+ noShortfall: () => 'No measured month would have fallen short of the floor.',
1039
+ breakEven: (usd) =>
1040
+ `Break-even is ${usd} of monthly spend. Below it you pay the floor for less usage than it buys; above it the saving grows.`,
1041
+ spread: (low, high, median) =>
1042
+ `Measured spread: ${low} to ${high}, median ${median}. That is the shortfall risk in the only form a log can state it \u2014 a count of real months and the range they covered, rather than a probability from a distribution nobody fitted.`,
1043
+ shortTerm: (covered, term) =>
1044
+ `This replays ${covered} months against a ${term}-month commitment. It is a real answer about ${covered} months and not about ${term}.`,
1045
+ cannotTell: (why, needed) =>
1046
+ why === 'no-history'
1047
+ ? 'Nothing to replay: this log has no whole months in it.'
1048
+ : `Cannot judge this from ${needed === '0' ? 'what exists' : `what exists \u2014 ${needed} more whole month(s) would settle it`}. A commitment is signed for a year, and an answer from one month is a year-long decision made on a fortnight of evidence.`,
1049
+ neverAForecast: () =>
1050
+ 'Nothing here is annualised, extrapolated or fitted to a trend. If next quarter looks nothing like last quarter, this arithmetic says nothing about it \u2014 which is the honest limit of what a log can tell you about a contract.',
1051
+ },
1052
+
1014
1053
  owners: {
1015
1054
  heading: () => 'Whose money',
1016
1055
  noOwners: () =>
package/src/i18n/es.ts CHANGED
@@ -48,6 +48,7 @@ ${bold('USO')}
48
48
  trazum experiment <log> --a <label> --b <label> --min-outcomes <n>
49
49
  trazum quality <log> --label <name> --at <iso> [--gate]
50
50
  trazum semantic <prompt> [--yes]
51
+ trazum commitment <log> --floor <usd> --discount <pct> [--months 12]
51
52
  trazum owners <log>
52
53
  trazum ladder <log>
53
54
  trazum feedback
@@ -150,6 +151,18 @@ ${bold('OPCIONES DE semantic')}
150
151
  carácter contra el prompt, los pares que el motor de reglas ya caza se
151
152
  descartan, y toda cifra de tokens se cuenta en vez de creérsela.
152
153
 
154
+ ${bold('OPCIONES DE commitment')}
155
+ --floor <usd> Lo que te comprometes a gastar cada mes, después
156
+ del descuento. Obligatorio.
157
+ --discount <pct> Lo que te quitan de tarifa. Vale 20 y vale 0.2.
158
+ --months <n> Cuánto dura el acuerdo. Por defecto 12.
159
+
160
+ Replica los meses completos medidos contra las condiciones del acuerdo. Se
161
+ tarifan las dos direcciones: los meses que superaron el suelo, y lo que
162
+ costó el suelo en los meses que se quedaron cortos — como cifra aparte,
163
+ porque metida en el ahorro desaparece. Un cálculo sobre el pasado, nunca una
164
+ previsión.
165
+
153
166
  ${bold('OPCIONES DE prune')}
154
167
  --cases <fichero> Una entrada por línea, o un array JSON. Obligatorio.
155
168
  --yes Gasta las llamadas de verdad. Sin él se imprime la
@@ -1047,6 +1060,33 @@ ${bold('EJEMPLOS')}
1047
1060
  `${path} existe y no se pudo interpretar, así que no se escribió nada encima. Arréglalo o muévelo primero.`,
1048
1061
  },
1049
1062
 
1063
+ commitment: {
1064
+ heading: (floor, discount, months) =>
1065
+ `Un compromiso de ${months} meses: ${floor} al mes con ${discount} de descuento`,
1066
+ needsTerms: () =>
1067
+ '--floor y --discount son obligatorios, y --months son 12 por defecto. S\u00e1calos del contrato que te ofrecen: el suelo es lo que te comprometes a gastar cada mes despu\u00e9s del descuento, y el descuento es lo que te quitan de tarifa.',
1068
+ asIf: () =>
1069
+ 'Esto es lo que el acuerdo HABR\u00cdA hecho sobre el tr\u00e1fico que realmente tuviste. Es una medici\u00f3n del pasado, no una predicci\u00f3n \u2014 todos los meses de abajo ocurrieron.',
1070
+ columns: { month: 'mes', list: 'tarifa', paid: 'pagar\u00edas', saving: 'ahorro' },
1071
+ net: (usd, months) => `Neto sobre ${months} meses medidos: ${usd}.`,
1072
+ good: (usd) => `Los meses que superaron el suelo ahorraron ${usd}.`,
1073
+ lost: (usd, months) =>
1074
+ `${months} de ellos se quedaron cortos, y el suelo que habr\u00edas pagado por capacidad que nadie us\u00f3 suma ${usd}. Esa cifra se mantiene aparte a prop\u00f3sito: metida en la l\u00ednea de arriba desaparece, y esa desaparici\u00f3n es de lo que vive la diapositiva de un comercial.`,
1075
+ noShortfall: () => 'Ning\u00fan mes medido se habr\u00eda quedado por debajo del suelo.',
1076
+ breakEven: (usd) =>
1077
+ `El equilibrio est\u00e1 en ${usd} de gasto mensual. Por debajo pagas el suelo por menos uso del que compra; por encima el ahorro crece.`,
1078
+ spread: (low, high, median) =>
1079
+ `Dispersi\u00f3n medida: de ${low} a ${high}, mediana ${median}. Ese es el riesgo de quedarse corto en la \u00fanica forma en que un log puede expresarlo \u2014 un recuento de meses reales y el rango que cubrieron, no una probabilidad de una distribuci\u00f3n que nadie ajust\u00f3.`,
1080
+ shortTerm: (covered, term) =>
1081
+ `Esto replica ${covered} meses contra un compromiso de ${term} meses. Es una respuesta real sobre ${covered} meses y no sobre ${term}.`,
1082
+ cannotTell: (why, needed) =>
1083
+ why === 'no-history'
1084
+ ? 'Nada que replicar: este log no tiene meses completos.'
1085
+ : `No se puede juzgar con ${needed === '0' ? 'lo que hay' : `lo que hay \u2014 ${needed} mes(es) completo(s) m\u00e1s lo zanjar\u00edan`}. Un compromiso se firma por un a\u00f1o, y una respuesta de un mes es una decisi\u00f3n anual tomada con quince d\u00edas de evidencia.`,
1086
+ neverAForecast: () =>
1087
+ 'Aqu\u00ed nada se anualiza, se extrapola ni se ajusta a una tendencia. Si el pr\u00f3ximo trimestre no se parece al anterior, esta aritm\u00e9tica no dice nada sobre \u00e9l \u2014 que es el l\u00edmite honesto de lo que un log puede contarte sobre un contrato.',
1088
+ },
1089
+
1050
1090
  owners: {
1051
1091
  heading: () => 'De qui\u00e9n es el dinero',
1052
1092
  noOwners: () =>
package/src/i18n/types.ts CHANGED
@@ -268,6 +268,22 @@ export interface CliMessages {
268
268
  * The ladder. Every line here exists to stop somebody reading "we route to
269
269
  * the cheap model first" as a saving without the number that decides it.
270
270
  */
271
+ commitment: {
272
+ heading(floor: string, discount: string, months: string): string;
273
+ needsTerms(): string;
274
+ asIf(): string;
275
+ columns: { month: string; list: string; paid: string; saving: string };
276
+ net(usd: string, months: string): string;
277
+ good(usd: string): string;
278
+ lost(usd: string, months: string): string;
279
+ noShortfall(): string;
280
+ breakEven(usd: string): string;
281
+ spread(low: string, high: string, median: string): string;
282
+ shortTerm(covered: string, term: string): string;
283
+ cannotTell(why: string, needed: string): string;
284
+ neverAForecast(): string;
285
+ };
286
+
271
287
  owners: {
272
288
  heading(): string;
273
289
  noOwners(): string;
package/src/index.ts CHANGED
@@ -41,6 +41,8 @@ import {
41
41
  conform,
42
42
  BREAK_EVEN_BAND,
43
43
  allocate,
44
+ replayCommitment,
45
+ coversTheTerm,
44
46
  runExperiment,
45
47
  qualityGate,
46
48
  semanticPassCost,
@@ -257,6 +259,9 @@ const VALUE_FLAGS = new Set([
257
259
  'a',
258
260
  'at',
259
261
  'b',
262
+ 'floor',
263
+ 'discount',
264
+ 'months',
260
265
  'min-outcomes',
261
266
  'against',
262
267
  'contract',
@@ -591,6 +596,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
591
596
  quality: ['label', 'at', 'gate', 'pricing', 'pricing-live'],
592
597
  semantic: ['yes', 'model', 'pricing', 'pricing-live'],
593
598
  owners: ['pricing', 'pricing-live', 'since', 'until'],
599
+ commitment: ['floor', 'discount', 'months', 'pricing', 'pricing-live'],
594
600
  where: [],
595
601
  rules: [],
596
602
  blame: ['limit', 'model', 'calls', 'output-tokens', 'batch', 'prompt', 'markdown-out'],
@@ -2876,6 +2882,167 @@ async function commandOwners(
2876
2882
  console.log();
2877
2883
  }
2878
2884
 
2885
+ /**
2886
+ * `trazum commitment <log> --floor <usd> --discount <pct> [--months 12]`
2887
+ *
2888
+ * What a committed-use deal would have been worth **on the traffic you
2889
+ * actually had**. Every team that signs one of these is doing arithmetic in a
2890
+ * spreadsheet against a number they guessed, and it is the highest-stakes
2891
+ * instance of exactly the failure this product exists to end — because the
2892
+ * guess is annual and signed.
2893
+ *
2894
+ * Nothing here projects. "On the traffic you actually had, this would have
2895
+ * saved $X" is a measurement; "you will save $X" is a claim about the future
2896
+ * this product has refused at every scale since 1.27.
2897
+ */
2898
+ async function commandCommitment(
2899
+ args: Args,
2900
+ config: TrazumConfig,
2901
+ pricing: PricingCatalogue,
2902
+ t: CliMessages,
2903
+ ): Promise<void> {
2904
+ const path = args.positional[0];
2905
+ if (path === undefined) throw new Error(t.errors.missingInputFile());
2906
+
2907
+ const floorRaw = stringFlag(args, 'floor');
2908
+ const discountRaw = stringFlag(args, 'discount');
2909
+ const floor = floorRaw === undefined ? Number.NaN : Number(floorRaw);
2910
+ const discountInput = discountRaw === undefined ? Number.NaN : Number(discountRaw);
2911
+ if (!Number.isFinite(floor) || floor <= 0 || !Number.isFinite(discountInput) || discountInput <= 0) {
2912
+ throw new Error(t.commitment.needsTerms());
2913
+ }
2914
+ // Written either way in a contract, so read either way: 20 and 0.2 are the
2915
+ // same deal, and refusing one of them would be pedantry with a stack trace.
2916
+ const discount = discountInput > 1 ? discountInput / 100 : discountInput;
2917
+ const months = Number(stringFlag(args, 'months') ?? 12);
2918
+ const terms = { monthlyFloorUsd: floor, discount, months };
2919
+
2920
+ const report = profileUsage(await readUsageLog(path, t), { catalogue: pricing });
2921
+ /**
2922
+ * Whole calendar months only.
2923
+ *
2924
+ * A partial month replayed against a monthly floor is a shortfall the
2925
+ * traffic never had — the deal would be judged against a fortnight of usage
2926
+ * and a full month of commitment. Dropping them costs an answer; keeping
2927
+ * them would manufacture one.
2928
+ */
2929
+ const byMonth = new Map<string, number>();
2930
+ for (const day of report.spendByDay) {
2931
+ const key = day.day.slice(0, 7);
2932
+ byMonth.set(key, (byMonth.get(key) ?? 0) + day.usd);
2933
+ }
2934
+ const days = new Map<string, Set<string>>();
2935
+ for (const day of report.spendByDay) {
2936
+ const key = day.day.slice(0, 7);
2937
+ const set = days.get(key) ?? new Set<string>();
2938
+ set.add(day.day);
2939
+ days.set(key, set);
2940
+ }
2941
+ const whole = [...byMonth.entries()]
2942
+ .filter(([key]) => {
2943
+ const [y, m] = key.split('-').map(Number);
2944
+ const inMonth = new Date(Date.UTC(y ?? 2026, m ?? 1, 0)).getUTCDate();
2945
+ return (days.get(key)?.size ?? 0) >= inMonth - 2;
2946
+ })
2947
+ .map(([month, usd]) => ({ month, usd }))
2948
+ .sort((a, b) => a.month.localeCompare(b.month));
2949
+
2950
+ const replay = replayCommitment(whole, terms);
2951
+ const coverage = coversTheTerm(replay, terms);
2952
+ const n = (value: number): string => value.toLocaleString(t.numberLocale);
2953
+ const pct = (value: number): string => `${(value * 100).toFixed(0)}%`;
2954
+
2955
+ console.log();
2956
+ console.log(c.bold(t.commitment.heading(formatUsd(floor), pct(discount), n(months))));
2957
+ console.log(` ${c.dim(wrap(t.commitment.asIf(), 74, ' '))}`);
2958
+ console.log();
2959
+
2960
+ if (replay.unknown !== null) {
2961
+ console.log(
2962
+ ` ${c.yellow('?')} ${wrap(t.commitment.cannotTell(replay.unknown, n(replay.monthsNeeded ?? 0)), 74, ' ')}`,
2963
+ );
2964
+ console.log();
2965
+ console.log(` ${c.dim(t.commitment.breakEven(formatUsd(replay.breakEvenMonthlyUsd)))}`);
2966
+ console.log();
2967
+ return;
2968
+ }
2969
+
2970
+ const col = t.commitment.columns;
2971
+ const rows = replay.months.map((m) => ({
2972
+ month: m.month,
2973
+ list: formatUsd(m.listUsd),
2974
+ paid: formatUsd(m.paidUsd),
2975
+ // Signed: every month in this column can go either way, and formatUsd
2976
+ // renders a negative as `$-2,400`, which reads as a typo. The sign carries
2977
+ // the whole meaning here, so it goes where a reader expects it.
2978
+ saving: formatSignedUsd(m.savingUsd),
2979
+ shortfall: m.shortfall,
2980
+ }));
2981
+ const w = {
2982
+ month: Math.max(...rows.map((r) => r.month.length), col.month.length),
2983
+ list: Math.max(...rows.map((r) => r.list.length), col.list.length),
2984
+ paid: Math.max(...rows.map((r) => r.paid.length), col.paid.length),
2985
+ saving: Math.max(...rows.map((r) => r.saving.length), col.saving.length),
2986
+ };
2987
+ console.log(
2988
+ c.dim(
2989
+ ` ${col.month.padEnd(w.month)} ${col.list.padStart(w.list)} ` +
2990
+ `${col.paid.padStart(w.paid)} ${col.saving.padStart(w.saving)}`,
2991
+ ),
2992
+ );
2993
+ for (const row of rows) {
2994
+ const tint = row.shortfall ? c.red : c.dim;
2995
+ console.log(
2996
+ ` ${row.month.padEnd(w.month)} ${row.list.padStart(w.list)} ` +
2997
+ `${row.paid.padStart(w.paid)} ${tint(row.saving.padStart(w.saving))}`,
2998
+ );
2999
+ }
3000
+
3001
+ console.log();
3002
+ console.log(` ${c.bold(t.commitment.net(formatUsd(replay.netUsd), n(replay.months.length)))}`);
3003
+ console.log(` ${c.dim(t.commitment.good(formatUsd(replay.savedInGoodMonthsUsd)))}`);
3004
+ if (replay.shortfallMonths > 0) {
3005
+ console.log(
3006
+ ` ${c.yellow('!')} ${wrap(
3007
+ t.commitment.lost(formatUsd(replay.lostToUnusedFloorUsd), n(replay.shortfallMonths)),
3008
+ 74,
3009
+ ' ',
3010
+ )}`,
3011
+ );
3012
+ } else {
3013
+ console.log(` ${c.dim(t.commitment.noShortfall())}`);
3014
+ }
3015
+
3016
+ console.log();
3017
+ console.log(` ${c.dim(wrap(t.commitment.breakEven(formatUsd(replay.breakEvenMonthlyUsd)), 74, ' '))}`);
3018
+ if (replay.spread !== null) {
3019
+ console.log(
3020
+ ` ${c.dim(
3021
+ wrap(
3022
+ t.commitment.spread(
3023
+ formatUsd(replay.spread.lowUsd),
3024
+ formatUsd(replay.spread.highUsd),
3025
+ formatUsd(replay.spread.medianUsd),
3026
+ ),
3027
+ 74,
3028
+ ' ',
3029
+ ),
3030
+ )}`,
3031
+ );
3032
+ }
3033
+ // Said, not enforced: a shorter history is a real answer about a shorter
3034
+ // period, and the gap must not go unmarked.
3035
+ if (coverage.short) {
3036
+ console.log();
3037
+ console.log(
3038
+ ` ${c.yellow('!')} ${wrap(t.commitment.shortTerm(n(coverage.covered), n(coverage.ofMonths)), 74, ' ')}`,
3039
+ );
3040
+ }
3041
+ console.log();
3042
+ console.log(` ${c.dim(wrap(t.commitment.neverAForecast(), 74, ' '))}`);
3043
+ console.log();
3044
+ }
3045
+
2879
3046
  function commandModels(t: CliMessages, pricing: PricingCatalogue): void {
2880
3047
  const n = (value: number): string => value.toLocaleString(t.numberLocale);
2881
3048
  const col = t.models.columns;
@@ -9076,6 +9243,9 @@ async function main(): Promise<void> {
9076
9243
  case 'models':
9077
9244
  commandModels(t, pricing);
9078
9245
  break;
9246
+ case 'commitment':
9247
+ await commandCommitment(args, config, pricing, t);
9248
+ break;
9079
9249
  case 'owners':
9080
9250
  await commandOwners(args, config, pricing, t);
9081
9251
  break;