agentdb 1.0.0

package/dist/cli/index/hnsw.d.ts

@@ -0,0 +1,164 @@
+/**
+ * HNSW (Hierarchical Navigable Small World) Index Implementation
+ * High-performance approximate nearest neighbor search with O(log n) complexity
+ *
+ * Algorithm: Hierarchical graph structure with multiple layers
+ * - Layer 0: All vectors with dense connections
+ * - Higher layers: Sparse long-range connections for efficient navigation
+ *
+ * Performance targets:
+ * - Search: <10ms for 10K vectors
+ * - Build: <5s for 10K vectors
+ * - Recall: >95% accuracy
+ */
+import Database from 'better-sqlite3';
+/**
+ * HNSW configuration parameters
+ */
+export interface HNSWConfig {
+    /** Maximum number of bi-directional links per element (default: 16) */
+    M: number;
+    /** Maximum connections for layer 0 (default: M * 2) */
+    M0: number;
+    /** Size of dynamic candidate list during construction (default: 200) */
+    efConstruction: number;
+    /** Size of dynamic candidate list during search (default: 50) */
+    efSearch: number;
+    /** Random level generation parameter (default: 1 / ln(M)) */
+    mL: number;
+    /** Minimum vectors to enable index (default: 1000) */
+    minVectorsForIndex: number;
+    /** Auto-rebuild index on updates (default: false) */
+    autoRebuild: boolean;
+    /** Enable index usage (default: true) */
+    enabled: boolean;
+}
+/**
+ * Default HNSW configuration optimized for most use cases
+ */
+export declare const DEFAULT_HNSW_CONFIG: HNSWConfig;
+/**
+ * Search result with distance
+ */
+interface HNSWSearchResult {
+    id: string;
+    vectorId: string;
+    distance: number;
+    embedding: number[];
+}
+/**
+ * HNSW Index implementation
+ */
+export declare class HNSWIndex {
+    private db;
+    private config;
+    private entryPoint;
+    private maxLevel;
+    private isBuilt;
+    private insertNodeStmt;
+    private insertEdgeStmt;
+    private getNodeStmt;
+    private getNeighborsStmt;
+    private deleteNodeStmt;
+    private deleteEdgesStmt;
+    constructor(db: Database.Database, config?: Partial<HNSWConfig>);
+    /**
+     * Initialize HNSW schema in SQLite
+     */
+    private initializeSchema;
+    /**
+     * Prepare frequently used SQL statements
+     */
+    private prepareStatements;
+    /**
+     * Load metadata from database
+     */
+    private loadMetadata;
+    /**
+     * Save metadata to database
+     */
+    private saveMetadata;
+    /**
+     * Calculate random level for new node using exponential decay
+     */
+    private randomLevel;
+    /**
+     * Calculate Euclidean distance between two vectors
+     */
+    private calculateDistance;
+    /**
+     * Serialize embedding to Buffer
+     */
+    private serializeEmbedding;
+    /**
+     * Deserialize embedding from Buffer
+     */
+    private deserializeEmbedding;
+    /**
+     * Get node by ID
+     */
+    private getNode;
+    /**
+     * Get neighbors of a node at a specific level
+     */
+    private getNeighbors;
+    /**
+     * Search for k nearest neighbors at a specific layer
+     */
+    private searchLayer;
+    /**
+     * Select neighbors using heuristic (Alg 4 from HNSW paper)
+     */
+    private selectNeighborsHeuristic;
+    /**
+     * Add bidirectional link between nodes
+     */
+    private addEdge;
+    /**
+     * Insert a new node into the HNSW index (optimized version)
+     */
+    insert(vectorId: string, embedding: number[]): void;
+    /**
+     * Search for k nearest neighbors using HNSW index
+     */
+    search(query: number[], k: number): HNSWSearchResult[];
+    /**
+     * Build HNSW index from all vectors in database with optimizations
+     */
+    build(): void;
+    /**
+     * Build index incrementally (non-blocking for large datasets)
+     */
+    buildAsync(onProgress?: (current: number, total: number, timeMs: number) => void): Promise<void>;
+    /**
+     * Clear the entire index
+     */
+    clear(): void;
+    /**
+     * Delete a node from the index
+     */
+    delete(vectorId: string): void;
+    /**
+     * Get index statistics
+     */
+    getStats(): {
+        nodeCount: number;
+        edgeCount: number;
+        maxLevel: number;
+        isBuilt: boolean;
+        avgDegree: number;
+    };
+    /**
+     * Check if index is ready to use
+     */
+    isReady(): boolean;
+    /**
+     * Get configuration
+     */
+    getConfig(): HNSWConfig;
+    /**
+     * Update configuration (requires rebuild)
+     */
+    updateConfig(config: Partial<HNSWConfig>): void;
+}
+export {};