/**
 * Semantic Cache for API Responses
 *
 * Based on research showing 68% API call reduction with semantic caching:
 * - Uses cosine similarity to match similar queries
 * - Simple embedding via character n-grams (no external API needed)
 * - LRU eviction with configurable size limits
 * - TTL-based expiration
 *
 * This provides significant cost and latency reduction for repeated queries.
 */
import { EventEmitter } from 'events';
export interface CacheEntry<T = unknown> {
    key: string;
    query: string;
    response: T;
    embedding: number[];
    timestamp: number;
    expiresAt: number;
    hits: number;
    metadata?: Record<string, unknown>;
}
export interface CacheConfig {
    maxEntries: number;
    ttlMs: number;
    similarityThreshold: number;
    persistToDisk: boolean;
    cachePath: string;
    ngramSize: number;
    embeddingDim: number;
    /** Enable adaptive similarity threshold based on context */
    adaptiveThreshold: boolean;
    /** Minimum similarity threshold (used with adaptive) */
    minSimilarityThreshold: number;
    /** Maximum similarity threshold (used with adaptive) */
    maxSimilarityThreshold: number;
    /** Enable locality-sensitive hashing for faster lookup */
    enableLSH: boolean;
    /** Number of LSH hash tables */
    lshTables: number;
    /** Number of LSH hash functions per table */
    lshHashFunctions: number;
    /** Enable query clustering for better cache organization */
    enableClustering: boolean;
    /** Number of clusters for query organization */
    numClusters: number;
}
export interface CacheStats {
    totalEntries: number;
    hits: number;
    misses: number;
    hitRate: number;
    semanticHits: number;
    exactHits: number;
    evictions: number;
    avgSimilarity: number;
    /** Number of LSH lookups performed */
    lshLookups: number;
    /** Number of LSH candidates found */
    lshCandidates: number;
    /** Average lookup time in ms */
    avgLookupTimeMs: number;
    /** Memory estimation in bytes */
    memoryEstimateBytes: number;
    /** Number of clusters (if enabled) */
    clusters: number;
}
export interface CacheLookupResult<T = unknown> {
    hit: boolean;
    entry?: CacheEntry<T>;
    similarity?: number;
    isExactMatch?: boolean;
}
export declare class SemanticCache<T = unknown> extends EventEmitter {
    private cache;
    private config;
    private stats;
    private similarityScores;
    private lookupTimes;
    private saveTimeout;
    private saveDebounceMs;
    private lshTables;
    private lshHyperplanes;
    private clusters;
    private clusterCentroids;
    constructor(config?: Partial<CacheConfig>);
    /**
     * Initialize LSH hash tables and hyperplanes
     */
    private initializeLSH;
    /**
     * Compute LSH hash for an embedding
     */
    private computeLSHHash;
    /**
     * Add entry to LSH tables
     */
    private addToLSH;
    /**
     * Remove entry from LSH tables
     */
    private removeFromLSH;
    /**
     * Find LSH candidates for a query embedding
     */
    private findLSHCandidates;
    /**
     * Get adaptive similarity threshold based on query characteristics
     */
    private getAdaptiveThreshold;
    /**
     * Get or compute a cached response
     */
    getOrCompute(query: string, computeFn: () => Promise<T>, metadata?: Record<string, unknown>): Promise<{
        result: T;
        cached: boolean;
        similarity?: number;
    }>;
    /**
     * Look up a query in the cache
     */
    lookup(query: string): CacheLookupResult<T>;
    /**
     * Record lookup time for metrics
     */
    private recordLookupTime;
    /**
     * Remove entry and clean up LSH
     */
    private removeEntry;
    /**
     * Store a response in the cache
     */
    set(query: string, response: T, metadata?: Record<string, unknown>): void;
    /**
     * Update memory estimate
     */
    private updateMemoryEstimate;
    /**
     * Schedule a debounced save to reduce I/O
     */
    private scheduleSave;
    /**
     * Invalidate cache entries matching a pattern
     */
    invalidate(pattern: string | RegExp): number;
    /**
     * Clear entire cache
     */
    clear(): void;
    /**
     * Get cache statistics
     */
    getStats(): CacheStats;
    /**
     * Compute simple n-gram based embedding
     * Uses character n-grams for language-agnostic similarity
     */
    private computeEmbedding;
    /**
     * Compute cosine similarity between two embeddings
     */
    private cosineSimilarity;
    /**
     * Simple hash function for n-grams
     */
    private simpleHash;
    /**
     * Hash query for exact match key
     */
    private hashQuery;
    /**
     * Check if entry is expired
     */
    private isExpired;
    /**
     * Evict least recently used entry (with frequency weighting)
     */
    private evictLRU;
    /**
     * Update hit rate statistic
     */
    private updateHitRate;
    /**
     * Update average similarity statistic
     */
    private updateAvgSimilarity;
    /**
     * Load cache from disk
     */
    private loadFromDisk;
    /**
     * Save cache to disk (async)
     */
    private saveToDisk;
    /**
     * Dispose and flush pending saves
     */
    dispose(): void;
    /**
     * Get config
     */
    getConfig(): CacheConfig;
    /**
     * Update config
     */
    updateConfig(config: Partial<CacheConfig>): void;
}
export declare function getApiCache(config?: Partial<CacheConfig>): SemanticCache;
export declare function resetApiCache(): void;
/**
 * Create a cache key from tool name and arguments
 */
export declare function createToolCacheKey(toolName: string, args: Record<string, unknown>): string;
/**
 * Check if a tool response is cacheable
 */
export declare function isCacheable(toolName: string): boolean;
