abb-opencode-local-rag 0.1.0

package/dist/vectordb/index.d.ts

@@ -0,0 +1,168 @@
+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 readonly config;
+    private ftsEnabled;
+    constructor(config: VectorStoreConfig);
+    /**
+     * Initialize LanceDB and create table
+     */
+    initialize(): Promise<void>;
+    /**
+     * 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<number>;
+    /**
+     * 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<ChunkRow[]>;
+    /**
+     * 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<VectorChunk[]>;
+    /**
+     * Batch insert vector chunks
+     *
+     * @param chunks - Array of vector chunks
+     */
+    insertChunks(chunks: VectorChunk[]): Promise<void>;
+    /**
+     * 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<void>;
+    /**
+     * 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<SearchResult[]>;
+    /**
+     * 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<AttachmentHydrationResult>;
+    /**
+     * 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<void>;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vectordb/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,QAAQ,EAQb,KAAK,aAAa,EAClB,KAAK,YAAY,EAIjB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAA;AAGnB,YAAY,EACV,yBAAyB,EACzB,YAAY,EACZ,wBAAwB,EACxB,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,MAAM,YAAY,CAAA;AAMnB;;;;;;;GAOG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,UAAU,CAAQ;IAE1B,YAAY,MAAM,EAAE,iBAAiB,EAEpC;IAED;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAgChC;IAED;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BpD;IAED;;;;;;;;;;;;;;;;;OAiBG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CA0B5F;IAED;;;;;;;;;;OAUG;IACG,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAYlE;IAED;;;;OAIG;IACG,YAAY,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8CvD;IAED;;;;OAIG;YACW,cAAc;IAyC5B;;;;OAIG;YACW,mBAAmB;IAyBjC;;;;;;;OAOG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAO9B;IAED;;;;;;;;;;;;OAYG;IACG,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAkGxF;IAED;;;;OAIG;IACG,wBAAwB,CAC5B,OAAO,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,GACjC,OAAO,CAAC,yBAAyB,CAAC,CA+CpC;IAED;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAI3B,mEAAmE;IACnE,OAAO,CAAC,oBAAoB;IAO5B,4EAA4E;IAC5E,OAAO,CAAC,YAAY;IAIpB,sHAAsH;IACtH,OAAO,CAAC,UAAU;IAQlB;;;;;;;;;;;;;OAaG;IACG,eAAe,IAAI,OAAO,CAC9B;QACE,QAAQ,EAAE,MAAM,CAAA;QAChB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;KAC3B,EAAE,CACJ,CA2BA;IAED;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CA6CxF;IAED;;;;OAIG;IACG,SAAS,IAAI,OAAO,CAAC;QACzB,aAAa,EAAE,MAAM,CAAA;QACrB,UAAU,EAAE,MAAM,CAAA;QAClB,WAAW,EAAE,MAAM,CAAA;QACnB,MAAM,EAAE,MAAM,CAAA;QACd,eAAe,EAAE,OAAO,CAAA;QACxB,UAAU,EAAE,QAAQ,GAAG,aAAa,CAAA;KACrC,CAAC,CA+CD;IAED;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAS3B;CACF"}