@trazum/cli 1.50.11 → 1.51.1

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.11",
3
+ "version": "1.51.1",
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.11"
40
+ "@trazum/core": "1.51.1"
41
41
  },
42
42
  "devDependencies": {
43
43
  "@types/node": "^26.2.0",
package/src/i18n/en.ts CHANGED
@@ -62,6 +62,7 @@ ${bold('USAGE')}
62
62
  trazum quality <log> --label <name> --at <iso> [--gate]
63
63
  trazum semantic <prompt> [--yes]
64
64
  trazum commitment <log> --floor <usd> --discount <pct> [--months 12]
65
+ trazum report <log> --year <yyyy>
65
66
  trazum owners <log>
66
67
  trazum ladder <log>
67
68
  trazum feedback
@@ -172,6 +173,15 @@ ${bold('OPTIONS FOR commitment')}
172
173
  months that fell short — kept as its own figure, because netted into the
173
174
  saving it disappears. An as-if calculation about the past, never a forecast.
174
175
 
176
+ ${bold('OPTIONS FOR report')}
177
+ --year <yyyy> Required. Which year to assemble.
178
+ --json Also emit the record as JSON.
179
+
180
+ Everything comes from the store and the plans you already keep — nothing is
181
+ computed that cannot be checked against a document that already exists.
182
+ Months with no record are named rather than filled, promises are kept in
183
+ three outcomes rather than two, and the report lists what it cannot say.
184
+
175
185
  ${bold('OPTIONS FOR prune')}
176
186
  --cases <file> One input per line, or a JSON array. Required.
177
187
  --yes Actually spend the calls. Without it the estimate is
@@ -1023,6 +1033,40 @@ ${bold('EXAMPLES')}
1023
1033
  `${path} exists and could not be parsed, so nothing was written over it. Fix or move it first.`,
1024
1034
  },
1025
1035
 
1036
+ annual: {
1037
+ heading: (year) => `The year ${year}, from what was already written down`,
1038
+ needsYear: () => '--year is required, as four digits: trazum report <log> --year 2026.',
1039
+ spent: (usd, calls, months) => `${usd} across ${calls} calls, over ${months} recorded months.`,
1040
+ missing: (months) =>
1041
+ `No record at all for ${months}. Those months are named rather than filled: a year that quietly covers part of itself and prints an annual total is wrong by the rest and says nothing about it.`,
1042
+ promises: (planned, arrived, notArrived, cannotTell) =>
1043
+ `${planned} actions planned. ${arrived} arrived, ${notArrived} did not, and ${cannotTell} could not be judged. Three outcomes, never two \u2014 the third is the one an ordinary annual report folds into the flattering one.`,
1044
+ projected: (usd) => `The plans projected ${usd} of savings.`,
1045
+ noArrivedFigure: () =>
1046
+ 'There is deliberately no figure beside it for what arrived. A verification says WHETHER each action landed; it has never carried a per-action dollar figure for the saving. Assembling one here would mean deciding which of several observed numbers is "the saving" \u2014 a judgement the verification refused to make, and exactly the annual-report arithmetic this document replaces.',
1047
+ outcomes: (recorded, parsed, unrecordedUsd) =>
1048
+ `${recorded} of ${parsed} calls recorded an outcome; ${unrecordedUsd} of the year\u2019s spend did not.`,
1049
+ noOutcomes: () =>
1050
+ 'No outcome was recorded this year, so nothing here says what the money bought. That is not a success rate of zero \u2014 an uninstrumented year and a failing year are different sentences.',
1051
+ cannotSayHeading: () => 'What this record cannot say',
1052
+ cannotSay: (kind) =>
1053
+ kind === 'months-missing'
1054
+ ? 'what happened in the months with no record'
1055
+ : kind === 'nothing-was-planned'
1056
+ ? 'whether anything was promised, because no plan was made'
1057
+ : kind === 'nothing-was-verified'
1058
+ ? 'whether the promises were kept, because no plan was verified'
1059
+ : kind === 'some-promises-unjudgeable'
1060
+ ? 'whether some promises were kept \u2014 they could not be judged from the logs that exist'
1061
+ : kind === 'arrived-savings-not-quantified'
1062
+ ? 'how many dollars the kept promises were worth'
1063
+ : kind === 'no-outcomes-recorded'
1064
+ ? 'what any of the money bought'
1065
+ : 'what the uninstrumented share of the traffic did',
1066
+ noNewData: () =>
1067
+ 'Every figure above comes from the store and the plans you already keep. Nothing was computed here that cannot be checked against a document that already exists \u2014 which is the only reason an annual report is worth trusting, since it is the document most likely to be quoted out of the room it was written in.',
1068
+ },
1069
+
1026
1070
  commitment: {
1027
1071
  heading: (floor, discount, months) =>
1028
1072
  `A ${months}-month commitment: ${floor} a month at ${discount} off`,
package/src/i18n/es.ts CHANGED
@@ -49,6 +49,7 @@ ${bold('USO')}
49
49
  trazum quality <log> --label <name> --at <iso> [--gate]
50
50
  trazum semantic <prompt> [--yes]
51
51
  trazum commitment <log> --floor <usd> --discount <pct> [--months 12]
52
+ trazum report <log> --year <yyyy>
52
53
  trazum owners <log>
53
54
  trazum ladder <log>
54
55
  trazum feedback
@@ -163,6 +164,15 @@ ${bold('OPCIONES DE commitment')}
163
164
  porque metida en el ahorro desaparece. Un cálculo sobre el pasado, nunca una
164
165
  previsión.
165
166
 
167
+ ${bold('OPCIONES DE report')}
168
+ --year <yyyy> Obligatorio. Qué año montar.
169
+ --json Emite también el registro como JSON.
170
+
171
+ Todo sale del almacén y de los planes que ya guardas — no se calcula nada
172
+ que no se pueda comprobar contra un documento que ya existe. Los meses sin
173
+ registro se nombran en vez de rellenarse, las promesas se cuentan en tres
174
+ resultados y no en dos, y el informe lista lo que no puede decir.
175
+
166
176
  ${bold('OPCIONES DE prune')}
167
177
  --cases <fichero> Una entrada por línea, o un array JSON. Obligatorio.
168
178
  --yes Gasta las llamadas de verdad. Sin él se imprime la
@@ -1060,6 +1070,40 @@ ${bold('EJEMPLOS')}
1060
1070
  `${path} existe y no se pudo interpretar, así que no se escribió nada encima. Arréglalo o muévelo primero.`,
1061
1071
  },
1062
1072
 
1073
+ annual: {
1074
+ heading: (year) => `El a\u00f1o ${year}, a partir de lo que ya estaba escrito`,
1075
+ needsYear: () => '--year es obligatorio, con cuatro d\u00edgitos: trazum report <log> --year 2026.',
1076
+ spent: (usd, calls, months) => `${usd} en ${calls} llamadas, sobre ${months} meses registrados.`,
1077
+ missing: (months) =>
1078
+ `Sin ning\u00fan registro de ${months}. Esos meses se nombran en vez de rellenarse: un a\u00f1o que cubre parte de s\u00ed mismo en silencio e imprime un total anual est\u00e1 equivocado en el resto y no dice nada al respecto.`,
1079
+ promises: (planned, arrived, notArrived, cannotTell) =>
1080
+ `${planned} acciones planeadas. ${arrived} llegaron, ${notArrived} no, y ${cannotTell} no se pudieron juzgar. Tres resultados, nunca dos \u2014 el tercero es el que un informe anual normal mete dentro del que favorece.`,
1081
+ projected: (usd) => `Los planes proyectaron ${usd} de ahorro.`,
1082
+ noArrivedFigure: () =>
1083
+ 'A prop\u00f3sito no hay una cifra al lado de lo que lleg\u00f3. Una verificaci\u00f3n dice SI cada acci\u00f3n aterriz\u00f3; nunca ha llevado una cifra en d\u00f3lares por acci\u00f3n del ahorro. Montarla aqu\u00ed significar\u00eda decidir cu\u00e1l de varios n\u00fameros observados es "el ahorro" \u2014 un juicio que la verificaci\u00f3n se neg\u00f3 a hacer, y justo la aritm\u00e9tica de informe anual que este documento sustituye.',
1084
+ outcomes: (recorded, parsed, unrecordedUsd) =>
1085
+ `${recorded} de ${parsed} llamadas registraron un resultado; ${unrecordedUsd} del gasto del a\u00f1o no.`,
1086
+ noOutcomes: () =>
1087
+ 'No se registr\u00f3 ning\u00fan resultado este a\u00f1o, as\u00ed que nada de esto dice qu\u00e9 compr\u00f3 el dinero. Eso no es una tasa de \u00e9xito de cero \u2014 un a\u00f1o sin instrumentar y un a\u00f1o que falla son frases distintas.',
1088
+ cannotSayHeading: () => 'Lo que este registro no puede decir',
1089
+ cannotSay: (kind) =>
1090
+ kind === 'months-missing'
1091
+ ? 'qu\u00e9 pas\u00f3 en los meses sin registro'
1092
+ : kind === 'nothing-was-planned'
1093
+ ? 'si se prometi\u00f3 algo, porque no se hizo ning\u00fan plan'
1094
+ : kind === 'nothing-was-verified'
1095
+ ? 'si se cumplieron las promesas, porque no se verific\u00f3 ning\u00fan plan'
1096
+ : kind === 'some-promises-unjudgeable'
1097
+ ? 'si algunas promesas se cumplieron \u2014 no se pudieron juzgar con los logs que existen'
1098
+ : kind === 'arrived-savings-not-quantified'
1099
+ ? 'cu\u00e1ntos d\u00f3lares val\u00edan las promesas cumplidas'
1100
+ : kind === 'no-outcomes-recorded'
1101
+ ? 'qu\u00e9 compr\u00f3 nada de ese dinero'
1102
+ : 'qu\u00e9 hizo la parte del tr\u00e1fico sin instrumentar',
1103
+ noNewData: () =>
1104
+ 'Todas las cifras de arriba salen del almac\u00e9n y de los planes que ya guardas. Aqu\u00ed no se ha calculado nada que no se pueda comprobar contra un documento que ya existe \u2014 que es la \u00fanica raz\u00f3n por la que un informe anual merece confianza, siendo el documento con m\u00e1s probabilidad de acabar citado fuera de la sala donde se escribi\u00f3.',
1105
+ },
1106
+
1063
1107
  commitment: {
1064
1108
  heading: (floor, discount, months) =>
1065
1109
  `Un compromiso de ${months} meses: ${floor} al mes con ${discount} de descuento`,
package/src/i18n/types.ts CHANGED
@@ -268,6 +268,21 @@ 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
+ annual: {
272
+ heading(year: string): string;
273
+ needsYear(): string;
274
+ spent(usd: string, calls: string, months: string): string;
275
+ missing(months: string): string;
276
+ promises(planned: string, arrived: string, notArrived: string, cannotTell: string): string;
277
+ projected(usd: string): string;
278
+ noArrivedFigure(): string;
279
+ outcomes(recorded: string, parsed: string, unrecordedUsd: string): string;
280
+ noOutcomes(): string;
281
+ cannotSayHeading(): string;
282
+ cannotSay(kind: string): string;
283
+ noNewData(): string;
284
+ };
285
+
271
286
  commitment: {
272
287
  heading(floor: string, discount: string, months: string): string;
273
288
  needsTerms(): string;
package/src/index.ts CHANGED
@@ -41,6 +41,7 @@ import {
41
41
  conform,
42
42
  BREAK_EVEN_BAND,
43
43
  allocate,
44
+ annualRecord,
44
45
  replayCommitment,
45
46
  coversTheTerm,
46
47
  runExperiment,
@@ -258,6 +259,7 @@ interface Args {
258
259
  const VALUE_FLAGS = new Set([
259
260
  'a',
260
261
  'at',
262
+ 'year',
261
263
  'b',
262
264
  'floor',
263
265
  'discount',
@@ -597,6 +599,7 @@ const COMMAND_FLAGS: Record<string, string[]> = {
597
599
  semantic: ['yes', 'model', 'pricing', 'pricing-live'],
598
600
  owners: ['pricing', 'pricing-live', 'since', 'until'],
599
601
  commitment: ['floor', 'discount', 'months', 'pricing', 'pricing-live'],
602
+ report: ['year', 'json', 'pricing', 'pricing-live'],
600
603
  where: [],
601
604
  rules: [],
602
605
  blame: ['limit', 'model', 'calls', 'output-tokens', 'batch', 'prompt', 'markdown-out'],
@@ -3043,6 +3046,136 @@ async function commandCommitment(
3043
3046
  console.log();
3044
3047
  }
3045
3048
 
3049
+ /**
3050
+ * `trazum report <log> --year <yyyy>` — the year, from what was already
3051
+ * written down.
3052
+ *
3053
+ * The last chapter of the arc, and the one that turns this product's argument
3054
+ * into something a stranger can audit. **No new data**: everything here comes
3055
+ * from the store and the plans a team already keeps, and nothing is computed
3056
+ * that could not be checked against a document that already exists.
3057
+ *
3058
+ * That constraint is the whole design. An annual report is the document most
3059
+ * likely to be quoted out of the room it was written in, and the one nobody
3060
+ * goes back to verify.
3061
+ */
3062
+ async function commandReport(
3063
+ args: Args,
3064
+ config: TrazumConfig,
3065
+ pricing: PricingCatalogue,
3066
+ t: CliMessages,
3067
+ ): Promise<void> {
3068
+ const path = args.positional[0];
3069
+ if (path === undefined) throw new Error(t.errors.missingInputFile());
3070
+ const year = stringFlag(args, 'year');
3071
+ if (year === undefined || !/^\d{4}$/.test(year)) throw new Error(t.annual.needsYear());
3072
+
3073
+ const report = profileUsage(await readUsageLog(path, t), { catalogue: pricing });
3074
+
3075
+ /**
3076
+ * One period per calendar month, built from the day series.
3077
+ *
3078
+ * Partial months are kept here, unlike in `commitment`: a year report is
3079
+ * about what happened, and a month that only ran for a week still happened.
3080
+ * What it must not do is imply the month was whole, which is why the count
3081
+ * of recorded months is stated beside the total.
3082
+ */
3083
+ const byMonth = new Map<string, { usd: number; calls: number }>();
3084
+ for (const day of report.spendByDay) {
3085
+ const key = day.day.slice(0, 7);
3086
+ const entry = byMonth.get(key) ?? { usd: 0, calls: 0 };
3087
+ entry.usd += day.usd;
3088
+ entry.calls += day.calls;
3089
+ byMonth.set(key, entry);
3090
+ }
3091
+ const outcomes = outcomeReport(report.outcomeTally, config.outcomes ?? null);
3092
+ const periods = [...byMonth.entries()]
3093
+ .map(([month, entry], index) => ({
3094
+ month,
3095
+ usd: entry.usd,
3096
+ calls: entry.calls,
3097
+ /**
3098
+ * Attached only when something was **recorded**, not merely parsed.
3099
+ *
3100
+ * The first version keyed on `parsed > 0`, which is true of any log with
3101
+ * calls in it — so a year that recorded no outcome at all still got an
3102
+ * outcomes object saying "0 of 120", and the honest sentence ("no
3103
+ * outcome was recorded this year, so nothing here says what the money
3104
+ * bought") was unreachable. A zero dressed as a measurement, which is
3105
+ * the exact failure the field's own contract forbids.
3106
+ *
3107
+ * Attached to the first month rather than divided across them: dividing
3108
+ * would invent a monthly figure nobody measured, and the year's total is
3109
+ * what this document reports.
3110
+ */
3111
+ ...(index === 0 && outcomes.coverage.recorded > 0 ? { outcomes } : {}),
3112
+ }))
3113
+ .sort((a, b) => a.month.localeCompare(b.month));
3114
+
3115
+ const record = annualRecord(year, periods);
3116
+ const n = (value: number): string => value.toLocaleString(t.numberLocale);
3117
+
3118
+ console.log();
3119
+ console.log(c.bold(t.annual.heading(year)));
3120
+ console.log();
3121
+ console.log(
3122
+ ` ${t.annual.spent(formatUsd(record.totalUsd), n(record.totalCalls), n(record.months.length))}`,
3123
+ );
3124
+ if (record.missingMonths.length > 0) {
3125
+ console.log(
3126
+ ` ${c.yellow('!')} ${wrap(t.annual.missing(record.missingMonths.join(', ')), 74, ' ')}`,
3127
+ );
3128
+ }
3129
+
3130
+ console.log();
3131
+ const p = record.promises;
3132
+ console.log(
3133
+ ` ${wrap(t.annual.promises(n(p.planned), n(p.arrived), n(p.notArrived), n(p.cannotTell)), 74, ' ')}`,
3134
+ );
3135
+ if (p.projectedUsd > 0) {
3136
+ console.log(` ${t.annual.projected(formatUsd(p.projectedUsd))}`);
3137
+ console.log(` ${c.dim(wrap(t.annual.noArrivedFigure(), 74, ' '))}`);
3138
+ }
3139
+
3140
+ console.log();
3141
+ if (record.outcomes === null) {
3142
+ console.log(` ${c.dim(wrap(t.annual.noOutcomes(), 74, ' '))}`);
3143
+ } else {
3144
+ console.log(
3145
+ ` ${wrap(
3146
+ t.annual.outcomes(
3147
+ n(record.outcomes.recorded),
3148
+ n(record.outcomes.parsed),
3149
+ formatUsd(record.outcomes.unrecordedUsd),
3150
+ ),
3151
+ 74,
3152
+ ' ',
3153
+ )}`,
3154
+ );
3155
+ }
3156
+
3157
+ /**
3158
+ * The section an annual report is usually missing, and the reason this one
3159
+ * is worth trusting: a document that lists its own blind spots is a document
3160
+ * somebody can act on the rest of.
3161
+ */
3162
+ if (record.cannotSay.length > 0) {
3163
+ console.log();
3164
+ console.log(` ${c.bold(t.annual.cannotSayHeading())}`);
3165
+ for (const kind of record.cannotSay) {
3166
+ console.log(` ${c.dim('·')} ${wrap(t.annual.cannotSay(kind), 70, ' ')}`);
3167
+ }
3168
+ }
3169
+
3170
+ console.log();
3171
+ console.log(` ${c.dim(wrap(t.annual.noNewData(), 74, ' '))}`);
3172
+ console.log();
3173
+
3174
+ if (boolFlag(args, 'json')) {
3175
+ console.log(JSON.stringify(record, null, 2));
3176
+ }
3177
+ }
3178
+
3046
3179
  function commandModels(t: CliMessages, pricing: PricingCatalogue): void {
3047
3180
  const n = (value: number): string => value.toLocaleString(t.numberLocale);
3048
3181
  const col = t.models.columns;
@@ -9243,6 +9376,9 @@ async function main(): Promise<void> {
9243
9376
  case 'models':
9244
9377
  commandModels(t, pricing);
9245
9378
  break;
9379
+ case 'report':
9380
+ await commandReport(args, config, pricing, t);
9381
+ break;
9246
9382
  case 'commitment':
9247
9383
  await commandCommitment(args, config, pricing, t);
9248
9384
  break;