agentdb 3.0.0-alpha.9 → 3.1.0

package/dist/src/simd/simd-vector-ops.d.ts

@@ -0,0 +1,343 @@
+/**
+ * SIMD-Accelerated Vector Operations for AgentDB
+ *
+ * High-performance vector operations with WebAssembly SIMD acceleration.
+ * Provides 2-8x speedup over standard JavaScript implementations through:
+ * - 8x loop unrolling with separate accumulators for Instruction-Level Parallelism (ILP)
+ * - Pre-allocated buffer pools to minimize GC pressure
+ * - SIMD detection and graceful fallback to optimized scalar code
+ * - Batch operations for cache-friendly memory access patterns
+ *
+ * @module simd-vector-ops
+ */
+/** @inline Maximum allowed vector dimension to prevent DoS via large allocations */
+export declare const MAX_VECTOR_DIMENSION = 4096;
+/** @inline Maximum batch size for optimal cache utilization */
+export declare const MAX_BATCH_SIZE = 10000;
+/** @inline Default cache size for embedding storage */
+export declare const DEFAULT_CACHE_SIZE = 10000;
+/**
+ * Configuration options for SIMD vector operations
+ */
+export interface SIMDConfig {
+    /** Enable SIMD acceleration (auto-detected if not specified) */
+    enableSIMD?: boolean;
+    /** Size of pre-allocated buffer pool */
+    bufferPoolSize?: number;
+    /** Default vector dimension for buffer allocation */
+    defaultDimension?: number;
+    /** Enable performance logging */
+    enableLogging?: boolean;
+}
+/**
+ * Result of batch similarity computation
+ */
+export interface BatchSimilarityResult {
+    /** Index in the original vector array */
+    index: number;
+    /** Cosine similarity score [-1, 1] */
+    similarity: number;
+    /** Euclidean distance (L2 norm) */
+    distance?: number;
+}
+/**
+ * Statistics about SIMD operations
+ */
+export interface SIMDStats {
+    /** Whether SIMD is available and enabled */
+    simdEnabled: boolean;
+    /** Number of vectors processed */
+    vectorsProcessed: number;
+    /** Total operations performed */
+    operationsCount: number;
+    /** Buffers currently in pool */
+    buffersInPool: number;
+    /** Peak buffer usage */
+    peakBufferUsage: number;
+}
+/**
+ * Detect WebAssembly SIMD support
+ *
+ * This function caches the result after first call for performance.
+ * The detection is done by validating a minimal WASM module containing
+ * SIMD instructions.
+ *
+ * @returns true if SIMD is supported, false otherwise
+ */
+export declare function detectSIMDSupport(): boolean;
+/**
+ * Alternative SIMD detection using the simpler v128.const check
+ * This is the same check used in WASMVectorSearch for consistency
+ */
+export declare function detectSIMDSupportLegacy(): boolean;
+/**
+ * Calculate cosine similarity with 8x loop unrolling and ILP
+ *
+ * Uses 8 separate accumulators to maximize instruction-level parallelism.
+ * Modern CPUs can execute multiple independent operations in parallel,
+ * and separate accumulators prevent data dependencies between iterations.
+ *
+ * Performance characteristics:
+ * - 8x unrolling reduces loop overhead by 87.5%
+ * - Separate accumulators enable out-of-order execution
+ * - Final reduction combines accumulators efficiently
+ *
+ * @param a - First vector (Float32Array)
+ * @param b - Second vector (Float32Array)
+ * @returns Cosine similarity in range [-1, 1]
+ * @throws Error if vectors have different lengths
+ */
+export declare function cosineSimilaritySIMD(a: Float32Array, b: Float32Array): number;
+/**
+ * Squared L2 norm accumulated in the same 8 lanes as cosineSimilaritySIMD,
+ * so cosineSimilarityWithNormsSIMD(a, b, squaredNormSIMD(a), squaredNormSIMD(b))
+ * is bit-identical to cosineSimilaritySIMD(a, b). Cache it per stored vector.
+ */
+export declare function squaredNormSIMD(v: Float32Array): number;
+/**
+ * cosineSimilaritySIMD with both squared norms supplied (see squaredNormSIMD):
+ * only the dot product is computed per call. Same validation, guards and clamp.
+ */
+export declare function cosineSimilarityWithNormsSIMD(a: Float32Array, b: Float32Array, normASq: number, normBSq: number): number;
+/**
+ * Calculate Euclidean (L2) distance with 8x loop unrolling
+ *
+ * Uses the same ILP optimization as cosine similarity.
+ *
+ * @param a - First vector (Float32Array)
+ * @param b - Second vector (Float32Array)
+ * @returns Euclidean distance (non-negative)
+ * @throws Error if vectors have different lengths
+ */
+export declare function euclideanDistanceSIMD(a: Float32Array, b: Float32Array): number;
+/**
+ * Calculate squared Euclidean distance (faster than euclideanDistanceSIMD)
+ *
+ * Useful when you only need to compare distances (skip the sqrt).
+ *
+ * @param a - First vector
+ * @param b - Second vector
+ * @returns Squared Euclidean distance
+ */
+export declare function euclideanDistanceSquaredSIMD(a: Float32Array, b: Float32Array): number;
+/**
+ * Calculate dot product with 8x loop unrolling
+ *
+ * @param a - First vector
+ * @param b - Second vector
+ * @returns Dot product
+ */
+export declare function dotProductSIMD(a: Float32Array, b: Float32Array): number;
+/**
+ * Calculate L2 norm (magnitude) of a vector with 8x unrolling
+ *
+ * @param v - Input vector
+ * @returns L2 norm
+ */
+export declare function l2NormSIMD(v: Float32Array): number;
+/**
+ * Normalize a vector to unit length (in-place)
+ *
+ * @param v - Vector to normalize (modified in-place)
+ * @returns The same vector, normalized
+ */
+export declare function normalizeVectorInPlace(v: Float32Array): Float32Array;
+/**
+ * Create a normalized copy of a vector
+ *
+ * @param v - Input vector
+ * @returns New normalized vector
+ */
+export declare function normalizeVector(v: Float32Array): Float32Array;
+/**
+ * Batch cosine similarity calculation with early termination optimization
+ *
+ * Efficiently computes similarities between a query vector and multiple
+ * candidate vectors. Uses cache-friendly memory access patterns.
+ *
+ * @inline V8 optimization hint - hot path function
+ * @param query - Query vector
+ * @param vectors - Array of candidate vectors
+ * @param options - Optional configuration
+ * @returns Array of similarity scores (same order as input vectors)
+ */
+export declare function batchCosineSimilarity(query: Float32Array, vectors: Float32Array[], options?: {
+    /** Return only top-k results (sorted by similarity) */
+    topK?: number;
+    /** Minimum similarity threshold */
+    threshold?: number;
+    /** Early termination when this many perfect matches found */
+    earlyTerminationThreshold?: number;
+}): BatchSimilarityResult[];
+/**
+ * Batch Euclidean distance calculation with early termination
+ *
+ * @inline V8 optimization hint - hot path function
+ * @param query - Query vector
+ * @param vectors - Array of candidate vectors
+ * @param options - Optional configuration
+ * @returns Array of distance results (same order as input vectors)
+ */
+export declare function batchEuclideanDistance(query: Float32Array, vectors: Float32Array[], options?: {
+    /** Return only top-k results (sorted by distance, ascending) */
+    topK?: number;
+    /** Maximum distance threshold */
+    maxDistance?: number;
+    /** Use squared distance (faster, useful for comparisons) */
+    squared?: boolean;
+    /** Early termination distance threshold */
+    earlyTerminationDistance?: number;
+}): BatchSimilarityResult[];
+/**
+ * SIMD-accelerated vector operations manager
+ *
+ * Provides a stateful wrapper around vector operations with:
+ * - Automatic SIMD detection
+ * - Pre-allocated buffer pools
+ * - Operation statistics tracking
+ * - Configurable behavior
+ */
+export declare class SIMDVectorOps {
+    private config;
+    private simdEnabled;
+    private bufferPool;
+    private stats;
+    constructor(config?: SIMDConfig);
+    /**
+     * Calculate cosine similarity between two vectors
+     */
+    cosineSimilarity(a: Float32Array, b: Float32Array): number;
+    /**
+     * Calculate Euclidean distance between two vectors
+     */
+    euclideanDistance(a: Float32Array, b: Float32Array): number;
+    /**
+     * Calculate squared Euclidean distance (faster for comparisons)
+     */
+    euclideanDistanceSquared(a: Float32Array, b: Float32Array): number;
+    /**
+     * Calculate dot product
+     */
+    dotProduct(a: Float32Array, b: Float32Array): number;
+    /**
+     * Calculate L2 norm
+     */
+    l2Norm(v: Float32Array): number;
+    /**
+     * Normalize a vector (creates a copy)
+     */
+    normalize(v: Float32Array): Float32Array;
+    /**
+     * Normalize a vector in place
+     */
+    normalizeInPlace(v: Float32Array): Float32Array;
+    /**
+     * Batch cosine similarity
+     */
+    batchCosineSimilarity(query: Float32Array, vectors: Float32Array[], options?: {
+        topK?: number;
+        threshold?: number;
+    }): BatchSimilarityResult[];
+    /**
+     * Batch Euclidean distance
+     */
+    batchEuclideanDistance(query: Float32Array, vectors: Float32Array[], options?: {
+        topK?: number;
+        maxDistance?: number;
+        squared?: boolean;
+    }): BatchSimilarityResult[];
+    /**
+     * Acquire a temporary buffer from the pool
+     */
+    acquireBuffer(size?: number): Float32Array;
+    /**
+     * Release a buffer back to the pool
+     */
+    releaseBuffer(buffer: Float32Array): void;
+    /**
+     * Get operation statistics
+     */
+    getStats(): SIMDStats;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+    /**
+     * Check if SIMD is enabled
+     */
+    isSIMDEnabled(): boolean;
+    /**
+     * Clear buffer pools
+     */
+    clearBufferPool(): void;
+}
+/**
+ * Create a Float32Array from various input types
+ *
+ * @param data - Input data (array of numbers, ArrayBuffer, or existing Float32Array)
+ * @returns Float32Array
+ */
+export declare function toFloat32Array(data: number[] | ArrayBuffer | Float32Array | ArrayLike<number>): Float32Array;
+/**
+ * Create random unit vector for testing
+ *
+ * @param dimension - Vector dimension
+ * @returns Normalized random vector
+ */
+export declare function randomUnitVector(dimension: number): Float32Array;
+/**
+ * Vector addition with 8x unrolling
+ *
+ * @param a - First vector
+ * @param b - Second vector
+ * @param out - Optional output buffer (creates new if not provided)
+ * @returns Result vector (a + b)
+ */
+export declare function vectorAdd(a: Float32Array, b: Float32Array, out?: Float32Array): Float32Array;
+/**
+ * Vector subtraction with 8x unrolling
+ *
+ * @param a - First vector
+ * @param b - Second vector
+ * @param out - Optional output buffer
+ * @returns Result vector (a - b)
+ */
+export declare function vectorSub(a: Float32Array, b: Float32Array, out?: Float32Array): Float32Array;
+/**
+ * Scalar multiplication with 8x unrolling
+ *
+ * @param v - Input vector
+ * @param scalar - Scalar multiplier
+ * @param out - Optional output buffer
+ * @returns Result vector (v * scalar)
+ */
+export declare function vectorScale(v: Float32Array, scalar: number, out?: Float32Array): Float32Array;
+/**
+ * Default SIMD vector operations instance
+ *
+ * Pre-configured with sensible defaults. For custom configuration,
+ * create a new SIMDVectorOps instance.
+ */
+export declare const defaultSIMDOps: SIMDVectorOps;
+declare const _default: {
+    cosineSimilaritySIMD: typeof cosineSimilaritySIMD;
+    euclideanDistanceSIMD: typeof euclideanDistanceSIMD;
+    euclideanDistanceSquaredSIMD: typeof euclideanDistanceSquaredSIMD;
+    dotProductSIMD: typeof dotProductSIMD;
+    l2NormSIMD: typeof l2NormSIMD;
+    normalizeVector: typeof normalizeVector;
+    normalizeVectorInPlace: typeof normalizeVectorInPlace;
+    batchCosineSimilarity: typeof batchCosineSimilarity;
+    batchEuclideanDistance: typeof batchEuclideanDistance;
+    vectorAdd: typeof vectorAdd;
+    vectorSub: typeof vectorSub;
+    vectorScale: typeof vectorScale;
+    toFloat32Array: typeof toFloat32Array;
+    randomUnitVector: typeof randomUnitVector;
+    detectSIMDSupport: typeof detectSIMDSupport;
+    detectSIMDSupportLegacy: typeof detectSIMDSupportLegacy;
+    SIMDVectorOps: typeof SIMDVectorOps;
+    defaultSIMDOps: SIMDVectorOps;
+};
+export default _default;
+//# sourceMappingURL=simd-vector-ops.d.ts.map

package/dist/src/simd/simd-vector-ops.d.ts.map

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