@pleaseai/context-please-core 0.3.0 → 0.5.0

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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"}