@trazum/cli 1.50.8 → 1.50.10

package/dist/index.js

@@ -4,7 +4,7 @@ import { open, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve as resolvePath } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { gunzipSync } from 'node:zlib';
-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, runExperiment, qualityGate, 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';
+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, 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';
 import { cacheDir, cacheStats, cachingProvider, clearCache } from './suggest-cache.js';
 import { dayOf, formatGap, median, spanDays } from './time.js';
 // Everything that reads the filesystem, on its own entry point so the web
@@ -326,6 +326,8 @@ const COMMAND_FLAGS = {
     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'],
+    owners: ['pricing', 'pricing-live', 'since', 'until'],
     where: [],
     rules: [],
     blame: ['limit', 'model', 'calls', 'output-tokens', 'batch', 'prompt', 'markdown-out'],
@@ -1966,6 +1968,204 @@ async function commandQuality(args, config, pricing, t) {
     }
     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, config, pricing, t) {
+    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) => 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 = [];
+    try {
+        const parsed = 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) => typeof entry === 'object' &&
+                entry !== null &&
+                Array.isArray(entry.spans) &&
+                entry.spans.length === 2 &&
+                entry.spans.every((span) => typeof span === 'string'));
+        }
+    }
+    catch {
+        proposals = [];
+    }
+    const result = verifySemanticProposals(prompt, proposals);
+    const lineOf = (offset) => 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();
+}
+/**
+ * `trazum owners <log>` — whose budget each workload lands on.
+ *
+ * The fleet answered *which service* in 1.37. This answers *whose money*,
+ * which is the question that decides whether anything on the list gets done: a
+ * report saying "the bill is $40,000 and here is $9,000 of savings" is read by
+ * four people who each assume it is one of the other three's problem.
+ *
+ * **The unallocated is its own line and is never spread.** See `owners.ts` for
+ * why that is worth breaking a module over.
+ */
+async function commandOwners(args, config, pricing, t) {
+    const path = args.positional[0];
+    if (path === undefined)
+        throw new Error(t.errors.missingInputFile());
+    console.log();
+    console.log(c.bold(t.owners.heading()));
+    if (config.owners === undefined) {
+        console.log(`  ${c.dim(wrap(t.owners.noOwners(), 74, '  '))}`);
+        console.log();
+        return;
+    }
+    const report = profileUsage(await readUsageLog(path, t), { catalogue: pricing });
+    const result = allocate(report.byLabel.map((entry) => ({
+        label: entry.label,
+        usd: entry.breakdown.totalUsd,
+        calls: entry.breakdown.calls,
+    })), config.owners);
+    const n = (value) => value.toLocaleString(t.numberLocale);
+    const pct = (value) => `${(value * 100).toFixed(1)}%`;
+    /**
+     * Problems first, before any figure.
+     *
+     * A split that does not sum to one sends a whole workload to unallocated,
+     * and a reader who saw the table before the explanation would go looking for
+     * a bug in their logs.
+     */
+    if (result.problems.length > 0) {
+        console.log();
+        console.log(`  ${c.red('✗')} ${c.bold(t.owners.problemsHeading())}`);
+        for (const problem of result.problems) {
+            const detail = problem.kind === 'budget-for-unknown-owner'
+                ? problem.owner
+                : problem.kind === 'split-does-not-sum'
+                    ? `"${problem.label}" sums to ${problem.total}`
+                    : problem.kind === 'negative-share' || problem.kind === 'split-names-unknown-owner'
+                        ? `"${problem.label}" → ${problem.owner}`
+                        : `"${problem.label}"`;
+            console.log(`      ${wrap(t.owners.problem(problem.kind, detail), 70, '      ')}`);
+        }
+        process.exitCode = 1;
+    }
+    console.log();
+    const col = t.owners.columns;
+    const rows = result.owners.map((line) => ({
+        owner: line.owner,
+        spend: formatUsd(line.usd),
+        budget: line.budgetUsd === null ? '—' : formatUsd(line.budgetUsd),
+        calls: n(Math.round(line.calls)),
+        verdict: t.owners.verdict(line.verdict),
+        kind: line.verdict,
+    }));
+    const w = {
+        owner: Math.max(...rows.map((r) => r.owner.length), col.owner.length),
+        spend: Math.max(...rows.map((r) => r.spend.length), col.spend.length),
+        budget: Math.max(...rows.map((r) => r.budget.length), col.budget.length),
+        calls: Math.max(...rows.map((r) => r.calls.length), col.calls.length),
+    };
+    console.log(c.dim(`  ${col.owner.padEnd(w.owner)}  ${col.spend.padStart(w.spend)}  ` +
+        `${col.budget.padStart(w.budget)}  ${col.calls.padStart(w.calls)}`));
+    for (const row of rows) {
+        const tint = row.kind === 'over' ? c.red : row.kind === 'not-measured' ? c.yellow : c.dim;
+        console.log(`  ${row.owner.padEnd(w.owner)}  ${row.spend.padStart(w.spend)}  ` +
+            `${row.budget.padStart(w.budget)}  ${row.calls.padStart(w.calls)}  ${tint(row.verdict)}`);
+    }
+    // The 1.37 refusal, applied to people, said in full for each owner it hits.
+    for (const line of result.owners) {
+        if (line.verdict === 'not-measured') {
+            console.log();
+            console.log(`  ${c.yellow('!')} ${wrap(t.owners.notMeasured(line.owner), 74, '    ')}`);
+        }
+    }
+    console.log();
+    if (result.unallocated.usd > 0) {
+        console.log(`  ${c.yellow('!')} ${wrap(t.owners.unallocated(formatUsd(result.unallocated.usd), report.total.totalUsd > 0 ? pct(result.unallocated.usd / report.total.totalUsd) : '—', result.unallocated.labels.slice(0, 6).join(', ')), 74, '    ')}`);
+        console.log(`    ${c.dim(wrap(t.owners.neverSpread(), 72, '    '))}`);
+    }
+    else {
+        console.log(`  ${c.dim(t.owners.nothingUnallocated())}`);
+    }
+    /**
+     * The shared rules, printed with the report.
+     *
+     * The whole design: the argument then happens about the rule — "why is
+     * search 60/40?" — rather than about the number, which is an argument nobody
+     * can win because nobody can see where the number came from.
+     */
+    if (result.sharedApplied.length > 0) {
+        console.log();
+        console.log(`  ${c.bold(t.owners.sharedHeading())}`);
+        for (const { label, split } of result.sharedApplied) {
+            const rule = Object.entries(split)
+                .map(([owner, share]) => `${owner} ${pct(share)}`)
+                .join(', ');
+            console.log(`    ${c.dim(t.owners.sharedRule(label, rule))}`);
+        }
+    }
+    console.log();
+}
 function commandModels(t, pricing) {
     const n = (value) => value.toLocaleString(t.numberLocale);
     const col = t.models.columns;
@@ -7013,6 +7213,12 @@ async function main() {
         case 'models':
             commandModels(t, pricing);
             break;
+        case 'owners':
+            await commandOwners(args, config, pricing, t);
+            break;
+        case 'semantic':
+            await commandSemantic(args, config, pricing, t);
+            break;
         case 'quality':
             await commandQuality(args, config, pricing, t);
             break;