ai-functions 2.1.3 → 2.3.0

package/dist/middleware/budget.d.ts

@@ -0,0 +1,84 @@
+/**
+ * budgetMiddleware — record token usage + cost into a {@link BudgetTracker}
+ *
+ * Replaces the post-hoc duck-typing in
+ * `services-as-software/src/v3/invoke/cost-estimate.ts` with a single
+ * AI-SDK-6 middleware: on `doGenerate` / `doStream` completion, read the
+ * `LanguageModelV3Usage` shape directly off the result and call
+ * `tracker.recordUsage(...)`. The pricing overlay is supplied via
+ * `customPricing` on the {@link BudgetTracker} (or we hand the tracker the
+ * pricing at construction time when the caller wants per-call isolation).
+ *
+ * Key V3 → BudgetTracker mapping detail: AI SDK 6 reports
+ * `usage.inputTokens.total` / `usage.outputTokens.total` as
+ * `number | undefined`. We coerce undefined → 0 so partial-streaming results
+ * (where the upstream provider didn't emit token counts) don't blow up the
+ * tracker. The `inputTokens.cacheRead` / `inputTokens.cacheWrite` breakdown
+ * is *not* propagated yet — round 13+ work to add prompt-cache awareness to
+ * BudgetTracker.
+ *
+ * Composition note: install **after** cache (so a cache hit still records
+ * the cost — the wrapped result is the same regardless of which layer
+ * served it) and **before** trace (so the trace event sees the final
+ * computed cost via the tracker).
+ *
+ * @packageDocumentation
+ */
+import type { LanguageModelV3GenerateResult, LanguageModelV3Middleware } from '@ai-sdk/provider';
+import type { BudgetTracker, ModelPricing } from '../budget.js';
+/**
+ * Pricing overlay supplied to the middleware. Mirrors the
+ * `BudgetConfig.customPricing` shape — keyed on model id, value is the
+ * per-million USD rate. Sourced (in services-as-software) from the
+ * `language-models/data/models.json` catalog so Llama / DeepSeek / Mistral /
+ * Qwen / Grok / Perplexity Sonar all get their real per-token rate.
+ */
+export type PricingOverlay = Record<string, ModelPricing>;
+/** Options for {@link budgetMiddleware}. */
+export interface BudgetMiddlewareOptions {
+    /**
+     * The {@link BudgetTracker} to record usage into. Required — the
+     * middleware never constructs its own tracker (the tracker holds budget
+     * limits + alert callbacks, which the caller owns).
+     */
+    tracker: BudgetTracker;
+    /**
+     * Pricing overlay (per-model rates). When supplied, takes precedence over
+     * the BudgetTracker's own default pricing for any matching model id. Pass
+     * the language-models catalog overlay here to extend pricing without
+     * mutating the tracker.
+     */
+    pricing?: PricingOverlay;
+    /**
+     * Optional override for the model id reported to the tracker. Defaults to
+     * `model.modelId` (the wrapped model's underlying id). Pass an alias
+     * (`'sonnet'`, `'opus'`) to bridge to the alias-based pricing tables.
+     */
+    modelIdOverride?: string;
+}
+/**
+ * Build a budget middleware for `wrapLanguageModel`. Records
+ * {@link LanguageModelV3Usage} into the supplied {@link BudgetTracker} on
+ * every successful `doGenerate` / `doStream` completion. Errors from the
+ * downstream model propagate unchanged — the tracker is only updated on
+ * success.
+ *
+ * For streaming calls, we accumulate the final `usage` from the `'finish'`
+ * stream part (per the V3 spec, the final `'finish'` event carries the
+ * authoritative usage shape) and record once on stream end.
+ *
+ * @example
+ * ```ts
+ * import { wrapLanguageModel } from 'ai'
+ * import { BudgetTracker, budgetMiddleware } from 'ai-functions'
+ *
+ * const tracker = new BudgetTracker({ maxCost: 1.0 })
+ * const model = wrapLanguageModel({
+ *   model: openai('gpt-4o'),
+ *   middleware: budgetMiddleware({ tracker }),
+ * })
+ * ```
+ */
+export declare function budgetMiddleware(options: BudgetMiddlewareOptions): LanguageModelV3Middleware;
+export type { LanguageModelV3GenerateResult };
+//# sourceMappingURL=budget.d.ts.map

package/dist/middleware/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/middleware/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EACV,6BAA6B,EAC7B,yBAAyB,EAI1B,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAM/D;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;AAEzD,4CAA4C;AAC5C,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,OAAO,EAAE,aAAa,CAAA;IACtB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,cAAc,CAAA;IACxB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAuCD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,yBAAyB,CAkC5F;AAID,YAAY,EAAE,6BAA6B,EAAE,CAAA"}

package/dist/middleware/budget.js

@@ -0,0 +1,110 @@
+/**
+ * budgetMiddleware — record token usage + cost into a {@link BudgetTracker}
+ *
+ * Replaces the post-hoc duck-typing in
+ * `services-as-software/src/v3/invoke/cost-estimate.ts` with a single
+ * AI-SDK-6 middleware: on `doGenerate` / `doStream` completion, read the
+ * `LanguageModelV3Usage` shape directly off the result and call
+ * `tracker.recordUsage(...)`. The pricing overlay is supplied via
+ * `customPricing` on the {@link BudgetTracker} (or we hand the tracker the
+ * pricing at construction time when the caller wants per-call isolation).
+ *
+ * Key V3 → BudgetTracker mapping detail: AI SDK 6 reports
+ * `usage.inputTokens.total` / `usage.outputTokens.total` as
+ * `number | undefined`. We coerce undefined → 0 so partial-streaming results
+ * (where the upstream provider didn't emit token counts) don't blow up the
+ * tracker. The `inputTokens.cacheRead` / `inputTokens.cacheWrite` breakdown
+ * is *not* propagated yet — round 13+ work to add prompt-cache awareness to
+ * BudgetTracker.
+ *
+ * Composition note: install **after** cache (so a cache hit still records
+ * the cost — the wrapped result is the same regardless of which layer
+ * served it) and **before** trace (so the trace event sees the final
+ * computed cost via the tracker).
+ *
+ * @packageDocumentation
+ */
+// ============================================================================
+// Helpers
+// ============================================================================
+function coerceUsage(usage) {
+    if (!usage)
+        return { inputTokens: 0, outputTokens: 0 };
+    return {
+        inputTokens: usage.inputTokens?.total ?? 0,
+        outputTokens: usage.outputTokens?.total ?? 0,
+    };
+}
+function record(tracker, pricing, modelId, usage) {
+    const { inputTokens, outputTokens } = coerceUsage(usage);
+    if (inputTokens === 0 && outputTokens === 0)
+        return;
+    // The pricing overlay is wired in via the tracker's `customPricing`
+    // already (set at BudgetTracker construction time by the caller). When
+    // the caller wants per-call pricing override, they install
+    // `pricing[modelId]` ahead of time. We expose `pricing` here as a
+    // forward-looking hook so we can later add per-call pricing without a
+    // breaking change.
+    void pricing;
+    tracker.recordUsage({ inputTokens, outputTokens, model: modelId });
+}
+// ============================================================================
+// Middleware
+// ============================================================================
+/**
+ * Build a budget middleware for `wrapLanguageModel`. Records
+ * {@link LanguageModelV3Usage} into the supplied {@link BudgetTracker} on
+ * every successful `doGenerate` / `doStream` completion. Errors from the
+ * downstream model propagate unchanged — the tracker is only updated on
+ * success.
+ *
+ * For streaming calls, we accumulate the final `usage` from the `'finish'`
+ * stream part (per the V3 spec, the final `'finish'` event carries the
+ * authoritative usage shape) and record once on stream end.
+ *
+ * @example
+ * ```ts
+ * import { wrapLanguageModel } from 'ai'
+ * import { BudgetTracker, budgetMiddleware } from 'ai-functions'
+ *
+ * const tracker = new BudgetTracker({ maxCost: 1.0 })
+ * const model = wrapLanguageModel({
+ *   model: openai('gpt-4o'),
+ *   middleware: budgetMiddleware({ tracker }),
+ * })
+ * ```
+ */
+export function budgetMiddleware(options) {
+    const { tracker, pricing, modelIdOverride } = options;
+    return {
+        specificationVersion: 'v3',
+        async wrapGenerate({ doGenerate, model }) {
+            const result = await doGenerate();
+            const modelId = modelIdOverride ?? model.modelId;
+            record(tracker, pricing, modelId, result.usage);
+            return result;
+        },
+        async wrapStream({ doStream, model }) {
+            const result = await doStream();
+            const modelId = modelIdOverride ?? model.modelId;
+            let finalUsage;
+            const transformedStream = result.stream.pipeThrough(new TransformStream({
+                transform(chunk, controller) {
+                    if (chunk.type === 'finish') {
+                        finalUsage = chunk.usage;
+                    }
+                    controller.enqueue(chunk);
+                },
+                flush() {
+                    record(tracker, pricing, modelId, finalUsage);
+                },
+            }));
+            const wrapped = {
+                ...result,
+                stream: transformedStream,
+            };
+            return wrapped;
+        },
+    };
+}
+//# sourceMappingURL=budget.js.map

package/dist/middleware/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../src/middleware/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AA+CH,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E,SAAS,WAAW,CAAC,KAAuC;IAI1D,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAA;IACtD,OAAO;QACL,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC;QAC1C,YAAY,EAAE,KAAK,CAAC,YAAY,EAAE,KAAK,IAAI,CAAC;KAC7C,CAAA;AACH,CAAC;AAED,SAAS,MAAM,CACb,OAAsB,EACtB,OAAmC,EACnC,OAAe,EACf,KAAuC;IAEvC,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,CAAA;IACxD,IAAI,WAAW,KAAK,CAAC,IAAI,YAAY,KAAK,CAAC;QAAE,OAAM;IACnD,oEAAoE;IACpE,uEAAuE;IACvE,2DAA2D;IAC3D,kEAAkE;IAClE,sEAAsE;IACtE,mBAAmB;IACnB,KAAK,OAAO,CAAA;IACZ,OAAO,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAA;AACpE,CAAC;AAED,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgC;IAC/D,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,OAAO,CAAA;IACrD,OAAO;QACL,oBAAoB,EAAE,IAAI;QAC1B,KAAK,CAAC,YAAY,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE;YACtC,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAA;YACjC,MAAM,OAAO,GAAG,eAAe,IAAI,KAAK,CAAC,OAAO,CAAA;YAChD,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAA;YAC/C,OAAO,MAAM,CAAA;QACf,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE;YAClC,MAAM,MAAM,GAAG,MAAM,QAAQ,EAAE,CAAA;YAC/B,MAAM,OAAO,GAAG,eAAe,IAAI,KAAK,CAAC,OAAO,CAAA;YAChD,IAAI,UAA4C,CAAA;YAChD,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CACjD,IAAI,eAAe,CAAuD;gBACxE,SAAS,CAAC,KAAK,EAAE,UAAU;oBACzB,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;wBAC5B,UAAU,GAAG,KAAK,CAAC,KAAK,CAAA;oBAC1B,CAAC;oBACD,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;gBAC3B,CAAC;gBACD,KAAK;oBACH,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,CAAA;gBAC/C,CAAC;aACF,CAAC,CACH,CAAA;YACD,MAAM,OAAO,GAAgC;gBAC3C,GAAG,MAAM;gBACT,MAAM,EAAE,iBAAiB;aAC1B,CAAA;YACD,OAAO,OAAO,CAAA;QAChB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/middleware/cache.d.ts

@@ -0,0 +1,103 @@
+/**
+ * cacheMiddleware — content-addressable cache for `wrapLanguageModel`
+ *
+ * Implements the AI SDK cookbook's local-caching-middleware pattern
+ * (https://ai-sdk.dev/cookbook/node/local-caching-middleware) on top of the
+ * AI SDK 6 `LanguageModelV3Middleware` shape:
+ *
+ * - **Hit derivation:** content-hash of `{ prompt, modelId, responseFormat }`
+ *   so a schema change (responseFormat.type === 'json' carries a `schema`
+ *   JSONSchema7) invalidates the entry. Generation parameters (temperature,
+ *   topP, etc.) are deliberately *not* part of the key for the eval-fixture
+ *   use case — flipping temperature shouldn't blow up a 5x verify-time win.
+ *   Callers who want strict keying should pass a custom `keyHash`.
+ *
+ * - **Stream support:** cached entries store the `LanguageModelV3StreamPart[]`
+ *   array; `wrapStream` replays them via `simulateReadableStream` so consumers
+ *   see the same chunked event sequence on a hit. (`wrapGenerate` is the
+ *   common path; both share the same cache map.)
+ *
+ * - **TTL:** 24h default, configurable via `ttlMs`. Entries past TTL are
+ *   evicted on access (lazy expiry — no background timer).
+ *
+ * - **Pluggable store:** in-memory default (Map-backed); `'disk'` writes to
+ *   a JSON file at `.cache/v3-eval-cache.json` for cross-process fixture
+ *   sharing. Disk reads/writes are best-effort — IO failures fall through
+ *   to the wrapped model.
+ *
+ * - **Env gate:** honors `process.env.V3_EVAL_CACHE`. When unset/empty, the
+ *   middleware short-circuits to a passthrough — useful for production where
+ *   cache hits would be incorrect but the operator wants the same wrap chain.
+ *   Set to `'1'` (or any truthy non-empty string) to enable.
+ *
+ * @packageDocumentation
+ */
+import type { LanguageModelV3CallOptions, LanguageModelV3GenerateResult, LanguageModelV3Middleware, LanguageModelV3StreamPart } from '@ai-sdk/provider';
+/** Cached payload — both generate result and stream chunks under one key. */
+interface CacheEntry {
+    /** Result captured from `doGenerate`. Absent if the entry came from a stream call. */
+    generateResult?: LanguageModelV3GenerateResult;
+    /** Stream chunks captured from `doStream` (replayed via simulateReadableStream). */
+    streamChunks?: LanguageModelV3StreamPart[];
+    /** Insert epoch ms — drives TTL eviction. */
+    createdAt: number;
+}
+/** Pluggable cache store for cached LLM results. */
+export interface CacheMiddlewareStore {
+    get(key: string): CacheEntry | undefined;
+    set(key: string, value: CacheEntry): void;
+    delete(key: string): void;
+}
+/** Options for {@link cacheMiddleware}. */
+export interface CacheMiddlewareOptions {
+    /**
+     * Cache backend. `'memory'` uses a process-local Map; `'disk'` writes to
+     * `.cache/v3-eval-cache.json` for cross-process fixture sharing. A custom
+     * {@link CacheMiddlewareStore} can be passed instead.
+     *
+     * @default 'memory'
+     */
+    store?: 'memory' | 'disk' | CacheMiddlewareStore;
+    /**
+     * TTL in milliseconds. Entries older than `ttlMs` are evicted on access.
+     *
+     * @default 86_400_000 (24h)
+     */
+    ttlMs?: number;
+    /**
+     * Custom hash function for cache keys. Defaults to a stable hash of
+     * `{ prompt, modelId, responseFormat }`.
+     */
+    keyHash?: (params: LanguageModelV3CallOptions, modelId: string) => string;
+    /**
+     * Optional override for the env gate. When `false`, the middleware acts
+     * as a passthrough regardless of `V3_EVAL_CACHE`. When `true`, always
+     * caches. Defaults to `process.env.V3_EVAL_CACHE` truthy-check.
+     */
+    enabled?: boolean;
+    /** Optional custom path for the disk store (defaults to `.cache/v3-eval-cache.json`). */
+    diskPath?: string;
+}
+/**
+ * Build a cache middleware for `wrapLanguageModel`. Wraps `doGenerate` and
+ * `doStream`; on a hit replays the cached payload, on a miss invokes the
+ * downstream model and stores the result.
+ *
+ * Composition note: install **before** budget/trace so cache hits don't
+ * pay the downstream model cost (the trace/budget middleware still see the
+ * payload via the wrapped result they observe in their own `wrapGenerate`).
+ *
+ * @example
+ * ```ts
+ * import { wrapLanguageModel } from 'ai'
+ * import { cacheMiddleware } from 'ai-functions'
+ *
+ * const model = wrapLanguageModel({
+ *   model: openai('gpt-4o'),
+ *   middleware: cacheMiddleware({ store: 'disk', ttlMs: 86_400_000 }),
+ * })
+ * ```
+ */
+export declare function cacheMiddleware(options?: CacheMiddlewareOptions): LanguageModelV3Middleware;
+export {};
+//# sourceMappingURL=cache.d.ts.map

package/dist/middleware/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/middleware/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,KAAK,EACV,0BAA0B,EAC1B,6BAA6B,EAC7B,yBAAyB,EACzB,yBAAyB,EAE1B,MAAM,kBAAkB,CAAA;AAOzB,6EAA6E;AAC7E,UAAU,UAAU;IAClB,sFAAsF;IACtF,cAAc,CAAC,EAAE,6BAA6B,CAAA;IAC9C,oFAAoF;IACpF,YAAY,CAAC,EAAE,yBAAyB,EAAE,CAAA;IAC1C,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACnC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAAA;IACxC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;IACzC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,oBAAoB,CAAA;IAChD;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,0BAA0B,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IACzE;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAmHD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,yBAAyB,CAoE/F"}

package/dist/middleware/cache.js

@@ -0,0 +1,228 @@
+/**
+ * cacheMiddleware — content-addressable cache for `wrapLanguageModel`
+ *
+ * Implements the AI SDK cookbook's local-caching-middleware pattern
+ * (https://ai-sdk.dev/cookbook/node/local-caching-middleware) on top of the
+ * AI SDK 6 `LanguageModelV3Middleware` shape:
+ *
+ * - **Hit derivation:** content-hash of `{ prompt, modelId, responseFormat }`
+ *   so a schema change (responseFormat.type === 'json' carries a `schema`
+ *   JSONSchema7) invalidates the entry. Generation parameters (temperature,
+ *   topP, etc.) are deliberately *not* part of the key for the eval-fixture
+ *   use case — flipping temperature shouldn't blow up a 5x verify-time win.
+ *   Callers who want strict keying should pass a custom `keyHash`.
+ *
+ * - **Stream support:** cached entries store the `LanguageModelV3StreamPart[]`
+ *   array; `wrapStream` replays them via `simulateReadableStream` so consumers
+ *   see the same chunked event sequence on a hit. (`wrapGenerate` is the
+ *   common path; both share the same cache map.)
+ *
+ * - **TTL:** 24h default, configurable via `ttlMs`. Entries past TTL are
+ *   evicted on access (lazy expiry — no background timer).
+ *
+ * - **Pluggable store:** in-memory default (Map-backed); `'disk'` writes to
+ *   a JSON file at `.cache/v3-eval-cache.json` for cross-process fixture
+ *   sharing. Disk reads/writes are best-effort — IO failures fall through
+ *   to the wrapped model.
+ *
+ * - **Env gate:** honors `process.env.V3_EVAL_CACHE`. When unset/empty, the
+ *   middleware short-circuits to a passthrough — useful for production where
+ *   cache hits would be incorrect but the operator wants the same wrap chain.
+ *   Set to `'1'` (or any truthy non-empty string) to enable.
+ *
+ * @packageDocumentation
+ */
+import { simulateReadableStream } from 'ai';
+import { hashKey } from '../cache.js';
+// ============================================================================
+// Stores
+// ============================================================================
+class MemoryStore {
+    map = new Map();
+    get(key) {
+        return this.map.get(key);
+    }
+    set(key, value) {
+        this.map.set(key, value);
+    }
+    delete(key) {
+        this.map.delete(key);
+    }
+}
+/**
+ * Disk-backed store. Best-effort — JSON parse / write errors fall through
+ * silently so a corrupt cache file never blocks an LLM call. The whole map
+ * is rewritten on each `set` (cheap for the eval-fixture use case which is
+ * dominated by reads).
+ */
+class DiskStore {
+    path;
+    cache = null;
+    constructor(path) {
+        this.path = path;
+    }
+    load() {
+        if (this.cache !== null)
+            return this.cache;
+        this.cache = new Map();
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const fs = require('fs');
+            if (fs.existsSync(this.path)) {
+                const raw = fs.readFileSync(this.path, 'utf-8');
+                const parsed = JSON.parse(raw);
+                for (const [k, v] of Object.entries(parsed)) {
+                    this.cache.set(k, v);
+                }
+            }
+        }
+        catch {
+            // best-effort
+        }
+        return this.cache;
+    }
+    flush() {
+        if (this.cache === null)
+            return;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const fs = require('fs');
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const path = require('path');
+            const dir = path.dirname(this.path);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            const obj = Object.fromEntries(this.cache);
+            fs.writeFileSync(this.path, JSON.stringify(obj), 'utf-8');
+        }
+        catch {
+            // best-effort
+        }
+    }
+    get(key) {
+        return this.load().get(key);
+    }
+    set(key, value) {
+        this.load().set(key, value);
+        this.flush();
+    }
+    delete(key) {
+        this.load().delete(key);
+        this.flush();
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
+function defaultKeyHash(params, modelId) {
+    // Stable hash of prompt + model + responseFormat (which carries the
+    // schema for object generation). Generation knobs are deliberately
+    // excluded so the eval-fixture cache survives temperature tweaks.
+    return hashKey({
+        prompt: params.prompt,
+        modelId,
+        responseFormat: params.responseFormat,
+    });
+}
+function envGateEnabled() {
+    const v = process.env['V3_EVAL_CACHE'];
+    return typeof v === 'string' && v.length > 0;
+}
+function isExpired(entry, ttlMs) {
+    return Date.now() - entry.createdAt > ttlMs;
+}
+// ============================================================================
+// Middleware
+// ============================================================================
+/**
+ * Build a cache middleware for `wrapLanguageModel`. Wraps `doGenerate` and
+ * `doStream`; on a hit replays the cached payload, on a miss invokes the
+ * downstream model and stores the result.
+ *
+ * Composition note: install **before** budget/trace so cache hits don't
+ * pay the downstream model cost (the trace/budget middleware still see the
+ * payload via the wrapped result they observe in their own `wrapGenerate`).
+ *
+ * @example
+ * ```ts
+ * import { wrapLanguageModel } from 'ai'
+ * import { cacheMiddleware } from 'ai-functions'
+ *
+ * const model = wrapLanguageModel({
+ *   model: openai('gpt-4o'),
+ *   middleware: cacheMiddleware({ store: 'disk', ttlMs: 86_400_000 }),
+ * })
+ * ```
+ */
+export function cacheMiddleware(options = {}) {
+    const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    const keyHash = options.keyHash ?? defaultKeyHash;
+    const store = options.store === undefined || options.store === 'memory'
+        ? new MemoryStore()
+        : options.store === 'disk'
+            ? new DiskStore(options.diskPath ?? '.cache/v3-eval-cache.json')
+            : options.store;
+    const enabled = options.enabled ?? envGateEnabled();
+    return {
+        specificationVersion: 'v3',
+        async wrapGenerate({ doGenerate, params, model }) {
+            if (!enabled)
+                return doGenerate();
+            const key = keyHash(params, model.modelId);
+            const cached = store.get(key);
+            if (cached !== undefined) {
+                if (isExpired(cached, ttlMs)) {
+                    store.delete(key);
+                }
+                else if (cached.generateResult !== undefined) {
+                    return cached.generateResult;
+                }
+            }
+            const result = await doGenerate();
+            store.set(key, { generateResult: result, createdAt: Date.now() });
+            return result;
+        },
+        async wrapStream({ doStream, params, model }) {
+            if (!enabled)
+                return doStream();
+            const key = keyHash(params, model.modelId);
+            const cached = store.get(key);
+            if (cached !== undefined) {
+                if (isExpired(cached, ttlMs)) {
+                    store.delete(key);
+                }
+                else if (cached.streamChunks !== undefined) {
+                    // Replay cached chunks via simulateReadableStream so consumers
+                    // see the same async iteration shape as a fresh call.
+                    const replay = {
+                        stream: simulateReadableStream({
+                            chunks: cached.streamChunks,
+                            initialDelayInMs: 0,
+                            chunkDelayInMs: 0,
+                        }),
+                    };
+                    return replay;
+                }
+            }
+            const result = await doStream();
+            // Tee the stream: forward to caller, accumulate for cache.
+            const chunks = [];
+            const transformedStream = result.stream.pipeThrough(new TransformStream({
+                transform(chunk, controller) {
+                    chunks.push(chunk);
+                    controller.enqueue(chunk);
+                },
+                flush() {
+                    store.set(key, { streamChunks: chunks, createdAt: Date.now() });
+                },
+            }));
+            return {
+                ...result,
+                stream: transformedStream,
+            };
+        },
+    };
+}
+//# sourceMappingURL=cache.js.map

package/dist/middleware/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/middleware/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,IAAI,CAAA;AAQ3C,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAsDrC,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,MAAM,WAAW;IACE,GAAG,GAA4B,IAAI,GAAG,EAAE,CAAA;IACzD,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC1B,CAAC;IACD,GAAG,CAAC,GAAW,EAAE,KAAiB;QAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;IAC1B,CAAC;IACD,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IACtB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,SAAS;IACI,IAAI,CAAQ;IACrB,KAAK,GAAmC,IAAI,CAAA;IAEpD,YAAY,IAAY;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAEO,IAAI;QACV,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,KAAK,CAAA;QAC1C,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,EAAE,CAAA;QACtB,IAAI,CAAC;YACH,iEAAiE;YACjE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAwB,CAAA;YAC/C,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC7B,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;gBAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA+B,CAAA;gBAC5D,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC5C,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;gBACtB,CAAC;YACH,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,cAAc;QAChB,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAA;IACnB,CAAC;IAEO,KAAK;QACX,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI;YAAE,OAAM;QAC/B,IAAI,CAAC;YACH,iEAAiE;YACjE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAwB,CAAA;YAC/C,iEAAiE;YACjE,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAA0B,CAAA;YACrD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YACnC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;gBACxB,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;YACxC,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YAC1C,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAAA;QAC3D,CAAC;QAAC,MAAM,CAAC;YACP,cAAc;QAChB,CAAC;IACH,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC7B,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAiB;QAChC,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QAC3B,IAAI,CAAC,KAAK,EAAE,CAAA;IACd,CAAC;IAED,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACvB,IAAI,CAAC,KAAK,EAAE,CAAA;IACd,CAAC;CACF;AAED,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E,MAAM,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;AAE1C,SAAS,cAAc,CAAC,MAAkC,EAAE,OAAe;IACzE,oEAAoE;IACpE,mEAAmE;IACnE,kEAAkE;IAClE,OAAO,OAAO,CAAC;QACb,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,OAAO;QACP,cAAc,EAAE,MAAM,CAAC,cAAc;KACtC,CAAC,CAAA;AACJ,CAAC;AAED,SAAS,cAAc;IACrB,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAA;IACtC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAA;AAC9C,CAAC;AAED,SAAS,SAAS,CAAC,KAAiB,EAAE,KAAa;IACjD,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,GAAG,KAAK,CAAA;AAC7C,CAAC;AAED,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,eAAe,CAAC,UAAkC,EAAE;IAClE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,cAAc,CAAA;IAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,cAAc,CAAA;IACjD,MAAM,KAAK,GACT,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,KAAK,KAAK,QAAQ;QACvD,CAAC,CAAC,IAAI,WAAW,EAAE;QACnB,CAAC,CAAC,OAAO,CAAC,KAAK,KAAK,MAAM;YAC1B,CAAC,CAAC,IAAI,SAAS,CAAC,OAAO,CAAC,QAAQ,IAAI,2BAA2B,CAAC;YAChE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAA;IACnB,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,cAAc,EAAE,CAAA;IAEnD,OAAO;QACL,oBAAoB,EAAE,IAAI;QAC1B,KAAK,CAAC,YAAY,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE;YAC9C,IAAI,CAAC,OAAO;gBAAE,OAAO,UAAU,EAAE,CAAA;YACjC,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;YAC1C,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAC7B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,IAAI,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;oBAC7B,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;gBACnB,CAAC;qBAAM,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;oBAC/C,OAAO,MAAM,CAAC,cAAc,CAAA;gBAC9B,CAAC;YACH,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAA;YACjC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;YACjE,OAAO,MAAM,CAAA;QACf,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE;YAC1C,IAAI,CAAC,OAAO;gBAAE,OAAO,QAAQ,EAAE,CAAA;YAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;YAC1C,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;YAC7B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,IAAI,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;oBAC7B,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;gBACnB,CAAC;qBAAM,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;oBAC7C,+DAA+D;oBAC/D,sDAAsD;oBACtD,MAAM,MAAM,GAAgC;wBAC1C,MAAM,EAAE,sBAAsB,CAA4B;4BACxD,MAAM,EAAE,MAAM,CAAC,YAAY;4BAC3B,gBAAgB,EAAE,CAAC;4BACnB,cAAc,EAAE,CAAC;yBAClB,CAAC;qBACH,CAAA;oBACD,OAAO,MAAM,CAAA;gBACf,CAAC;YACH,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,QAAQ,EAAE,CAAA;YAC/B,2DAA2D;YAC3D,MAAM,MAAM,GAAgC,EAAE,CAAA;YAC9C,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CACjD,IAAI,eAAe,CAAuD;gBACxE,SAAS,CAAC,KAAK,EAAE,UAAU;oBACzB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;oBAClB,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;gBAC3B,CAAC;gBACD,KAAK;oBACH,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;gBACjE,CAAC;aACF,CAAC,CACH,CAAA;YACD,OAAO;gBACL,GAAG,MAAM;gBACT,MAAM,EAAE,iBAAiB;aAC1B,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/middleware/embed-cache.d.ts

@@ -0,0 +1,99 @@
+/**
+ * embeddingCacheMiddleware — content-addressable cache for `wrapEmbeddingModel`
+ *
+ * Embedding-side analogue of {@link cacheMiddleware}. Wraps `doEmbed` and
+ * caches the resulting embeddings keyed on
+ * `{ values, modelId, providerOptions }` so a re-embed of the same value
+ * batch with the same model returns the cached vectors without hitting the
+ * provider.
+ *
+ * **Why a separate middleware instead of reusing `cacheMiddleware`?**
+ * AI SDK 6 splits language-model and embedding-model surfaces:
+ * `LanguageModelV3Middleware` exposes `wrapGenerate` / `wrapStream` against
+ * `LanguageModelV3CallOptions`, while `EmbeddingModelV3Middleware` exposes
+ * `wrapEmbed` against `EmbeddingModelV3CallOptions`. The cache shape
+ * (per-value vector vs. per-prompt completion payload) is also different —
+ * embeddings cache batched arrays, generations cache single result objects.
+ *
+ * - **Hit derivation:** stable hash of `{ values, modelId, providerOptions }`.
+ *   `values` is the array as-passed (caller can pre-normalise if they want
+ *   case/whitespace insensitivity). Generation knobs don't apply.
+ *
+ * - **Batch semantics:** the cache key is the *whole* batch. A subset hit
+ *   doesn't trigger a partial-fill — that's a more invasive shape change
+ *   (the legacy `EmbeddingCache.getMany` did per-text caching, but it was
+ *   only used in the example and added 100+ LOC of bookkeeping). Callers
+ *   that want per-text caching should use stable per-text batches.
+ *
+ * - **TTL:** 24h default, configurable. Lazy expiry on access.
+ *
+ * - **Pluggable store:** in-memory default (Map-backed); custom store
+ *   honored as-is. Disk persistence is intentionally not provided here —
+ *   embedding payloads (large `number[][]`) make on-disk JSON a bad fit;
+ *   callers who want it should pass a custom store.
+ *
+ * - **Env gate:** honors `process.env.V3_EVAL_CACHE` for parity with
+ *   `cacheMiddleware`. Override via the `enabled` option.
+ *
+ * @packageDocumentation
+ */
+import type { EmbeddingModelV3CallOptions, EmbeddingModelV3Embedding, EmbeddingModelV3Middleware, SharedV3Warning } from '@ai-sdk/provider';
+/** Cached embedding payload. */
+interface EmbedCacheEntry {
+    /** The embedding vectors returned for the cached batch. */
+    embeddings: Array<EmbeddingModelV3Embedding>;
+    /** Provider warnings carried alongside the cached batch. */
+    warnings: Array<SharedV3Warning>;
+    /** Insert epoch ms — drives TTL eviction. */
+    createdAt: number;
+}
+/** Pluggable cache store for embedding results. */
+export interface EmbedCacheMiddlewareStore {
+    get(key: string): EmbedCacheEntry | undefined;
+    set(key: string, value: EmbedCacheEntry): void;
+    delete(key: string): void;
+}
+/** Options for {@link embeddingCacheMiddleware}. */
+export interface EmbedCacheMiddlewareOptions {
+    /**
+     * Cache backend. `'memory'` uses a process-local Map. A custom
+     * {@link EmbedCacheMiddlewareStore} can be passed instead.
+     *
+     * @default 'memory'
+     */
+    store?: 'memory' | EmbedCacheMiddlewareStore;
+    /**
+     * TTL in milliseconds. Entries older than `ttlMs` are evicted on access.
+     *
+     * @default 86_400_000 (24h)
+     */
+    ttlMs?: number;
+    /**
+     * Custom hash function for cache keys. Defaults to a stable hash of
+     * `{ values, modelId, providerOptions }`.
+     */
+    keyHash?: (params: EmbeddingModelV3CallOptions, modelId: string) => string;
+    /**
+     * Optional override for the env gate. When `false`, the middleware acts
+     * as a passthrough regardless of `V3_EVAL_CACHE`. When `true`, always
+     * caches. Defaults to `process.env.V3_EVAL_CACHE` truthy-check.
+     */
+    enabled?: boolean;
+}
+/**
+ * Build an embedding-cache middleware for `wrapEmbeddingModel`.
+ *
+ * @example
+ * ```ts
+ * import { wrapEmbeddingModel } from 'ai'
+ * import { embeddingCacheMiddleware } from 'ai-functions'
+ *
+ * const model = wrapEmbeddingModel({
+ *   model: openai.embedding('text-embedding-3-small'),
+ *   middleware: embeddingCacheMiddleware({ ttlMs: 86_400_000 }),
+ * })
+ * ```
+ */
+export declare function embeddingCacheMiddleware(options?: EmbedCacheMiddlewareOptions): EmbeddingModelV3Middleware;
+export {};
+//# sourceMappingURL=embed-cache.d.ts.map

package/dist/middleware/embed-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed-cache.d.ts","sourceRoot":"","sources":["../../src/middleware/embed-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EACV,2BAA2B,EAC3B,yBAAyB,EACzB,0BAA0B,EAE1B,eAAe,EAChB,MAAM,kBAAkB,CAAA;AAOzB,gCAAgC;AAChC,UAAU,eAAe;IACvB,2DAA2D;IAC3D,UAAU,EAAE,KAAK,CAAC,yBAAyB,CAAC,CAAA;IAC5C,4DAA4D;IAC5D,QAAQ,EAAE,KAAK,CAAC,eAAe,CAAC,CAAA;IAChC,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,mDAAmD;AACnD,MAAM,WAAW,yBAAyB;IACxC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAAA;IAC7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI,CAAA;IAC9C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B;AAED,oDAAoD;AACpD,MAAM,WAAW,2BAA2B;IAC1C;;;;;OAKG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,yBAAyB,CAAA;IAC5C;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,2BAA2B,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAA;IAC1E;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AA8CD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,2BAAgC,GACxC,0BAA0B,CAoC5B"}