import { type AttachmentHydrationResult, type ChunkRow, type SearchOptions, type SearchResult, type VectorChunk, type VectorStoreConfig } from './types.js'; export type { AttachmentHydrationResult, GroupingMode, HydratedChunkAttachments, SearchResult, VectorChunk, VisualAttachment, } from './types.js'; /** * Vector storage class using LanceDB * * Responsibilities: * - LanceDB operations (insert, delete, search) * - Transaction handling (atomicity of delete→insert) * - Metadata management */ export declare class VectorStore { private db; private table; private openingTable; private readonly config; private ftsEnabled; constructor(config: VectorStoreConfig); /** * Initialize LanceDB and create table */ initialize(): Promise; /** Discover a table created after this connection was initialized. */ private openExistingTable; /** * Delete all chunks for specified file path * * @param filePath - File path (absolute) * @returns Number of chunks removed (0 when nothing matched) */ deleteChunks(filePath: string): Promise; /** * Return chunk rows for a single file whose chunkIndex is within the * inclusive [minIdx, maxIdx] range, sorted ascending by chunkIndex. * * This is a feature-agnostic primitive: it knows nothing * about before/after/isTarget semantics — those live in the handler. * Ascending sort by chunkIndex is a contract, not incidental storage * order. * * Lazy-table null returns [] (mirrors search, listFiles, deleteChunks). * LanceDB errors are wrapped as DatabaseError with the original error * preserved as cause. * * @param filePath - File path (absolute) * @param minIdx - Minimum chunk index (inclusive) * @param maxIdx - Maximum chunk index (inclusive) * @returns Array of chunk rows sorted ascending by chunkIndex */ getChunksByRange(filePath: string, minIdx: number, maxIdx: number): Promise; /** * Return every stored chunk for a file as a full {@link VectorChunk}, * including the real embedding vector — suitable for re-insertion via * {@link insertChunks}. Used by the ingest handler to back up existing data * before a destructive re-ingest so a failure can be rolled back without * data loss or vector corruption. * * Lazy-table null returns `[]`. LanceDB errors are wrapped as DatabaseError. * * @param filePath - File path (absolute) */ getChunksByFilePath(filePath: string): Promise; /** * Batch insert vector chunks * * @param chunks - Array of vector chunks */ insertChunks(chunks: VectorChunk[]): Promise; /** * Ensure FTS index exists for hybrid search * Creates ngram-based index if it doesn't exist, drops old versions * @throws DatabaseError if index creation fails (Fail-Fast principle) */ private ensureFtsIndex; /** * Ensure schema is up to date by adding missing columns. * Uses table.addColumns() API for top-level column additions. * Idempotent: checks for column existence before adding. */ private ensureSchemaVersion; /** * Optimize table: compact fragments, update FTS index, and clean up old versions. * LanceDB OSS requires explicit optimize() call to update FTS index. * * Callers are responsible for deciding when to invoke this (e.g., once per * ingest rather than after every insert/delete) to avoid O(n²) overhead * during bulk operations. */ optimize(): Promise; /** * Execute vector search with quality filtering * Architecture: Semantic search → Filter (maxDistance, grouping) → Keyword boost → File filter (maxFiles) * * This "prefetch then rerank" approach ensures: * - maxDistance and grouping work on meaningful vector distances * - Keyword matching acts as a boost, not a replacement for semantic similarity * * @param queryVector - Query vector (dimension depends on model) * @param options - Optional search options (queryText for keyword boost, * limit, and scope path-prefix prefilter) * @returns Array of search results (sorted by distance ascending, filtered by quality settings) */ search(queryVector: number[], options?: SearchOptions): Promise; /** * Load and validate attachments for the ordered unique final search identities. * Candidate retrieval and ranking are deliberately complete before this one * projected batch query runs. */ hydrateVisualAttachments(results: readonly { id: string; }[]): Promise; /** * Build a LanceDB `.where()` predicate restricting `filePath` to the * exact-or-descendant set of the given prefixes (OR'd): `filePath = P OR * filePath LIKE 'D%'`, where the separator boundary in D stops `/a/b` from * matching `/a/bc`. Consumed by the vector branch only — the FTS branch * inherits scope via its own `filePath IN (...)` over the scoped hits. */ private buildScopePredicate; /** Build the exact-or-descendant predicate for a single prefix. */ private buildPrefixPredicate; /** Escape single quotes for a SQL string literal (mirrors deleteChunks). */ private escapeQuotes; /** Escape for a LIKE term with `ESCAPE '\'`: backslash first (else it double-escapes), then `%`, `_`, then quotes. */ private escapeLike; /** * Per-chunk `(filePath, contentHash)` projection used by incremental sync. * * One entry per stored row rather than one per file, because a file whose * rows disagree on the hash (or carry none) must be detectable as dirty. * `filePath` is the verbatim stored spelling, since that is what * {@link deleteChunks} matches. An empty-string hash — the value the * create-path seeds for Arrow schema inference — is normalized to `null` so a * hashless row can never read as a real hash, mirroring `toVectorChunk`. * * Projects only the two convergence columns so a manifest load does not * materialize embedding vectors or attachment payloads. Lazy-table null * returns `[]` (mirrors {@link listFiles}). */ listChunkHashes(): Promise<{ filePath: string; contentHash: string | null; }[]>; /** * Get list of ingested files * * @returns Array of file information */ listFiles(): Promise<{ filePath: string; chunkCount: number; timestamp: string; }[]>; /** * Get system status * * @returns System status information */ getStatus(): Promise<{ documentCount: number; chunkCount: number; memoryUsage: number; uptime: number; ftsIndexEnabled: boolean; searchMode: 'hybrid' | 'vector-only'; }>; /** * Close the database connection */ close(): Promise; } //# sourceMappingURL=index.d.ts.map