agentdb 3.0.0-alpha.9 → 3.1.0

package/dist/agentdb.wasm-loader.js

@@ -1,207 +0,0 @@
-/**
- * AgentDB WASM Attention Module Loader
- * Lazy-loaded high-performance attention mechanisms
- *
- * Features:
- * - Flash Attention
- * - Hyperbolic Attention
- * - Memory Consolidation
- */
-
-let wasmModule = null;
-let wasmLoading = null;
-let wasmLoadError = null;
-
-/**
- * Initialize WASM module (lazy loaded on first use)
- */
-export async function initWASM() {
-  if (wasmModule) return wasmModule;
-  if (wasmLoading) return wasmLoading;
-
-  wasmLoading = (async () => {
-    try {
-      // Check for WASM support
-      if (typeof WebAssembly === 'undefined') {
-        throw new Error('WebAssembly not supported in this browser');
-      }
-
-      // Check for SIMD support
-      const simdSupported = await detectWasmSIMD();
-      console.log(`WASM SIMD support: ${simdSupported}`);
-
-      // In a real implementation, this would load the actual WASM binary
-      // For now, we create a mock implementation
-      wasmModule = {
-        flashAttention: createFlashAttentionMock(),
-        hyperbolicAttention: createHyperbolicAttentionMock(),
-        memoryConsolidation: createMemoryConsolidationMock(),
-        simdSupported
-      };
-
-      console.log('✅ WASM attention module loaded');
-      return wasmModule;
-    } catch (error) {
-      wasmLoadError = error;
-      console.warn('⚠️  WASM loading failed, using fallback:', error.message);
-
-      // Return fallback implementations
-      wasmModule = {
-        flashAttention: createFlashAttentionMock(),
-        hyperbolicAttention: createHyperbolicAttentionMock(),
-        memoryConsolidation: createMemoryConsolidationMock(),
-        simdSupported: false
-      };
-
-      return wasmModule;
-    } finally {
-      wasmLoading = null;
-    }
-  })();
-
-  return wasmLoading;
-}
-
-/**
- * Detect WASM SIMD support
- */
-async function detectWasmSIMD() {
-  try {
-    const simdTest = new Uint8Array([
-      0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00,
-      0x01, 0x05, 0x01, 0x60, 0x00, 0x01, 0x7b, 0x03,
-      0x02, 0x01, 0x00, 0x0a, 0x0a, 0x01, 0x08, 0x00,
-      0xfd, 0x0c, 0xfd, 0x0c, 0xfd, 0x54, 0x0b
-    ]);
-
-    const module = await WebAssembly.instantiate(simdTest);
-    return module instanceof WebAssembly.Instance;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Mock implementations (replaced by actual WASM in production)
- */
-function createFlashAttentionMock() {
-  return (query, keys, values, options = {}) => {
-    const { dim = 384, numHeads = 4, blockSize = 64 } = options;
-    const seqLen = keys.length / dim;
-    const output = new Float32Array(query.length);
-
-    // Simple attention for demonstration
-    for (let i = 0; i < query.length; i += dim) {
-      const q = query.slice(i, i + dim);
-      let sumWeights = 0;
-      const weights = new Float32Array(seqLen);
-
-      // Compute attention weights
-      for (let j = 0; j < seqLen; j++) {
-        const k = keys.slice(j * dim, (j + 1) * dim);
-        let dot = 0;
-        for (let d = 0; d < dim; d++) {
-          dot += q[d] * k[d];
-        }
-        weights[j] = Math.exp(dot / Math.sqrt(dim));
-        sumWeights += weights[j];
-      }
-
-      // Normalize and apply to values
-      for (let j = 0; j < seqLen; j++) {
-        weights[j] /= sumWeights;
-        const v = values.slice(j * dim, (j + 1) * dim);
-        for (let d = 0; d < dim; d++) {
-          output[i + d] += weights[j] * v[d];
-        }
-      }
-    }
-
-    return output;
-  };
-}
-
-function createHyperbolicAttentionMock() {
-  return (query, keys, options = {}) => {
-    const { curvature = -1.0 } = options;
-    const k = Math.abs(curvature);
-    const similarities = new Float32Array(keys.length / query.length);
-
-    // Hyperbolic distance computation
-    for (let i = 0; i < similarities.length; i++) {
-      const offset = i * query.length;
-      let dotProduct = 0;
-      let normQ = 0;
-      let normK = 0;
-
-      for (let j = 0; j < query.length; j++) {
-        dotProduct += query[j] * keys[offset + j];
-        normQ += query[j] * query[j];
-        normK += keys[offset + j] * keys[offset + j];
-      }
-
-      // Poincaré distance approximation
-      const euclidean = Math.sqrt(normQ + normK - 2 * dotProduct);
-      const poincare = Math.acosh(1 + 2 * k * euclidean * euclidean);
-      similarities[i] = 1 / (1 + poincare);
-    }
-
-    return similarities;
-  };
-}
-
-function createMemoryConsolidationMock() {
-  return (memories, options = {}) => {
-    const { threshold = 0.8, maxClusters = 10 } = options;
-    const consolidated = [];
-    const used = new Set();
-
-    // Simple clustering by similarity
-    for (let i = 0; i < memories.length; i++) {
-      if (used.has(i)) continue;
-
-      const cluster = [memories[i]];
-      used.add(i);
-
-      for (let j = i + 1; j < memories.length; j++) {
-        if (used.has(j)) continue;
-
-        // Compute similarity
-        let dot = 0;
-        let norm1 = 0;
-        let norm2 = 0;
-        for (let k = 0; k < memories[i].length; k++) {
-          dot += memories[i][k] * memories[j][k];
-          norm1 += memories[i][k] * memories[i][k];
-          norm2 += memories[j][k] * memories[j][k];
-        }
-        const similarity = dot / (Math.sqrt(norm1 * norm2) || 1);
-
-        if (similarity > threshold) {
-          cluster.push(memories[j]);
-          used.add(j);
-        }
-      }
-
-      // Average cluster members
-      const avg = new Float32Array(memories[i].length);
-      for (const mem of cluster) {
-        for (let k = 0; k < avg.length; k++) {
-          avg[k] += mem[k] / cluster.length;
-        }
-      }
-
-      consolidated.push({
-        memory: avg,
-        count: cluster.size,
-        members: cluster
-      });
-
-      if (consolidated.length >= maxClusters) break;
-    }
-
-    return consolidated;
-  };
-}
-
-export { wasmModule, wasmLoadError };

package/dist/backends/VectorBackend.d.ts

@@ -1,120 +0,0 @@
-/**
- * VectorBackend - Unified interface for vector database backends
- *
- * Provides abstraction over different vector search implementations
- * (RuVector, hnswlib-node) for AgentDB v2.
- *
- * Design:
- * - String-based IDs for all operations (backends handle label mapping internally)
- * - Consistent SearchResult format across backends
- * - Save/load with metadata persistence
- * - Backend-specific optimizations hidden behind interface
- */
-export interface VectorConfig {
-    /** Vector dimension (e.g., 384, 768, 1536) */
-    dimension?: number;
-    /** Alias for dimension (backward compatibility) */
-    dimensions?: number;
-    /** Distance metric: 'cosine', 'l2' (Euclidean), 'ip' (inner product) */
-    metric: 'cosine' | 'l2' | 'ip';
-    /** Maximum number of elements (default: 100000) */
-    maxElements?: number;
-    /** HNSW M parameter - connections per layer (default: 16) */
-    M?: number;
-    /** HNSW efConstruction - build quality (default: 200) */
-    efConstruction?: number;
-    /** HNSW efSearch - search quality (default: 100) */
-    efSearch?: number;
-}
-export interface SearchResult {
-    /** String ID of the vector */
-    id: string;
-    /** Raw distance value from backend */
-    distance: number;
-    /** Normalized similarity (0-1, higher is more similar) */
-    similarity: number;
-    /** Optional metadata attached to vector */
-    metadata?: Record<string, any>;
-}
-export interface SearchOptions {
-    /** Minimum similarity threshold (0-1) */
-    threshold?: number;
-    /** Override efSearch for this query */
-    efSearch?: number;
-    /** Metadata filters (post-filtering) */
-    filter?: Record<string, any>;
-}
-export interface VectorStats {
-    /** Number of vectors in index */
-    count: number;
-    /** Vector dimension */
-    dimension: number;
-    /** Distance metric */
-    metric: string;
-    /** Backend name */
-    backend: 'ruvector' | 'hnswlib';
-    /** Memory usage in bytes (0 if not available) */
-    memoryUsage: number;
-}
-/**
- * VectorBackend - Interface for vector search implementations
- *
- * All backends must:
- * 1. Accept string IDs and handle label mapping internally
- * 2. Normalize distances to similarities (0-1 range)
- * 3. Support save/load with metadata persistence
- * 4. Provide stats for monitoring
- */
-export interface VectorBackend {
-    /** Backend name for detection and logging */
-    readonly name: 'ruvector' | 'hnswlib';
-    /**
-     * Insert a single vector with optional metadata
-     * @param id - Unique string identifier
-     * @param embedding - Vector as Float32Array
-     * @param metadata - Optional metadata to store with vector
-     */
-    insert(id: string, embedding: Float32Array, metadata?: Record<string, any>): void;
-    /**
-     * Insert multiple vectors in batch (more efficient)
-     * @param items - Array of {id, embedding, metadata?}
-     */
-    insertBatch(items: Array<{
-        id: string;
-        embedding: Float32Array;
-        metadata?: Record<string, any>;
-    }>): void;
-    /**
-     * Search for k-nearest neighbors
-     * @param query - Query vector
-     * @param k - Number of results
-     * @param options - Search options (threshold, efSearch, filters)
-     * @returns Sorted results (most similar first)
-     */
-    search(query: Float32Array, k: number, options?: SearchOptions): SearchResult[];
-    /**
-     * Remove a vector by ID
-     * @param id - Vector ID to remove
-     * @returns true if removed, false if not found
-     */
-    remove(id: string): boolean;
-    /**
-     * Get backend statistics
-     * @returns Stats object with count, dimension, backend name, etc.
-     */
-    getStats(): VectorStats;
-    /**
-     * Save index to disk
-     * @param path - File path (backend adds extensions as needed)
-     */
-    save(path: string): Promise<void>;
-    /**
-     * Load index from disk
-     * @param path - File path (backend looks for associated files)
-     */
-    load(path: string): Promise<void>;
-    /**
-     * Close and cleanup resources
-     */
-    close(): void;
-}

package/dist/backends/VectorBackend.js

@@ -1,14 +0,0 @@
-/**
- * VectorBackend - Unified interface for vector database backends
- *
- * Provides abstraction over different vector search implementations
- * (RuVector, hnswlib-node) for AgentDB v2.
- *
- * Design:
- * - String-based IDs for all operations (backends handle label mapping internally)
- * - Consistent SearchResult format across backends
- * - Save/load with metadata persistence
- * - Backend-specific optimizations hidden behind interface
- */
-export {};
-//# sourceMappingURL=VectorBackend.js.map

package/dist/backends/VectorBackend.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"VectorBackend.js","sourceRoot":"","sources":["../../src/backends/VectorBackend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/optimizations/RVFOptimizer.d.ts

@@ -1,225 +0,0 @@
-/**
- * RVFOptimizer - RuVector Format Optimization Patterns
- *
- * Implements RVF (RuVector Format) optimization patterns for AgentDB:
- * - Embedding compression via quantization (4/8/16-bit)
- * - Deduplication of near-identical embeddings
- * - Memory pruning based on confidence and age
- * - Batch embedding with configurable queue and timer
- * - LRU caching for frequently accessed embeddings
- * - 4-bit INT4 quantization for 8x memory compression (ADR-065)
- * - Adaptive quantization based on importance scores
- * - Progressive compression with automatic promotion/demotion
- * - Multi-level caching with zero-copy hot paths
- *
- * Performance targets (ADR-062, ADR-065):
- * - 10-100x speedup via batch embedding
- * - 8x memory reduction via 4-bit quantization (vs 4x with 8-bit)
- * - 20-50% storage reduction via deduplication
- * - <5% quality degradation with adaptive quantization
- */
-export interface RVFConfig {
-    compression: {
-        enabled: boolean;
-        quantizeBits: 4 | 8 | 16;
-        deduplicationThreshold: number;
-        adaptive: boolean;
-        progressive: boolean;
-    };
-    pruning: {
-        enabled: boolean;
-        minConfidence: number;
-        maxAge: number;
-    };
-    batching: {
-        enabled: boolean;
-        batchSize: number;
-        maxWaitMs: number;
-    };
-    caching: {
-        enabled: boolean;
-        maxSize: number;
-        ttl: number;
-        multiLevel: boolean;
-    };
-}
-export interface CompressionMetrics {
-    originalSize: number;
-    compressedSize: number;
-    compressionRatio: number;
-    qualityScore: number;
-    quantizationBits: 4 | 8 | 16;
-    adaptiveBoost: number;
-}
-export interface CacheLevel {
-    name: 'L1' | 'L2' | 'L3';
-    maxSize: number;
-    quantizeBits: 4 | 8 | 16;
-    hitRate: number;
-    entries: number;
-}
-export declare class RVFOptimizer {
-    private config;
-    private cache;
-    private batchQueue;
-    private batchTimer?;
-    private l1Cache;
-    private l2Cache;
-    private l3Cache;
-    private importanceScores;
-    private compressionMetrics;
-    private cacheStats;
-    constructor(config?: Partial<RVFConfig>);
-    /**
-     * 4-bit INT4 quantization for 8x memory compression.
-     *
-     * ADR-065: Implements aggressive 4-bit quantization with:
-     * - 16 levels per component (0-15)
-     * - Min-max normalization per vector
-     * - 8x compression ratio (32-bit → 4-bit)
-     *
-     * @returns Compressed embedding with quality metrics
-     */
-    quantize4Bit(embedding: number[]): {
-        compressed: number[];
-        metrics: CompressionMetrics;
-    };
-    /**
-     * Adaptive quantization: adjust bit depth based on importance score.
-     *
-     * ADR-065: High-importance embeddings get higher bit depth:
-     * - importance > 0.8: 16-bit (minimal quality loss)
-     * - importance 0.5-0.8: 8-bit (balanced)
-     * - importance < 0.5: 4-bit (max compression)
-     */
-    adaptiveQuantize(embedding: number[], importance?: number): {
-        compressed: number[];
-        metrics: CompressionMetrics;
-    };
-    /**
-     * Progressive compression: automatically promote/demote based on access patterns.
-     *
-     * ADR-065: Multi-level caching:
-     * - L1 (4-bit): Hot embeddings (accessed frequently)
-     * - L2 (8-bit): Warm embeddings (moderate access)
-     * - L3 (16-bit): Cold embeddings (rare access)
-     *
-     * Automatic promotion on cache hits, demotion on age.
-     */
-    progressiveCompress(key: string, embedding: number[], accessCount?: number): {
-        compressed: number[];
-        cacheLevel: 'L1' | 'L2' | 'L3';
-        metrics: CompressionMetrics;
-    };
-    /**
-     * Zero-copy compression using Int8Array for hot paths.
-     *
-     * ADR-065: For frequently accessed embeddings, use typed arrays
-     * to avoid allocation overhead and enable SIMD optimizations.
-     */
-    zeroCopyCompress4Bit(embedding: Float32Array): Int8Array;
-    /**
-     * Measure quality degradation from compression.
-     *
-     * @returns Quality metrics: cosine similarity, MSE, max error
-     */
-    measureQuality(original: number[], compressed: number[]): {
-        cosineSimilarity: number;
-        mse: number;
-        maxError: number;
-    };
-    /**
-     * Get multi-level cache statistics.
-     */
-    getCacheLevels(): CacheLevel[];
-    /**
-     * Compress embeddings using quantization.
-     *
-     * Maps each component to an N-bit integer range then reconstructs
-     * the approximate float value. This reduces memory per vector by
-     * up to 8x (float32 -> 4-bit) while retaining search accuracy.
-     */
-    compressEmbedding(embedding: number[]): number[];
-    /**
-     * Compress a Float32Array embedding (zero-copy friendly).
-     */
-    compressFloat32(embedding: Float32Array): Float32Array;
-    /**
-     * Deduplicate similar embeddings by cosine similarity.
-     *
-     * Scans the list and removes items whose embedding is above
-     * the deduplication threshold compared to an already-kept item.
-     * Keeps the higher-confidence entry when duplicates are found.
-     */
-    deduplicate(embeddings: Array<{
-        id: string;
-        embedding: number[];
-        confidence: number;
-    }>): Array<{
-        id: string;
-        embedding: number[];
-        confidence: number;
-    }>;
-    /**
-     * Identify memories that should be pruned based on confidence and age.
-     *
-     * Returns an array of IDs that are below the minimum confidence
-     * threshold or older than the maximum allowed age.
-     */
-    pruneMemories(memories: Array<{
-        id: string;
-        confidence: number;
-        timestamp: number;
-    }>): string[];
-    /**
-     * Batch embedding generation for 10-100x throughput improvement.
-     *
-     * Queues individual embed requests and flushes them either when
-     * the batch reaches `batchSize` or after `maxWaitMs` milliseconds.
-     * Uses the provided `embedFn` callback for the actual embedding.
-     */
-    batchEmbed(query: string, embedFn: (text: string) => Promise<number[]>): Promise<number[]>;
-    /**
-     * Flush any pending batch items immediately.
-     */
-    flush(embedFn: (text: string) => Promise<number[]>): Promise<void>;
-    /**
-     * Clear the embedding cache.
-     */
-    clearCache(): void;
-    /**
-     * Get optimizer statistics.
-     */
-    getStats(): {
-        config: RVFConfig;
-        cacheSize: number;
-        batchQueueSize: number;
-        multiLevelCache?: {
-            l1: {
-                size: number;
-                hits: number;
-                misses: number;
-                hitRate: number;
-            };
-            l2: {
-                size: number;
-                hits: number;
-                misses: number;
-                hitRate: number;
-            };
-            l3: {
-                size: number;
-                hits: number;
-                misses: number;
-                hitRate: number;
-            };
-        };
-        compressionMetrics?: {
-            avgCompressionRatio: number;
-            avgQualityScore: number;
-            totalCompressed: number;
-        };
-    };
-    private processBatch;
-    private cosineSimilarity;
-}