agentdb 3.0.0-alpha.2 → 3.0.0-alpha.4

package/src/utils/vector-math.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared Vector Math Utilities
+ *
+ * Eliminates 8+ duplicate cosineSimilarity implementations across controllers.
+ * Uses 4x loop unrolling from WASMVectorSearch for best JS performance.
+ * Future: WASM SIMD acceleration via P2.2.
+ */
+
+/**
+ * Cosine similarity with 4x loop unrolling for optimal JS performance.
+ * Handles both number[] and Float32Array inputs.
+ */
+export function cosineSimilarity(a: ArrayLike<number>, b: ArrayLike<number>): number {
+  const len = Math.min(a.length, b.length);
+  if (len === 0) return 0;
+
+  let dot = 0, magA = 0, magB = 0;
+
+  // 4x loop unrolling
+  const unrolled = len - (len % 4);
+  for (let i = 0; i < unrolled; i += 4) {
+    dot  += a[i] * b[i] + a[i+1] * b[i+1] + a[i+2] * b[i+2] + a[i+3] * b[i+3];
+    magA += a[i] * a[i] + a[i+1] * a[i+1] + a[i+2] * a[i+2] + a[i+3] * a[i+3];
+    magB += b[i] * b[i] + b[i+1] * b[i+1] + b[i+2] * b[i+2] + b[i+3] * b[i+3];
+  }
+  // Handle remainder
+  for (let i = unrolled; i < len; i++) {
+    dot  += a[i] * b[i];
+    magA += a[i] * a[i];
+    magB += b[i] * b[i];
+  }
+
+  const denom = Math.sqrt(magA) * Math.sqrt(magB);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+/**
+ * Batch cosine similarity: compute similarity of query against multiple vectors.
+ */
+export function batchCosineSimilarity(query: ArrayLike<number>, corpus: ArrayLike<number>[]): number[] {
+  return corpus.map(vec => cosineSimilarity(query, vec));
+}
+
+/**
+ * Convert distance metric to similarity score (0-1).
+ */
+export function distanceToSimilarity(distance: number, metric: 'cosine' | 'l2' | 'ip' = 'cosine'): number {
+  switch (metric) {
+    case 'cosine': return 1 - distance;
+    case 'l2': return 1 / (1 + distance);
+    case 'ip': return distance; // inner product is already a similarity
+    default: return 1 - distance;
+  }
+}
+
+/**
+ * Serialize embedding to Buffer for storage.
+ */
+export function serializeEmbedding(embedding: Float32Array): Buffer {
+  return Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
+}
+
+/**
+ * Deserialize embedding from Buffer.
+ */
+export function deserializeEmbedding(buffer: Buffer): Float32Array {
+  const ab = new ArrayBuffer(buffer.length);
+  const view = new Uint8Array(ab);
+  for (let i = 0; i < buffer.length; i++) view[i] = buffer[i];
+  return new Float32Array(ab);
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024-2025 ruv
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/dist/src/backends/rvf/AdaptiveIndexTuner.d.ts

@@ -1,175 +0,0 @@
-/**
- * AdaptiveIndexTuner - Self-Learning Index & Memory Management for AgentDB
- *
- * Provides:
- * - Adaptive HNSW index monitoring via indexStats() + performance tracking
- * - Temporal memory decay via @ruvector/gnn TensorCompress
- * - Thompson Sampling query strategy selection via AgentDBSolver
- *
- * Security:
- * - TensorCompress operates on embeddings only (lossless reversible)
- * - All bounds checked (frequency 0-1, compression levels validated)
- * - No file I/O (operates on in-memory vectors)
- */
-import type { IndexStats } from './RvfBackend.js';
-import type { SolverBandit } from './SolverBandit.js';
-/** Compression tier for temporal memory decay */
-export type CompressionTier = 'none' | 'half' | 'pq8' | 'pq4' | 'binary';
-/** Compressed vector entry */
-export interface CompressedEntry {
-    id: string;
-    compressedJson: string;
-    tier: CompressionTier;
-    originalDim: number;
-    accessFrequency: number;
-    lastAccessed: number;
-    /** Matryoshka truncated dimension (SOTA: MRL truncation) */
-    truncatedDim?: number;
-}
-/** Index health assessment */
-export interface IndexHealth {
-    healthy: boolean;
-    indexedVectors: number;
-    layers: number;
-    needsRebuild: boolean;
-    avgSearchMs: number;
-    avgInsertMs: number;
-    recommendations: string[];
-}
-/** Compression statistics */
-export interface CompressionStats {
-    totalEntries: number;
-    byTier: Record<CompressionTier, number>;
-    estimatedSavingsPercent: number;
-}
-/**
- * TemporalCompressor - Access-frequency-based vector compression
- *
- * Uses tiered JSON compression for progressive compression of
- * aged embeddings. Hot data stays uncompressed, cold data is compressed
- * to save memory while remaining decompressible on demand.
- *
- * Compression tiers:
- * - none (freq >= 0.8): Full Float32Array stored
- * - half (freq >= 0.6): Float16-quantized
- * - pq8 (freq >= 0.4): 8-bit scalar quantization
- * - pq4 (freq >= 0.2): 4-bit scalar quantization
- * - binary (freq < 0.2): 1-bit sign encoding
- */
-export declare class TemporalCompressor {
-    private entries;
-    private _destroyed;
-    private accel;
-    private bandit;
-    /**
-     * Create a new temporal compressor.
-     * Lazy-loads NativeAccelerator for native compression when available.
-     */
-    static create(bandit?: SolverBandit): Promise<TemporalCompressor>;
-    /**
-     * Always available (built-in compression).
-     */
-    static isAvailable(): Promise<boolean>;
-    /** Whether native tensor compression is available (ADR-007 Phase 1) */
-    get nativeCompressAvailable(): boolean;
-    /**
-     * Compress a vector based on its access frequency.
-     * Uses Matryoshka-style dimensional truncation for cold tiers (SOTA: MRL).
-     * ADR-007 Phase 1: delegates to NativeAccelerator tensorCompress when available.
-     *
-     * @param id - Unique identifier for this entry
-     * @param embedding - The vector to compress
-     * @param accessFrequency - Access frequency in [0.0, 1.0] (1.0 = hot)
-     */
-    compress(id: string, embedding: Float32Array, accessFrequency: number): CompressedEntry;
-    /**
-     * Batch compress multiple vectors (ADR-007 Phase 1).
-     * Uses NativeAccelerator.tensorBatchCompress when available.
-     */
-    compressBatch(items: Array<{
-        id: string;
-        embedding: Float32Array;
-        accessFrequency: number;
-    }>): CompressedEntry[];
-    /**
-     * Decompress a vector back to its original form.
-     * Matryoshka-truncated vectors are zero-padded to original dimension.
-     */
-    decompress(id: string): Float32Array | null;
-    /**
-     * Decompress from raw compressed JSON with known tier and dimension.
-     */
-    decompressRaw(compressedJson: string, tier: CompressionTier, dim: number): Float32Array;
-    /**
-     * Update the access frequency for an entry and recompress if tier changed.
-     */
-    updateFrequency(id: string, newFrequency: number): CompressionTier | null;
-    /**
-     * Get compression statistics.
-     */
-    getStats(): CompressionStats;
-    /** Check if an entry exists */
-    has(id: string): boolean;
-    /** Remove an entry */
-    remove(id: string): boolean;
-    /** Get number of compressed entries */
-    get size(): number;
-    /** Check if destroyed */
-    get isDestroyed(): boolean;
-    /** Destroy the compressor */
-    destroy(): void;
-    /** Map compression tier to native level (0-4) */
-    private tierToLevel;
-    /** Encode Uint8Array to base64 string */
-    private toBase64;
-    /** Decode base64 string to Uint8Array */
-    private fromBase64;
-    private compressVector;
-    private decompressVector;
-    private frequencyToTier;
-    /**
-     * Matryoshka-style dimensional truncation (SOTA: MRL).
-     * For cold tiers, store only leading dimensions. Matryoshka-trained
-     * embeddings concentrate information in early dimensions, so truncation
-     * preserves more semantic content than quantization at equal byte cost.
-     *
-     * Truncation ratios: none=100%, half=100%, pq8=75%, pq4=50%, binary=25%
-     */
-    /**
-     * Matryoshka-style dimensional truncation ratios (SOTA: MRL).
-     *
-     * Only the most aggressive tier (binary) gets truncation. pq8/pq4 keep full
-     * dimensions because their quantization error alone is already significant
-     * and truncation on non-MRL-trained embeddings compounds error too aggressively.
-     * Binary tier has a generous tolerance (1.0) so truncation to 50% is safe.
-     */
-    private matryoshkaDim;
-    private ensureAlive;
-}
-/**
- * IndexHealthMonitor - Adaptive HNSW index health monitoring
- *
- * Tracks index statistics and query performance to recommend
- * parameter adjustments and rebuild triggers.
- */
-export declare class IndexHealthMonitor {
-    private searchLatencies;
-    private insertLatencies;
-    private readonly maxSamples;
-    /**
-     * Record a search latency sample (in milliseconds).
-     */
-    recordSearch(latencyMs: number): void;
-    /**
-     * Record an insert latency sample (in milliseconds).
-     */
-    recordInsert(latencyMs: number): void;
-    /**
-     * Assess index health based on stats and recorded latencies.
-     */
-    assess(stats: IndexStats): IndexHealth;
-    /** Reset all recorded samples */
-    reset(): void;
-    private average;
-}
-//# sourceMappingURL=AdaptiveIndexTuner.d.ts.map

package/dist/src/backends/rvf/AdaptiveIndexTuner.d.ts.map

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