@trazum/core 1.81.0 → 1.83.0

package/src/pricing.ts

@@ -1,4 +1,4 @@
-import type { ModelPricing } from './types.js';
+import type { ModelPricing, PricingTier, TierCondition } from './types.js';
 
 /**
  * Model and pricing catalogue (USD per million tokens).
@@ -8,7 +8,57 @@ import type { ModelPricing } from './types.js';
  * 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';
+/**
+ * When each provider's prices were last checked against that provider's own
+ * published table.
+ *
+ * One date for the whole catalogue was the wrong shape, and it cost a real
+ * error. Seven providers publish independently and are checked independently;
+ * a single date forces a partial review to either overstate itself by moving
+ * the date for everyone, or throw itself away by leaving it. What happened is
+ * the second: this constant was written on 2026-08-04 already reading
+ * 2026-06-24, and never moved again.
+ *
+ * Meanwhile Anthropic cancelled the increase that was going to take Sonnet 5
+ * from its 2/10 introductory price to 3/15 on 2026-09-01, and made 2/10
+ * standard. The catalogue still carried the promotion with its end date, so on
+ * 2026-09-01 every Sonnet 5 figure this tool printed would have risen 50% with
+ * no code change and no way for a reader to tell. A price nobody charges is
+ * the one error this product cannot make, and it was four days out on a timer.
+ *
+ * So: a date per provider, checked against that provider's own page, and the
+ * catalogue's headline date derived as the oldest of them rather than typed.
+ */
+export const PROVIDER_REVIEWED: Readonly<Record<string, string>> = Object.freeze({
+  /* platform.claude.com/docs/en/about-claude/pricing, read 2026-08-27. */
+  anthropic: '2026-08-27',
+  openai: '2026-06-24',
+  /* ai.google.dev/gemini-api/docs/pricing, read 2026-08-28. */
+  google: '2026-08-28',
+  moonshot: '2026-06-24',
+  /* api-docs.deepseek.com/quick_start/pricing, read 2026-08-28. */
+  deepseek: '2026-08-28',
+  xai: '2026-06-24',
+  /*
+   * `mistral.ai/pricing`, read 2026-08-28 — by a human, because the page
+   * renders its table in the browser and serves a fetch only an FAQ example
+   * with no model id attached.
+   *
+   * This date stayed at 2026-06-24 for a few hours after the other two moved,
+   * which is the point of having one per provider: looking and finding nothing
+   * servable is not the same as checking, and moving the date then would have
+   * said it was.
+   */
+  mistral: '2026-08-28',
+});
+
+/**
+ * The catalogue's age is its oldest provider's, because a reader asking how
+ * old this table is wants the answer for the worst part of it, not the best.
+ */
+export const PRICING_LAST_REVIEWED: string = Object.values(PROVIDER_REVIEWED).reduce(
+  (oldest, date) => (date < oldest ? date : oldest),
+);
 
 /** Cost multipliers relative to the input price. */
 /**
@@ -138,14 +188,15 @@ export const MODELS: ModelPricing[] = [
     id: 'claude-sonnet-5',
     provider: 'anthropic',
     displayName: 'Claude Sonnet 5',
-    inputPerMTok: 3,
-    outputPerMTok: 15,
+    inputPerMTok: 2,
+    outputPerMTok: 10,
     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.',
+    notes:
+      'Launched with 2/10 as introductory pricing through 2026-08-31; the scheduled'
+      + ' increase to 3/15 on 2026-09-01 was cancelled and 2/10 is the standard price.',
   },
   {
     id: 'claude-sonnet-4-6',
@@ -237,6 +288,12 @@ export const MODELS: ModelPricing[] = [
     cacheMinTokens: 2048,
     caching: 'explicit',
     multipliers: { cacheRead: 0.25, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
+    /* Refused on 2026-08-28: still in `GET /v1beta/models`, and a 404 to a request. */
+    retired: {
+      on: '2026-08-28',
+      because:
+        'This model models/gemini-2.5-pro is no longer available to new users. Please update your code to use models/gemini-3.1-pro-preview for the latest features and improvements. We recommend you to use the Interactions API.',
+    },
     capability: 'large',
     tier: 'opus',
     notes: 'Context caching is billed for storage per hour as well as per read.',
@@ -251,10 +308,50 @@ export const MODELS: ModelPricing[] = [
     cacheMinTokens: 1024,
     caching: 'explicit',
     multipliers: { cacheRead: 0.25, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
+    /* Refused on 2026-08-28: still in `GET /v1beta/models`, and a 404 to a request. */
+    retired: {
+      on: '2026-08-28',
+      because:
+        'This model models/gemini-2.5-flash is no longer available to new users. Please update your code to use models/gemini-3.6-flash for the latest features and improvements. We recommend you to use the Interactions API.',
+    },
     capability: 'mid',
     tier: 'sonnet',
   },
 
+  {
+    /*
+     * Google's own error message names this as the replacement for the two
+     * retired 2.5 models, and ai.google.dev/gemini-api/docs/pricing carries the
+     * rates, read 2026-08-28.
+     *
+     * The introductory price has a published end date and a published successor,
+     * which is exactly what `promo` is for and is the shape the catalogue nearly
+     * shipped Sonnet 5 wrong on: on 2027-01-01 every figure here doubles with no
+     * code change, and `pricing-review.test.js` fails before that arrives.
+     */
+    id: 'gemini-3.6-flash',
+    provider: 'google',
+    displayName: 'Gemini 3.6 Flash',
+    inputPerMTok: 1.5,
+    outputPerMTok: 7.5,
+    promo: { inputPerMTok: 0.75, outputPerMTok: 3.75, until: '2026-12-31' },
+    contextWindow: 1_048_576,
+    cacheMinTokens: 1024,
+    caching: 'explicit',
+    /*
+     * $0.075 against $0.75 inside the introductory window, and $0.15 against
+     * $1.50 after it: Google scales the cache price with the headline one, so
+     * a single ratio is right on both sides of 2027-01-01 and the multiplier
+     * does not need a date of its own.
+     */
+    multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: 0.5 },
+    capability: 'mid',
+    tier: 'sonnet',
+    notes:
+      'Context caching is billed for storage per hour as well as per read:'
+      + ' $0.50 per 1M tokens per hour through 2026-12-31, $1.00 after.',
+  },
+
   // ------------------------------------------------------------------------
   // Moonshot
   // ------------------------------------------------------------------------
@@ -286,9 +383,70 @@ export const MODELS: ModelPricing[] = [
     cacheMinTokens: 1024,
     caching: 'automatic',
     multipliers: { cacheRead: 0.1, cacheWrite5m: 1, cacheWrite1h: 1, batch: null },
+    /* Refused on 2026-08-28: the id itself is rejected, and the error names the survivors. */
+    retired: {
+      on: '2026-08-28',
+      because:
+        'The supported API model names are deepseek-v4-pro, deepseek-v4-flash, and deepseek-v4-flash-vision-exp, but you passed deepseek-v3.',
+    },
     capability: 'mid',
     tier: 'sonnet',
   },
+  {
+    /*
+     * DeepSeek V4 Flash, from api-docs.deepseek.com/quick_start/pricing, read
+     * 2026-08-28. It replaced `deepseek-v3`, which the API now refuses.
+     *
+     * The base rate is off-peak because off-peak is the common case: peak is
+     * 01:00-04:00 and 06:00-10:00 UTC on weekdays, which is 35 hours of 168.
+     * The peak tier is exactly double, published as such.
+     */
+    id: 'deepseek-v4-flash',
+    provider: 'deepseek',
+    displayName: 'DeepSeek V4 Flash',
+    inputPerMTok: 0.22,
+    outputPerMTok: 0.66,
+    tiers: [
+      {
+        id: 'peak',
+        when: { kind: 'utc-hours', hours: [1, 2, 3, 6, 7, 8, 9], weekdaysOnly: true },
+        inputPerMTok: 0.44,
+        outputPerMTok: 1.32,
+      },
+    ],
+    contextWindow: 1_000_000,
+    cacheMinTokens: 1024,
+    caching: 'automatic',
+    /* $0.007 cache hit against $0.22 input off-peak. */
+    multipliers: { cacheRead: 0.0318, cacheWrite5m: 1, cacheWrite1h: 1, batch: null },
+    capability: 'mid',
+    tier: 'sonnet',
+    notes: 'Maximum output 384K tokens.',
+  },
+  {
+    /* Same page, same clock. Pro is three times Flash at both ends. */
+    id: 'deepseek-v4-pro',
+    provider: 'deepseek',
+    displayName: 'DeepSeek V4 Pro',
+    inputPerMTok: 0.66,
+    outputPerMTok: 1.98,
+    tiers: [
+      {
+        id: 'peak',
+        when: { kind: 'utc-hours', hours: [1, 2, 3, 6, 7, 8, 9], weekdaysOnly: true },
+        inputPerMTok: 1.32,
+        outputPerMTok: 3.96,
+      },
+    ],
+    contextWindow: 1_000_000,
+    cacheMinTokens: 1024,
+    caching: 'automatic',
+    /* $0.022 cache hit against $0.66 input off-peak. */
+    multipliers: { cacheRead: 0.0333, cacheWrite5m: 1, cacheWrite1h: 1, batch: null },
+    capability: 'large',
+    tier: 'opus',
+    notes: 'Maximum output 384K tokens.',
+  },
 
   // ------------------------------------------------------------------------
   // xAI
@@ -320,10 +478,89 @@ export const MODELS: ModelPricing[] = [
     cacheMinTokens: 0,
     caching: 'none',
     multipliers: { batch: 0.5 },
+    /* Refused on 2026-08-28: the id itself is rejected. */
+    retired: {
+      on: '2026-08-28',
+      because:
+        'Invalid model: mistral-large-2',
+    },
+    capability: 'large',
+    tier: 'opus',
+    notes: 'No prompt caching: reordering still helps readability but saves nothing here.',
+  },
+  {
+    /*
+     * Mistral Large 3, the replacement for the refused `mistral-large-2`.
+     *
+     * **Read by a human from `mistral.ai/pricing` on 2026-08-28, and that is the
+     * provenance.** The page renders its table in the browser, so a fetch sees
+     * only an FAQ example with no model id attached: this repository looked,
+     * found nothing servable, left the model unpriced and said so, and the table
+     * was then read off the page and handed over. A price is a reading of the
+     * provider's page; who did the reading is a fact about the reading, not a
+     * reason to accept a worse source.
+     *
+     * The identity is measured rather than inferred. `GET /v1/models` declares
+     * `mistral-large-latest` and `mistral-large-2512` as aliases of each other,
+     * both reporting the name `mistral-large-2512` and a 262,144 context, so the
+     * dated id is what a usage log carries and the moving pointer is the alias.
+     */
+    id: 'mistral-large-2512',
+    aliases: ['mistral-large-latest'],
+    provider: 'mistral',
+    displayName: 'Mistral Large 3',
+    inputPerMTok: 0.5,
+    outputPerMTok: 1.5,
+    contextWindow: 262_144,
+    cacheMinTokens: 0,
+    caching: 'none',
+    multipliers: { batch: 0.5 },
     capability: 'large',
     tier: 'opus',
     notes: 'No prompt caching: reordering still helps readability but saves nothing here.',
   },
+  {
+    /*
+     * Same page, same day, same reading.
+     *
+     * **This provider's ladder is not monotonic in price, and that is not a
+     * typo.** Medium 3.5 costs three times Large 3 on input and five times on
+     * output, because Mistral positions Large as the open-weight flagship and
+     * Medium as the model for long-horizon agentic work. `capability` follows
+     * the vendor's own description rather than the price, which is what the
+     * field means; the consequence is that a step down from `large` to `mid`
+     * here is dearer, and `levers.ts` simply does not offer a route whose saving
+     * is not above zero. Nothing to fix, and worth saying so before somebody
+     * "corrects" the ladder into producing a saving that does not exist.
+     */
+    id: 'mistral-medium-2604',
+    aliases: ['mistral-medium-latest', 'mistral-medium-3-5'],
+    provider: 'mistral',
+    displayName: 'Mistral Medium 3.5',
+    inputPerMTok: 1.5,
+    outputPerMTok: 7.5,
+    contextWindow: 262_144,
+    cacheMinTokens: 0,
+    caching: 'none',
+    multipliers: { batch: 0.5 },
+    capability: 'mid',
+    tier: 'sonnet',
+  },
+  {
+    /* Same page, same day. `mistral-small-2603` is what the API reports. */
+    id: 'mistral-small-2603',
+    aliases: ['mistral-small-latest'],
+    provider: 'mistral',
+    displayName: 'Mistral Small 4',
+    inputPerMTok: 0.15,
+    outputPerMTok: 0.6,
+    contextWindow: 262_144,
+    cacheMinTokens: 0,
+    caching: 'none',
+    multipliers: { batch: 0.5 },
+    capability: 'small',
+    tier: 'haiku',
+  },
 ];
 
 export const DEFAULT_MODEL = 'claude-opus-5';
@@ -390,6 +627,28 @@ function makeCatalogue(
 /** The prices compiled into this release. */
 export const BUNDLED_CATALOGUE: PricingCatalogue = makeCatalogue(MODELS, PRICING_LAST_REVIEWED);
 
+/**
+ * Whether this model may be offered to a reader as something to move to.
+ *
+ * One home for a two-part rule that used to be written in four places as one
+ * part. `recommendable: false` — a private programme, a waitlist — was honoured
+ * at every one of them. `retired` is the stronger statement: the provider
+ * answered a real request for the id with an error, so a switch to it is not a
+ * worse recommendation, it is one that cannot be carried out at all.
+ *
+ * Written as a function rather than as a second `&&` at four call sites,
+ * because the fifth call site is always the one that gets written with only the
+ * first half. `pricing.test.js` fails a source file that filters on
+ * `recommendable` without coming through here, and that guard was proved by
+ * planting exactly that filter.
+ *
+ * Pricing is a separate question and stays answered: a retired model keeps its
+ * price, because a log full of its calls records money that was really spent.
+ */
+export function isOffered(model: ModelPricing): boolean {
+  return model.recommendable !== false && model.retired === undefined;
+}
+
 /** Looks a model up in a specific catalogue. */
 export function modelFrom(catalogue: PricingCatalogue, id: string): ModelPricing {
   const model = catalogue.byId.get(id);
@@ -422,7 +681,7 @@ export function cheapestOfTierIn(
   const candidates = catalogue.models.filter(
     (m) =>
       m.tier === tier &&
-      m.recommendable !== false &&
+      isOffered(m) &&
       (provider === undefined || m.provider === provider),
   );
   const first = candidates[0];
@@ -453,46 +712,172 @@ export function listModels(): ModelPricing[] {
  * possible answers; `on` still decides which answer applies on every call,
  * so behaviour is unchanged to the millisecond.
  */
+interface Rates {
+  inputPerMTok: number;
+  outputPerMTok: number;
+  promoApplied: boolean;
+  tier: { applied: string | null; decided: boolean; because: string } | null;
+}
+
 const pricingMemo = new WeakMap<
   ModelPricing,
-  {
-    untilMs: number | null;
-    promo: { inputPerMTok: number; outputPerMTok: number; promoApplied: boolean } | null;
-    base: { inputPerMTok: number; outputPerMTok: number; promoApplied: boolean };
-  }
+  { untilMs: number | null; promo: Rates | null; base: Rates }
 >();
 
+/** The two unconditional answers for one model, parsed once. */
+function cache(model: ModelPricing): {
+  untilMs: number | null;
+  promo: Rates | null;
+  base: Rates;
+} {
+  const entry = {
+    untilMs: model.promo ? new Date(`${model.promo.until}T23:59:59.999Z`).getTime() : null,
+    promo: model.promo
+      ? Object.freeze({
+          inputPerMTok: model.promo.inputPerMTok,
+          outputPerMTok: model.promo.outputPerMTok,
+          promoApplied: true,
+          tier: null,
+        })
+      : null,
+    base: Object.freeze({
+      inputPerMTok: model.inputPerMTok,
+      outputPerMTok: model.outputPerMTok,
+      promoApplied: false,
+      tier: null,
+    }),
+  };
+  pricingMemo.set(model, entry);
+  return entry;
+}
+
+/**
+ * Whether one condition holds, for a call at `on` of `inputTokens` tokens.
+ *
+ * Returns `null` rather than `false` when the condition cannot be decided,
+ * because "this does not apply" and "nobody said" lead to different reports and
+ * collapsing them is the oldest mistake in this repository.
+ */
+function holds(
+  when: TierCondition,
+  on: Date,
+  inputTokens: number | undefined,
+): boolean | null {
+  if (when.kind === 'utc-hours') {
+    const day = on.getUTCDay();
+    if (when.weekdaysOnly && (day === 0 || day === 6)) return false;
+    return when.hours.includes(on.getUTCHours());
+  }
+  if (inputTokens === undefined) return null;
+  return inputTokens > when.tokens;
+}
+
+/**
+ * What one call is billed at, and what decided it.
+ *
+ * `tier` is the field this grew for, and it carries three states rather than
+ * two. A model with no tiers gets `null`. A model whose condition could be
+ * evaluated gets the tier that applied, or the base rate with `applied: null`
+ * and `decided: true`. A model whose condition could **not** be evaluated —
+ * a size tier priced without a token count — gets `decided: false`, the
+ * **dearer** of the candidate rates, and `because` naming what would settle it.
+ *
+ * The dearer one is not a shrug. A cost figure that is a ceiling can prove
+ * "under budget" and can never surprise a bill; a floor chosen for looking
+ * better is the flattering direction this product spends its time refusing.
+ * The reader still has to be told, which is what `decided: false` is for, and
+ * `pricing.test.js` fails a tiered model whose report drops it.
+ */
 export function effectivePricing(
   model: ModelPricing,
   on: Date = new Date(),
-): { inputPerMTok: number; outputPerMTok: number; promoApplied: boolean } {
-  let memo = pricingMemo.get(model);
-  if (memo === undefined) {
-    memo = {
-      untilMs: model.promo ? new Date(`${model.promo.until}T23:59:59.999Z`).getTime() : null,
-      promo: model.promo
+  context: { inputTokens?: number } = {},
+): Rates {
+  const memo = pricingMemo.get(model) ?? cache(model);
+
+  /**
+   * Tiers first, and a promotion never runs on top of one.
+   *
+   * No provider here does both, and combining them would be this repository
+   * inventing a price out of two real ones — the composed figure the first rule
+   * in the doctrine is about. A model that grew both would fail the guard in
+   * `pricing.test.js` rather than quietly getting a multiplied rate.
+   */
+  if (model.tiers !== undefined && model.tiers.length > 0) {
+    const undecided: PricingTier[] = [];
+    for (const tier of model.tiers) {
+      const verdict = holds(tier.when, on, context.inputTokens);
+      if (verdict === true) {
+        return {
+          inputPerMTok: tier.inputPerMTok,
+          outputPerMTok: tier.outputPerMTok,
+          promoApplied: false,
+          tier: { applied: tier.id, decided: true, because: describe(tier.when) },
+        };
+      }
+      if (verdict === null) undecided.push(tier);
+    }
+
+    if (undecided.length === 0) {
+      return {
+        ...memo.base,
+        tier: { applied: null, decided: true, because: 'no conditional rate applies' },
+      };
+    }
+
+    /* The dearest candidate, so the figure is a ceiling rather than a wish. */
+    const dearest = undecided.reduce((worst, tier) =>
+      tier.inputPerMTok > worst.inputPerMTok ? tier : worst,
+    );
+    const ceiling =
+      dearest.inputPerMTok > model.inputPerMTok
         ? {
-            inputPerMTok: model.promo.inputPerMTok,
-            outputPerMTok: model.promo.outputPerMTok,
-            promoApplied: true,
+            inputPerMTok: dearest.inputPerMTok,
+            outputPerMTok: dearest.outputPerMTok,
+            applied: dearest.id,
           }
-        : null,
-      base: Object.freeze({
-        inputPerMTok: model.inputPerMTok,
-        outputPerMTok: model.outputPerMTok,
-        promoApplied: false,
-      }),
+        : {
+            inputPerMTok: model.inputPerMTok,
+            outputPerMTok: model.outputPerMTok,
+            applied: null,
+          };
+    return {
+      inputPerMTok: ceiling.inputPerMTok,
+      outputPerMTok: ceiling.outputPerMTok,
+      promoApplied: false,
+      tier: {
+        applied: ceiling.applied,
+        decided: false,
+        because: `${describe(dearest.when)}, and the token count was not given`,
+      },
     };
-    if (memo.promo) Object.freeze(memo.promo);
-    pricingMemo.set(model, memo);
   }
+
   if (memo.untilMs !== null && on.getTime() <= memo.untilMs) return memo.promo!;
   return memo.base;
 }
 
+/** One condition as a sentence a reader can check against a provider's page. */
+function describe(when: TierCondition): string {
+  if (when.kind === 'input-tokens-above') {
+    return `prompts over ${when.tokens.toLocaleString('en-US')} input tokens`;
+  }
+  const windows = [];
+  let start = null;
+  const sorted = [...when.hours].sort((a, b) => a - b);
+  for (let i = 0; i < sorted.length; i += 1) {
+    if (start === null) start = sorted[i]!;
+    if (sorted[i]! + 1 !== sorted[i + 1]) {
+      windows.push(`${String(start).padStart(2, '0')}:00-${String(sorted[i]! + 1).padStart(2, '0')}:00`);
+      start = null;
+    }
+  }
+  return `${windows.join(' and ')} UTC${when.weekdaysOnly ? ', Monday to Friday' : ''}`;
+}
+
 /** 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 candidates = MODELS.filter((m) => m.tier === tier && isOffered(m));
   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);
@@ -514,6 +899,21 @@ export function cheapestOfTier(tier: ModelPricing['tier']): ModelPricing {
  * a date — an overlay supplies this string, and a wrong one should read as
  * unknown rather than as a confident number computed from `NaN`.
  */
+/**
+ * The age at which this product stops treating its own price table as current.
+ *
+ * Three surfaces warn a reader that the figures above may be off — `profile`,
+ * the MCP report, the browser's bill — and each of them had typed `45` into
+ * its own comparison, with four locale sentences stating it again in prose.
+ * Seven copies of one claim, and nothing that would notice when they
+ * disagreed; the sentence a reader sees names the number, so a drift between
+ * them would have been a surface telling the reader one threshold and applying
+ * another.
+ *
+ * The value is what those surfaces already published, not a new judgement.
+ */
+export const STALE_PRICING_DAYS = 45;
+
 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`);