ai-functions 2.1.1 → 2.3.0

package/dist/cache.d.ts

@@ -0,0 +1,295 @@
+/**
+ * Caching layer for embeddings and generations
+ *
+ * Provides content-addressable caching for embeddings and parameter-aware
+ * caching for text/object generations with TTL support and LRU eviction.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Cache entry with metadata for tracking and eviction
+ */
+export interface CacheEntry<T> {
+    /** The cached value */
+    value: T;
+    /** When the entry was created */
+    createdAt: number;
+    /** When the entry was last accessed */
+    lastAccessedAt: number;
+    /** Number of times this entry has been accessed */
+    accessCount: number;
+    /** When the entry expires (if TTL is set) */
+    expiresAt?: number;
+}
+/**
+ * Options for cache operations
+ */
+export interface CacheOptions {
+    /** Time-to-live in milliseconds */
+    ttl?: number;
+    /** Whether to bypass cache and force fresh result */
+    bypass?: boolean;
+}
+/**
+ * Cache statistics for monitoring
+ */
+export interface CacheStats {
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Hit rate (0-1) */
+    hitRate: number;
+    /** Current number of entries */
+    size: number;
+}
+/**
+ * Configuration options for MemoryCache
+ */
+export interface MemoryCacheOptions {
+    /** Default TTL for entries in milliseconds */
+    defaultTTL?: number;
+    /** Maximum number of entries (enables LRU eviction) */
+    maxSize?: number;
+    /** Whether to refresh TTL on access (sliding window) */
+    slidingExpiration?: boolean;
+    /** Interval for cleanup of expired entries in milliseconds */
+    cleanupInterval?: number;
+}
+/**
+ * Abstract cache storage interface for pluggable backends
+ */
+export interface CacheStorage<T> {
+    /** Get a value by key */
+    get(key: string): Promise<T | undefined>;
+    /** Set a value by key */
+    set(key: string, value: T, options?: CacheOptions): Promise<void>;
+    /** Check if a key exists */
+    has(key: string): Promise<boolean>;
+    /** Delete a key */
+    delete(key: string): Promise<void>;
+    /** Clear all entries */
+    clear(): Promise<void>;
+    /** Get the number of entries */
+    size(): Promise<number>;
+    /** Get all keys */
+    keys(): Promise<string[]>;
+}
+/**
+ * In-memory cache implementation with TTL and LRU eviction support
+ *
+ * @deprecated Phase C Week 1 — `MemoryCache` has zero production callers in
+ * primitives.org.ai (audited 2026-05-06; see `bd show aip-ibid`). New code
+ * should use `cacheMiddleware` (for `wrapLanguageModel`) or
+ * `embeddingCacheMiddleware` (for `wrapEmbeddingModel`) instead — both
+ * compose with AI SDK 6's `wrapLanguageModel` / `wrapEmbeddingModel` and
+ * carry per-call telemetry (TraceEvent emission) and budget tracking when
+ * paired via `wrapForV3`. The `MemoryCache` class will be removed in the
+ * Phase C semver bump alongside `EmbeddingCache` and `GenerationCache`.
+ */
+export declare class MemoryCache<T> implements CacheStorage<T> {
+    private cache;
+    private accessOrder;
+    private options;
+    private cleanupTimer?;
+    constructor(options?: MemoryCacheOptions);
+    /**
+     * Get a value by key
+     */
+    get(key: string): Promise<T | undefined>;
+    /**
+     * Set a value by key
+     */
+    set(key: string, value: T, options?: CacheOptions): Promise<void>;
+    /**
+     * Check if a key exists
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Delete a key
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Clear all entries
+     */
+    clear(): Promise<void>;
+    /**
+     * Get the number of entries (excluding expired)
+     */
+    size(): Promise<number>;
+    /**
+     * Get all keys
+     */
+    keys(): Promise<string[]>;
+    /**
+     * Get full entry with metadata
+     */
+    getEntry(key: string): Promise<CacheEntry<T> | undefined>;
+    /**
+     * Dispose cleanup timer
+     */
+    dispose(): void;
+    /**
+     * Clean up expired entries
+     */
+    private cleanup;
+    /**
+     * Evict the least recently used entry
+     */
+    private evictLRU;
+    /**
+     * Update access order for LRU tracking
+     */
+    private updateAccessOrder;
+    /**
+     * Remove a key from access order
+     */
+    private removeFromAccessOrder;
+}
+/**
+ * Generate a hash for cache keys
+ * Uses a fast, non-cryptographic hash suitable for cache keys
+ */
+export declare function hashKey(input: unknown): string;
+/**
+ * Cache key type
+ */
+export type CacheKeyType = 'embedding' | 'generation';
+/**
+ * Create a cache key for a specific type and parameters
+ */
+export declare function createCacheKey(type: CacheKeyType, params: Record<string, unknown>): string;
+/**
+ * Options for embedding cache operations
+ */
+export interface EmbeddingCacheOptions {
+    /** The embedding model used */
+    model: string;
+}
+/**
+ * Result from batch embedding cache lookup
+ */
+export interface BatchEmbeddingResult {
+    /** Map of text to cached embedding */
+    hits: Record<string, number[]>;
+    /** Texts that were not in cache */
+    misses: string[];
+}
+/**
+ * Specialized cache for embedding vectors
+ *
+ * @deprecated Phase C Week 1 — `EmbeddingCache` has zero production callers
+ * in primitives.org.ai (audited 2026-05-06; see `bd show aip-ibid`). New
+ * code should use `embeddingCacheMiddleware` (for `wrapEmbeddingModel`) —
+ * it composes with AI SDK 6 directly and carries trace + budget telemetry
+ * when paired via `wrapForV3`. Note: `embeddingCacheMiddleware` keys on the
+ * whole batch, not per-text — callers wanting per-text caching should pass
+ * stable per-text batches. Will be removed in the Phase C semver bump.
+ */
+export declare class EmbeddingCache {
+    private storage;
+    private stats;
+    constructor(options?: MemoryCacheOptions);
+    /**
+     * Get a cached embedding
+     */
+    get(content: string, options: EmbeddingCacheOptions): Promise<number[] | undefined>;
+    /**
+     * Set a cached embedding
+     */
+    set(content: string, embedding: number[], options: EmbeddingCacheOptions): Promise<void>;
+    /**
+     * Set multiple embeddings at once
+     */
+    setMany(texts: string[], embeddings: number[][], options: EmbeddingCacheOptions): Promise<void>;
+    /**
+     * Get multiple embeddings, returning hits and misses
+     */
+    getMany(texts: string[], options: EmbeddingCacheOptions): Promise<BatchEmbeddingResult>;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Clear the cache
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Parameters for generation cache key
+ */
+export interface GenerationParams {
+    /** The prompt text */
+    prompt: string;
+    /** The model to use */
+    model: string;
+    /** System prompt */
+    system?: string;
+    /** Temperature setting */
+    temperature?: number;
+    /** Schema version for structured outputs */
+    schemaVersion?: string;
+}
+/**
+ * Options for generation cache retrieval
+ */
+export interface GenerationCacheGetOptions {
+    /** Bypass cache and return undefined */
+    bypass?: boolean;
+}
+/**
+ * Specialized cache for generation results
+ *
+ * @deprecated Phase C Week 1 — `GenerationCache` has zero production callers
+ * in primitives.org.ai (audited 2026-05-06; see `bd show aip-ibid`). New
+ * code should use `cacheMiddleware` (for `wrapLanguageModel`) — it composes
+ * with AI SDK 6 directly and carries trace + budget telemetry when paired
+ * via `wrapForV3`. Will be removed in the Phase C semver bump.
+ */
+export declare class GenerationCache {
+    private storage;
+    private stats;
+    constructor(options?: MemoryCacheOptions);
+    /**
+     * Get a cached generation result
+     */
+    get<T = unknown>(params: GenerationParams, options?: GenerationCacheGetOptions): Promise<T | undefined>;
+    /**
+     * Set a cached generation result
+     */
+    set<T = unknown>(params: GenerationParams, result: T): Promise<void>;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Clear the cache
+     */
+    clear(): Promise<void>;
+    /**
+     * Create a cache key from generation parameters
+     */
+    private createKey;
+}
+/**
+ * Options for withCache wrapper
+ */
+export interface WithCacheOptions<TArgs extends unknown[]> {
+    /** Function to generate cache key from arguments */
+    keyFn: (...args: TArgs) => string;
+    /** TTL for cached entries */
+    ttl?: number;
+}
+/**
+ * Cached function type with bypass support
+ */
+export interface CachedFunction<TArgs extends unknown[], TResult> {
+    (...args: TArgs): Promise<TResult>;
+    /** Call with cache bypass (force fresh result) */
+    bypass: (...args: TArgs) => Promise<TResult>;
+}
+/**
+ * Wrap an async function with caching
+ */
+export declare function withCache<TArgs extends unknown[], TResult>(cache: CacheStorage<TResult>, fn: (...args: TArgs) => Promise<TResult>, options: WithCacheOptions<TArgs>): CachedFunction<TArgs, TResult>;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

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