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

package/dist/src/quantization/vector-quantization.d.ts

@@ -1,388 +0,0 @@
-/**
- * Vector Quantization for AgentDB
- *
- * Provides memory-efficient vector storage through quantization techniques:
- *
- * 1. Scalar Quantization (8-bit and 4-bit)
- *    - 8-bit: 4x memory reduction (Float32 -> Uint8)
- *    - 4-bit: 8x memory reduction (Float32 -> 4-bit packed)
- *
- * 2. Product Quantization
- *    - Configurable subspaces and centroids
- *    - Higher compression ratios (up to 32x+)
- *    - Requires training on representative data
- *
- * 3. QuantizedVectorStore
- *    - Wraps vector collections with quantized storage
- *    - Asymmetric distance computation (full precision queries)
- *    - On-the-fly dequantization for similarity calculations
- */
-/** @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;
-/**
- * Statistics for quantization operations
- */
-export interface QuantizationStats {
-    /** Minimum value in the original vector */
-    min: number;
-    /** Maximum value in the original vector */
-    max: number;
-    /** Mean quantization error (per element) */
-    meanError?: number;
-    /** Maximum quantization error (per element) */
-    maxError?: number;
-    /** Compression ratio achieved */
-    compressionRatio: number;
-}
-/**
- * Quantized vector with metadata for dequantization
- */
-export interface QuantizedVector {
-    /** The quantized data */
-    data: Uint8Array;
-    /** Minimum value used for quantization */
-    min: number;
-    /** Maximum value used for quantization */
-    max: number;
-    /** Original vector dimension */
-    dimension: number;
-    /** Quantization type */
-    type: '8bit' | '4bit';
-}
-/**
- * Configuration for Product Quantizer
- */
-export interface ProductQuantizerConfig {
-    /** Vector dimension (must be divisible by numSubspaces) */
-    dimension: number;
-    /** Number of subspaces to divide the vector into */
-    numSubspaces: number;
-    /** Number of centroids per subspace (max 256 for uint8 codes) */
-    numCentroids: number;
-    /** Maximum iterations for k-means training */
-    maxIterations?: number;
-    /** Convergence threshold for k-means */
-    convergenceThreshold?: number;
-    /** Seed for reproducible random initialization */
-    seed?: number;
-}
-/**
- * Encoded vector from Product Quantization
- */
-export interface PQEncodedVector {
-    /** Centroid indices for each subspace */
-    codes: Uint8Array;
-    /** Original vector norm (for normalized distance computation) */
-    norm: number;
-}
-/**
- * Configuration for QuantizedVectorStore
- */
-export interface QuantizedVectorStoreConfig {
-    /** Vector dimension */
-    dimension: number;
-    /** Quantization method to use */
-    quantizationType: 'scalar8bit' | 'scalar4bit' | 'product';
-    /** Product quantization config (required if quantizationType is 'product') */
-    productQuantizerConfig?: Omit<ProductQuantizerConfig, 'dimension'>;
-    /** Distance metric for similarity calculations */
-    metric?: 'cosine' | 'l2' | 'ip';
-}
-/**
- * Search result from QuantizedVectorStore
- */
-export interface QuantizedSearchResult {
-    /** Vector ID */
-    id: string;
-    /** Distance (lower is more similar for L2, higher for cosine/IP) */
-    distance: number;
-    /** Normalized similarity score (0-1, higher is more similar) */
-    similarity: number;
-    /** Optional metadata */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Quantize a vector to 8-bit values (4x memory reduction)
- *
- * Formula: quantized = round((value - min) / (max - min) * 255)
- *
- * @param vector - Input vector as Float32Array
- * @returns Object containing quantized data and min/max for dequantization
- */
-export declare function quantize8bit(vector: Float32Array): QuantizedVector;
-/**
- * Quantize a vector to 4-bit values (8x memory reduction)
- *
- * Formula: quantized = round((value - min) / (max - min) * 15)
- * Two 4-bit values are packed into each byte.
- *
- * @param vector - Input vector as Float32Array
- * @returns Object containing quantized data (packed) and min/max for dequantization
- */
-export declare function quantize4bit(vector: Float32Array): QuantizedVector;
-/**
- * Dequantize an 8-bit vector back to Float32
- *
- * @param quantized - Quantized data as Uint8Array
- * @param min - Minimum value from original quantization
- * @param max - Maximum value from original quantization
- * @returns Reconstructed Float32Array
- */
-export declare function dequantize8bit(quantized: Uint8Array, min: number, max: number): Float32Array;
-/**
- * Dequantize a 4-bit packed vector back to Float32
- *
- * @param quantized - Packed quantized data as Uint8Array
- * @param min - Minimum value from original quantization
- * @param max - Maximum value from original quantization
- * @param originalLength - Original vector length (needed due to packing)
- * @returns Reconstructed Float32Array
- */
-export declare function dequantize4bit(quantized: Uint8Array, min: number, max: number, originalLength?: number): Float32Array;
-/**
- * Calculate quantization error statistics
- *
- * @param original - Original vector
- * @param reconstructed - Reconstructed vector after quantization/dequantization
- * @returns Statistics about the quantization error
- */
-export declare function calculateQuantizationError(original: Float32Array, reconstructed: Float32Array): {
-    meanError: number;
-    maxError: number;
-    mse: number;
-};
-/**
- * Get quantization statistics for a vector
- *
- * @param vector - Original vector
- * @param type - Quantization type ('8bit' or '4bit')
- * @returns Quantization statistics including error metrics
- */
-export declare function getQuantizationStats(vector: Float32Array, type: '8bit' | '4bit'): QuantizationStats;
-/**
- * Product Quantizer for high compression ratios
- *
- * Divides vectors into subspaces and learns centroids for each subspace.
- * Vectors are encoded as indices into the centroid codebooks.
- */
-export declare class ProductQuantizer {
-    private config;
-    private subspaceDim;
-    private codebooks;
-    private trained;
-    private rng;
-    constructor(config: ProductQuantizerConfig);
-    /**
-     * Train the codebooks using k-means clustering
-     *
-     * @param vectors - Training vectors (should be representative of the data)
-     */
-    train(vectors: Float32Array[]): Promise<void>;
-    /**
-     * K-means clustering with k-means++ initialization
-     */
-    private kMeans;
-    /**
-     * K-means++ initialization for better centroid selection
-     */
-    private kMeansPlusPlus;
-    /**
-     * Encode a vector using the trained codebooks
-     *
-     * @param vector - Vector to encode
-     * @returns Encoded vector with centroid codes and norm
-     */
-    encode(vector: Float32Array): PQEncodedVector;
-    /**
-     * Decode an encoded vector (approximate reconstruction)
-     *
-     * @param encoded - Encoded vector
-     * @returns Reconstructed Float32Array
-     */
-    decode(encoded: PQEncodedVector): Float32Array;
-    /**
-     * Compute asymmetric distance between a query and encoded vector
-     * Query is in full precision, database vector is encoded
-     *
-     * @param query - Full precision query vector
-     * @param encoded - Encoded database vector
-     * @returns Squared L2 distance
-     */
-    asymmetricDistance(query: Float32Array, encoded: PQEncodedVector): number;
-    /**
-     * Precompute distance tables for efficient batch search
-     * Tables[s][c] = squared distance from query subvector s to centroid c
-     *
-     * @param query - Query vector
-     * @returns Distance lookup tables for each subspace
-     */
-    precomputeDistanceTables(query: Float32Array): Float32Array[];
-    /**
-     * Compute distance using precomputed tables (very fast)
-     *
-     * @param tables - Precomputed distance tables from precomputeDistanceTables()
-     * @param encoded - Encoded vector
-     * @returns Squared L2 distance
-     */
-    distanceFromTables(tables: Float32Array[], encoded: PQEncodedVector): number;
-    /**
-     * Get compression ratio
-     */
-    getCompressionRatio(): number;
-    /**
-     * Get quantizer statistics
-     */
-    getStats(): {
-        trained: boolean;
-        dimension: number;
-        numSubspaces: number;
-        subspaceDim: number;
-        numCentroids: number;
-        compressionRatio: number;
-        codebookSizeBytes: number;
-    };
-    /**
-     * Export codebooks for persistence
-     */
-    exportCodebooks(): string;
-    /**
-     * Import codebooks from persisted data
-     * Includes validation to prevent prototype pollution and type confusion
-     */
-    importCodebooks(json: string): void;
-    /**
-     * Check if the quantizer is trained
-     */
-    isTrained(): boolean;
-    /**
-     * Squared L2 distance utility
-     */
-    private squaredL2Distance;
-}
-/**
- * QuantizedVectorStore - Memory-efficient vector storage
- *
- * Wraps vector collections with quantized storage while providing
- * full-precision query support through asymmetric distance computation.
- */
-export declare class QuantizedVectorStore {
-    private config;
-    private vectors;
-    private productQuantizer;
-    constructor(config: QuantizedVectorStoreConfig);
-    /**
-     * Train the product quantizer (required for 'product' quantization type)
-     *
-     * @param vectors - Training vectors
-     */
-    train(vectors: Float32Array[]): Promise<void>;
-    /**
-     * Check if the store is ready for insertions
-     */
-    isReady(): boolean;
-    /**
-     * Insert a vector into the store
-     *
-     * @param id - Unique identifier
-     * @param vector - Vector to store
-     * @param metadata - Optional metadata
-     */
-    insert(id: string, vector: Float32Array, metadata?: Record<string, unknown>): void;
-    /**
-     * Insert multiple vectors in batch
-     *
-     * @param items - Array of {id, vector, metadata}
-     */
-    insertBatch(items: Array<{
-        id: string;
-        vector: Float32Array;
-        metadata?: Record<string, unknown>;
-    }>): void;
-    /**
-     * Search for nearest neighbors
-     * Uses asymmetric distance computation: query in full precision,
-     * database vectors in quantized form.
-     *
-     * @param query - Query vector (full precision)
-     * @param k - Number of results to return
-     * @param threshold - Optional similarity threshold
-     * @returns Sorted search results (most similar first)
-     */
-    search(query: Float32Array, k: number, threshold?: number): QuantizedSearchResult[];
-    /**
-     * Remove a vector by ID
-     *
-     * @param id - Vector ID to remove
-     * @returns true if removed, false if not found
-     */
-    remove(id: string): boolean;
-    /**
-     * Get a dequantized vector by ID
-     *
-     * @param id - Vector ID
-     * @returns Reconstructed vector or null if not found
-     */
-    getVector(id: string): Float32Array | null;
-    /**
-     * Get store statistics
-     */
-    getStats(): {
-        count: number;
-        dimension: number;
-        quantizationType: string;
-        metric: string;
-        compressionRatio: number;
-        memoryUsageBytes: number;
-        productQuantizerStats?: ReturnType<ProductQuantizer['getStats']>;
-    };
-    /**
-     * Clear all vectors
-     */
-    clear(): void;
-    /**
-     * Export store to JSON (for persistence)
-     */
-    export(): string;
-    /**
-     * Import store from JSON
-     */
-    import(json: string): void;
-    /**
-     * Compute asymmetric distance (query full precision, database quantized)
-     */
-    private computeAsymmetricDistance;
-    /**
-     * Dequantize a stored vector
-     */
-    private dequantizeStored;
-    /**
-     * Normalize a vector to unit length
-     */
-    private normalize;
-    /**
-     * Squared L2 distance
-     */
-    private squaredL2Distance;
-}
-/**
- * Create an 8-bit scalar quantized vector store (4x compression)
- */
-export declare function createScalar8BitStore(dimension: number, metric?: 'cosine' | 'l2' | 'ip'): QuantizedVectorStore;
-/**
- * Create a 4-bit scalar quantized vector store (8x compression)
- */
-export declare function createScalar4BitStore(dimension: number, metric?: 'cosine' | 'l2' | 'ip'): QuantizedVectorStore;
-/**
- * Create a product quantized vector store (configurable compression)
- *
- * @param dimension - Vector dimension
- * @param numSubspaces - Number of subspaces (8, 16, 32, 64 typical)
- * @param numCentroids - Number of centroids per subspace (256 max for uint8)
- * @param metric - Distance metric
- */
-export declare function createProductQuantizedStore(dimension: number, numSubspaces?: number, numCentroids?: number, metric?: 'cosine' | 'l2' | 'ip'): QuantizedVectorStore;
-//# sourceMappingURL=vector-quantization.d.ts.map

package/dist/src/quantization/vector-quantization.d.ts.map

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