@vivantel/virage-store-lancedb 0.2.0

package/README.md

@@ -0,0 +1,78 @@
+# @vivantel/virage-store-lancedb
+
+[![npm](https://img.shields.io/npm/v/@vivantel/virage-store-lancedb.svg)](https://www.npmjs.com/package/@vivantel/virage-store-lancedb)
+
+LanceDB vector store for [`@vivantel/virage-core`](../rag-core/README.md). Embedded and file-based — no server required. Data lives in a local directory (or LanceDB Cloud with an API key).
+
+## Installation
+
+```bash
+npm install @vivantel/virage-store-lancedb @vivantel/virage-core
+```
+
+## Quick start (JSON config)
+
+Local file storage — no server needed:
+
+```json
+{
+  "vectorStore": {
+    "package": "@vivantel/virage-store-lancedb",
+    "config": {
+      "uri": "./lancedb"
+    }
+  }
+}
+```
+
+## LanceDB Cloud
+
+Pass your LanceDB Cloud URI and API key:
+
+```json
+{
+  "vectorStore": {
+    "package": "@vivantel/virage-store-lancedb",
+    "config": {
+      "uri": "db://my-project",
+      "apiKey": "${LANCEDB_API_KEY}"
+    }
+  }
+}
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `uri` | `string` | **required** | Local path (`"./lancedb"`) or LanceDB Cloud URI (`"db://…"`) |
+| `apiKey` | `string` | `undefined` | LanceDB Cloud API key |
+| `tableName` | `string` | `"documents"` | Table name inside the database |
+| `dimensions` | `number` | `1536` | Vector size — must match your embedder |
+
+## TypeScript usage
+
+```typescript
+import { LanceDBVectorStore } from "@vivantel/virage-store-lancedb";
+
+const store = new LanceDBVectorStore({
+  uri: "./lancedb",
+  tableName: "my-docs",
+  dimensions: 1536,
+});
+```
+
+## Self-registration
+
+This package declares a `"rag-plugin"` field in its `package.json`. Once installed, `virage init` discovers it automatically — no manual config required.
+
+```jsonc
+// package.json (excerpt)
+"rag-plugin": {
+  "type": "vectorStore",
+  "label": "LanceDB (embedded, file-based)",
+  "key": "lancedb",
+  "envVars": [],
+  "defaultConfig": { "uri": "./lancedb" }
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { LanceDBVectorStore, type LanceDBVectorStoreOptions } from "./store.js";
+import type { VectorStore } from "@vivantel/virage-core";
+/** Factory used by the JSON config loader. */
+export declare function createVectorStore(config: Record<string, unknown>): VectorStore;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAEhF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAGzD,8CAA8C;AAC9C,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,WAAW,CAeb"}

package/dist/index.js

@@ -0,0 +1,16 @@
+export { LanceDBVectorStore } from "./store.js";
+import { LanceDBVectorStore } from "./store.js";
+/** Factory used by the JSON config loader. */
+export function createVectorStore(config) {
+    const uri = typeof config.uri === "string" ? config.uri : undefined;
+    if (!uri) {
+        throw new Error('@vivantel/virage-store-lancedb: config.uri is required (e.g. "./lancedb" for local file storage)');
+    }
+    return new LanceDBVectorStore({
+        uri,
+        apiKey: typeof config.apiKey === "string" ? config.apiKey : undefined,
+        tableName: typeof config.tableName === "string" ? config.tableName : undefined,
+        dimensions: typeof config.dimensions === "number" ? config.dimensions : undefined,
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAkC,MAAM,YAAY,CAAC;AAGhF,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,8CAA8C;AAC9C,MAAM,UAAU,iBAAiB,CAC/B,MAA+B;IAE/B,MAAM,GAAG,GAAG,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACpE,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,kGAAkG,CACnG,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,kBAAkB,CAAC;QAC5B,GAAG;QACH,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;QACrE,SAAS,EACP,OAAO,MAAM,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;QACrE,UAAU,EACR,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;KACxE,CAAC,CAAC;AACL,CAAC"}

package/dist/query-perf.d.ts

@@ -0,0 +1,3 @@
+import type { QueryPerfReport } from "@vivantel/virage-core";
+export declare function getQueryPerfReport(table: any, dimensions: number, timeframeHours: number): Promise<QueryPerfReport>;
+//# sourceMappingURL=query-perf.d.ts.map

package/dist/query-perf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-perf.d.ts","sourceRoot":"","sources":["../src/query-perf.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAa7D,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,GAAG,EACV,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,eAAe,CAAC,CA4C1B"}

package/dist/query-perf.js

@@ -0,0 +1,49 @@
+const SAMPLE_COUNT = 20;
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return -1;
+    return (sorted[Math.floor((p / 100) * sorted.length)] ??
+        sorted[sorted.length - 1] ??
+        0);
+}
+export async function getQueryPerfReport(table, dimensions, timeframeHours) {
+    const zeroVector = Array(dimensions).fill(0);
+    const latencies = [];
+    for (let i = 0; i < SAMPLE_COUNT; i++) {
+        const start = performance.now();
+        try {
+            await table
+                .vectorSearch(zeroVector)
+                .column("embedding")
+                .distanceType("cosine")
+                .limit(10)
+                .toArray();
+        }
+        catch {
+            // Table may be empty or index unavailable — still record timing
+        }
+        latencies.push(performance.now() - start);
+    }
+    latencies.sort((a, b) => a - b);
+    const p50 = percentile(latencies, 50);
+    const p95 = percentile(latencies, 95);
+    const p99 = percentile(latencies, 99);
+    const slowQueryCount = latencies.filter((ms) => ms > 100).length;
+    const suggestedIndexes = [];
+    if (p95 > 50) {
+        suggestedIndexes.push(`p95 latency (${p95.toFixed(1)} ms) is high. ` +
+            `Consider creating an IVF-PQ index to speed up searches.`);
+    }
+    else {
+        suggestedIndexes.push("Query performance looks healthy.");
+    }
+    return {
+        timeframeHours,
+        p50LatencyMs: Math.round(p50 * 10) / 10,
+        p95LatencyMs: Math.round(p95 * 10) / 10,
+        p99LatencyMs: Math.round(p99 * 10) / 10,
+        slowQueryCount,
+        suggestedIndexes,
+    };
+}
+//# sourceMappingURL=query-perf.js.map

package/dist/query-perf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-perf.js","sourceRoot":"","sources":["../src/query-perf.ts"],"names":[],"mappings":"AAEA,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB,SAAS,UAAU,CAAC,MAAgB,EAAE,CAAS;IAC7C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,CAAC;IACnC,OAAO,CACL,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7C,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;QACzB,CAAC,CACF,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAU,EACV,UAAkB,EAClB,cAAsB;IAEtB,MAAM,UAAU,GAAG,KAAK,CAAS,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACrD,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAChC,IAAI,CAAC;YACH,MAAM,KAAK;iBACR,YAAY,CAAC,UAAU,CAAC;iBACxB,MAAM,CAAC,WAAW,CAAC;iBACnB,YAAY,CAAC,QAAQ,CAAC;iBACtB,KAAK,CAAC,EAAE,CAAC;iBACT,OAAO,EAAE,CAAC;QACf,CAAC;QAAC,MAAM,CAAC;YACP,gEAAgE;QAClE,CAAC;QACD,SAAS,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;IAC5C,CAAC;IAED,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAEhC,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACtC,MAAM,GAAG,GAAG,UAAU,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACtC,MAAM,cAAc,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC;IAEjE,MAAM,gBAAgB,GAAa,EAAE,CAAC;IACtC,IAAI,GAAG,GAAG,EAAE,EAAE,CAAC;QACb,gBAAgB,CAAC,IAAI,CACnB,gBAAgB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,gBAAgB;YAC5C,yDAAyD,CAC5D,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,gBAAgB,CAAC,IAAI,CAAC,kCAAkC,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO;QACL,cAAc;QACd,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,EAAE;QACvC,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,EAAE;QACvC,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,EAAE;QACvC,cAAc;QACd,gBAAgB;KACjB,CAAC;AACJ,CAAC"}

package/dist/query-perf.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=query-perf.test.d.ts.map

package/dist/query-perf.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-perf.test.d.ts","sourceRoot":"","sources":["../src/query-perf.test.ts"],"names":[],"mappings":""}

package/dist/query-perf.test.js

@@ -0,0 +1,67 @@
+import { describe, it, expect, vi } from "vitest";
+import { getQueryPerfReport } from "./query-perf.js";
+function makeTable(searchDelayMs = 5) {
+    return {
+        vectorSearch: vi.fn().mockReturnValue({
+            column: vi.fn().mockReturnThis(),
+            distanceType: vi.fn().mockReturnThis(),
+            limit: vi.fn().mockReturnThis(),
+            toArray: vi
+                .fn()
+                .mockImplementation(() => new Promise((resolve) => setTimeout(() => resolve([]), searchDelayMs))),
+        }),
+    };
+}
+describe("getQueryPerfReport (LanceDB)", () => {
+    it("returns valid latency percentiles (p50 ≤ p95 ≤ p99)", async () => {
+        const report = await getQueryPerfReport(makeTable(1), 384, 24);
+        expect(report.timeframeHours).toBe(24);
+        expect(report.p50LatencyMs).toBeGreaterThanOrEqual(0);
+        expect(report.p95LatencyMs).toBeGreaterThanOrEqual(report.p50LatencyMs);
+        expect(report.p99LatencyMs).toBeGreaterThanOrEqual(report.p95LatencyMs);
+    });
+    it("timeframeHours is reflected in the report", async () => {
+        const report = await getQueryPerfReport(makeTable(1), 384, 48);
+        expect(report.timeframeHours).toBe(48);
+    });
+    it("slowQueryCount is 0 for fast queries (< 100 ms)", async () => {
+        const report = await getQueryPerfReport(makeTable(1), 384, 24);
+        expect(report.slowQueryCount).toBe(0);
+    });
+    it("returns healthy suggestion when p95 latency ≤ 50 ms", async () => {
+        const report = await getQueryPerfReport(makeTable(1), 384, 24);
+        expect(report.suggestedIndexes[0]).toMatch(/healthy/i);
+    });
+    it("suggests IVF-PQ when p95 latency > 50 ms", async () => {
+        const report = await getQueryPerfReport(makeTable(80), 384, 24);
+        expect(report.suggestedIndexes[0]).toMatch(/IVF-PQ/i);
+    }, 10_000);
+    it("records timing even when table.vectorSearch throws", async () => {
+        const table = {
+            vectorSearch: vi.fn().mockReturnValue({
+                column: vi.fn().mockReturnThis(),
+                distanceType: vi.fn().mockReturnThis(),
+                limit: vi.fn().mockReturnThis(),
+                toArray: vi.fn().mockRejectedValue(new Error("table is empty")),
+            }),
+        };
+        const report = await getQueryPerfReport(table, 384, 24);
+        // Must still return a report with valid (≥ 0) latencies
+        expect(report.p50LatencyMs).toBeGreaterThanOrEqual(0);
+        expect(report.slowQueryCount).toBeGreaterThanOrEqual(0);
+    });
+    it("uses the provided dimensions to build the zero-vector query", async () => {
+        const searchSpy = vi.fn().mockReturnValue({
+            column: vi.fn().mockReturnThis(),
+            distanceType: vi.fn().mockReturnThis(),
+            limit: vi.fn().mockReturnThis(),
+            toArray: vi.fn().mockResolvedValue([]),
+        });
+        await getQueryPerfReport({ vectorSearch: searchSpy }, 128, 24);
+        // vectorSearch should have been called with a 128-dimensional zero vector
+        const firstArg = searchSpy.mock.calls[0][0];
+        expect(firstArg).toHaveLength(128);
+        expect(firstArg.every((v) => v === 0)).toBe(true);
+    });
+}, 30_000);
+//# sourceMappingURL=query-perf.test.js.map

package/dist/query-perf.test.js.map

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

package/dist/stats.d.ts

@@ -0,0 +1,3 @@
+import type { IndexStats } from "@vivantel/virage-core";
+export declare function getIndexStats(table: any): Promise<IndexStats>;
+//# sourceMappingURL=stats.d.ts.map

package/dist/stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.d.ts","sourceRoot":"","sources":["../src/stats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGxD,wBAAsB,aAAa,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC,CA0CnE"}

package/dist/stats.js

@@ -0,0 +1,40 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function getIndexStats(table) {
+    const totalVectors = (await table.countRows());
+    const suggestions = [];
+    let indexType = "flat";
+    try {
+        const indices = (await table.listIndices());
+        if (indices.length > 0) {
+            const types = indices.map((i) => (i.indexType ?? "").toLowerCase());
+            if (types.some((t) => t.includes("hnsw"))) {
+                indexType = "hnsw";
+            }
+            else if (types.some((t) => t.includes("ivf"))) {
+                indexType = "ivfflat";
+            }
+        }
+    }
+    catch {
+        // listIndices unavailable — assume flat
+    }
+    if (totalVectors === 0) {
+        suggestions.push("Table is empty.");
+    }
+    else if (totalVectors > 10_000 && indexType === "flat") {
+        suggestions.push(`Table has ${totalVectors.toLocaleString()} vectors on a flat index. ` +
+            `Consider creating an IVF-PQ index for faster searches.`);
+    }
+    else {
+        suggestions.push("Index looks healthy.");
+    }
+    return {
+        totalVectors,
+        indexType,
+        annRecallAt10: -1,
+        indexAgeHours: -1,
+        deadTupleFraction: 0,
+        suggestions,
+    };
+}
+//# sourceMappingURL=stats.js.map

package/dist/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../src/stats.ts"],"names":[],"mappings":"AAEA,8DAA8D;AAC9D,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,KAAU;IAC5C,MAAM,YAAY,GAAG,CAAC,MAAM,KAAK,CAAC,SAAS,EAAE,CAAW,CAAC;IACzD,MAAM,WAAW,GAAa,EAAE,CAAC;IAEjC,IAAI,SAAS,GAA4B,MAAM,CAAC;IAEhD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,CAAC,MAAM,KAAK,CAAC,WAAW,EAAE,CAGxC,CAAC;QACH,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;YACpE,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;gBAC1C,SAAS,GAAG,MAAM,CAAC;YACrB,CAAC;iBAAM,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;gBAChD,SAAS,GAAG,SAAS,CAAC;YACxB,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,wCAAwC;IAC1C,CAAC;IAED,IAAI,YAAY,KAAK,CAAC,EAAE,CAAC;QACvB,WAAW,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;IACtC,CAAC;SAAM,IAAI,YAAY,GAAG,MAAM,IAAI,SAAS,KAAK,MAAM,EAAE,CAAC;QACzD,WAAW,CAAC,IAAI,CACd,aAAa,YAAY,CAAC,cAAc,EAAE,4BAA4B;YACpE,wDAAwD,CAC3D,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,WAAW,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO;QACL,YAAY;QACZ,SAAS;QACT,aAAa,EAAE,CAAC,CAAC;QACjB,aAAa,EAAE,CAAC,CAAC;QACjB,iBAAiB,EAAE,CAAC;QACpB,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/dist/stats.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stats.test.d.ts.map

package/dist/stats.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.test.d.ts","sourceRoot":"","sources":["../src/stats.test.ts"],"names":[],"mappings":""}

package/dist/stats.test.js

@@ -0,0 +1,96 @@
+import { describe, it, expect, vi } from "vitest";
+import { getIndexStats } from "./stats.js";
+function makeTable(overrides = {}) {
+    return {
+        countRows: vi.fn().mockResolvedValue(0),
+        listIndices: vi.fn().mockResolvedValue([]),
+        ...overrides,
+    };
+}
+describe("getIndexStats (LanceDB)", () => {
+    describe("empty table", () => {
+        it("returns flat indexType and empty-table suggestion when table has no rows", async () => {
+            const table = makeTable({ countRows: vi.fn().mockResolvedValue(0) });
+            const stats = await getIndexStats(table);
+            expect(stats.totalVectors).toBe(0);
+            expect(stats.indexType).toBe("flat");
+            expect(stats.suggestions[0]).toMatch(/empty/i);
+        });
+    });
+    describe("flat index with various vector counts", () => {
+        it("returns healthy suggestion for a small table (≤ 10 000 vectors, no index)", async () => {
+            const stats = await getIndexStats(makeTable({ countRows: vi.fn().mockResolvedValue(500) }));
+            expect(stats.suggestions[0]).toMatch(/healthy/i);
+        });
+        it("returns healthy suggestion at exactly 10 000 vectors (boundary)", async () => {
+            const stats = await getIndexStats(makeTable({ countRows: vi.fn().mockResolvedValue(10_000) }));
+            expect(stats.suggestions[0]).toMatch(/healthy/i);
+        });
+        it("suggests creating an IVF-PQ index when > 10 000 vectors and no index", async () => {
+            const stats = await getIndexStats(makeTable({ countRows: vi.fn().mockResolvedValue(15_000) }));
+            expect(stats.totalVectors).toBe(15_000);
+            expect(stats.indexType).toBe("flat");
+            expect(stats.suggestions[0]).toMatch(/IVF-PQ/i);
+        });
+    });
+    describe("index type detection via listIndices", () => {
+        it("detects hnsw from HNSW indexType", async () => {
+            const table = makeTable({
+                countRows: vi.fn().mockResolvedValue(1000),
+                listIndices: vi
+                    .fn()
+                    .mockResolvedValue([{ name: "emb_idx", indexType: "HNSW" }]),
+            });
+            const stats = await getIndexStats(table);
+            expect(stats.indexType).toBe("hnsw");
+            expect(stats.suggestions[0]).toMatch(/healthy/i);
+        });
+        it("detects ivfflat from IVF_PQ indexType", async () => {
+            const table = makeTable({
+                countRows: vi.fn().mockResolvedValue(20_000),
+                listIndices: vi
+                    .fn()
+                    .mockResolvedValue([{ name: "emb_idx", indexType: "IVF_PQ" }]),
+            });
+            const stats = await getIndexStats(table);
+            expect(stats.indexType).toBe("ivfflat");
+            // Has a real index → should be healthy, not suggest IVF-PQ creation
+            expect(stats.suggestions[0]).toMatch(/healthy/i);
+        });
+        it("does not suggest IVF-PQ creation when a non-flat index is present (even > 10k)", async () => {
+            const table = makeTable({
+                countRows: vi.fn().mockResolvedValue(50_000),
+                listIndices: vi
+                    .fn()
+                    .mockResolvedValue([{ name: "idx", indexType: "IVF_PQ" }]),
+            });
+            const stats = await getIndexStats(table);
+            expect(stats.suggestions.every((s) => !/IVF-PQ creation/i.test(s))).toBe(true);
+        });
+        it("falls back to flat when listIndices throws", async () => {
+            const table = makeTable({
+                countRows: vi.fn().mockResolvedValue(500),
+                listIndices: vi.fn().mockRejectedValue(new Error("not supported")),
+            });
+            const stats = await getIndexStats(table);
+            expect(stats.indexType).toBe("flat");
+        });
+        it("falls back to flat when listIndices returns an empty array", async () => {
+            const table = makeTable({
+                countRows: vi.fn().mockResolvedValue(500),
+                listIndices: vi.fn().mockResolvedValue([]),
+            });
+            const stats = await getIndexStats(table);
+            expect(stats.indexType).toBe("flat");
+        });
+    });
+    describe("fixed metadata fields", () => {
+        it("always returns annRecallAt10 = -1, indexAgeHours = -1, deadTupleFraction = 0", async () => {
+            const stats = await getIndexStats(makeTable({ countRows: vi.fn().mockResolvedValue(100) }));
+            expect(stats.annRecallAt10).toBe(-1);
+            expect(stats.indexAgeHours).toBe(-1);
+            expect(stats.deadTupleFraction).toBe(0);
+        });
+    });
+});
+//# sourceMappingURL=stats.test.js.map

package/dist/stats.test.js.map

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

package/dist/store.d.ts

@@ -0,0 +1,27 @@
+import type { VectorDocument, VectorSearchResult, VectorStore, IndexStats, QueryPerfReport, Logger } from "@vivantel/virage-core";
+export interface LanceDBVectorStoreOptions {
+    uri: string;
+    apiKey?: string;
+    tableName?: string;
+    dimensions?: number;
+}
+export declare class LanceDBVectorStore implements VectorStore {
+    readonly name = "lancedb";
+    private readonly uri;
+    private readonly apiKey;
+    private readonly tableName;
+    private readonly dimensions;
+    private db;
+    private table;
+    private logger;
+    constructor(options: LanceDBVectorStoreOptions);
+    setLogger(logger: Logger): void;
+    initialize(): Promise<void>;
+    upsert(documents: VectorDocument[]): Promise<void>;
+    deleteBySourceFile(sourceFiles: string[]): Promise<void>;
+    getCurrentState(): Promise<Map<string, string>>;
+    getIndexStats(): Promise<IndexStats>;
+    getQueryPerfReport(timeframeHours: number): Promise<QueryPerfReport>;
+    search(queryEmbedding: number[], topK: number): Promise<VectorSearchResult[]>;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,eAAe,EACf,MAAM,EACP,MAAM,uBAAuB,CAAC;AAK/B,MAAM,WAAW,yBAAyB;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAKD,qBAAa,kBAAmB,YAAW,WAAW;IACpD,QAAQ,CAAC,IAAI,aAAa;IAE1B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,OAAO,CAAC,EAAE,CAAM;IAEhB,OAAO,CAAC,KAAK,CAAM;IACnB,OAAO,CAAC,MAAM,CAAuB;gBAEzB,OAAO,EAAE,yBAAyB;IAU9C,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIzB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA8B3B,MAAM,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBlD,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAUxD,eAAe,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAoB/C,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC;IAIpC,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAIpE,MAAM,CACV,cAAc,EAAE,MAAM,EAAE,EACxB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,kBAAkB,EAAE,CAAC;CAiCjC"}

package/dist/store.js

@@ -0,0 +1,131 @@
+import { Field, FixedSizeList, Float32, Schema, Utf8 } from "apache-arrow";
+import { getIndexStats } from "./stats.js";
+import { getQueryPerfReport } from "./query-perf.js";
+const DEFAULT_TABLE = "documents";
+const DEFAULT_DIMENSIONS = 1536;
+export class LanceDBVectorStore {
+    name = "lancedb";
+    uri;
+    apiKey;
+    tableName;
+    dimensions;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    db;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    table;
+    logger = null;
+    constructor(options) {
+        if (!options.uri) {
+            throw new Error("LanceDBVectorStore: uri is required");
+        }
+        this.uri = options.uri;
+        this.apiKey = options.apiKey;
+        this.tableName = options.tableName ?? DEFAULT_TABLE;
+        this.dimensions = options.dimensions ?? DEFAULT_DIMENSIONS;
+    }
+    setLogger(logger) {
+        this.logger = logger.withTag("lancedb");
+    }
+    async initialize() {
+        this.logger?.info(`Connecting to lancedb at ${this.uri}, table: ${this.tableName}`);
+        // Dynamic import to avoid native-module issues at load time
+        const lancedb = await import("@lancedb/lancedb");
+        this.db = this.apiKey
+            ? await lancedb.connect(this.uri, { apiKey: this.apiKey })
+            : await lancedb.connect(this.uri);
+        const schema = new Schema([
+            new Field("id", new Utf8()),
+            new Field("content", new Utf8()),
+            new Field("embedding", new FixedSizeList(this.dimensions, new Field("item", new Float32()))),
+            new Field("metadata_json", new Utf8()),
+            new Field("source_file", new Utf8()),
+            new Field("commit_hash", new Utf8()),
+            new Field("content_hash", new Utf8()),
+        ]);
+        this.table = await this.db.createEmptyTable(this.tableName, schema, {
+            existOk: true,
+        });
+        this.logger?.debug(`Table "${this.tableName}" ready (${this.dimensions}d)`);
+    }
+    async upsert(documents) {
+        this.logger?.verbose(`Upserting ${documents.length} docs into "${this.tableName}"`);
+        const rows = documents.map((doc) => ({
+            id: doc.id ?? crypto.randomUUID(),
+            content: doc.content,
+            embedding: doc.embedding,
+            metadata_json: JSON.stringify(doc.metadata),
+            source_file: doc.sourceFile,
+            commit_hash: doc.commitHash,
+            content_hash: doc.contentHash,
+        }));
+        this.logger?.trace(`  Row IDs: ${rows.map((r) => r.id.slice(0, 8)).join(", ")}`);
+        await this.table
+            .mergeInsert("id")
+            .whenMatchedUpdateAll()
+            .whenNotMatchedInsertAll()
+            .execute(rows);
+    }
+    async deleteBySourceFile(sourceFiles) {
+        if (sourceFiles.length === 0)
+            return;
+        this.logger?.verbose(`Deleting docs for ${sourceFiles.length} source file(s)`);
+        const escaped = sourceFiles.map((f) => f.replace(/'/g, "''"));
+        const list = escaped.map((f) => `'${f}'`).join(", ");
+        await this.table.delete(`source_file IN (${list})`);
+    }
+    async getCurrentState() {
+        const rows = await this.table
+            .query()
+            .select(["source_file", "commit_hash"])
+            .toArray();
+        const state = new Map();
+        for (const row of rows) {
+            const sourceFile = typeof row.source_file === "string" ? row.source_file : null;
+            const commitHash = typeof row.commit_hash === "string" ? row.commit_hash : null;
+            if (sourceFile && commitHash) {
+                state.set(sourceFile, commitHash);
+            }
+        }
+        this.logger?.verbose(`getCurrentState: ${state.size} source version(s)`);
+        return state;
+    }
+    async getIndexStats() {
+        return getIndexStats(this.table);
+    }
+    async getQueryPerfReport(timeframeHours) {
+        return getQueryPerfReport(this.table, this.dimensions, timeframeHours);
+    }
+    async search(queryEmbedding, topK) {
+        this.logger?.debug(`Search: topK=${topK}`);
+        const rows = await this.table
+            .vectorSearch(queryEmbedding)
+            .column("embedding")
+            .distanceType("cosine")
+            .limit(topK)
+            .toArray();
+        return rows.map((row) => {
+            const distance = typeof row._distance === "number" ? row._distance : 1;
+            return {
+                id: typeof row.id === "string" ? row.id : "",
+                content: typeof row.content === "string" ? row.content : "",
+                metadata: (() => {
+                    try {
+                        const parsed = typeof row.metadata_json === "string"
+                            ? JSON.parse(row.metadata_json)
+                            : {};
+                        return parsed &&
+                            typeof parsed === "object" &&
+                            !Array.isArray(parsed)
+                            ? parsed
+                            : {};
+                    }
+                    catch {
+                        return {};
+                    }
+                })(),
+                similarity: 1 - distance,
+            };
+        });
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

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

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@vivantel/virage-store-lancedb",
+  "version": "0.2.0",
+  "description": "LanceDB vector store for @vivantel/rag-core (embedded, file-based)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "rag-plugin": {
+    "type": "vectorStore",
+    "label": "LanceDB (embedded, file-based)",
+    "key": "lancedb",
+    "envVars": [],
+    "defaultConfig": {
+      "uri": "./lancedb"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "fix": "npm run lint:fix && npm run format"
+  },
+  "keywords": [
+    "rag",
+    "vector-store",
+    "lancedb",
+    "vector-database",
+    "semantic-search",
+    "embedded"
+  ],
+  "author": "Vivantel",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vivantel/virage",
+    "directory": "packages/virage-store-lancedb"
+  },
+  "dependencies": {
+    "@lancedb/lancedb": "^0.18.0",
+    "apache-arrow": "^18.0.0"
+  },
+  "peerDependencies": {
+    "@vivantel/virage-core": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@vivantel/virage-core": "0.2.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}