@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/dist/index.js CHANGED
@@ -4,7 +4,7 @@ import { open, readdir, readFile, stat, writeFile } from 'node:fs/promises';
4
4
  import { dirname, join, resolve as resolvePath } from 'node:path';
5
5
  import { fileURLToPath } from 'node:url';
6
6
  import { gunzipSync } from 'node:zlib';
7
- import { applyRewrites, BASELINE_FILENAME, BASELINE_VERSION, breaches, cacheableMinimum, analyzeCachePrefix, billLevers, bucketedCacheEconomics, bucketedProfile, buildHistory, buildPlan, connectorFor, CONNECTORS, normalizeAnthropicUsage, normalizeOpenAIUsage, bucketsFromRecords, evaluateWatch, firedKey, pruneRecords, recordsFromBuckets, storeInventory, storedReportFrom, verifyPlan, cacheEconomics, cacheHitRate, contextPressure, comparePrompts, compareToBaseline, computeSavings, countTokensAnthropic, DEFAULT_USAGE, budgetPositions, conform, BREAK_EVEN_BAND, allocate, replayCommitment, coversTheTerm, runExperiment, qualityGate, semanticPassCost, verifySemanticProposals, SEMANTIC_SYSTEM_PROMPT, ladderPosition, validateLadder, outcomeReport, rankPerOutcome, FAILURE_POLICIES, detectFromSource, matchLocale, parsePlanDocument, waiverDay, waiverHistory, proposeInit, MIN_RATE_DAYS, parseConfig, coverageDrift, driversBetween, explainGateFailure, assignSources, fleetRollup, labelCoverage, measuredUsage, gateMargin, GATE_MARGIN_TIGHT, estimateTokens, evaluate, extractPrompts, findExamples, formatBaseline, formatSignedUsd, formatUsd, getMessages, getModel, hasMarker, LOCALES, MAX_BASELINE_BYTES, moneyIsComparable, mostSpecificMatch, nearestName, optimize, parseBaseline, PHRASE_LANGUAGES, plannedCalls, profilePrompt, profileToCsv, profileUsage, promptId, providerFromEnv, pruneExamples, refineWithLlm, rejectionText, reorderForCache, repriceProfile, reviewAgeDays, reviewExamples, RULES, sharedPrefixes, sharesOf, SOURCE_EXTENSIONS, suggestRewrites, toOtlpMetrics, toPromptfoo, TTL_1H_MS, UNLABELLED, withExactTokenCounts, } from '@trazum/core';
7
+ import { applyRewrites, BASELINE_FILENAME, BASELINE_VERSION, breaches, cacheableMinimum, analyzeCachePrefix, billLevers, bucketedCacheEconomics, bucketedProfile, buildHistory, buildPlan, connectorFor, CONNECTORS, normalizeAnthropicUsage, normalizeOpenAIUsage, bucketsFromRecords, evaluateWatch, firedKey, pruneRecords, recordsFromBuckets, storeInventory, storedReportFrom, verifyPlan, cacheEconomics, cacheHitRate, contextPressure, comparePrompts, compareToBaseline, computeSavings, countTokensAnthropic, DEFAULT_USAGE, budgetPositions, conform, BREAK_EVEN_BAND, allocate, annualRecord, replayCommitment, coversTheTerm, runExperiment, qualityGate, semanticPassCost, verifySemanticProposals, SEMANTIC_SYSTEM_PROMPT, ladderPosition, validateLadder, outcomeReport, rankPerOutcome, FAILURE_POLICIES, detectFromSource, matchLocale, parsePlanDocument, waiverDay, waiverHistory, proposeInit, MIN_RATE_DAYS, parseConfig, coverageDrift, driversBetween, explainGateFailure, assignSources, fleetRollup, labelCoverage, measuredUsage, gateMargin, GATE_MARGIN_TIGHT, estimateTokens, evaluate, extractPrompts, findExamples, formatBaseline, formatSignedUsd, formatUsd, getMessages, getModel, hasMarker, LOCALES, MAX_BASELINE_BYTES, moneyIsComparable, mostSpecificMatch, nearestName, optimize, parseBaseline, PHRASE_LANGUAGES, plannedCalls, profilePrompt, profileToCsv, profileUsage, promptId, providerFromEnv, pruneExamples, refineWithLlm, rejectionText, reorderForCache, repriceProfile, reviewAgeDays, reviewExamples, RULES, sharedPrefixes, sharesOf, SOURCE_EXTENSIONS, suggestRewrites, toOtlpMetrics, toPromptfoo, TTL_1H_MS, UNLABELLED, withExactTokenCounts, } from '@trazum/core';
8
8
  import { cacheDir, cacheStats, cachingProvider, clearCache } from './suggest-cache.js';
9
9
  import { dayOf, formatGap, median, spanDays } from './time.js';
10
10
  // Everything that reads the filesystem, on its own entry point so the web
@@ -34,6 +34,7 @@ const c = {
34
34
  const VALUE_FLAGS = new Set([
35
35
  'a',
36
36
  'at',
37
+ 'year',
37
38
  'b',
38
39
  'floor',
39
40
  'discount',
@@ -332,6 +333,7 @@ const COMMAND_FLAGS = {
332
333
  semantic: ['yes', 'model', 'pricing', 'pricing-live'],
333
334
  owners: ['pricing', 'pricing-live', 'since', 'until'],
334
335
  commitment: ['floor', 'discount', 'months', 'pricing', 'pricing-live'],
336
+ report: ['year', 'json', 'pricing', 'pricing-live'],
335
337
  where: [],
336
338
  rules: [],
337
339
  blame: ['limit', 'model', 'calls', 'output-tokens', 'batch', 'prompt', 'markdown-out'],
@@ -2291,6 +2293,108 @@ async function commandCommitment(args, config, pricing, t) {
2291
2293
  console.log(` ${c.dim(wrap(t.commitment.neverAForecast(), 74, ' '))}`);
2292
2294
  console.log();
2293
2295
  }
2296
+ /**
2297
+ * `trazum report <log> --year <yyyy>` — the year, from what was already
2298
+ * written down.
2299
+ *
2300
+ * The last chapter of the arc, and the one that turns this product's argument
2301
+ * into something a stranger can audit. **No new data**: everything here comes
2302
+ * from the store and the plans a team already keeps, and nothing is computed
2303
+ * that could not be checked against a document that already exists.
2304
+ *
2305
+ * That constraint is the whole design. An annual report is the document most
2306
+ * likely to be quoted out of the room it was written in, and the one nobody
2307
+ * goes back to verify.
2308
+ */
2309
+ async function commandReport(args, config, pricing, t) {
2310
+ const path = args.positional[0];
2311
+ if (path === undefined)
2312
+ throw new Error(t.errors.missingInputFile());
2313
+ const year = stringFlag(args, 'year');
2314
+ if (year === undefined || !/^\d{4}$/.test(year))
2315
+ throw new Error(t.annual.needsYear());
2316
+ const report = profileUsage(await readUsageLog(path, t), { catalogue: pricing });
2317
+ /**
2318
+ * One period per calendar month, built from the day series.
2319
+ *
2320
+ * Partial months are kept here, unlike in `commitment`: a year report is
2321
+ * about what happened, and a month that only ran for a week still happened.
2322
+ * What it must not do is imply the month was whole, which is why the count
2323
+ * of recorded months is stated beside the total.
2324
+ */
2325
+ const byMonth = new Map();
2326
+ for (const day of report.spendByDay) {
2327
+ const key = day.day.slice(0, 7);
2328
+ const entry = byMonth.get(key) ?? { usd: 0, calls: 0 };
2329
+ entry.usd += day.usd;
2330
+ entry.calls += day.calls;
2331
+ byMonth.set(key, entry);
2332
+ }
2333
+ const outcomes = outcomeReport(report.outcomeTally, config.outcomes ?? null);
2334
+ const periods = [...byMonth.entries()]
2335
+ .map(([month, entry], index) => ({
2336
+ month,
2337
+ usd: entry.usd,
2338
+ calls: entry.calls,
2339
+ /**
2340
+ * Attached only when something was **recorded**, not merely parsed.
2341
+ *
2342
+ * The first version keyed on `parsed > 0`, which is true of any log with
2343
+ * calls in it — so a year that recorded no outcome at all still got an
2344
+ * outcomes object saying "0 of 120", and the honest sentence ("no
2345
+ * outcome was recorded this year, so nothing here says what the money
2346
+ * bought") was unreachable. A zero dressed as a measurement, which is
2347
+ * the exact failure the field's own contract forbids.
2348
+ *
2349
+ * Attached to the first month rather than divided across them: dividing
2350
+ * would invent a monthly figure nobody measured, and the year's total is
2351
+ * what this document reports.
2352
+ */
2353
+ ...(index === 0 && outcomes.coverage.recorded > 0 ? { outcomes } : {}),
2354
+ }))
2355
+ .sort((a, b) => a.month.localeCompare(b.month));
2356
+ const record = annualRecord(year, periods);
2357
+ const n = (value) => value.toLocaleString(t.numberLocale);
2358
+ console.log();
2359
+ console.log(c.bold(t.annual.heading(year)));
2360
+ console.log();
2361
+ console.log(` ${t.annual.spent(formatUsd(record.totalUsd), n(record.totalCalls), n(record.months.length))}`);
2362
+ if (record.missingMonths.length > 0) {
2363
+ console.log(` ${c.yellow('!')} ${wrap(t.annual.missing(record.missingMonths.join(', ')), 74, ' ')}`);
2364
+ }
2365
+ console.log();
2366
+ const p = record.promises;
2367
+ console.log(` ${wrap(t.annual.promises(n(p.planned), n(p.arrived), n(p.notArrived), n(p.cannotTell)), 74, ' ')}`);
2368
+ if (p.projectedUsd > 0) {
2369
+ console.log(` ${t.annual.projected(formatUsd(p.projectedUsd))}`);
2370
+ console.log(` ${c.dim(wrap(t.annual.noArrivedFigure(), 74, ' '))}`);
2371
+ }
2372
+ console.log();
2373
+ if (record.outcomes === null) {
2374
+ console.log(` ${c.dim(wrap(t.annual.noOutcomes(), 74, ' '))}`);
2375
+ }
2376
+ else {
2377
+ console.log(` ${wrap(t.annual.outcomes(n(record.outcomes.recorded), n(record.outcomes.parsed), formatUsd(record.outcomes.unrecordedUsd)), 74, ' ')}`);
2378
+ }
2379
+ /**
2380
+ * The section an annual report is usually missing, and the reason this one
2381
+ * is worth trusting: a document that lists its own blind spots is a document
2382
+ * somebody can act on the rest of.
2383
+ */
2384
+ if (record.cannotSay.length > 0) {
2385
+ console.log();
2386
+ console.log(` ${c.bold(t.annual.cannotSayHeading())}`);
2387
+ for (const kind of record.cannotSay) {
2388
+ console.log(` ${c.dim('·')} ${wrap(t.annual.cannotSay(kind), 70, ' ')}`);
2389
+ }
2390
+ }
2391
+ console.log();
2392
+ console.log(` ${c.dim(wrap(t.annual.noNewData(), 74, ' '))}`);
2393
+ console.log();
2394
+ if (boolFlag(args, 'json')) {
2395
+ console.log(JSON.stringify(record, null, 2));
2396
+ }
2397
+ }
2294
2398
  function commandModels(t, pricing) {
2295
2399
  const n = (value) => value.toLocaleString(t.numberLocale);
2296
2400
  const col = t.models.columns;
@@ -7338,6 +7442,9 @@ async function main() {
7338
7442
  case 'models':
7339
7443
  commandModels(t, pricing);
7340
7444
  break;
7445
+ case 'report':
7446
+ await commandReport(args, config, pricing, t);
7447
+ break;
7341
7448
  case 'commitment':
7342
7449
  await commandCommitment(args, config, pricing, t);
7343
7450
  break;