@molecule/api-resource-ai-models 1.0.2 → 1.2.0

package/dist/lookup.js

@@ -4,21 +4,57 @@
  * @module
  */
 import { MODELS } from './models.js';
+/**
+ * Whether a model may be offered for selection: not `disabled` (retired
+ * upstream) and not `supersededBy` a newer generation of its own family. Both
+ * kinds stay in the catalog for pricing — this predicate is the single place
+ * that decides *exposure*, so every listing/validation surface agrees.
+ *
+ * @param model - The model definition (or the two flags from one).
+ * @returns True when the model may be listed and chosen.
+ */
+export function isSelectableModel(model) {
+    return !model.disabled && !model.supersededBy;
+}
+/**
+ * Resolve a model id FORWARD to the selectable model that replaces it, following
+ * the {@link ModelDefinition.supersededBy} chain (a saved `qwen3.7-max` →
+ * `qwen3.8-max`). Lets a persisted selection keep the user's intent — the same
+ * tier from the same provider — instead of falling back to the platform default
+ * once the older generation stops being offered.
+ *
+ * @param id - The persisted model id.
+ * @returns The selectable successor's id, the id itself when it is already
+ *   selectable, or `undefined` for an unknown or `disabled` model (nothing to
+ *   forward to).
+ */
+export function resolveSelectableModelId(id) {
+    let model = getModel(id);
+    // Bounded by the catalog size: a supersession cycle would otherwise spin here,
+    // and the invariant that forbids one is a test, not a runtime guarantee.
+    for (let hops = 0; model && !isSelectableModel(model) && hops <= MODELS.length; hops++) {
+        if (!model.supersededBy)
+            return undefined; // disabled — no successor declared
+        model = getModel(model.supersededBy);
+    }
+    return model && isSelectableModel(model) ? model.id : undefined;
+}
 /**
  * Set of *selectable* model IDs for fast validation.
  *
  * Excludes `disabled` models so a retired model (e.g. `grok-code-fast-1`) can
- * never be chosen for a new chat, while {@link getModel} still resolves it for
- * historical pricing.
+ * never be chosen for a new chat, and `supersededBy` models so an older
+ * generation of a family (e.g. `qwen3.7-max` next to `qwen3.8-max`) is never
+ * offered — while {@link getModel} still resolves both for historical pricing.
  */
-export const MODEL_IDS = new Set(MODELS.filter((m) => !m.disabled).map((m) => m.id));
+export const MODEL_IDS = new Set(MODELS.filter(isSelectableModel).map((m) => m.id));
 /**
  * Look up a model definition by ID.
  *
- * Returns `disabled` models too: a saved selection or a historical usage row
- * may reference a since-retired model, and it must stay priceable. Use
- * {@link MODEL_IDS} / {@link getAvailableModels} (which exclude disabled
- * models) to decide what is *selectable*.
+ * Returns `disabled` and `supersededBy` models too: a saved selection or a
+ * historical usage row may reference a since-retired or since-superseded model,
+ * and it must stay priceable. Use {@link MODEL_IDS} / {@link getAvailableModels}
+ * (or {@link isSelectableModel}) to decide what is *selectable*.
  *
  * @param id - The API model ID.
  * @returns The model definition, or `undefined` if not found.
@@ -39,29 +75,137 @@ export function getModelsByProvider(provider) {
  * Get models that are currently usable — filtered to only providers that are available.
  *
  * The caller passes in which provider IDs are active (i.e. have a bond wired).
- * `disabled` models are excluded — they are never offered for selection.
+ * Models that are not {@link isSelectableModel} — `disabled` or superseded by a
+ * newer generation — are excluded; they are never offered for selection.
  *
  * @param availableProviders - Set or array of provider IDs that have active bonds.
- * @returns Non-disabled models whose provider is in the available set.
+ * @returns Selectable models whose provider is in the available set.
  */
 export function getAvailableModels(availableProviders) {
     const providerSet = availableProviders instanceof Set ? availableProviders : new Set(availableProviders);
-    return MODELS.filter((m) => providerSet.has(m.provider) && !m.disabled);
+    return MODELS.filter((m) => providerSet.has(m.provider) && isSelectableModel(m));
 }
 /**
- * The price multiplier in effect for a model at a given instant.
+ * Whether a model's staged {@link ModelDefinition.scheduledPricing} change has
+ * taken effect at a given instant.
+ *
+ * @param modelDef - The model definition.
+ * @param at - The instant to evaluate.
+ * @returns `true` once `at` is at or past the scheduled `effectiveFrom`.
+ */
+function scheduledPricingApplies(modelDef, at) {
+    const scheduled = modelDef.scheduledPricing;
+    if (!scheduled)
+        return false;
+    const effectiveFrom = Date.parse(scheduled.effectiveFrom);
+    // An unparseable date must never silently reprice a model. Ignoring the
+    // staged entry keeps the current, verified rates in force.
+    if (Number.isNaN(effectiveFrom))
+        return false;
+    return at.getTime() >= effectiveFrom;
+}
+/**
+ * A model's BASE token rates in effect at a given instant — the staged
+ * {@link ModelDefinition.scheduledPricing} rates once their `effectiveFrom` has
+ * passed, else the base fields.
+ *
+ * These are the native provider's rates. A `regionPricing` override is a
+ * different host's rate card and is resolved separately by
+ * {@link modelRegionRates}.
+ *
+ * @param modelDef - The model definition.
+ * @param at - The instant to price at (defaults to now).
+ * @returns The base rates in effect at that instant.
+ */
+export function effectiveBaseRates(modelDef, at = new Date()) {
+    const scheduled = modelDef.scheduledPricing;
+    if (scheduled && scheduledPricingApplies(modelDef, at)) {
+        return {
+            inputPricePerMTok: scheduled.inputPricePerMTok,
+            outputPricePerMTok: scheduled.outputPricePerMTok,
+            cacheReadPricePerMTok: scheduled.cacheReadPricePerMTok,
+            cacheWritePricePerMTok: scheduled.cacheWritePricePerMTok,
+        };
+    }
+    return {
+        inputPricePerMTok: modelDef.inputPricePerMTok,
+        outputPricePerMTok: modelDef.outputPricePerMTok,
+        cacheReadPricePerMTok: modelDef.cacheReadPricePerMTok,
+        cacheWritePricePerMTok: modelDef.cacheWritePricePerMTok,
+    };
+}
+/**
+ * A model's peak-hour pricing in effect at a given instant: the staged
+ * {@link ModelDefinition.scheduledPricing} `peakPricing` once its
+ * `effectiveFrom` has passed (when that entry declares one — an omitted one
+ * leaves the existing windows in force), else the model's own `peakPricing`.
+ *
+ * @param modelDef - The model definition.
+ * @param at - The instant to evaluate (defaults to now).
+ * @returns The peak-pricing config in effect, or `undefined` when none is.
+ */
+export function effectivePeakPricing(modelDef, at = new Date()) {
+    const scheduled = modelDef.scheduledPricing;
+    if (scheduled?.peakPricing && scheduledPricingApplies(modelDef, at)) {
+        return scheduled.peakPricing;
+    }
+    return modelDef.peakPricing;
+}
+/**
+ * A model projected onto the pricing in effect at a given instant: the staged
+ * {@link ModelDefinition.scheduledPricing} rates folded into the base fields
+ * (and its peak windows into `peakPricing`) once effective, with the staged
+ * entry stripped.
+ *
+ * This is what the `GET /ai/models` handler serves, so a client renders the
+ * rates that are actually billing right now without needing to resolve a
+ * schedule against its own clock — the server's clock is the only one that
+ * decides when a price change lands.
+ *
+ * @param modelDef - The model definition.
+ * @param at - The instant to project at (defaults to now).
+ * @returns The model with effective pricing and no `scheduledPricing`.
+ */
+export function withEffectivePricing(modelDef, at = new Date()) {
+    if (!modelDef.scheduledPricing)
+        return modelDef;
+    const { scheduledPricing: _scheduledPricing, ...rest } = modelDef;
+    const peakPricing = effectivePeakPricing(modelDef, at);
+    return {
+        ...rest,
+        ...effectiveBaseRates(modelDef, at),
+        ...(peakPricing ? { peakPricing } : {}),
+    };
+}
+/**
+ * The price multiplier in effect for a model at a given instant, in a region.
  *
  * Consults the model's {@link ModelDefinition.peakPricing} windows (UTC,
  * half-open, may wrap midnight). Metering MUST call this with each request's
  * own timestamp so peak-hour usage bills at the provider's real rate — pricing
  * everything at the flat rate silently under-meters peak traffic.
  *
+ * Peak windows belong to the NATIVE provider, so they apply only where the base
+ * rates do. A region with a {@link ModelDefinition.regionPricing} override is a
+ * different host billing its own complete rate card, including whether it has
+ * time-of-day pricing at all — and re-hosts generally do not. Applying the
+ * native provider's surcharge on top of a re-host's flat rates would over-bill
+ * every turn in its windows (DeepSeek's 2× Beijing-hours pricing charged
+ * against DeepInfra, which has no peak pricing).
+ *
  * @param modelDef - The model definition (or undefined).
  * @param at - The instant the request was made.
- * @returns The multiplier (`1` outside peak windows or when none are declared).
+ * @param region - The user's per-model region choice, if any (omitted → the
+ *   model's default region).
+ * @returns The multiplier (`1` outside peak windows, when none are declared, or
+ *   in a region that prices off its own override).
  */
-export function priceMultiplierAt(modelDef, at) {
-    const peak = modelDef?.peakPricing;
+export function priceMultiplierAt(modelDef, at, region) {
+    if (!modelDef)
+        return 1;
+    if (modelDef.regionPricing?.[effectiveModelRegion(modelDef, region)])
+        return 1;
+    const peak = effectivePeakPricing(modelDef, at);
     if (!peak || peak.windows.length === 0)
         return 1;
     const minute = at.getUTCHours() * 60 + at.getUTCMinutes();
@@ -92,25 +236,28 @@ export function effectiveModelRegion(modelDef, requested) {
 /**
  * The token rates for a model in a given processing region: the model's
  * {@link ModelDefinition.regionPricing} override for the region when one
- * exists, else the base rates (the native provider's list prices). Omitted
- * cache fields in an override fall back to the override's input price (hosts
- * with no cache discount / no write premium). The region is resolved via
- * {@link effectiveModelRegion}, so callers may pass the raw user choice.
+ * exists, else the base rates in effect at `at` (the native provider's list
+ * prices, including any staged {@link ModelDefinition.scheduledPricing} change
+ * that has landed). Omitted cache fields in an override fall back to the
+ * override's input price (hosts with no cache discount / no write premium). The
+ * region is resolved via {@link effectiveModelRegion}, so callers may pass the
+ * raw user choice.
+ *
+ * `at` defaults to NOW rather than being required, so an existing caller cannot
+ * keep billing a superseded rate by omitting it — metering should still pass
+ * each request's own timestamp, the same way it must for
+ * {@link priceMultiplierAt}.
  *
  * @param modelDef - The model definition.
  * @param requested - The user's per-model region choice, if any.
+ * @param at - The instant to price at (defaults to now).
  * @returns The region-effective rates.
  */
-export function modelRegionRates(modelDef, requested) {
+export function modelRegionRates(modelDef, requested, at = new Date()) {
     const region = effectiveModelRegion(modelDef, requested);
     const override = modelDef.regionPricing?.[region];
     if (!override) {
-        return {
-            inputPricePerMTok: modelDef.inputPricePerMTok,
-            outputPricePerMTok: modelDef.outputPricePerMTok,
-            cacheReadPricePerMTok: modelDef.cacheReadPricePerMTok,
-            cacheWritePricePerMTok: modelDef.cacheWritePricePerMTok,
-        };
+        return effectiveBaseRates(modelDef, at);
     }
     return {
         inputPricePerMTok: override.inputPricePerMTok,

package/dist/models.d.ts

@@ -28,6 +28,18 @@ import type { ModelDefinition } from './types.js';
  *   control) carries `thinkingConfigurable: false` and OMITS both fields —
  *   there is nothing to tune.
  *
+ * ONE GENERATION PER FAMILY. When a provider ships a newer generation of a
+ * model line, the older entry gets `supersededBy: '<newer id>'` and stops being
+ * offered — the picker never shows both `qwen3.7-max` and `qwen3.8-max`. The
+ * entry is NEVER deleted: `getModel()` still resolves it so saved selections and
+ * historical usage stay priceable, and a persisted id resolves forward to the
+ * successor. Supersede only within the same TIER: a cheaper or specialist model
+ * with no newer equivalent (`gemini-3.1-pro-preview`, `qwen3-coder-plus`,
+ * `kimi-k2.7-code`, `grok-build-0.1`) keeps at most `deprecatedAt`, so every
+ * provider keeps a real choice. `__tests__/lookup.test.ts` fails on any two
+ * selectable models of one family at different versions that aren't a
+ * documented exception.
+ *
  * Sources (verified 2026-07-28; OpenAI re-verified 2026-07-31 after the
  * 2026-07-30 GPT-5.6 repricing — cross-check prices against models.dev with
  * `npm run check:model-freshness` from the workspace root):
@@ -49,21 +61,31 @@ import type { ModelDefinition } from './types.js';
  *   2026-07-21 $1.50/$7.50 supersedes 3.5-flash as the agentic flagship;
  *   gemini-3.1-pro-preview still the pro tier — "3.5 Pro" has NOT shipped as
  *   of 2026-07-28 despite the coming-soon badge; do not add until it has an id)
+ *   (re-verified 2026-08-13: gemini-3.7-flash "New Stable" — supersedes
+ *   3.6-flash as the flash flagship at the SAME list price ($1.50/$7.50, cache
+ *   read $0.15), with a launch promo ($0.75/$3.75, cache read $0.075) through
+ *   2026-12-31 billed here at list; specs from /docs/models/gemini-3.7-flash:
+ *   1M ctx / 65,536 out, thinking low|medium|high (no minimal), vision, tools,
+ *   caching, search grounding, code execution, url context)
  * - xAI: https://docs.x.ai/developers/models + /developers/grok-4-5
  *   (grok-4.5 flagship 2026-07-08: $2/$6, 500K ctx, ≥200K prompts bill 2× —
  *   not modeled; reasoning_effort low|medium|high default high, image input;
  *   grok-4.3 still served at $1.25/$2.50 with the bigger 1M window;
  *   grok-code-fast-1 no longer listed — retires 2026-08-15)
- * - DeepSeek: https://api-docs.deepseek.com/quick_start/pricing (unchanged V4
- *   Pro/Flash pricing; legacy deepseek-chat/-reasoner ids fully retired
- *   2026-07-24 — never in this catalog; the announced peak-hour 2× surcharge is
- *   still NOT active as of 2026-07-28, see the entries)
- * - Moonshot: https://platform.kimi.ai/docs/models (kimi-k3 flagship 2026-07-16
+ * - DeepSeek: https://api-docs.deepseek.com/quick_start/pricing (verified
+ *   2026-08-14; legacy deepseek-chat/-reasoner ids fully retired 2026-07-24 —
+ *   never in this catalog. V4-Pro GA on 2026-08-13 came with a price RISE
+ *   effective 2026-08-16T16:00Z plus the long-announced peak-hour 2×: both
+ *   entries carry it as `scheduledPricing`, so today's rates bill until that
+ *   instant and the new ones after. Re-verify weekday-vs-daily peak windows and
+ *   the CN/US region default once it lands — see the entries.)
+ * - Moonshot: https://platform.kimi.ai/docs/models + DeepInfra's model API for
+ *   the US re-host (kimi-k3 flagship 2026-07-16
  *   — 2.8T MoE, 1M ctx, $3/$15 — NOT added: thinking is forced-on with
  *   reasoning_content that must be replayed through tool loops, the same
- *   constraint that keeps kimi-k2.7-code out; add BOTH once the moonshot bond
- *   supports preserved thinking + reasoning_effort low|high|max. kimi-k2.6
- *   remains the newest model the bond can run correctly.)
+ *   constraint that kept kimi-k2.7-code out. BOTH are now in the catalog: the
+ *   moonshot bond gained preserved thinking (reasoning replayed through tool
+ *   loops), so kimi-k3 is the Moonshot pick.)
  * - MiniMax: https://platform.minimax.io/docs/guides/pricing-paygo (unchanged;
  *   minimax-m3 $0.30/$1.20 is a "permanent 50% off" list rate)
  * - Alibaba: https://www.alibabacloud.com/help/en/model-studio/deep-thinking

package/dist/models.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,eAAe,EAmtCnC,CAAA"}
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,eAAe,EA+5CnC,CAAA"}