@trazum/core 1.8.0

package/src/pricing.ts

@@ -0,0 +1,468 @@
+import type { ModelPricing } from './types.js';
+
+/**
+ * Model and pricing catalogue (USD per million tokens).
+ *
+ * Source: official Claude API documentation. Prices change: check
+ * `PRICING_LAST_REVIEWED` and update this file before making budget decisions.
+ * Amazon Bedrock and Vertex AI pricing is set by each partner and is NOT the
+ * pricing in this table.
+ */
+export const PRICING_LAST_REVIEWED = '2026-06-24';
+
+/** Cost multipliers relative to the input price. */
+/**
+ * The defaults, which are Anthropic's numbers.
+ *
+ * Still exported and still correct for every Anthropic model, but no longer the
+ * whole story: a model can override any of these through `multipliers`, and
+ * anything computing a cost should go through `multipliersFor` rather than
+ * reading these directly. A cache read is ~10% of input on Anthropic and ~50%
+ * on OpenAI, and using one number for both invents a saving.
+ */
+export const COST_MULTIPLIERS = {
+  /** Cache write with a 5-minute TTL. */
+  cacheWrite5m: 1.25,
+  /** Cache write with a 1-hour TTL. */
+  cacheWrite1h: 2.0,
+  /** Cache read: ~10% of the input price. */
+  cacheRead: 0.1,
+  /** Batch API: 50% discount on input and output. */
+  batch: 0.5,
+} as const;
+
+/**
+ * The multipliers that apply to one model, defaults filled in.
+ *
+ * `batch` stays `null` when the provider has no batch API, which is different
+ * from "unspecified": the first should stop the advisory firing, the second
+ * should fall back to the default.
+ */
+export function multipliersFor(model: ModelPricing): {
+  cacheWrite5m: number;
+  cacheWrite1h: number;
+  cacheRead: number;
+  batch: number | null;
+} {
+  const m = model.multipliers ?? {};
+  return {
+    cacheWrite5m: m.cacheWrite5m ?? COST_MULTIPLIERS.cacheWrite5m,
+    cacheWrite1h: m.cacheWrite1h ?? COST_MULTIPLIERS.cacheWrite1h,
+    cacheRead: m.cacheRead ?? COST_MULTIPLIERS.cacheRead,
+    batch: m.batch === undefined ? COST_MULTIPLIERS.batch : m.batch,
+  };
+}
+
+export const MODELS: ModelPricing[] = [
+  {
+    id: 'claude-fable-5',
+    provider: 'anthropic',
+    displayName: 'Claude Fable 5',
+    inputPerMTok: 10,
+    outputPerMTok: 50,
+    contextWindow: 1_000_000,
+    cacheMinTokens: 512,
+    capability: 'frontier',
+    tier: 'frontier',
+    notes: 'Highest capability. Requires 30-day data retention.',
+  },
+  {
+    id: 'claude-mythos-5',
+    provider: 'anthropic',
+    displayName: 'Claude Mythos 5',
+    recommendable: false,
+    inputPerMTok: 10,
+    outputPerMTok: 50,
+    contextWindow: 1_000_000,
+    cacheMinTokens: 512,
+    capability: 'frontier',
+    tier: 'frontier',
+    notes: 'Available only through Project Glasswing.',
+  },
+  {
+    id: 'claude-opus-5',
+    provider: 'anthropic',
+    displayName: 'Claude Opus 5',
+    inputPerMTok: 5,
+    outputPerMTok: 25,
+    contextWindow: 1_000_000,
+    cacheMinTokens: 512,
+    capability: 'large',
+    tier: 'opus',
+    notes: '512-token cache minimum: caches prompts that would miss on Opus 4.6.',
+  },
+  {
+    id: 'claude-opus-4-8',
+    provider: 'anthropic',
+    displayName: 'Claude Opus 4.8',
+    inputPerMTok: 5,
+    outputPerMTok: 25,
+    contextWindow: 1_000_000,
+    cacheMinTokens: 1024,
+    capability: 'large',
+    tier: 'opus',
+  },
+  {
+    id: 'claude-opus-4-7',
+    provider: 'anthropic',
+    displayName: 'Claude Opus 4.7',
+    inputPerMTok: 5,
+    outputPerMTok: 25,
+    contextWindow: 1_000_000,
+    cacheMinTokens: 2048,
+    capability: 'large',
+    tier: 'opus',
+  },
+  {
+    id: 'claude-opus-4-6',
+    provider: 'anthropic',
+    displayName: 'Claude Opus 4.6',
+    inputPerMTok: 5,
+    outputPerMTok: 25,
+    contextWindow: 1_000_000,
+    cacheMinTokens: 4096,
+    capability: 'large',
+    tier: 'opus',
+  },
+  {
+    id: 'claude-sonnet-5',
+    provider: 'anthropic',
+    displayName: 'Claude Sonnet 5',
+    inputPerMTok: 3,
+    outputPerMTok: 15,
+    contextWindow: 1_000_000,
+    cacheMinTokens: 1024,
+    capability: 'mid',
+    tier: 'sonnet',
+    promo: { inputPerMTok: 2, outputPerMTok: 10, until: '2026-08-31' },
+    notes: 'Introductory pricing of 2/10 until 2026-08-31; 3/15 afterwards.',
+  },
+  {
+    id: 'claude-sonnet-4-6',
+    provider: 'anthropic',
+    displayName: 'Claude Sonnet 4.6',
+    inputPerMTok: 3,
+    outputPerMTok: 15,
+    contextWindow: 1_000_000,
+    cacheMinTokens: 1024,
+    capability: 'mid',
+    tier: 'sonnet',
+  },
+  {
+    id: 'claude-haiku-4-5',
+    provider: 'anthropic',
+    displayName: 'Claude Haiku 4.5',
+    inputPerMTok: 1,
+    outputPerMTok: 5,
+    contextWindow: 200_000,
+    cacheMinTokens: 4096,
+    capability: 'small',
+    tier: 'haiku',
+    notes: '200K context window and a 64K output cap, smaller than the rest.',
+  },
+
+  // ------------------------------------------------------------------------
+  // OpenAI
+  //
+  // Caching is AUTOMATIC above 1,024 tokens — there is no cache_control to set,
+  // and a cached read costs about half the input price rather than a tenth. The
+  // reordering advice is identical (a prefix is a prefix), the marker advice is
+  // not, which is why `caching` and `multipliers` exist at all.
+  // ------------------------------------------------------------------------
+  {
+    id: 'gpt-5',
+    provider: 'openai',
+    displayName: 'GPT-5',
+    inputPerMTok: 1.25,
+    outputPerMTok: 10,
+    contextWindow: 400_000,
+    cacheMinTokens: 1024,
+    caching: 'automatic',
+    multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
+    capability: 'frontier',
+    tier: 'frontier',
+    notes: 'Caching is automatic above 1,024 tokens; there is no cache_control to set.',
+  },
+  {
+    id: 'gpt-5-mini',
+    provider: 'openai',
+    displayName: 'GPT-5 mini',
+    inputPerMTok: 0.25,
+    outputPerMTok: 2,
+    contextWindow: 400_000,
+    cacheMinTokens: 1024,
+    caching: 'automatic',
+    multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
+    capability: 'mid',
+    tier: 'sonnet',
+  },
+  {
+    id: 'gpt-5-nano',
+    provider: 'openai',
+    displayName: 'GPT-5 nano',
+    inputPerMTok: 0.05,
+    outputPerMTok: 0.4,
+    contextWindow: 400_000,
+    cacheMinTokens: 1024,
+    caching: 'automatic',
+    multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
+    capability: 'small',
+    tier: 'haiku',
+  },
+
+  // ------------------------------------------------------------------------
+  // Google
+  // ------------------------------------------------------------------------
+  {
+    id: 'gemini-2.5-pro',
+    provider: 'google',
+    displayName: 'Gemini 2.5 Pro',
+    inputPerMTok: 1.25,
+    outputPerMTok: 10,
+    contextWindow: 1_048_576,
+    cacheMinTokens: 2048,
+    caching: 'explicit',
+    multipliers: { cacheRead: 0.25, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
+    capability: 'large',
+    tier: 'opus',
+    notes: 'Context caching is billed for storage per hour as well as per read.',
+  },
+  {
+    id: 'gemini-2.5-flash',
+    provider: 'google',
+    displayName: 'Gemini 2.5 Flash',
+    inputPerMTok: 0.3,
+    outputPerMTok: 2.5,
+    contextWindow: 1_048_576,
+    cacheMinTokens: 1024,
+    caching: 'explicit',
+    multipliers: { cacheRead: 0.25, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
+    capability: 'mid',
+    tier: 'sonnet',
+  },
+
+  // ------------------------------------------------------------------------
+  // Moonshot
+  // ------------------------------------------------------------------------
+  {
+    id: 'kimi-k2',
+    provider: 'moonshot',
+    displayName: 'Kimi K2',
+    inputPerMTok: 0.6,
+    outputPerMTok: 2.5,
+    contextWindow: 256_000,
+    cacheMinTokens: 1024,
+    caching: 'automatic',
+    multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: null },
+    capability: 'mid',
+    tier: 'sonnet',
+    notes: 'No batch API: the batch advisory stays quiet rather than offering a discount you cannot buy.',
+  },
+
+  // ------------------------------------------------------------------------
+  // DeepSeek
+  // ------------------------------------------------------------------------
+  {
+    id: 'deepseek-v3',
+    provider: 'deepseek',
+    displayName: 'DeepSeek V3',
+    inputPerMTok: 0.27,
+    outputPerMTok: 1.1,
+    contextWindow: 128_000,
+    cacheMinTokens: 1024,
+    caching: 'automatic',
+    multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: null },
+    capability: 'mid',
+    tier: 'sonnet',
+  },
+
+  // ------------------------------------------------------------------------
+  // xAI
+  // ------------------------------------------------------------------------
+  {
+    id: 'grok-4',
+    provider: 'xai',
+    displayName: 'Grok 4',
+    inputPerMTok: 3,
+    outputPerMTok: 15,
+    contextWindow: 256_000,
+    cacheMinTokens: 1024,
+    caching: 'automatic',
+    multipliers: { cacheRead: 0.25, cacheWrite5m: 1, cacheWrite1h: 1, batch: null },
+    capability: 'large',
+    tier: 'opus',
+  },
+
+  // ------------------------------------------------------------------------
+  // Mistral
+  // ------------------------------------------------------------------------
+  {
+    id: 'mistral-large-2',
+    provider: 'mistral',
+    displayName: 'Mistral Large 2',
+    inputPerMTok: 2,
+    outputPerMTok: 6,
+    contextWindow: 128_000,
+    cacheMinTokens: 0,
+    caching: 'none',
+    multipliers: { batch: 0.5 },
+    capability: 'large',
+    tier: 'opus',
+    notes: 'No prompt caching: reordering still helps readability but saves nothing here.',
+  },
+];
+
+export const DEFAULT_MODEL = 'claude-opus-5';
+
+/**
+ * A set of prices to work from.
+ *
+ * Prices change on someone else's schedule, and until 1.0 correcting one meant
+ * upgrading the library — which is backwards: a stale price is a wrong number in
+ * a budget decision, and nobody should have to take a dependency bump to fix it.
+ *
+ * So the catalogue is a **value**, not module state. The bundled one below is the
+ * default, and `applyPricingOverlay` returns a *new* catalogue with local
+ * corrections layered on. Nothing mutates: a caller who overlays prices does not
+ * change what any other caller sees, and two catalogues can exist in one process
+ * — which is what makes it testable and what stops one consumer's local prices
+ * leaking into another's report.
+ */
+export interface PricingCatalogue {
+  models: ModelPricing[];
+  byId: Map<string, ModelPricing>;
+  /** The date the prices in this catalogue were last checked. */
+  lastReviewed: string;
+  /** Ids whose bundled prices an overlay replaced. Empty for the bundled set. */
+  overriddenModels: string[];
+  /** Ids an overlay introduced that the bundled catalogue does not have. */
+  addedModels: string[];
+}
+
+function makeCatalogue(
+  models: ModelPricing[],
+  lastReviewed: string,
+  overriddenModels: string[] = [],
+  addedModels: string[] = [],
+): PricingCatalogue {
+  return {
+    models,
+    byId: new Map(models.map((m) => [m.id, m])),
+    lastReviewed,
+    overriddenModels,
+    addedModels,
+  };
+}
+
+/** The prices compiled into this release. */
+export const BUNDLED_CATALOGUE: PricingCatalogue = makeCatalogue(MODELS, PRICING_LAST_REVIEWED);
+
+/** Looks a model up in a specific catalogue. */
+export function modelFrom(catalogue: PricingCatalogue, id: string): ModelPricing {
+  const model = catalogue.byId.get(id);
+  if (!model) {
+    throw new Error(
+      `Unknown model: "${id}". Available: ${catalogue.models.map((m) => m.id).join(', ')}`,
+    );
+  }
+  return model;
+}
+
+/**
+ * Cheapest model of a tier within a catalogue.
+ *
+ * Compared on the **effective** price, so a model in a promotional window is
+ * ranked at what it actually costs today rather than at its list price.
+ */
+export function cheapestOfTierIn(
+  catalogue: PricingCatalogue,
+  tier: ModelPricing['tier'],
+  on: Date = new Date(),
+  /**
+   * Restrict to one provider. Omit to search the whole catalogue, which is what
+   * this did before other providers existed — kept as the default so the
+   * signature stays additive, though the advisory always passes one: switching
+   * vendor is a migration, not a cheaper model.
+   */
+  provider?: string,
+): ModelPricing {
+  const candidates = catalogue.models.filter(
+    (m) =>
+      m.tier === tier &&
+      m.recommendable !== false &&
+      (provider === undefined || m.provider === provider),
+  );
+  const first = candidates[0];
+  if (!first) throw new Error(`No models for tier "${tier}"`);
+  return candidates.reduce(
+    (best, m) =>
+      effectivePricing(m, on).inputPerMTok < effectivePricing(best, on).inputPerMTok ? m : best,
+    first,
+  );
+}
+
+export function getModel(id: string): ModelPricing {
+  return modelFrom(BUNDLED_CATALOGUE, id);
+}
+
+export function listModels(): ModelPricing[] {
+  return [...MODELS];
+}
+
+/** Effective price on a given date, applying any live promotion. */
+export function effectivePricing(
+  model: ModelPricing,
+  on: Date = new Date(),
+): { inputPerMTok: number; outputPerMTok: number; promoApplied: boolean } {
+  if (model.promo) {
+    const until = new Date(`${model.promo.until}T23:59:59.999Z`);
+    if (on.getTime() <= until.getTime()) {
+      return {
+        inputPerMTok: model.promo.inputPerMTok,
+        outputPerMTok: model.promo.outputPerMTok,
+        promoApplied: true,
+      };
+    }
+  }
+  return {
+    inputPerMTok: model.inputPerMTok,
+    outputPerMTok: model.outputPerMTok,
+    promoApplied: false,
+  };
+}
+
+/** Cheapest model of each capability tier, for recommendations. */
+export function cheapestOfTier(tier: ModelPricing['tier']): ModelPricing {
+  const candidates = MODELS.filter((m) => m.tier === tier && m.recommendable !== false);
+  const first = candidates[0];
+  if (!first) throw new Error(`No models for tier "${tier}"`);
+  return candidates.reduce((best, m) => (m.inputPerMTok < best.inputPerMTok ? m : best), first);
+}
+
+/**
+ * Whole days between a `YYYY-MM-DD` review date and now, or `null`.
+ *
+ * Every dollar figure Trazum prints descends from a price list, and the list
+ * carries the date it was checked. Printing only that date makes the reader do
+ * arithmetic against today to learn the one thing they wanted to know — whether
+ * to trust it — and a reader who is not already suspicious will not bother.
+ *
+ * `now` is a parameter for the reason `computeSavings` takes a `Date`: a function
+ * that reads the clock can only be asserted for shape.
+ *
+ * Compared at UTC midnight on both sides, so the answer does not change by one
+ * depending on what time of day the command runs. `null` for anything that is not
+ * a date — an overlay supplies this string, and a wrong one should read as
+ * unknown rather than as a confident number computed from `NaN`.
+ */
+export function reviewAgeDays(lastReviewed: string, now: Date): number | null {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(lastReviewed)) return null;
+  const then = Date.parse(`${lastReviewed}T00:00:00Z`);
+  if (Number.isNaN(then)) return null;
+
+  const today = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+  const days = Math.round((today - then) / 86_400_000);
+  // A future date is a typo or a clock problem, not an age. Reported as unknown
+  // rather than as a negative number of days, which reads like a bug either way.
+  return days < 0 ? null : days;
+}

package/src/profile.ts

@@ -0,0 +1,124 @@
+import { segment } from './segment.js';
+import { findExamples, findRestatedFormat } from './structure.js';
+import { estimateTokens } from './tokenizer.js';
+import type { TokenCounter } from './types.js';
+
+/**
+ * What a prompt is made of, so a team can decide which one to fix first.
+ *
+ * ## Why this is not a score
+ *
+ * The obvious shape for "which prompts should we optimise?" is a number out of
+ * a hundred, and it is the wrong shape. `Complexity: 74` cannot be argued with,
+ * cannot be reproduced by hand, and does not tell anybody what to do on Monday.
+ * Worse, the weights that turn four measurements into one number are invented —
+ * and once invented they get tuned until the ranking looks right, which is
+ * fitting the metric to the answer.
+ *
+ * So this returns **the measurements**, each with a definition you can check
+ * against the prompt in front of you, and ranks on the one quantity that is not
+ * a matter of opinion: **what optimising it would actually save.** That figure
+ * comes from running the deterministic rules, not from a formula.
+ *
+ * The structural facts are the *explanation* for a prompt's position in that
+ * ranking, not a substitute for it. "1,204 tokens across 8 sentences" says why
+ * a prompt is worth looking at; "$310 a month recoverable" says whether it is
+ * worth looking at before the other thirty-nine.
+ *
+ * ## What each measurement means, exactly
+ *
+ * - **sentences** — spans ending in `.`, `!`, `?`, `。`, `！`, `？`, or a line
+ *   break where the line ends without punctuation (a bullet is a sentence).
+ *   Protected content is excluded, so a code block is not forty sentences.
+ * - **tokensPerSentence** — the verbosity signal, and the only ratio here. It
+ *   is length-independent: a padded 300-token prompt and a padded 3,000-token
+ *   one look the same, which is the point. Reported with units, never as an
+ *   index.
+ * - **examples / exampleTokens** — from `findExamples`, the same detector the
+ *   advisories use. Few-shot examples are usually the largest single block in
+ *   an expensive prompt and the easiest to trim by one.
+ * - **formatTokens** — a restated output format (a JSON schema written out
+ *   twice, or written out at all when the API takes a schema parameter).
+ * - **protectedTokens** — code, URLs, placeholders and tags. Counted separately
+ *   because **no amount of optimising will touch them**, and a prompt that is
+ *   80% code has far less headroom than its size suggests. Leaving this out is
+ *   how a ranking sends somebody to spend an afternoon on a file that cannot
+ *   move.
+ */
+
+export interface PromptProfile {
+  tokens: number;
+  /** Tokens that cannot be touched: code, URLs, placeholders, tags. */
+  protectedTokens: number;
+  sentences: number;
+  /** `tokens / sentences`, rounded to one decimal. Zero when there are none. */
+  tokensPerSentence: number;
+  examples: number;
+  exampleTokens: number;
+  /** Tokens in a restated output format, or 0. */
+  formatTokens: number;
+}
+
+const SENTENCE_END = /[.!?。！？]+/;
+
+/**
+ * Sentences in the mutable part of the prompt.
+ *
+ * Deliberately simple and stated rather than clever. An abbreviation splits a
+ * sentence in two here, and that is accepted: the number is used as a
+ * denominator for a verbosity ratio, where a few percent of noise changes
+ * nothing, and the alternative is a sentence tokeniser this project would then
+ * have to defend.
+ */
+export function countSentences(prompt: string): number {
+  let total = 0;
+
+  for (const piece of segment(prompt)) {
+    if (piece.kind === 'protected') continue;
+
+    for (const line of piece.text.split('\n')) {
+      const trimmed = line.trim();
+      if (trimmed === '') continue;
+
+      const parts = trimmed
+        .split(SENTENCE_END)
+        .map((part) => part.trim())
+        .filter((part) => part !== '');
+
+      // A line with no terminal punctuation is still one thing being said — a
+      // bullet, a heading, a rule in a list. Counting it as zero would make
+      // every bulleted prompt look infinitely verbose.
+      total += Math.max(1, parts.length);
+    }
+  }
+
+  return total;
+}
+
+export interface ProfileOptions {
+  count?: TokenCounter;
+}
+
+/** Measures a prompt. Deterministic, offline, and free. */
+export function profilePrompt(prompt: string, options: ProfileOptions = {}): PromptProfile {
+  const count = options.count ?? estimateTokens;
+
+  const tokens = count(prompt);
+  const protectedTokens = segment(prompt)
+    .filter((piece) => piece.kind === 'protected')
+    .reduce((sum, piece) => sum + count(piece.text), 0);
+
+  const sentences = countSentences(prompt);
+  const examples = findExamples(prompt, count);
+  const format = findRestatedFormat(prompt, count);
+
+  return {
+    tokens,
+    protectedTokens,
+    sentences,
+    tokensPerSentence: sentences === 0 ? 0 : Math.round((tokens / sentences) * 10) / 10,
+    examples: examples.length,
+    exampleTokens: examples.reduce((sum, block) => sum + block.tokens, 0),
+    formatTokens: format?.restatedTokens ?? 0,
+  };
+}