@mcampa/ai-context-core 0.0.2 → 0.1.0-beta.ff0e631

package/dist/vectordb/base/base-vector-database.d.ts

@@ -0,0 +1,58 @@
+import type { HybridSearchOptions, HybridSearchRequest, HybridSearchResult, SearchOptions, VectorDatabase, VectorDocument, VectorSearchResult } from "../types";
+/**
+ * Base configuration interface for all vector databases
+ */
+export interface BaseDatabaseConfig {
+    address?: string;
+    token?: string;
+    username?: string;
+    password?: string;
+}
+/**
+ * Abstract base class for vector database implementations
+ *
+ * Provides common functionality:
+ * - Asynchronous initialization pattern
+ * - Configuration management
+ * - Address resolution
+ *
+ * Subclasses must implement:
+ * - initialize(): Database-specific initialization logic
+ * - All VectorDatabase interface methods
+ *
+ * @template TConfig - The configuration type for the database
+ */
+export declare abstract class BaseVectorDatabase<TConfig extends BaseDatabaseConfig = BaseDatabaseConfig> implements VectorDatabase {
+    protected config: TConfig;
+    protected initializationPromise: Promise<void>;
+    constructor(config: TConfig);
+    /**
+     * Initialize the database connection
+     * Called automatically in constructor
+     * Subclasses should implement database-specific initialization
+     */
+    protected abstract initialize(): Promise<void>;
+    /**
+     * Ensure initialization is complete before method execution
+     * Should be called at the start of every public method
+     */
+    protected ensureInitialized(): Promise<void>;
+    /**
+     * Ensure collection is loaded before search/query operations
+     * Subclasses should implement database-specific loading logic
+     */
+    protected abstract ensureLoaded(collectionName: string): Promise<void>;
+    abstract createCollection(collectionName: string, dimension: number, description?: string): Promise<void>;
+    abstract createHybridCollection(collectionName: string, dimension: number, description?: string): Promise<void>;
+    abstract dropCollection(collectionName: string): Promise<void>;
+    abstract hasCollection(collectionName: string): Promise<boolean>;
+    abstract listCollections(): Promise<string[]>;
+    abstract insert(collectionName: string, documents: VectorDocument[]): Promise<void>;
+    abstract insertHybrid(collectionName: string, documents: VectorDocument[]): Promise<void>;
+    abstract search(collectionName: string, queryVector: number[], options?: SearchOptions): Promise<VectorSearchResult[]>;
+    abstract hybridSearch(collectionName: string, searchRequests: HybridSearchRequest[], options?: HybridSearchOptions): Promise<HybridSearchResult[]>;
+    abstract delete(collectionName: string, ids: string[]): Promise<void>;
+    abstract query(collectionName: string, filter: string, outputFields: string[], limit?: number): Promise<Record<string, any>[]>;
+    abstract checkCollectionLimit(): Promise<boolean>;
+}
+//# sourceMappingURL=base-vector-database.d.ts.map

package/dist/vectordb/base/base-vector-database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-vector-database.d.ts","sourceRoot":"","sources":["../../../src/vectordb/base/base-vector-database.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,cAAc,EACd,kBAAkB,EACnB,MAAM,UAAU,CAAC;AAElB;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,8BAAsB,kBAAkB,CACtC,OAAO,SAAS,kBAAkB,GAAG,kBAAkB,CACvD,YAAW,cAAc;IACzB,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC;IAC1B,SAAS,CAAC,qBAAqB,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;gBAEnC,MAAM,EAAE,OAAO;IAK3B;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAE9C;;;OAGG;cACa,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;IAIlD;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAGtE,QAAQ,CAAC,gBAAgB,CACvB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC;IAEhB,QAAQ,CAAC,sBAAsB,CAC7B,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC;IAEhB,QAAQ,CAAC,cAAc,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAE9D,QAAQ,CAAC,aAAa,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAEhE,QAAQ,CAAC,eAAe,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAE7C,QAAQ,CAAC,MAAM,CACb,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,cAAc,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC;IAEhB,QAAQ,CAAC,YAAY,CACnB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,cAAc,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC;IAEhB,QAAQ,CAAC,MAAM,CACb,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,EAAE,EACrB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAEhC,QAAQ,CAAC,YAAY,CACnB,cAAc,EAAE,MAAM,EACtB,cAAc,EAAE,mBAAmB,EAAE,EACrC,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAEhC,QAAQ,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAErE,QAAQ,CAAC,KAAK,CACZ,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,EAAE,EACtB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;IAEjC,QAAQ,CAAC,oBAAoB,IAAI,OAAO,CAAC,OAAO,CAAC;CAClD"}

package/dist/vectordb/base/base-vector-database.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseVectorDatabase = void 0;
+/**
+ * Abstract base class for vector database implementations
+ *
+ * Provides common functionality:
+ * - Asynchronous initialization pattern
+ * - Configuration management
+ * - Address resolution
+ *
+ * Subclasses must implement:
+ * - initialize(): Database-specific initialization logic
+ * - All VectorDatabase interface methods
+ *
+ * @template TConfig - The configuration type for the database
+ */
+class BaseVectorDatabase {
+    constructor(config) {
+        this.config = config;
+        this.initializationPromise = this.initialize();
+    }
+    /**
+     * Ensure initialization is complete before method execution
+     * Should be called at the start of every public method
+     */
+    async ensureInitialized() {
+        await this.initializationPromise;
+    }
+}
+exports.BaseVectorDatabase = BaseVectorDatabase;
+//# sourceMappingURL=base-vector-database.js.map

package/dist/vectordb/base/base-vector-database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-vector-database.js","sourceRoot":"","sources":["../../../src/vectordb/base/base-vector-database.ts"],"names":[],"mappings":";;;AAoBA;;;;;;;;;;;;;GAaG;AACH,MAAsB,kBAAkB;IAMtC,YAAY,MAAe;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,qBAAqB,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;IACjD,CAAC;IASD;;;OAGG;IACO,KAAK,CAAC,iBAAiB;QAC/B,MAAM,IAAI,CAAC,qBAAqB,CAAC;IACnC,CAAC;CA2DF;AAnFD,gDAmFC"}

package/dist/vectordb/factory.d.ts

@@ -0,0 +1,113 @@
+import type { FaissConfig } from "./faiss-vectordb";
+import type { LibSQLConfig } from "./libsql-vectordb";
+import type { MilvusRestfulConfig } from "./milvus-restful-vectordb";
+import type { MilvusConfig } from "./milvus-vectordb";
+import type { QdrantConfig } from "./qdrant-vectordb";
+import type { VectorDatabase } from "./types";
+/**
+ * Supported vector database types
+ */
+export declare enum VectorDatabaseType {
+    /**
+     * Milvus with gRPC protocol
+     * Use for Node.js environments with full gRPC support
+     */
+    MILVUS_GRPC = "milvus-grpc",
+    /**
+     * Milvus with RESTful API
+     * Use for browser/VSCode extension environments where gRPC is not available
+     */
+    MILVUS_RESTFUL = "milvus-restful",
+    /**
+     * Qdrant with gRPC protocol
+     * Use for Node.js environments with native hybrid search support
+     * Supports both self-hosted and Qdrant Cloud
+     */
+    QDRANT_GRPC = "qdrant-grpc",
+    /**
+     * FAISS local file-based vector database
+     * Use for local-only deployments with zero configuration
+     * Ideal for development and small-to-medium codebases
+     */
+    FAISS_LOCAL = "faiss-local",
+    /**
+     * LibSQL local file-based vector database
+     * Use for local-only deployments without native bindings
+     * Advantages over FAISS: supports deletion, filtering, pure JS
+     */
+    LIBSQL_LOCAL = "libsql"
+}
+/**
+ * Configuration type for each database type
+ */
+export interface VectorDatabaseConfig {
+    [VectorDatabaseType.MILVUS_GRPC]: MilvusConfig;
+    [VectorDatabaseType.MILVUS_RESTFUL]: MilvusRestfulConfig;
+    [VectorDatabaseType.QDRANT_GRPC]: QdrantConfig;
+    [VectorDatabaseType.FAISS_LOCAL]: FaissConfig;
+    [VectorDatabaseType.LIBSQL_LOCAL]: LibSQLConfig;
+}
+/**
+ * Factory class for creating vector database instances
+ *
+ * Usage:
+ * ```typescript
+ * const db = VectorDatabaseFactory.create(
+ *     VectorDatabaseType.MILVUS_GRPC,
+ *     { address: 'localhost:19530', token: 'xxx' }
+ * );
+ * ```
+ */
+export declare class VectorDatabaseFactory {
+    /**
+     * Create a vector database instance
+     *
+     * @param type - The type of vector database to create
+     * @param config - Configuration for the database
+     * @returns A VectorDatabase instance
+     *
+     * @example
+     * ```typescript
+     * // Create Milvus gRPC database
+     * const db = VectorDatabaseFactory.create(
+     *     VectorDatabaseType.MILVUS_GRPC,
+     *     { address: 'localhost:19530' }
+     * );
+     *
+     * // Create Milvus RESTful database
+     * const restDb = VectorDatabaseFactory.create(
+     *     VectorDatabaseType.MILVUS_RESTFUL,
+     *     { address: 'https://your-cluster.com', token: 'xxx' }
+     * );
+     *
+     * // Create Qdrant gRPC database
+     * const qdrantDb = VectorDatabaseFactory.create(
+     *     VectorDatabaseType.QDRANT_GRPC,
+     *     { address: 'localhost:6334', apiKey: 'xxx' }
+     * );
+     *
+     * // Create FAISS local database
+     * const faissDb = VectorDatabaseFactory.create(
+     *     VectorDatabaseType.FAISS_LOCAL,
+     *     { storageDir: '~/.context/faiss-indexes' }
+     * );
+     *
+     * // Create LibSQL local database
+     * const libsqlDB = VectorDatabaseFactory.create(
+     *     VectorDatabaseType.LIBSQL_LOCAL,
+     *     { storageDir: '~/.context/libsql-indexes' }
+     * );
+     * ```
+     */
+    static create<T extends VectorDatabaseType>(type: T, config: VectorDatabaseConfig[T]): VectorDatabase;
+    /**
+     * Get all supported database types
+     * Note: FAISS may not be available if native bindings are missing
+     */
+    static getSupportedTypes(): VectorDatabaseType[];
+    /**
+     * Check if FAISS is available in the current environment
+     */
+    static isFaissAvailable(): boolean;
+}
+//# sourceMappingURL=factory.d.ts.map

package/dist/vectordb/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/vectordb/factory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAqD9C;;GAEG;AACH,oBAAY,kBAAkB;IAC5B;;;OAGG;IACH,WAAW,gBAAgB;IAE3B;;;OAGG;IACH,cAAc,mBAAmB;IAEjC;;;;OAIG;IACH,WAAW,gBAAgB;IAE3B;;;;OAIG;IACH,WAAW,gBAAgB;IAE3B;;;;OAIG;IACH,YAAY,WAAW;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,CAAC,kBAAkB,CAAC,WAAW,CAAC,EAAE,YAAY,CAAC;IAC/C,CAAC,kBAAkB,CAAC,cAAc,CAAC,EAAE,mBAAmB,CAAC;IACzD,CAAC,kBAAkB,CAAC,WAAW,CAAC,EAAE,YAAY,CAAC;IAC/C,CAAC,kBAAkB,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC9C,CAAC,kBAAkB,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;CACjD;AAED;;;;;;;;;;GAUG;AACH,qBAAa,qBAAqB;IAChC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,kBAAkB,EACxC,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC9B,cAAc;IA6BjB;;;OAGG;IACH,MAAM,CAAC,iBAAiB,IAAI,kBAAkB,EAAE;IAQhD;;OAEG;IACH,MAAM,CAAC,gBAAgB,IAAI,OAAO;CAGnC"}

package/dist/vectordb/factory.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VectorDatabaseFactory = exports.VectorDatabaseType = void 0;
+const libsql_vectordb_1 = require("./libsql-vectordb");
+const milvus_restful_vectordb_1 = require("./milvus-restful-vectordb");
+const milvus_vectordb_1 = require("./milvus-vectordb");
+const qdrant_vectordb_1 = require("./qdrant-vectordb");
+// FAISS is optional - may not be available in all environments (e.g., CI without native bindings)
+// Use lazy loading to avoid import errors
+let FaissVectorDatabase;
+let faissAvailable = null; // null = not checked yet
+let faissCheckError = null;
+function checkFaissAvailability() {
+    if (faissAvailable !== null) {
+        return faissAvailable;
+    }
+    try {
+        FaissVectorDatabase = require("./faiss-vectordb").FaissVectorDatabase;
+        faissAvailable = true;
+        return true;
+    }
+    catch (error) {
+        const errorMsg = error.message || String(error);
+        const errorCode = error.code;
+        // Treat as "FAISS unavailable" for:
+        // 1. Native binding errors (faiss-node not compiled)
+        // 2. Module not found errors (module path resolution in test environments)
+        const isExpectedUnavailableError = errorMsg.includes("Could not locate the bindings file") ||
+            errorMsg.includes("faiss-node") ||
+            errorCode === "MODULE_NOT_FOUND";
+        if (isExpectedUnavailableError) {
+            faissAvailable = false;
+            faissCheckError = errorMsg.includes("faiss-node")
+                ? "FAISS native bindings not available"
+                : "FAISS module not found";
+            console.warn(`[VectorDatabaseFactory] ${faissCheckError}. FAISS support disabled.`);
+            return false;
+        }
+        // For syntax errors, type errors, or other real bugs - re-throw
+        console.error("[VectorDatabaseFactory] Unexpected error loading FAISS module:", errorMsg);
+        throw error;
+    }
+}
+/**
+ * Supported vector database types
+ */
+var VectorDatabaseType;
+(function (VectorDatabaseType) {
+    /**
+     * Milvus with gRPC protocol
+     * Use for Node.js environments with full gRPC support
+     */
+    VectorDatabaseType["MILVUS_GRPC"] = "milvus-grpc";
+    /**
+     * Milvus with RESTful API
+     * Use for browser/VSCode extension environments where gRPC is not available
+     */
+    VectorDatabaseType["MILVUS_RESTFUL"] = "milvus-restful";
+    /**
+     * Qdrant with gRPC protocol
+     * Use for Node.js environments with native hybrid search support
+     * Supports both self-hosted and Qdrant Cloud
+     */
+    VectorDatabaseType["QDRANT_GRPC"] = "qdrant-grpc";
+    /**
+     * FAISS local file-based vector database
+     * Use for local-only deployments with zero configuration
+     * Ideal for development and small-to-medium codebases
+     */
+    VectorDatabaseType["FAISS_LOCAL"] = "faiss-local";
+    /**
+     * LibSQL local file-based vector database
+     * Use for local-only deployments without native bindings
+     * Advantages over FAISS: supports deletion, filtering, pure JS
+     */
+    VectorDatabaseType["LIBSQL_LOCAL"] = "libsql";
+})(VectorDatabaseType || (exports.VectorDatabaseType = VectorDatabaseType = {}));
+/**
+ * Factory class for creating vector database instances
+ *
+ * Usage:
+ * ```typescript
+ * const db = VectorDatabaseFactory.create(
+ *     VectorDatabaseType.MILVUS_GRPC,
+ *     { address: 'localhost:19530', token: 'xxx' }
+ * );
+ * ```
+ */
+class VectorDatabaseFactory {
+    /**
+     * Create a vector database instance
+     *
+     * @param type - The type of vector database to create
+     * @param config - Configuration for the database
+     * @returns A VectorDatabase instance
+     *
+     * @example
+     * ```typescript
+     * // Create Milvus gRPC database
+     * const db = VectorDatabaseFactory.create(
+     *     VectorDatabaseType.MILVUS_GRPC,
+     *     { address: 'localhost:19530' }
+     * );
+     *
+     * // Create Milvus RESTful database
+     * const restDb = VectorDatabaseFactory.create(
+     *     VectorDatabaseType.MILVUS_RESTFUL,
+     *     { address: 'https://your-cluster.com', token: 'xxx' }
+     * );
+     *
+     * // Create Qdrant gRPC database
+     * const qdrantDb = VectorDatabaseFactory.create(
+     *     VectorDatabaseType.QDRANT_GRPC,
+     *     { address: 'localhost:6334', apiKey: 'xxx' }
+     * );
+     *
+     * // Create FAISS local database
+     * const faissDb = VectorDatabaseFactory.create(
+     *     VectorDatabaseType.FAISS_LOCAL,
+     *     { storageDir: '~/.context/faiss-indexes' }
+     * );
+     *
+     * // Create LibSQL local database
+     * const libsqlDB = VectorDatabaseFactory.create(
+     *     VectorDatabaseType.LIBSQL_LOCAL,
+     *     { storageDir: '~/.context/libsql-indexes' }
+     * );
+     * ```
+     */
+    static create(type, config) {
+        switch (type) {
+            case VectorDatabaseType.MILVUS_GRPC:
+                return new milvus_vectordb_1.MilvusVectorDatabase(config);
+            case VectorDatabaseType.MILVUS_RESTFUL:
+                return new milvus_restful_vectordb_1.MilvusRestfulVectorDatabase(config);
+            case VectorDatabaseType.QDRANT_GRPC:
+                return new qdrant_vectordb_1.QdrantVectorDatabase(config);
+            case VectorDatabaseType.FAISS_LOCAL:
+                if (!checkFaissAvailability()) {
+                    throw new Error(`FAISS vector database is not available. ${faissCheckError || "Native bindings could not be loaded"}. ` +
+                        "This usually happens in environments without C++ build tools. " +
+                        "Please use another vector database type (MILVUS_GRPC, MILVUS_RESTFUL, QDRANT_GRPC, or LIBSQL_LOCAL).");
+                }
+                return new FaissVectorDatabase(config);
+            case VectorDatabaseType.LIBSQL_LOCAL:
+                return new libsql_vectordb_1.LibSQLVectorDatabase(config);
+            default:
+                throw new Error(`Unsupported database type: ${type}`);
+        }
+    }
+    /**
+     * Get all supported database types
+     * Note: FAISS may not be available if native bindings are missing
+     */
+    static getSupportedTypes() {
+        const types = Object.values(VectorDatabaseType);
+        if (!checkFaissAvailability()) {
+            return types.filter((t) => t !== VectorDatabaseType.FAISS_LOCAL);
+        }
+        return types;
+    }
+    /**
+     * Check if FAISS is available in the current environment
+     */
+    static isFaissAvailable() {
+        return checkFaissAvailability();
+    }
+}
+exports.VectorDatabaseFactory = VectorDatabaseFactory;
+//# sourceMappingURL=factory.js.map

package/dist/vectordb/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/vectordb/factory.ts"],"names":[],"mappings":";;;AAMA,uDAAyD;AACzD,uEAAwE;AACxE,uDAAyD;AACzD,uDAAyD;AAEzD,kGAAkG;AAClG,0CAA0C;AAC1C,IAAI,mBAAwB,CAAC;AAC7B,IAAI,cAAc,GAAmB,IAAI,CAAC,CAAC,yBAAyB;AACpE,IAAI,eAAe,GAAkB,IAAI,CAAC;AAE1C,SAAS,sBAAsB;IAC7B,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;QAC5B,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,IAAI,CAAC;QACH,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,mBAAmB,CAAC;QACtE,cAAc,GAAG,IAAI,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;QAChD,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC;QAE7B,oCAAoC;QACpC,qDAAqD;QACrD,2EAA2E;QAC3E,MAAM,0BAA0B,GAC9B,QAAQ,CAAC,QAAQ,CAAC,oCAAoC,CAAC;YACvD,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC;YAC/B,SAAS,KAAK,kBAAkB,CAAC;QAEnC,IAAI,0BAA0B,EAAE,CAAC;YAC/B,cAAc,GAAG,KAAK,CAAC;YACvB,eAAe,GAAG,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC;gBAC/C,CAAC,CAAC,qCAAqC;gBACvC,CAAC,CAAC,wBAAwB,CAAC;YAC7B,OAAO,CAAC,IAAI,CACV,2BAA2B,eAAe,2BAA2B,CACtE,CAAC;YACF,OAAO,KAAK,CAAC;QACf,CAAC;QAED,gEAAgE;QAChE,OAAO,CAAC,KAAK,CACX,gEAAgE,EAChE,QAAQ,CACT,CAAC;QACF,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,IAAY,kBAiCX;AAjCD,WAAY,kBAAkB;IAC5B;;;OAGG;IACH,iDAA2B,CAAA;IAE3B;;;OAGG;IACH,uDAAiC,CAAA;IAEjC;;;;OAIG;IACH,iDAA2B,CAAA;IAE3B;;;;OAIG;IACH,iDAA2B,CAAA;IAE3B;;;;OAIG;IACH,6CAAuB,CAAA;AACzB,CAAC,EAjCW,kBAAkB,kCAAlB,kBAAkB,QAiC7B;AAaD;;;;;;;;;;GAUG;AACH,MAAa,qBAAqB;IAChC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,MAAM,CAAC,MAAM,CACX,IAAO,EACP,MAA+B;QAE/B,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,kBAAkB,CAAC,WAAW;gBACjC,OAAO,IAAI,sCAAoB,CAAC,MAAsB,CAAC,CAAC;YAE1D,KAAK,kBAAkB,CAAC,cAAc;gBACpC,OAAO,IAAI,qDAA2B,CAAC,MAA6B,CAAC,CAAC;YAExE,KAAK,kBAAkB,CAAC,WAAW;gBACjC,OAAO,IAAI,sCAAoB,CAAC,MAAsB,CAAC,CAAC;YAE1D,KAAK,kBAAkB,CAAC,WAAW;gBACjC,IAAI,CAAC,sBAAsB,EAAE,EAAE,CAAC;oBAC9B,MAAM,IAAI,KAAK,CACb,2CAA2C,eAAe,IAAI,qCAAqC,IAAI;wBACrG,gEAAgE;wBAChE,sGAAsG,CACzG,CAAC;gBACJ,CAAC;gBACD,OAAO,IAAI,mBAAmB,CAAC,MAAqB,CAAC,CAAC;YAExD,KAAK,kBAAkB,CAAC,YAAY;gBAClC,OAAO,IAAI,sCAAoB,CAAC,MAAsB,CAAC,CAAC;YAE1D;gBACE,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,EAAE,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,iBAAiB;QACtB,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;QAChD,IAAI,CAAC,sBAAsB,EAAE,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,kBAAkB,CAAC,WAAW,CAAC,CAAC;QACnE,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,gBAAgB;QACrB,OAAO,sBAAsB,EAAE,CAAC;IAClC,CAAC;CACF;AA3FD,sDA2FC"}

package/dist/vectordb/faiss-vectordb.d.ts

@@ -0,0 +1,162 @@
+import { BaseDatabaseConfig, BaseVectorDatabase } from "./base/base-vector-database";
+import { BM25Config } from "./sparse/simple-bm25";
+import { HybridSearchOptions, HybridSearchRequest, HybridSearchResult, SearchOptions, VectorDocument, VectorSearchResult } from "./types";
+export interface FaissConfig extends BaseDatabaseConfig {
+    /**
+     * Storage directory for FAISS indexes
+     * @default ~/.context/faiss-indexes
+     */
+    storageDir?: string;
+    /**
+     * BM25 configuration for sparse vector generation
+     */
+    bm25Config?: BM25Config;
+}
+/**
+ * FAISS Vector Database implementation for local-only deployments
+ *
+ * Features:
+ * - Zero-configuration file-based storage
+ * - Hybrid search with BM25 sparse vectors
+ * - RRF (Reciprocal Rank Fusion) reranking
+ * - Perfect for local development and small-to-medium codebases
+ *
+ * Architecture:
+ * - Dense vectors: Stored in FAISS IndexFlatL2 (L2 distance)
+ * - Sparse vectors: Generated using SimpleBM25 for keyword matching
+ * - Hybrid search: Combines both using RRF fusion
+ *
+ * Storage structure:
+ * ~/.context/faiss-indexes/
+ *   └── {collection_name}/
+ *       ├── dense.index        # FAISS index file
+ *       ├── sparse.json        # BM25 model (vocabulary, IDF)
+ *       └── metadata.json      # Document metadata
+ *
+ * Limitations:
+ * - Document deletion is NOT supported (FAISS IndexFlatL2 limitation)
+ * - Query filters are NOT supported (returns all documents)
+ * - To remove documents, you must drop and recreate the collection
+ */
+export declare class FaissVectorDatabase extends BaseVectorDatabase<FaissConfig> {
+    private collections;
+    constructor(config: FaissConfig);
+    /**
+     * Get storage directory (lazily computed from config)
+     */
+    private get storageDir();
+    /**
+     * Initialize FAISS storage directory
+     */
+    protected initialize(): Promise<void>;
+    /**
+     * FAISS indexes are loaded on-demand when accessed
+     */
+    protected ensureLoaded(collectionName: string): Promise<void>;
+    /**
+     * Get collection storage path
+     */
+    private getCollectionPath;
+    /**
+     * Load collection from disk
+     */
+    private loadCollection;
+    /**
+     * Save collection to disk
+     */
+    private saveCollection;
+    /**
+     * Create collection with dense vectors only
+     */
+    createCollection(collectionName: string, dimension: number, _description?: string): Promise<void>;
+    /**
+     * Create collection with hybrid search support (dense + sparse vectors)
+     */
+    createHybridCollection(collectionName: string, dimension: number, _description?: string): Promise<void>;
+    /**
+     * Drop collection
+     */
+    dropCollection(collectionName: string): Promise<void>;
+    /**
+     * Check if collection exists
+     */
+    hasCollection(collectionName: string): Promise<boolean>;
+    /**
+     * List all collections
+     */
+    listCollections(): Promise<string[]>;
+    /**
+     * Insert vector documents (dense only)
+     */
+    insert(collectionName: string, documents: VectorDocument[]): Promise<void>;
+    /**
+     * Insert hybrid vector documents (dense + sparse)
+     */
+    insertHybrid(collectionName: string, documents: VectorDocument[]): Promise<void>;
+    /**
+     * Search similar vectors (dense search only)
+     */
+    search(collectionName: string, queryVector: number[], options?: SearchOptions): Promise<VectorSearchResult[]>;
+    /**
+     * Hybrid search with multiple vector fields (dense + sparse)
+     */
+    hybridSearch(collectionName: string, searchRequests: HybridSearchRequest[], options?: HybridSearchOptions): Promise<HybridSearchResult[]>;
+    /**
+     * Perform dense vector search using FAISS index
+     */
+    private performDenseSearch;
+    /**
+     * Perform sparse search using BM25
+     */
+    private performSparseSearch;
+    /**
+     * Calculate sparse vector dot product score
+     */
+    private calculateSparseScore;
+    /**
+     * Pre-compute ranks from scores (O(n log n) instead of O(n²))
+     */
+    private computeRanks;
+    /**
+     * Apply Reciprocal Rank Fusion (RRF) reranking
+     */
+    private applyRRF;
+    /**
+     * Delete documents by IDs
+     *
+     * ⚠️ NOT IMPLEMENTED: FAISS does not support document deletion
+     *
+     * The FAISS IndexFlatL2 library does not provide a way to remove vectors
+     * from an existing index. To fully remove documents, you must:
+     *
+     * 1. Drop the collection using dropCollection()
+     * 2. Recreate it using createCollection() or createHybridCollection()
+     * 3. Re-insert all documents except the ones you want to delete
+     *
+     * @throws Error Always throws - deletion is not supported
+     * @param collectionName Collection name
+     * @param ids Document IDs to delete (not used)
+     */
+    delete(collectionName: string, ids: string[]): Promise<void>;
+    /**
+     * Query documents with filter conditions
+     *
+     * ⚠️ LIMITATION: Filter parameter is currently ignored
+     *
+     * This method returns ALL documents in the collection (up to limit),
+     * not filtered results. Filter parsing is not yet implemented for FAISS.
+     *
+     * @param collectionName Collection name
+     * @param filter Filter expression (currently ignored - returns all documents)
+     * @param outputFields Fields to return in results
+     * @param limit Maximum number of results (only limit is enforced)
+     * @returns All documents with specified fields (up to limit)
+     */
+    query(collectionName: string, filter: string, outputFields: string[], limit?: number): Promise<Record<string, any>[]>;
+    /**
+     * Check collection limit
+     * FAISS has no inherent collection limit (only limited by disk space)
+     */
+    checkCollectionLimit(): Promise<boolean>;
+}
+//# sourceMappingURL=faiss-vectordb.d.ts.map

package/dist/vectordb/faiss-vectordb.d.ts.map

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