ai-functions 2.1.3 → 2.4.0

package/dist/logger.js

@@ -0,0 +1,187 @@
+/**
+ * Configurable Logger for AI Functions
+ *
+ * Provides a pluggable logging interface that defaults to console but can be
+ * configured to use any logging implementation. This allows library consumers
+ * to integrate with their own logging infrastructure.
+ *
+ * @example
+ * ```ts
+ * import { configureLogger, getLogger } from 'ai-functions'
+ *
+ * // Use with default console logger
+ * const logger = getLogger()
+ * logger.warn('Something happened')
+ *
+ * // Configure a custom logger
+ * configureLogger({
+ *   debug: (msg, ...args) => myLogger.debug(msg, ...args),
+ *   info: (msg, ...args) => myLogger.info(msg, ...args),
+ *   warn: (msg, ...args) => myLogger.warn(msg, ...args),
+ *   error: (msg, ...args) => myLogger.error(msg, ...args),
+ * })
+ *
+ * // Disable logging entirely
+ * configureLogger(null)
+ * ```
+ *
+ * @packageDocumentation
+ */
+// ============================================================================
+// Logger State
+// ============================================================================
+/** Log level priority (lower = more verbose) */
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+/** Default console-based logger */
+const defaultLogger = {
+    debug: (message, ...args) => console.debug(message, ...args),
+    info: (message, ...args) => console.info(message, ...args),
+    warn: (message, ...args) => console.warn(message, ...args),
+    error: (message, ...args) => console.error(message, ...args),
+};
+/** No-op logger for when logging is disabled */
+const noopLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+/** Current logger instance */
+let currentLogger = defaultLogger;
+/** Current minimum log level */
+let currentLevel = 'warn';
+// ============================================================================
+// Configuration Functions
+// ============================================================================
+/**
+ * Configure the global logger for ai-functions.
+ *
+ * @param config - Logger configuration or just a logger instance
+ *
+ * @example
+ * ```ts
+ * // Use a custom logger
+ * configureLogger({
+ *   logger: {
+ *     debug: (msg) => myLogger.debug(msg),
+ *     info: (msg) => myLogger.info(msg),
+ *     warn: (msg) => myLogger.warn(msg),
+ *     error: (msg) => myLogger.error(msg),
+ *   },
+ *   level: 'info',
+ * })
+ *
+ * // Just set the log level
+ * configureLogger({ level: 'debug' })
+ *
+ * // Disable all logging
+ * configureLogger({ logger: null })
+ * // or
+ * configureLogger({ level: 'silent' })
+ *
+ * // Reset to defaults
+ * configureLogger({})
+ * ```
+ */
+export function configureLogger(config) {
+    // Handle null (disable logging)
+    if (config === null) {
+        currentLogger = noopLogger;
+        return;
+    }
+    // Handle Logger directly
+    if (config && ('debug' in config || 'info' in config || 'warn' in config || 'error' in config)) {
+        // Check if it's a Logger (has at least one log method but no 'logger' or 'level' key)
+        if (!('logger' in config) && !('level' in config)) {
+            currentLogger = config;
+            return;
+        }
+    }
+    // Handle LoggerConfig
+    const loggerConfig = config;
+    if (loggerConfig.logger === null) {
+        currentLogger = noopLogger;
+    }
+    else if (loggerConfig.logger) {
+        currentLogger = loggerConfig.logger;
+    }
+    else if (config === undefined || Object.keys(config).length === 0) {
+        // Reset to default
+        currentLogger = defaultLogger;
+        currentLevel = 'warn';
+        return;
+    }
+    if (loggerConfig.level) {
+        currentLevel = loggerConfig.level;
+    }
+}
+/**
+ * Get the current logger instance.
+ *
+ * Returns a logger that respects the configured log level.
+ * Methods for levels below the configured minimum will be no-ops.
+ *
+ * @returns Logger instance with level filtering applied
+ *
+ * @example
+ * ```ts
+ * const logger = getLogger()
+ * logger.warn('This is a warning')
+ * logger.error('This is an error', { details: 'foo' })
+ * ```
+ */
+export function getLogger() {
+    const minLevel = LOG_LEVELS[currentLevel] ?? LOG_LEVELS['warn'];
+    return {
+        debug: (message, ...args) => {
+            if (minLevel <= LOG_LEVELS['debug']) {
+                currentLogger.debug?.(message, ...args);
+            }
+        },
+        info: (message, ...args) => {
+            if (minLevel <= LOG_LEVELS['info']) {
+                currentLogger.info?.(message, ...args);
+            }
+        },
+        warn: (message, ...args) => {
+            if (minLevel <= LOG_LEVELS['warn']) {
+                currentLogger.warn?.(message, ...args);
+            }
+        },
+        error: (message, ...args) => {
+            if (minLevel <= LOG_LEVELS['error']) {
+                currentLogger.error?.(message, ...args);
+            }
+        },
+    };
+}
+/**
+ * Reset the logger to default configuration.
+ *
+ * Restores the console-based logger with 'warn' minimum level.
+ */
+export function resetLogger() {
+    currentLogger = defaultLogger;
+    currentLevel = 'warn';
+}
+/**
+ * Get the current log level
+ */
+export function getLogLevel() {
+    return currentLevel;
+}
+/**
+ * Set the minimum log level
+ *
+ * @param level - Minimum level to log ('debug' | 'info' | 'warn' | 'error' | 'silent')
+ */
+export function setLogLevel(level) {
+    currentLevel = level;
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

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

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"}