@trazum/core 1.44.0 → 1.46.0

package/dist/init.js

@@ -0,0 +1,325 @@
+/**
+ * The first five minutes, decided without touching a disk.
+ *
+ * Everything since 1.41 raised the ceiling. This lowers the floor: from
+ * `npx @trazum/cli` to a finding worth money, without reading a page of
+ * documentation. Twenty-one commands is a wall to somebody who has none of
+ * them yet, and that wall is why a good tool gets closed inside a minute.
+ *
+ * **The proposal is a document, not a side effect.** What `init` would write
+ * is decided here, from observations the CLI collected, and returned as a
+ * value. So every rule below is testable without a filesystem, and `--dry-run`
+ * is the same code path minus the write rather than a second implementation
+ * that drifts from the first.
+ *
+ * **A key with no evidence is not written.** A generated config full of
+ * guessed thresholds is a config nobody trusts and everybody deletes — and it
+ * is worse than an empty one, because it looks like a decision somebody made.
+ * Every key that lands carries the observation that justified it; every key
+ * that does not carries what would settle it. Both are typed values, because a
+ * first run that explains itself only in prose cannot be checked by a test.
+ *
+ * **Measurement is not policy.** A log says what your traffic *was* — how many
+ * calls, which model, how long the outputs ran. Those are measurements and
+ * this file writes them. A budget says what your traffic *may cost*, which no
+ * log can answer: picking "the measured month plus twenty per cent" would be
+ * this tool inventing a threshold and then grading somebody against it. So
+ * `spend` is always declined, and the measured figure is handed over so the
+ * person who *can* set a budget has the number in front of them.
+ */
+import { DEFAULT_EXTENSIONS } from './config-schema.js';
+import { billLevers } from './levers.js';
+/** A month, for turning a measured span into a rate. */
+const DAYS_PER_MONTH = 30;
+/**
+ * The shortest measured span that may be stated as a monthly rate.
+ *
+ * Four weeks, so every weekday appears the same number of times. Three days of
+ * traffic multiplied by ten is a forecast wearing a measurement's clothes, and
+ * this repository has refused that since the series shipped in 1.40.
+ */
+export const MIN_RATE_DAYS = 28;
+/** The share of the bill a headline must clear to be worth being the headline. */
+export const HEADLINE_FLOOR_SHARE = 0.01;
+/** Days between two `YYYY-MM-DD` days, inclusive of both. */
+function spanDays(first, last) {
+    const a = Date.parse(`${first}T00:00:00Z`);
+    const b = Date.parse(`${last}T00:00:00Z`);
+    if (Number.isNaN(a) || Number.isNaN(b))
+        return 0;
+    return Math.round((b - a) / 86_400_000) + 1;
+}
+/** The extensions actually present among the prompt files found. */
+function extensionsOf(files) {
+    const seen = new Set();
+    for (const file of files) {
+        const dot = file.lastIndexOf('.');
+        const slash = Math.max(file.lastIndexOf('/'), file.lastIndexOf('\\'));
+        if (dot > slash + 1)
+            seen.add(file.slice(dot).toLowerCase());
+    }
+    return [...seen].sort();
+}
+/**
+ * The one model a config may name, from what was measured.
+ *
+ * A log spread across four models has no single answer, and writing the
+ * largest of the four would silently price every prompt in the repository
+ * against a model most of them never touch. The threshold is a majority: past
+ * half the bill, "this is what you use" is a fair sentence.
+ */
+function dominantModel(report) {
+    if (report.total.totalUsd <= 0 || report.byModel.length === 0)
+        return null;
+    const top = report.byModel[0];
+    if (top === undefined)
+        return null;
+    const share = top.breakdown.totalUsd / report.total.totalUsd;
+    return share > 0.5 ? { model: top.model, share } : null;
+}
+export function proposeInit(observations, options) {
+    const { catalogue, on = new Date() } = options;
+    const { measured } = observations;
+    const justified = [];
+    const declined = [];
+    const config = {};
+    // --- locale -------------------------------------------------------------
+    if (observations.locale !== null) {
+        config.locale = observations.locale;
+        justified.push({ key: 'locale', value: observations.locale, from: 'environment' });
+    }
+    // --- extensions ---------------------------------------------------------
+    //
+    // Only when the walk found something the defaults do not already cover.
+    // Writing `[".txt", ".md", ".prompt", ".tmpl"]` back into a config is a key
+    // that changes nothing and has to be maintained forever.
+    const extensions = extensionsOf(observations.promptFiles);
+    if (extensions.length > 0 && extensions.some((e) => !DEFAULT_EXTENSIONS.includes(e))) {
+        config.extensions = extensions;
+        justified.push({
+            key: 'extensions',
+            value: extensions,
+            from: 'walk',
+            files: observations.promptFiles.length,
+        });
+    }
+    // --- usage.model --------------------------------------------------------
+    //
+    // Measured beats detected, and it is not close. An import says which SDK
+    // somebody installed; a log says which model was billed. When there is no
+    // log, a literal in the source will do — but a *provider* with no model is
+    // declined rather than filled in from that provider's default. `where` may
+    // print a provider default because a reader can see it is a guess; a config
+    // file cannot, because six weeks later it reads as a decision.
+    const dominant = measured === null ? null : dominantModel(measured);
+    const modelSighting = observations.sightings.find((s) => s.detection.model !== null && s.detection.conflicts.length === 0);
+    const conflicting = observations.sightings.filter((s) => s.detection.conflicts.length > 0);
+    const providerOnly = observations.sightings.find((s) => s.detection.provider !== null && s.detection.model === null && s.detection.conflicts.length === 0);
+    if (dominant !== null) {
+        config.usage = { ...config.usage, model: dominant.model };
+        justified.push({
+            key: 'usage.model',
+            value: dominant.model,
+            from: 'measured',
+            share: dominant.share,
+        });
+    }
+    else if (modelSighting !== undefined) {
+        const evidence = modelSighting.detection.evidence.find((e) => e.model !== undefined) ??
+            modelSighting.detection.evidence[0];
+        config.usage = { ...config.usage, model: modelSighting.detection.model };
+        justified.push({
+            key: 'usage.model',
+            value: modelSighting.detection.model,
+            from: 'source',
+            file: modelSighting.file,
+            line: evidence?.line ?? 0,
+            evidence: evidence?.kind ?? 'model-literal',
+        });
+    }
+    else if (conflicting.length > 0) {
+        declined.push({
+            key: 'usage.model',
+            why: 'conflicting-evidence',
+            files: conflicting.map((s) => s.file),
+        });
+    }
+    else if (providerOnly !== undefined) {
+        declined.push({
+            key: 'usage.model',
+            why: 'provider-only',
+            provider: providerOnly.detection.provider,
+            file: providerOnly.file,
+        });
+    }
+    else {
+        declined.push({ key: 'usage.model', why: 'no-evidence' });
+    }
+    // --- the measured span, which three keys below depend on ----------------
+    const dated = measured?.spendByDay ?? [];
+    const first = dated[0];
+    const last = dated[dated.length - 1];
+    const days = first === undefined || last === undefined ? 0 : spanDays(first.day, last.day);
+    const datedCalls = dated.reduce((sum, d) => sum + d.calls, 0);
+    const undated = measured === null ? 0 : Math.max(0, measured.total.calls - datedCalls);
+    // --- usage.callsPerMonth ------------------------------------------------
+    //
+    // Three separate refusals, and they are not the same refusal. No log is one
+    // situation; a log covering four days is another; a log whose records carry
+    // no clock is a third — and that last one is the one that would go wrong
+    // quietly, because the calls are all *there*, they simply cannot be placed
+    // in time. Dividing them by a span they were never proven to fall inside is
+    // how a rate comes out too high and nobody can see why.
+    if (measured === null) {
+        declined.push({ key: 'usage.callsPerMonth', why: 'nothing-measured' });
+    }
+    else if (undated > 0) {
+        declined.push({
+            key: 'usage.callsPerMonth',
+            why: 'undated-calls',
+            undated,
+            calls: measured.total.calls,
+        });
+    }
+    else if (days < MIN_RATE_DAYS) {
+        declined.push({
+            key: 'usage.callsPerMonth',
+            why: 'window-too-short',
+            days,
+            calls: measured.total.calls,
+        });
+    }
+    else {
+        const perMonth = Math.round((measured.total.calls / days) * DAYS_PER_MONTH);
+        config.usage = { ...config.usage, callsPerMonth: perMonth };
+        justified.push({
+            key: 'usage.callsPerMonth',
+            value: perMonth,
+            from: 'measured',
+            calls: measured.total.calls,
+            days,
+        });
+    }
+    // --- usage.avgOutputTokens ----------------------------------------------
+    //
+    // An average of what happened, not a forecast of what will — so unlike the
+    // rate above it needs no minimum span. One day of real calls gives a real
+    // average of those calls.
+    if (measured === null || measured.total.calls === 0) {
+        declined.push({ key: 'usage.avgOutputTokens', why: 'nothing-measured' });
+    }
+    else {
+        const avg = Math.round(measured.total.outputTokens / measured.total.calls);
+        config.usage = { ...config.usage, avgOutputTokens: avg };
+        justified.push({
+            key: 'usage.avgOutputTokens',
+            value: avg,
+            from: 'measured',
+            outputTokens: measured.total.outputTokens,
+            calls: measured.total.calls,
+        });
+    }
+    // --- usage.cacheHitRate -------------------------------------------------
+    //
+    // **Not recorded is not not-happened.** A log with no cache fields at all
+    // does not prove a hit rate of zero — it proves the exporter did not write
+    // the column. Writing 0 there would tell every later caching advisory that
+    // caching is doing nothing, which is a finding invented out of a missing
+    // field.
+    if (measured === null) {
+        declined.push({ key: 'usage.cacheHitRate', why: 'nothing-measured' });
+    }
+    else {
+        const read = measured.total.cacheReadTokens;
+        const written = measured.total.cacheWriteTokens;
+        const input = measured.total.inputTokens;
+        if (read === 0 && written === 0) {
+            declined.push({ key: 'usage.cacheHitRate', why: 'not-recorded' });
+        }
+        else {
+            const denominator = read + input;
+            const rate = denominator === 0 ? 0 : Math.round((read / denominator) * 100) / 100;
+            config.usage = { ...config.usage, cacheHitRate: rate };
+            justified.push({
+                key: 'usage.cacheHitRate',
+                value: rate,
+                from: 'measured',
+                cacheReadTokens: read,
+                inputTokens: input,
+            });
+        }
+    }
+    // --- usage.batchEligible ------------------------------------------------
+    //
+    // Never written, in either direction. Whether the work tolerates a batch
+    // window is a fact about a product decision, and no log records it. A
+    // default of `false` would quietly delete the batch lever from every report
+    // this config touches; `true` would offer a saving on latency somebody never
+    // agreed to give up.
+    declined.push({ key: 'usage.batchEligible', why: 'only-you-know' });
+    // --- labels -------------------------------------------------------------
+    //
+    // Mapping a log label to a prompt file is a claim about which file produced
+    // which calls, and a directory walk cannot prove one. A wrong entry here is
+    // worse than a missing one: `profile` would go and read the wrong file and
+    // explain a cache verdict with the wrong prompt's structure, confidently.
+    const labels = measured?.byLabel.length ?? 0;
+    if (labels > 0)
+        declined.push({ key: 'labels', why: 'unprovable', labels });
+    // --- spend --------------------------------------------------------------
+    //
+    // The measured figure is handed over, and the threshold is not invented.
+    declined.push({
+        key: 'spend.maxUsd',
+        why: 'a-budget-is-a-policy',
+        measuredUsd: measured === null ? null : measured.total.totalUsd,
+        days: measured === null ? null : days,
+    });
+    // --- the headline -------------------------------------------------------
+    let headline = null;
+    let noHeadline = null;
+    if (measured === null) {
+        noHeadline = 'nothing-measured';
+    }
+    else if (measured.total.totalUsd <= 0) {
+        noHeadline = 'nothing-could-be-priced';
+    }
+    else {
+        const levers = billLevers(measured, { catalogue, on, minShare: HEADLINE_FLOOR_SHARE });
+        const top = levers.slices[0];
+        if (top === undefined || top.combinedUsd <= 0) {
+            noHeadline = 'no-lever-clears-the-floor';
+        }
+        else {
+            headline = {
+                slice: top,
+                lever: top.route !== null && top.batch !== null
+                    ? 'route+batch'
+                    : top.route !== null
+                        ? 'route'
+                        : 'batch',
+                savingUsd: top.combinedUsd,
+                provenance: 'measured',
+                days,
+            };
+        }
+    }
+    // --- what this would overwrite ------------------------------------------
+    let overwrites = null;
+    if (observations.existing !== null) {
+        const already = observations.existing.config;
+        const keys = [];
+        if (config.locale !== undefined && already.locale !== undefined)
+            keys.push('locale');
+        if (config.extensions !== undefined && already.extensions !== undefined)
+            keys.push('extensions');
+        for (const k of ['model', 'callsPerMonth', 'avgOutputTokens', 'cacheHitRate']) {
+            if (config.usage?.[k] !== undefined && already.usage?.[k] !== undefined) {
+                keys.push(`usage.${k}`);
+            }
+        }
+        overwrites = { path: observations.existing.path, keys };
+    }
+    return { schemaVersion: 1, config, justified, declined, headline, noHeadline, overwrites };
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trazum/core",
-  "version": "1.44.0",
+  "version": "1.46.0",
   "description": "Trazum core: priced advisories for LLM prompts (caching, model tier, batching, schemas), plus deterministic trimming, token counting and pricing.",
   "license": "MIT",
   "author": "David Mu\u00f1oz Rey",

package/src/guard.ts

@@ -0,0 +1,204 @@
+/**
+ * The thing spending the money can finally ask, and be told no.
+ *
+ * 1.44 gave an endpoint that *answers*. An agent may consult it and ignore it,
+ * which is fine — advice an implementation can skip is still advice worth
+ * having. What was missing is the shape of a refusal an agent can act on.
+ *
+ * **A guard that only says no teaches a caller to stop asking.** A model told
+ * "denied" with no alternative has exactly two moves: send it anyway, or fail
+ * the user's request. Both are worse than the call it wanted to make. So every
+ * refusal here arrives with the levers that exist — this work routes to a
+ * cheaper model that still fits, a batch window would halve it — each with
+ * what it is worth *for this call*, and the assumption it rests on.
+ *
+ * **The guard never spends to answer.** No provider call, no LLM pass, no
+ * pull. The answer comes from the store and the catalogue, or it says it
+ * cannot tell. A cost guard that costs money to consult is a joke with a bill
+ * attached.
+ *
+ * **An alternative the prompt does not fit in is not an alternative.** A
+ * cheaper model with a smaller context window does not make this call cheaper;
+ * it makes it impossible. Those are filtered out here rather than offered and
+ * blamed later.
+ */
+
+import { answerCost } from './answer.js';
+import type { AnswerRequest, CostAnswer } from './answer.js';
+import { effectivePricing, multipliersFor } from './pricing.js';
+import type { PricingCatalogue } from './pricing.js';
+import type { ModelPricing } from './types.js';
+import type { PlanAssumption } from './plan.js';
+
+export type GuardVerdict = 'yes' | 'no' | 'cannot-tell';
+
+export interface GuardAlternative {
+  kind: 'route' | 'batch' | 'route+batch';
+  /** The model this moves to, when it moves. */
+  model: { id: string; displayName: string } | null;
+  /**
+   * What this alternative saves **on this call** — not per month.
+   *
+   * The caller is deciding one call, right now. A monthly figure would be the
+   * right number at the wrong moment, and an agent has no way to act on it.
+   */
+  savingUsd: number;
+  /** What the log cannot confirm, typed as everywhere since 1.38. */
+  assumes: PlanAssumption[];
+  /**
+   * Whether the described call fits this alternative's context window.
+   *
+   * Only `true` ever reaches a caller — the false ones are dropped before
+   * they are offered. The field exists so the rule is visible in the type
+   * rather than buried in a filter nobody reads.
+   */
+  fits: true;
+}
+
+export interface GuardAnswer {
+  schemaVersion: 1;
+  verdict: GuardVerdict;
+  /** The full cost answer, halves and provenance intact. */
+  cost: CostAnswer;
+  /**
+   * What to do instead, dearest saving first. Present on a refusal, and on a
+   * yes as well: an agent that can spend less while still being allowed to
+   * spend should be told so.
+   */
+  alternatives: GuardAlternative[];
+  /**
+   * A one-line reason a human will read in a log. The fields above are what a
+   * machine acts on; this is never the only place a fact appears.
+   */
+  because: string;
+}
+
+/** Models cheaper than this one, in the same family, that the prompt fits in. */
+function cheaperThan(
+  model: ModelPricing,
+  catalogue: PricingCatalogue,
+  inputTokens: number,
+  on: Date,
+): ModelPricing[] {
+  const here = effectivePricing(model, on);
+  return [...catalogue.byId.values()]
+    .filter((candidate) => {
+      if (candidate.id === model.id) return false;
+      if (candidate.provider !== model.provider) return false;
+      const there = effectivePricing(candidate, on);
+      if (there.inputPerMTok >= here.inputPerMTok) return false;
+      // A model the prompt does not fit in is not a cheaper way to make this
+      // call; it is a way not to make it.
+      return candidate.contextWindow >= inputTokens;
+    })
+    .sort((a, b) => effectivePricing(b, on).inputPerMTok - effectivePricing(a, on).inputPerMTok);
+}
+
+export interface GuardRequest extends AnswerRequest {
+  /** Whether the caller says this work can wait for a batch window. */
+  batchEligible?: boolean;
+}
+
+export function guardSpend(
+  request: GuardRequest,
+  options: { catalogue: PricingCatalogue; on?: Date },
+): GuardAnswer {
+  const { catalogue, on = new Date() } = options;
+  const cost = answerCost(request, { catalogue, on });
+
+  const alternatives: GuardAlternative[] = [];
+  const model = request.model === undefined ? undefined : catalogue.byId.get(request.model);
+
+  if (model !== undefined && cost.call !== null) {
+    const inputTokens = cost.call.inputTokens;
+    const outputTokens = cost.call.outputTokens;
+    const here = effectivePricing(model, on);
+    const priceOf = (candidate: ModelPricing): number => {
+      const rates = effectivePricing(candidate, on);
+      return (inputTokens / 1_000_000) * rates.inputPerMTok + (outputTokens / 1_000_000) * rates.outputPerMTok;
+    };
+    const mine = (inputTokens / 1_000_000) * here.inputPerMTok + (outputTokens / 1_000_000) * here.outputPerMTok;
+    const batchRate = multipliersFor(model).batch;
+
+    for (const candidate of cheaperThan(model, catalogue, inputTokens, on)) {
+      const routed = priceOf(candidate);
+      const candidateBatch = multipliersFor(candidate).batch;
+      const both = candidateBatch === null ? null : routed * candidateBatch;
+      /**
+       * Route and batch on the same call combine the way `billLevers` has
+       * combined them since 1.23: the batch discount applies to the *cheaper*
+       * model's price, never as a second subtraction from this one. Adding the
+       * two savings is the arithmetic `plan` exists to kill.
+       */
+      if (request.batchEligible === true && both !== null) {
+        alternatives.push({
+          kind: 'route+batch',
+          model: { id: candidate.id, displayName: candidate.displayName },
+          savingUsd: mine - both,
+          assumes: [
+            { kind: 'model-capability', model: candidate.displayName },
+            { kind: 'batch-window' },
+          ],
+          fits: true,
+        });
+      }
+      alternatives.push({
+        kind: 'route',
+        model: { id: candidate.id, displayName: candidate.displayName },
+        savingUsd: mine - routed,
+        assumes: [{ kind: 'model-capability', model: candidate.displayName }],
+        fits: true,
+      });
+    }
+
+    if (request.batchEligible === true && batchRate !== null) {
+      alternatives.push({
+        kind: 'batch',
+        model: null,
+        savingUsd: mine - mine * batchRate,
+        assumes: [{ kind: 'batch-window' }],
+        fits: true,
+      });
+    }
+  }
+
+  alternatives.sort((a, b) => b.savingUsd - a.savingUsd);
+
+  /**
+   * The verdict maps the cost answer's three outcomes onto the three an agent
+   * can act on. `cannot-tell` stays `cannot-tell` rather than defaulting to
+   * yes: a guard that permits whatever it cannot judge is a guard that permits
+   * everything the moment its inputs go missing.
+   */
+  const verdict: GuardVerdict =
+    cost.verdict === 'cannot-tell' ? 'cannot-tell' : cost.verdict === 'over' ? 'no' : 'yes';
+
+  return {
+    schemaVersion: 1,
+    verdict,
+    cost,
+    alternatives,
+    because: reasonFor(verdict, cost, alternatives),
+  };
+}
+
+function reasonFor(verdict: GuardVerdict, cost: CostAnswer, alternatives: GuardAlternative[]): string {
+  if (verdict === 'cannot-tell') {
+    return cost.reason === 'no-budget-configured'
+      ? 'No budget is configured, so there is nothing to judge this against.'
+      : cost.reason === 'nothing-measured'
+        ? 'Nothing has been measured yet, so how much of the budget is gone is unknown.'
+        : 'This model is not in the price catalogue, so the call cannot be priced.';
+  }
+  if (verdict === 'no') {
+    const lead = cost.restsOn === 'measured'
+      ? 'The budget is already spent, measured.'
+      : 'This call would take the budget past its limit, on an estimate of the call.';
+    return alternatives.length === 0
+      ? `${lead} No cheaper way to make this call exists in the catalogue.`
+      : `${lead} The cheapest alternative below saves the most.`;
+  }
+  return alternatives.length === 0
+    ? 'Within budget, and no cheaper way to make this call exists in the catalogue.'
+    : 'Within budget — and there is still a cheaper way to make this call.';
+}

package/src/index.ts

@@ -49,6 +49,21 @@ export type { PlanAction, PlanActionKind, PlanAssumption, PlanDocument } from '.
 export { verifyPlan } from './verify.js';
 export { buildHistory, storedReportFrom, MIN_RUN } from './history.js';
 export { answerCost } from './answer.js';
+export { guardSpend } from './guard.js';
+export type { GuardAlternative, GuardAnswer, GuardRequest, GuardVerdict } from './guard.js';
+export { proposeInit, HEADLINE_FLOOR_SHARE, MIN_RATE_DAYS } from './init.js';
+export type {
+  InitDecline,
+  InitHeadline,
+  InitJustification,
+  InitKey,
+  InitObservations,
+  InitOptions,
+  InitProposal,
+  NoHeadline,
+  ProviderSighting,
+  UsageSighting,
+} from './init.js';
 export type {
   AnswerRequest,
   AnswerVerdict,