ai-functions/dist/cache.d.ts

Core AI primitives for building intelligent applications

/**
 * 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