agentdb 1.0.0

package/dist/core/vector-db.js

@@ -0,0 +1,266 @@
+"use strict";
+/**
+ * Core SQLiteVector database implementation with backend abstraction
+ * Supports both native (better-sqlite3) and WASM (sql.js) backends
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQLiteVectorDB = void 0;
+const backend_interface_1 = require("./backend-interface");
+const native_backend_1 = require("./native-backend");
+const wasm_backend_1 = require("./wasm-backend");
+const query_cache_1 = require("../cache/query-cache");
+const product_quantization_1 = require("../quantization/product-quantization");
+const query_builder_1 = require("../query/query-builder");
+class SQLiteVectorDB {
+    constructor(config = {}) {
+        // If path is provided but memoryMode not specified, default to file mode
+        if (config.path && config.memoryMode === undefined) {
+            config.memoryMode = false;
+        }
+        // Determine backend type
+        this.backendType = this.detectBackend(config);
+        // Create appropriate backend
+        this.backend = this.createBackend(this.backendType);
+        // Initialize query cache if enabled
+        if (config.queryCache?.enabled !== false) {
+            this.queryCache = new query_cache_1.QueryCache(config.queryCache);
+        }
+        // Initialize quantizer if enabled
+        if (config.quantization?.enabled) {
+            this.quantizer = new product_quantization_1.ProductQuantizer(config.quantization);
+        }
+        // Initialize backend
+        if (this.backendType === backend_interface_1.BackendType.WASM) {
+            // WASM backend requires async initialization
+            // Store config for later async init
+            this.backend._pendingConfig = config;
+        }
+        else {
+            // Native backend can initialize synchronously
+            this.backend.initialize(config);
+        }
+    }
+    /**
+     * Detect appropriate backend based on environment and configuration
+     */
+    detectBackend(config) {
+        // Explicit backend selection
+        if (config.backend) {
+            return config.backend;
+        }
+        // Auto-detect based on environment
+        if (typeof window !== 'undefined' || typeof process === 'undefined') {
+            // Browser environment
+            return backend_interface_1.BackendType.WASM;
+        }
+        // Node.js environment - check if better-sqlite3 is available
+        try {
+            require.resolve('better-sqlite3');
+            return backend_interface_1.BackendType.NATIVE;
+        }
+        catch {
+            return backend_interface_1.BackendType.WASM;
+        }
+    }
+    /**
+     * Create backend instance
+     */
+    createBackend(type) {
+        switch (type) {
+            case backend_interface_1.BackendType.NATIVE:
+                return new native_backend_1.NativeBackend();
+            case backend_interface_1.BackendType.WASM:
+                return new wasm_backend_1.WasmBackend();
+            default:
+                throw new Error(`Unsupported backend type: ${type}`);
+        }
+    }
+    /**
+     * Async initialization for WASM backend
+     * Must be called after constructor if using WASM backend
+     */
+    async initializeAsync(config) {
+        if (this.backendType === backend_interface_1.BackendType.WASM) {
+            const wasmBackend = this.backend;
+            const finalConfig = config || wasmBackend._pendingConfig || {};
+            await wasmBackend.initializeAsync(finalConfig);
+            delete wasmBackend._pendingConfig;
+        }
+    }
+    /**
+     * Get backend type
+     */
+    getBackendType() {
+        return this.backendType;
+    }
+    /**
+     * Check if backend is initialized
+     */
+    isInitialized() {
+        if (this.backendType === backend_interface_1.BackendType.WASM) {
+            return this.backend.isInitialized();
+        }
+        return this.backend.isInitialized();
+    }
+    /**
+     * Insert a single vector
+     */
+    insert(vector) {
+        return this.backend.insert(vector);
+    }
+    /**
+     * Insert multiple vectors in a transaction
+     */
+    insertBatch(vectors) {
+        return this.backend.insertBatch(vectors);
+    }
+    /**
+     * Search for k-nearest neighbors with optional caching
+     */
+    search(queryEmbedding, k = 5, metric = 'cosine', threshold = 0.0) {
+        // Check cache if enabled
+        if (this.queryCache) {
+            const cacheKey = query_cache_1.QueryCache.generateKey(queryEmbedding, k, metric, threshold);
+            const cached = this.queryCache.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+            // Cache miss - perform search and cache result
+            const results = this.backend.search(queryEmbedding, k, metric, threshold);
+            this.queryCache.set(cacheKey, results);
+            return results;
+        }
+        // No cache - perform search directly
+        return this.backend.search(queryEmbedding, k, metric, threshold);
+    }
+    /**
+     * Get vector by ID
+     */
+    get(id) {
+        return this.backend.get(id);
+    }
+    /**
+     * Delete vector by ID
+     */
+    delete(id) {
+        return this.backend.delete(id);
+    }
+    /**
+     * Get database statistics
+     */
+    stats() {
+        return this.backend.stats();
+    }
+    /**
+     * Close database connection
+     */
+    close() {
+        this.backend.close();
+    }
+    /**
+     * Export database to binary format (WASM only)
+     */
+    export() {
+        if (this.backend.export) {
+            return this.backend.export();
+        }
+        throw new Error('Export not supported by current backend');
+    }
+    /**
+     * Import database from binary format (WASM only)
+     */
+    async importAsync(data) {
+        if (this.backendType === backend_interface_1.BackendType.WASM) {
+            await this.backend.importAsync(data);
+        }
+        else {
+            throw new Error('Import not supported by native backend');
+        }
+    }
+    /**
+     * Get raw backend instance (for advanced usage)
+     */
+    getBackend() {
+        return this.backend;
+    }
+    /**
+     * Get raw database instance (for advanced usage with native backend)
+     * @deprecated Use getBackend() instead for cross-backend compatibility
+     */
+    getDatabase() {
+        if (this.backendType === backend_interface_1.BackendType.NATIVE) {
+            return this.backend.getDatabase();
+        }
+        throw new Error('getDatabase() only supported on native backend. Use getBackend() instead.');
+    }
+    /**
+     * Get query cache instance
+     */
+    getQueryCache() {
+        return this.queryCache;
+    }
+    /**
+     * Get query cache statistics
+     */
+    getCacheStats() {
+        return this.queryCache?.getStats();
+    }
+    /**
+     * Clear query cache
+     */
+    clearCache() {
+        this.queryCache?.clear();
+    }
+    /**
+     * Get quantizer instance
+     */
+    getQuantizer() {
+        return this.quantizer;
+    }
+    /**
+     * Train quantizer with existing vectors
+     */
+    async trainQuantizer() {
+        if (!this.quantizer) {
+            throw new Error('Quantization not enabled');
+        }
+        // Get all vectors from database
+        const allStats = this.stats();
+        if (allStats.count === 0) {
+            throw new Error('No vectors to train quantizer');
+        }
+        // Fetch all embeddings (simplified - in production, batch this)
+        const vectors = [];
+        // Note: This would need backend support to efficiently fetch all embeddings
+        console.log('Training quantizer with existing vectors...');
+        await this.quantizer.train(vectors);
+        console.log('Quantizer training complete');
+    }
+    /**
+     * Get compression statistics (if quantization enabled)
+     */
+    getCompressionStats() {
+        return this.quantizer?.getStats();
+    }
+    /**
+     * Create a fluent query builder for complex queries
+     *
+     * @returns VectorQueryBuilder instance
+     *
+     * @example
+     * ```typescript
+     * const results = await db.query()
+     *   .similarTo(queryVector)
+     *   .where('metadata.category', '=', 'tech')
+     *   .whereBetween('metadata.year', 2020, 2024)
+     *   .orderBySimilarity('desc')
+     *   .limit(10)
+     *   .execute();
+     * ```
+     */
+    query() {
+        return new query_builder_1.VectorQueryBuilder(this);
+    }
+}
+exports.SQLiteVectorDB = SQLiteVectorDB;
+//# sourceMappingURL=vector-db.js.map

package/dist/core/vector-db.js.map

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

package/dist/core/vector-db.mjs

@@ -0,0 +1,261 @@
+/**
+ * Core SQLiteVector database implementation with backend abstraction
+ * Supports both native (better-sqlite3) and WASM (sql.js) backends
+ */
+import { BackendType } from './backend-interface.mjs';
+import { NativeBackend } from './native-backend.mjs';
+import { WasmBackend } from './wasm-backend.mjs';
+import { QueryCache } from '../cache/query-cache.mjs';
+import { ProductQuantizer } from '../quantization/product-quantization.mjs';
+import { VectorQueryBuilder } from '../query/query-builder.mjs';
+export class SQLiteVectorDB {
+    constructor(config = {}) {
+        // If path is provided but memoryMode not specified, default to file mode
+        if (config.path && config.memoryMode === undefined) {
+            config.memoryMode = false;
+        }
+        // Determine backend type
+        this.backendType = this.detectBackend(config);
+        // Create appropriate backend
+        this.backend = this.createBackend(this.backendType);
+        // Initialize query cache if enabled
+        if (config.queryCache?.enabled !== false) {
+            this.queryCache = new QueryCache(config.queryCache);
+        }
+        // Initialize quantizer if enabled
+        if (config.quantization?.enabled) {
+            this.quantizer = new ProductQuantizer(config.quantization);
+        }
+        // Initialize backend
+        if (this.backendType === BackendType.WASM) {
+            // WASM backend requires async initialization
+            // Store config for later async init
+            this.backend._pendingConfig = config;
+        }
+        else {
+            // Native backend can initialize synchronously
+            this.backend.initialize(config);
+        }
+    }
+    /**
+     * Detect appropriate backend based on environment and configuration
+     */
+    detectBackend(config) {
+        // Explicit backend selection
+        if (config.backend) {
+            return config.backend;
+        }
+        // Auto-detect based on environment
+        if (typeof window !== 'undefined' || typeof process === 'undefined') {
+            // Browser environment
+            return BackendType.WASM;
+        }
+        // Node.js environment - check if better-sqlite3 is available
+        try {
+            require.resolve('better-sqlite3');
+            return BackendType.NATIVE;
+        }
+        catch {
+            return BackendType.WASM;
+        }
+    }
+    /**
+     * Create backend instance
+     */
+    createBackend(type) {
+        switch (type) {
+            case BackendType.NATIVE:
+                return new NativeBackend();
+            case BackendType.WASM:
+                return new WasmBackend();
+            default:
+                throw new Error(`Unsupported backend type: ${type}`);
+        }
+    }
+    /**
+     * Async initialization for WASM backend
+     * Must be called after constructor if using WASM backend
+     */
+    async initializeAsync(config) {
+        if (this.backendType === BackendType.WASM) {
+            const wasmBackend = this.backend;
+            const finalConfig = config || wasmBackend._pendingConfig || {};
+            await wasmBackend.initializeAsync(finalConfig);
+            delete wasmBackend._pendingConfig;
+        }
+    }
+    /**
+     * Get backend type
+     */
+    getBackendType() {
+        return this.backendType;
+    }
+    /**
+     * Check if backend is initialized
+     */
+    isInitialized() {
+        if (this.backendType === BackendType.WASM) {
+            return this.backend.isInitialized();
+        }
+        return this.backend.isInitialized();
+    }
+    /**
+     * Insert a single vector
+     */
+    insert(vector) {
+        return this.backend.insert(vector);
+    }
+    /**
+     * Insert multiple vectors in a transaction
+     */
+    insertBatch(vectors) {
+        return this.backend.insertBatch(vectors);
+    }
+    /**
+     * Search for k-nearest neighbors with optional caching
+     */
+    search(queryEmbedding, k = 5, metric = 'cosine', threshold = 0.0) {
+        // Check cache if enabled
+        if (this.queryCache) {
+            const cacheKey = QueryCache.generateKey(queryEmbedding, k, metric, threshold);
+            const cached = this.queryCache.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+            // Cache miss - perform search and cache result
+            const results = this.backend.search(queryEmbedding, k, metric, threshold);
+            this.queryCache.set(cacheKey, results);
+            return results;
+        }
+        // No cache - perform search directly
+        return this.backend.search(queryEmbedding, k, metric, threshold);
+    }
+    /**
+     * Get vector by ID
+     */
+    get(id) {
+        return this.backend.get(id);
+    }
+    /**
+     * Delete vector by ID
+     */
+    delete(id) {
+        return this.backend.delete(id);
+    }
+    /**
+     * Get database statistics
+     */
+    stats() {
+        return this.backend.stats();
+    }
+    /**
+     * Close database connection
+     */
+    close() {
+        this.backend.close();
+    }
+    /**
+     * Export database to binary format (WASM only)
+     */
+    export() {
+        if (this.backend.export) {
+            return this.backend.export();
+        }
+        throw new Error('Export not supported by current backend');
+    }
+    /**
+     * Import database from binary format (WASM only)
+     */
+    async importAsync(data) {
+        if (this.backendType === BackendType.WASM) {
+            await this.backend.importAsync(data);
+        }
+        else {
+            throw new Error('Import not supported by native backend');
+        }
+    }
+    /**
+     * Get raw backend instance (for advanced usage)
+     */
+    getBackend() {
+        return this.backend;
+    }
+    /**
+     * Get raw database instance (for advanced usage with native backend)
+     * @deprecated Use getBackend() instead for cross-backend compatibility
+     */
+    getDatabase() {
+        if (this.backendType === BackendType.NATIVE) {
+            return this.backend.getDatabase();
+        }
+        throw new Error('getDatabase() only supported on native backend. Use getBackend() instead.');
+    }
+    /**
+     * Get query cache instance
+     */
+    getQueryCache() {
+        return this.queryCache;
+    }
+    /**
+     * Get query cache statistics
+     */
+    getCacheStats() {
+        return this.queryCache?.getStats();
+    }
+    /**
+     * Clear query cache
+     */
+    clearCache() {
+        this.queryCache?.clear();
+    }
+    /**
+     * Get quantizer instance
+     */
+    getQuantizer() {
+        return this.quantizer;
+    }
+    /**
+     * Train quantizer with existing vectors
+     */
+    async trainQuantizer() {
+        if (!this.quantizer) {
+            throw new Error('Quantization not enabled');
+        }
+        // Get all vectors from database
+        const allStats = this.stats();
+        if (allStats.count === 0) {
+            throw new Error('No vectors to train quantizer');
+        }
+        // Fetch all embeddings (simplified - in production, batch this)
+        const vectors = [];
+        // Note: This would need backend support to efficiently fetch all embeddings
+        console.log('Training quantizer with existing vectors...');
+        await this.quantizer.train(vectors);
+        console.log('Quantizer training complete');
+    }
+    /**
+     * Get compression statistics (if quantization enabled)
+     */
+    getCompressionStats() {
+        return this.quantizer?.getStats();
+    }
+    /**
+     * Create a fluent query builder for complex queries
+     *
+     * @returns VectorQueryBuilder instance
+     *
+     * @example
+     * ```typescript
+     * const results = await db.query()
+     *   .similarTo(queryVector)
+     *   .where('metadata.category', '=', 'tech')
+     *   .whereBetween('metadata.year', 2020, 2024)
+     *   .orderBySimilarity('desc')
+     *   .limit(10)
+     *   .execute();
+     * ```
+     */
+    query() {
+        return new VectorQueryBuilder(this);
+    }
+}

package/dist/core/wasm-backend.d.ts

@@ -0,0 +1,96 @@
+/**
+ * WASM backend implementation using sql.js
+ * Provides browser-compatible vector database operations
+ */
+import { Vector, SearchResult, SimilarityMetric, DatabaseConfig } from '../types';
+import { VectorBackend } from './backend-interface';
+/**
+ * WASM backend using sql.js
+ * Runs in both Node.js and browser environments
+ */
+export declare class WasmBackend implements VectorBackend {
+    private SQL;
+    private db;
+    private initialized;
+    /**
+     * Initialize the WASM backend
+     */
+    initializeAsync(config?: DatabaseConfig): Promise<void>;
+    /**
+     * Synchronous initialization (throws if not already initialized)
+     */
+    initialize(config?: DatabaseConfig): void;
+    /**
+     * Initialize database schema
+     */
+    private initializeSchema;
+    /**
+     * Register custom SQL functions for similarity calculations
+     */
+    private registerCustomFunctions;
+    /**
+     * Calculate L2 norm of a vector
+     */
+    private calculateNorm;
+    /**
+     * Serialize embedding to Uint8Array (binary format)
+     */
+    private serializeEmbedding;
+    /**
+     * Deserialize embedding from Uint8Array
+     */
+    private deserializeEmbedding;
+    /**
+     * Generate unique ID
+     */
+    private generateId;
+    /**
+     * Insert a single vector
+     */
+    insert(vector: Vector): string;
+    /**
+     * Insert multiple vectors in a transaction with optimized batch processing
+     * Performance improvements:
+     * - Single transaction for all inserts
+     * - Prepared statement created once and reused
+     * - No wrapper function overhead
+     * - Chunked processing for large batches
+     */
+    insertBatch(vectors: Vector[]): string[];
+    /**
+     * Search for k-nearest neighbors
+     */
+    search(queryEmbedding: number[], k?: number, metric?: SimilarityMetric, threshold?: number): SearchResult[];
+    /**
+     * Get vector by ID
+     */
+    get(id: string): Vector | null;
+    /**
+     * Delete vector by ID
+     */
+    delete(id: string): boolean;
+    /**
+     * Get database statistics
+     */
+    stats(): {
+        count: number;
+        size: number;
+    };
+    /**
+     * Export database to binary format (for persistence)
+     */
+    export(): Uint8Array;
+    /**
+     * Import database from binary format
+     */
+    importAsync(data: Uint8Array): Promise<void>;
+    /**
+     * Close database and cleanup resources
+     */
+    close(): void;
+    /**
+     * Check if backend is initialized
+     */
+    isInitialized(): boolean;
+}
+//# sourceMappingURL=wasm-backend.d.ts.map

package/dist/core/wasm-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm-backend.d.ts","sourceRoot":"","sources":["../../src/core/wasm-backend.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAClF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;GAGG;AACH,qBAAa,WAAY,YAAW,aAAa;IAC/C,OAAO,CAAC,GAAG,CAA4B;IACvC,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,WAAW,CAAkB;IAErC;;OAEG;IACG,eAAe,CAAC,MAAM,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BjE;;OAEG;IACH,UAAU,CAAC,MAAM,GAAE,cAAmB,GAAG,IAAI;IAM7C;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAgCxB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA+C/B;;OAEG;IACH,OAAO,CAAC,aAAa;IAQrB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAO1B;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAK5B;;OAEG;IACH,OAAO,CAAC,UAAU;IAIlB;;OAEG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;IAiB9B;;;;;;;OAOG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IA2DxC;;OAEG;IACH,MAAM,CACJ,cAAc,EAAE,MAAM,EAAE,EACxB,CAAC,GAAE,MAAU,EACb,MAAM,GAAE,gBAA2B,EACnC,SAAS,GAAE,MAAY,GACtB,YAAY,EAAE;IA6EjB;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAuB9B;;OAEG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAY3B;;OAEG;IACH,KAAK,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IAiBxC;;OAEG;IACH,MAAM,IAAI,UAAU;IAKpB;;OAEG;IACG,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBlD;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,aAAa,IAAI,OAAO;CAGzB"}