@framers/agentos 0.1.0

package/dist/rag/implementations/vector_stores/SqlVectorStore.js

@@ -0,0 +1,755 @@
+/**
+ * @fileoverview SQL-backed Vector Store Implementation
+ *
+ * Implements `IVectorStore` using `@framers/sql-storage-adapter` for persistence.
+ * This allows vector storage to work across all platforms supported by the storage
+ * adapter (SQLite, PostgreSQL, IndexedDB, Capacitor, etc.).
+ *
+ * **Key Features:**
+ * - Cross-platform persistence using sql-storage-adapter
+ * - Full-text search support via SQLite FTS5 / PostgreSQL tsvector
+ * - Hybrid search (vector similarity + keyword matching)
+ * - Automatic schema management
+ * - Works with pgvector extension for PostgreSQL (when available)
+ *
+ * **Architecture:**
+ * ```
+ * AgentOS RAG System (RetrievalAugmentor)
+ *          ↓
+ *   VectorStoreManager
+ *          ↓
+ *   SqlVectorStore (this file)
+ *          ↓
+ *   @framers/sql-storage-adapter
+ *          ↓
+ *   Database (SQLite/PostgreSQL/IndexedDB/etc.)
+ * ```
+ *
+ * @module @framers/agentos/rag/implementations/vector_stores/SqlVectorStore
+ * @see ../../IVectorStore.ts for the interface definition.
+ * @see @framers/sql-storage-adapter for storage abstraction.
+ */
+import { resolveStorageAdapter, } from '@framers/sql-storage-adapter';
+import { GMIError, GMIErrorCode } from '../../../utils/errors.js';
+import { uuidv4 } from '../../../utils/uuid.js';
+// ============================================================================
+// SQL Vector Store Implementation
+// ============================================================================
+/**
+ * SQL-backed vector store implementation.
+ *
+ * Uses `@framers/sql-storage-adapter` for cross-platform persistence.
+ * Stores embeddings as JSON blobs and computes similarity in application code
+ * (with optional native vector extensions for PostgreSQL).
+ *
+ * @class SqlVectorStore
+ * @implements {IVectorStore}
+ *
+ * @example
+ * ```typescript
+ * const store = new SqlVectorStore();
+ *
+ * await store.initialize({
+ *   id: 'sql-vector-store',
+ *   type: 'sql',
+ *   storage: {
+ *     filePath: './vectors.db',
+ *     priority: ['better-sqlite3', 'sqljs']
+ *   },
+ *   enableFullTextSearch: true
+ * });
+ *
+ * // Create a collection
+ * await store.createCollection('documents', 1536);
+ *
+ * // Upsert documents
+ * await store.upsert('documents', [{
+ *   id: 'doc-1',
+ *   embedding: [...], // 1536-dim vector
+ *   textContent: 'Example document content',
+ *   metadata: { author: 'Alice', category: 'tech' }
+ * }]);
+ *
+ * // Query by similarity
+ * const results = await store.query('documents', queryEmbedding, { topK: 5 });
+ * ```
+ */
+export class SqlVectorStore {
+    /**
+     * Constructs a SqlVectorStore instance.
+     * The store is not operational until `initialize()` is called.
+     */
+    constructor() {
+        this.ownsAdapter = false; // Whether we created the adapter
+        this.isInitialized = false;
+        this.tablePrefix = 'agentos_rag_';
+        this.providerId = `sql-vector-store-${uuidv4()}`;
+    }
+    /**
+     * Initializes the vector store with the provided configuration.
+     *
+     * Creates necessary tables and indexes if they don't exist.
+     *
+     * @param {VectorStoreProviderConfig} config - Configuration object
+     * @throws {GMIError} If configuration is invalid or initialization fails
+     */
+    async initialize(config) {
+        if (this.isInitialized) {
+            console.warn(`SqlVectorStore (ID: ${this.providerId}) already initialized. Re-initializing.`);
+            await this.shutdown();
+        }
+        if (config.type !== 'sql') {
+            throw new GMIError(`Invalid configuration type for SqlVectorStore: ${config.type}. Expected 'sql'.`, GMIErrorCode.CONFIG_ERROR, { providedType: config.type });
+        }
+        this.config = config;
+        this.tablePrefix = this.config.tablePrefix ?? 'agentos_rag_';
+        // Initialize storage adapter
+        if (this.config.adapter) {
+            this.adapter = this.config.adapter;
+            this.ownsAdapter = false;
+        }
+        else if (this.config.storage) {
+            this.adapter = await resolveStorageAdapter(this.config.storage);
+            this.ownsAdapter = true;
+        }
+        else {
+            // Default to sql.js (in-memory when no file path provided)
+            this.adapter = await resolveStorageAdapter({ priority: ['sqljs'] });
+            this.ownsAdapter = true;
+            console.warn(`SqlVectorStore (ID: ${this.providerId}): No storage config provided, using sql.js (in-memory).`);
+        }
+        // Create schema
+        await this.createSchema();
+        this.isInitialized = true;
+        console.log(`SqlVectorStore (ID: ${this.providerId}, Config ID: ${this.config.id}) initialized successfully.`);
+    }
+    /**
+     * Creates the database schema for vector storage.
+     * @private
+     */
+    async createSchema() {
+        // Collections metadata table
+        await this.adapter.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.tablePrefix}collections (
+        name TEXT PRIMARY KEY,
+        dimension INTEGER NOT NULL,
+        similarity_metric TEXT NOT NULL DEFAULT 'cosine',
+        document_count INTEGER NOT NULL DEFAULT 0,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+    `);
+        // Documents table - stores vectors as JSON blobs
+        await this.adapter.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.tablePrefix}documents (
+        id TEXT NOT NULL,
+        collection_name TEXT NOT NULL,
+        embedding_blob TEXT NOT NULL,
+        text_content TEXT,
+        metadata_json TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        PRIMARY KEY (collection_name, id),
+        FOREIGN KEY (collection_name) REFERENCES ${this.tablePrefix}collections(name) ON DELETE CASCADE
+      );
+      
+      CREATE INDEX IF NOT EXISTS idx_${this.tablePrefix}docs_collection 
+        ON ${this.tablePrefix}documents(collection_name);
+      
+      CREATE INDEX IF NOT EXISTS idx_${this.tablePrefix}docs_updated 
+        ON ${this.tablePrefix}documents(updated_at);
+    `);
+        // Full-text search virtual table (SQLite FTS5)
+        if (this.config.enableFullTextSearch !== false) {
+            try {
+                await this.adapter.exec(`
+          CREATE VIRTUAL TABLE IF NOT EXISTS ${this.tablePrefix}documents_fts 
+          USING fts5(
+            id,
+            collection_name,
+            text_content,
+            content='${this.tablePrefix}documents',
+            content_rowid='rowid'
+          );
+        `);
+                console.log(`SqlVectorStore (ID: ${this.providerId}): FTS5 index created.`);
+            }
+            catch (error) {
+                // FTS5 might not be available (e.g., in some SQL.js builds)
+                console.warn(`SqlVectorStore (ID: ${this.providerId}): FTS5 not available: ${error.message}`);
+            }
+        }
+    }
+    /**
+     * Ensures the store is initialized before operations.
+     * @private
+     */
+    ensureInitialized() {
+        if (!this.isInitialized) {
+            throw new GMIError(`SqlVectorStore (ID: ${this.providerId}) is not initialized. Call initialize() first.`, GMIErrorCode.NOT_INITIALIZED);
+        }
+    }
+    /**
+     * Creates a new collection for storing vectors.
+     *
+     * @param {string} collectionName - Unique name for the collection
+     * @param {number} dimension - Vector embedding dimension
+     * @param {CreateCollectionOptions} [options] - Creation options
+     */
+    async createCollection(collectionName, dimension, options) {
+        this.ensureInitialized();
+        if (dimension <= 0) {
+            throw new GMIError(`Invalid dimension for collection '${collectionName}': ${dimension}. Must be positive.`, GMIErrorCode.VALIDATION_ERROR, { dimension });
+        }
+        const exists = await this.collectionExists(collectionName);
+        if (exists) {
+            if (options?.overwriteIfExists) {
+                await this.deleteCollection(collectionName);
+            }
+            else {
+                throw new GMIError(`Collection '${collectionName}' already exists.`, GMIErrorCode.ALREADY_EXISTS, { collectionName });
+            }
+        }
+        const now = Date.now();
+        const metric = options?.similarityMetric ?? this.config.similarityMetric ?? 'cosine';
+        await this.adapter.run(`INSERT INTO ${this.tablePrefix}collections 
+       (name, dimension, similarity_metric, document_count, created_at, updated_at)
+       VALUES (?, ?, ?, 0, ?, ?)`, [collectionName, dimension, metric, now, now]);
+        console.log(`SqlVectorStore (ID: ${this.providerId}): Collection '${collectionName}' created (dim=${dimension}, metric=${metric}).`);
+    }
+    /**
+     * Checks if a collection exists.
+     *
+     * @param {string} collectionName - Collection name to check
+     * @returns {Promise<boolean>} True if collection exists
+     */
+    async collectionExists(collectionName) {
+        this.ensureInitialized();
+        const row = await this.adapter.get(`SELECT COUNT(*) as count FROM ${this.tablePrefix}collections WHERE name = ?`, [collectionName]);
+        return (row?.count ?? 0) > 0;
+    }
+    /**
+     * Deletes a collection and all its documents.
+     *
+     * @param {string} collectionName - Collection to delete
+     */
+    async deleteCollection(collectionName) {
+        this.ensureInitialized();
+        // Delete documents first (due to foreign key)
+        await this.adapter.run(`DELETE FROM ${this.tablePrefix}documents WHERE collection_name = ?`, [collectionName]);
+        // Delete collection metadata
+        await this.adapter.run(`DELETE FROM ${this.tablePrefix}collections WHERE name = ?`, [collectionName]);
+        console.log(`SqlVectorStore (ID: ${this.providerId}): Collection '${collectionName}' deleted.`);
+    }
+    /**
+     * Gets collection metadata.
+     * @private
+     */
+    async getCollectionMetadata(collectionName) {
+        const row = await this.adapter.get(`SELECT * FROM ${this.tablePrefix}collections WHERE name = ?`, [collectionName]);
+        if (!row) {
+            throw new GMIError(`Collection '${collectionName}' not found.`, GMIErrorCode.NOT_FOUND, { collectionName });
+        }
+        return {
+            name: row.name,
+            dimension: row.dimension,
+            similarityMetric: row.similarity_metric,
+            documentCount: row.document_count,
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        };
+    }
+    /**
+     * Upserts documents into a collection.
+     *
+     * @param {string} collectionName - Target collection
+     * @param {VectorDocument[]} documents - Documents to upsert
+     * @param {UpsertOptions} [options] - Upsert options
+     * @returns {Promise<UpsertResult>} Result of the upsert operation
+     */
+    async upsert(collectionName, documents, options) {
+        this.ensureInitialized();
+        const collection = await this.getCollectionMetadata(collectionName);
+        const upsertedIds = [];
+        const errors = [];
+        const now = Date.now();
+        for (const doc of documents) {
+            // Validate dimension
+            if (doc.embedding.length !== collection.dimension) {
+                errors.push({
+                    id: doc.id,
+                    message: `Embedding dimension ${doc.embedding.length} does not match collection dimension ${collection.dimension}.`,
+                    details: { expected: collection.dimension, got: doc.embedding.length }
+                });
+                continue;
+            }
+            try {
+                // Check if document exists
+                const existing = await this.adapter.get(`SELECT id FROM ${this.tablePrefix}documents WHERE collection_name = ? AND id = ?`, [collectionName, doc.id]);
+                const embeddingBlob = JSON.stringify(doc.embedding);
+                const metadataJson = doc.metadata ? JSON.stringify(doc.metadata) : null;
+                if (existing && options?.overwrite === false) {
+                    errors.push({
+                        id: doc.id,
+                        message: `Document '${doc.id}' already exists and overwrite is disabled.`,
+                        details: { reason: 'NO_OVERWRITE' }
+                    });
+                    continue;
+                }
+                if (existing) {
+                    // Update existing document
+                    await this.adapter.run(`UPDATE ${this.tablePrefix}documents 
+             SET embedding_blob = ?, text_content = ?, metadata_json = ?, updated_at = ?
+             WHERE collection_name = ? AND id = ?`, [embeddingBlob, doc.textContent ?? null, metadataJson, now, collectionName, doc.id]);
+                }
+                else {
+                    // Insert new document
+                    await this.adapter.run(`INSERT INTO ${this.tablePrefix}documents 
+             (id, collection_name, embedding_blob, text_content, metadata_json, created_at, updated_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?)`, [doc.id, collectionName, embeddingBlob, doc.textContent ?? null, metadataJson, now, now]);
+                }
+                upsertedIds.push(doc.id);
+            }
+            catch (error) {
+                errors.push({
+                    id: doc.id,
+                    message: `Failed to upsert document: ${error.message}`,
+                    details: error
+                });
+            }
+        }
+        // Update collection document count
+        const countResult = await this.adapter.get(`SELECT COUNT(*) as count FROM ${this.tablePrefix}documents WHERE collection_name = ?`, [collectionName]);
+        await this.adapter.run(`UPDATE ${this.tablePrefix}collections SET document_count = ?, updated_at = ? WHERE name = ?`, [countResult?.count ?? 0, now, collectionName]);
+        return {
+            upsertedCount: upsertedIds.length,
+            upsertedIds,
+            failedCount: errors.length,
+            errors: errors.length > 0 ? errors : undefined,
+        };
+    }
+    /**
+     * Queries a collection for similar documents.
+     *
+     * @param {string} collectionName - Collection to query
+     * @param {number[]} queryEmbedding - Query vector
+     * @param {QueryOptions} [options] - Query options
+     * @returns {Promise<QueryResult>} Query results sorted by similarity
+     */
+    async query(collectionName, queryEmbedding, options) {
+        this.ensureInitialized();
+        const collection = await this.getCollectionMetadata(collectionName);
+        const topK = options?.topK ?? 10;
+        // Validate query embedding dimension
+        if (queryEmbedding.length !== collection.dimension) {
+            throw new GMIError(`Query embedding dimension ${queryEmbedding.length} does not match collection dimension ${collection.dimension}.`, GMIErrorCode.VALIDATION_ERROR, { expected: collection.dimension, got: queryEmbedding.length });
+        }
+        // Build query with optional metadata filter
+        const query = `SELECT * FROM ${this.tablePrefix}documents WHERE collection_name = ?`;
+        const params = [collectionName];
+        // Note: For more advanced filtering, we'd parse the MetadataFilter and generate SQL
+        // For now, we filter in application code for flexibility
+        const rows = await this.adapter.all(query, params);
+        // Compute similarities and filter
+        const candidates = [];
+        for (const row of rows) {
+            const embedding = JSON.parse(row.embedding_blob);
+            const metadata = row.metadata_json ? JSON.parse(row.metadata_json) : undefined;
+            // Apply metadata filter in application code
+            if (options?.filter && !this.matchesFilter(metadata, options.filter)) {
+                continue;
+            }
+            // Compute similarity
+            let similarityScore;
+            switch (collection.similarityMetric) {
+                case 'euclidean':
+                    similarityScore = -this.euclideanDistance(queryEmbedding, embedding); // Negate for "higher is better"
+                    break;
+                case 'dotproduct':
+                    similarityScore = this.dotProduct(queryEmbedding, embedding);
+                    break;
+                case 'cosine':
+                default:
+                    similarityScore = this.cosineSimilarity(queryEmbedding, embedding);
+                    break;
+            }
+            // Apply minimum similarity threshold
+            if (options?.minSimilarityScore !== undefined && similarityScore < options.minSimilarityScore) {
+                continue;
+            }
+            // Build result document
+            const retrievedDoc = {
+                id: row.id,
+                embedding: options?.includeEmbedding ? embedding : [],
+                similarityScore,
+            };
+            if (options?.includeMetadata !== false && metadata) {
+                retrievedDoc.metadata = metadata;
+            }
+            if (options?.includeTextContent && row.text_content) {
+                retrievedDoc.textContent = row.text_content;
+            }
+            candidates.push(retrievedDoc);
+        }
+        // Sort by similarity (descending) and take topK
+        candidates.sort((a, b) => b.similarityScore - a.similarityScore);
+        const results = candidates.slice(0, topK);
+        return {
+            documents: results,
+            queryId: `sql-query-${uuidv4()}`,
+            stats: {
+                totalCandidates: rows.length,
+                filteredCandidates: candidates.length,
+                returnedCount: results.length,
+            },
+        };
+    }
+    /**
+     * Performs hybrid search combining vector similarity with keyword matching.
+     *
+     * @param {string} collectionName - Collection to search
+     * @param {number[]} queryEmbedding - Query vector for semantic search
+     * @param {string} queryText - Text query for keyword search
+     * @param {QueryOptions & { alpha?: number }} [options] - Search options
+     * @returns {Promise<QueryResult>} Combined search results
+     *
+     * @example
+     * ```typescript
+     * const results = await store.hybridSearch(
+     *   'documents',
+     *   queryEmbedding,
+     *   'machine learning tutorial',
+     *   { topK: 10, alpha: 0.7 } // 70% vector, 30% keyword
+     * );
+     * ```
+     */
+    async hybridSearch(collectionName, queryEmbedding, queryText, options) {
+        this.ensureInitialized();
+        const alpha = options?.alpha ?? 0.7; // Default: 70% vector similarity
+        const topK = options?.topK ?? 10;
+        // Get vector search results
+        const vectorResults = await this.query(collectionName, queryEmbedding, {
+            ...options,
+            topK: topK * 3, // Get more candidates for merging
+            includeTextContent: true,
+        });
+        // Normalize vector scores to [0, 1]
+        const maxVectorScore = Math.max(...vectorResults.documents.map(d => d.similarityScore), 0.001);
+        const vectorScoreMap = new Map();
+        for (const doc of vectorResults.documents) {
+            vectorScoreMap.set(doc.id, doc.similarityScore / maxVectorScore);
+        }
+        // Compute keyword scores using simple term matching
+        const queryTerms = queryText.toLowerCase().split(/\s+/).filter(t => t.length > 2);
+        const keywordScoreMap = new Map();
+        for (const doc of vectorResults.documents) {
+            if (!doc.textContent)
+                continue;
+            const content = doc.textContent.toLowerCase();
+            let matchCount = 0;
+            for (const term of queryTerms) {
+                if (content.includes(term)) {
+                    matchCount++;
+                }
+            }
+            const keywordScore = queryTerms.length > 0 ? matchCount / queryTerms.length : 0;
+            keywordScoreMap.set(doc.id, keywordScore);
+        }
+        // Combine scores using reciprocal rank fusion or weighted average
+        const combinedResults = [];
+        for (const doc of vectorResults.documents) {
+            const vectorScore = vectorScoreMap.get(doc.id) ?? 0;
+            const keywordScore = keywordScoreMap.get(doc.id) ?? 0;
+            const combinedScore = alpha * vectorScore + (1 - alpha) * keywordScore;
+            combinedResults.push({
+                ...doc,
+                similarityScore: combinedScore,
+            });
+        }
+        // Sort by combined score and return top K
+        combinedResults.sort((a, b) => b.similarityScore - a.similarityScore);
+        return {
+            documents: combinedResults.slice(0, topK),
+            queryId: `sql-hybrid-${uuidv4()}`,
+            stats: {
+                vectorWeight: alpha,
+                keywordWeight: 1 - alpha,
+                queryTerms: queryTerms.length,
+            },
+        };
+    }
+    /**
+     * Deletes documents from a collection.
+     *
+     * @param {string} collectionName - Collection to delete from
+     * @param {string[]} [ids] - Specific document IDs to delete
+     * @param {DeleteOptions} [options] - Delete options (filter, deleteAll)
+     * @returns {Promise<DeleteResult>} Deletion result
+     */
+    async delete(collectionName, ids, options) {
+        this.ensureInitialized();
+        let deletedCount = 0;
+        const errors = [];
+        if (options?.deleteAll && !ids && !options.filter) {
+            // Delete all documents in collection
+            const result = await this.adapter.run(`DELETE FROM ${this.tablePrefix}documents WHERE collection_name = ?`, [collectionName]);
+            deletedCount = result.changes;
+            console.warn(`SqlVectorStore (ID: ${this.providerId}): All ${deletedCount} documents deleted from '${collectionName}'.`);
+        }
+        else if (ids && ids.length > 0) {
+            // Delete specific IDs
+            const placeholders = ids.map(() => '?').join(',');
+            const result = await this.adapter.run(`DELETE FROM ${this.tablePrefix}documents WHERE collection_name = ? AND id IN (${placeholders})`, [collectionName, ...ids]);
+            deletedCount = result.changes;
+        }
+        else if (options?.filter) {
+            // Delete by filter (fetch matching docs first, then delete)
+            const rows = await this.adapter.all(`SELECT id, metadata_json FROM ${this.tablePrefix}documents WHERE collection_name = ?`, [collectionName]);
+            const idsToDelete = [];
+            for (const row of rows) {
+                const metadata = row.metadata_json ? JSON.parse(row.metadata_json) : undefined;
+                if (this.matchesFilter(metadata, options.filter)) {
+                    idsToDelete.push(row.id);
+                }
+            }
+            if (idsToDelete.length > 0) {
+                const placeholders = idsToDelete.map(() => '?').join(',');
+                const result = await this.adapter.run(`DELETE FROM ${this.tablePrefix}documents WHERE collection_name = ? AND id IN (${placeholders})`, [collectionName, ...idsToDelete]);
+                deletedCount = result.changes;
+            }
+        }
+        // Update collection document count
+        const now = Date.now();
+        const countResult = await this.adapter.get(`SELECT COUNT(*) as count FROM ${this.tablePrefix}documents WHERE collection_name = ?`, [collectionName]);
+        await this.adapter.run(`UPDATE ${this.tablePrefix}collections SET document_count = ?, updated_at = ? WHERE name = ?`, [countResult?.count ?? 0, now, collectionName]);
+        return {
+            deletedCount,
+            failedCount: errors.length > 0 ? errors.length : undefined,
+            errors: errors.length > 0 ? errors : undefined,
+        };
+    }
+    /**
+     * Checks the health of the vector store.
+     *
+     * @returns {Promise<{ isHealthy: boolean; details?: any }>} Health status
+     */
+    async checkHealth() {
+        try {
+            this.ensureInitialized();
+            // Simple health check query
+            const collections = await this.adapter.all(`SELECT name, document_count FROM ${this.tablePrefix}collections`);
+            const totalDocuments = collections.reduce((sum, c) => sum + c.document_count, 0);
+            return {
+                isHealthy: true,
+                details: {
+                    providerId: this.providerId,
+                    configId: this.config.id,
+                    type: 'sql',
+                    collectionCount: collections.length,
+                    totalDocuments,
+                    collections: collections.map(c => ({ name: c.name, documentCount: c.document_count })),
+                },
+            };
+        }
+        catch (error) {
+            return {
+                isHealthy: false,
+                details: {
+                    providerId: this.providerId,
+                    error: error.message,
+                },
+            };
+        }
+    }
+    /**
+     * Gracefully shuts down the vector store.
+     */
+    async shutdown() {
+        if (!this.isInitialized) {
+            return;
+        }
+        if (this.ownsAdapter && this.adapter) {
+            await this.adapter.close();
+        }
+        this.isInitialized = false;
+        console.log(`SqlVectorStore (ID: ${this.providerId}) shut down.`);
+    }
+    /**
+     * Gets statistics for a collection or the entire store.
+     *
+     * @param {string} [collectionName] - Specific collection, or all if omitted
+     * @returns {Promise<Record<string, any>>} Statistics
+     */
+    async getStats(collectionName) {
+        this.ensureInitialized();
+        if (collectionName) {
+            const collection = await this.getCollectionMetadata(collectionName);
+            return {
+                collectionName: collection.name,
+                dimension: collection.dimension,
+                similarityMetric: collection.similarityMetric,
+                documentCount: collection.documentCount,
+                createdAt: collection.createdAt,
+                updatedAt: collection.updatedAt,
+            };
+        }
+        const collections = await this.adapter.all(`SELECT * FROM ${this.tablePrefix}collections`);
+        return {
+            providerId: this.providerId,
+            configId: this.config.id,
+            type: 'sql',
+            collectionCount: collections.length,
+            totalDocuments: collections.reduce((sum, c) => sum + c.document_count, 0),
+            collections: collections.map((c) => ({
+                name: c.name,
+                dimension: c.dimension,
+                documentCount: c.document_count,
+            })),
+        };
+    }
+    // ============================================================================
+    // Private Helper Methods
+    // ============================================================================
+    /**
+     * Computes cosine similarity between two vectors.
+     * @private
+     */
+    cosineSimilarity(vecA, vecB) {
+        let dotProduct = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < vecA.length; i++) {
+            dotProduct += vecA[i] * vecB[i];
+            normA += vecA[i] * vecA[i];
+            normB += vecB[i] * vecB[i];
+        }
+        const magnitudeA = Math.sqrt(normA);
+        const magnitudeB = Math.sqrt(normB);
+        if (magnitudeA === 0 || magnitudeB === 0) {
+            return 0;
+        }
+        return dotProduct / (magnitudeA * magnitudeB);
+    }
+    /**
+     * Computes Euclidean distance between two vectors.
+     * @private
+     */
+    euclideanDistance(vecA, vecB) {
+        let sum = 0;
+        for (let i = 0; i < vecA.length; i++) {
+            const diff = vecA[i] - vecB[i];
+            sum += diff * diff;
+        }
+        return Math.sqrt(sum);
+    }
+    /**
+     * Computes dot product between two vectors.
+     * @private
+     */
+    dotProduct(vecA, vecB) {
+        let sum = 0;
+        for (let i = 0; i < vecA.length; i++) {
+            sum += vecA[i] * vecB[i];
+        }
+        return sum;
+    }
+    /**
+     * Checks if metadata matches a filter.
+     * @private
+     */
+    matchesFilter(metadata, filter) {
+        if (!metadata) {
+            // Check if filter only has $exists: false conditions
+            for (const key in filter) {
+                const condition = filter[key];
+                if (typeof condition === 'object' && condition !== null && condition.$exists === false) {
+                    continue;
+                }
+                return false;
+            }
+            return true;
+        }
+        for (const key in filter) {
+            const docValue = metadata[key];
+            const filterValue = filter[key];
+            if (typeof filterValue === 'object' && filterValue !== null) {
+                if (!this.evaluateCondition(docValue, filterValue)) {
+                    return false;
+                }
+            }
+            else {
+                // Direct equality check
+                if (Array.isArray(docValue)) {
+                    if (!docValue.includes(filterValue)) {
+                        return false;
+                    }
+                }
+                else if (docValue !== filterValue) {
+                    return false;
+                }
+            }
+        }
+        return true;
+    }
+    /**
+     * Evaluates a single filter condition.
+     * @private
+     */
+    evaluateCondition(docValue, condition) {
+        if (condition.$exists !== undefined) {
+            return condition.$exists === (docValue !== undefined);
+        }
+        if (docValue === undefined)
+            return false;
+        if (condition.$eq !== undefined && docValue !== condition.$eq)
+            return false;
+        if (condition.$ne !== undefined && docValue === condition.$ne)
+            return false;
+        if (typeof docValue === 'number') {
+            if (condition.$gt !== undefined && !(docValue > condition.$gt))
+                return false;
+            if (condition.$gte !== undefined && !(docValue >= condition.$gte))
+                return false;
+            if (condition.$lt !== undefined && !(docValue < condition.$lt))
+                return false;
+            if (condition.$lte !== undefined && !(docValue <= condition.$lte))
+                return false;
+        }
+        if (condition.$in !== undefined) {
+            if (Array.isArray(docValue)) {
+                if (!docValue.some(val => condition.$in.includes(val)))
+                    return false;
+            }
+            else {
+                if (!condition.$in.includes(docValue))
+                    return false;
+            }
+        }
+        if (condition.$nin !== undefined) {
+            if (Array.isArray(docValue)) {
+                if (docValue.some(val => condition.$nin.includes(val)))
+                    return false;
+            }
+            else {
+                if (condition.$nin.includes(docValue))
+                    return false;
+            }
+        }
+        if (Array.isArray(docValue)) {
+            if (condition.$contains !== undefined && !docValue.includes(condition.$contains))
+                return false;
+            if (condition.$all !== undefined && !condition.$all.every(item => docValue.includes(item)))
+                return false;
+        }
+        else if (typeof docValue === 'string' && condition.$contains !== undefined) {
+            if (!docValue.includes(String(condition.$contains)))
+                return false;
+        }
+        if (condition.$textSearch !== undefined && typeof docValue === 'string') {
+            if (!docValue.toLowerCase().includes(condition.$textSearch.toLowerCase()))
+                return false;
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=SqlVectorStore.js.map