@vivantel/virage-store-qdrant 0.2.0

package/README.md

@@ -0,0 +1,96 @@
+# @vivantel/virage-store-qdrant
+
+Qdrant vector store for [`@vivantel/virage-core`](../rag-core/README.md). Works with both local Qdrant instances and Qdrant Cloud (SaaS).
+
+## Installation
+
+```bash
+npm install @vivantel/virage-store-qdrant @vivantel/virage-core
+```
+
+## Quick start (JSON config)
+
+```json
+{
+  "vectorStore": {
+    "package": "@vivantel/virage-store-qdrant",
+    "config": {
+      "url": "${QDRANT_URL}",
+      "apiKey": "${QDRANT_API_KEY}"
+    }
+  }
+}
+```
+
+For a local instance (no API key required):
+
+```json
+{
+  "vectorStore": {
+    "package": "@vivantel/virage-store-qdrant",
+    "config": {
+      "url": "http://localhost:6333"
+    }
+  }
+}
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | `string` | **required** | Qdrant instance URL |
+| `apiKey` | `string` | `undefined` | API key for Qdrant Cloud |
+| `collection` | `string` | `"documents"` | Collection name |
+| `dimensions` | `number` | `1536` | Vector size — must match your embedder |
+
+## TypeScript usage
+
+```typescript
+import { QdrantVectorStore } from "@vivantel/virage-store-qdrant";
+
+const store = new QdrantVectorStore({
+  url: process.env.QDRANT_URL!,
+  apiKey: process.env.QDRANT_API_KEY,
+  collection: "my-docs",
+  dimensions: 1536,
+});
+```
+
+## Observability (ROADMAP v2)
+
+### Index stats (`virage store stats`)
+
+```typescript
+const stats = await store.getIndexStats();
+// {
+//   totalVectors: 12500,
+//   indexType: "hnsw",
+//   annRecallAt10: 0.96,
+//   indexAgeHours: 0,
+//   deadTupleFraction: 0,
+//   suggestions: ["Collection looks healthy"]
+// }
+```
+
+### Query performance (`virage store perf --timeframe 24`)
+
+```typescript
+const perf = await store.getQueryPerfReport(24);
+// {
+//   timeframeHours: 24,
+//   p50LatencyMs: 3.2,
+//   p95LatencyMs: 8.7,
+//   p99LatencyMs: 14.1,
+//   slowQueryCount: 0,
+//   suggestedIndexes: ["Query performance looks healthy."]
+// }
+```
+
+Query performance metrics require Qdrant's `/metrics` endpoint to be reachable. Metrics are returned as `-1` if telemetry is not available.
+
+## Running Qdrant locally
+
+```bash
+docker run -p 6333:6333 qdrant/qdrant
+```

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { QdrantVectorStore, type QdrantVectorStoreOptions } 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,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAE9E,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,CAkBb"}

package/dist/index.js

@@ -0,0 +1,19 @@
+export { QdrantVectorStore } from "./store.js";
+import { QdrantVectorStore } from "./store.js";
+/** Factory used by the JSON config loader. */
+export function createVectorStore(config) {
+    const url = typeof config.url === "string" ? config.url : undefined;
+    const path = typeof config.path === "string" ? config.path : undefined;
+    if (!url && !path) {
+        throw new Error("@vivantel/virage-store-qdrant: config.url or config.path is required");
+    }
+    return new QdrantVectorStore({
+        url,
+        path,
+        port: typeof config.port === "number" ? config.port : undefined,
+        apiKey: typeof config.apiKey === "string" ? config.apiKey : undefined,
+        collection: typeof config.collection === "string" ? config.collection : 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,iBAAiB,EAAiC,MAAM,YAAY,CAAC;AAG9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,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,MAAM,IAAI,GAAG,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACvE,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,sEAAsE,CACvE,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,iBAAiB,CAAC;QAC3B,GAAG;QACH,IAAI;QACJ,IAAI,EAAE,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;QAC/D,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;QACrE,UAAU,EACR,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;QACvE,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(qdrantUrl: string, _collection: string, 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;AAc7D,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,eAAe,CAAC,CA4C1B"}

package/dist/query-perf.js

@@ -0,0 +1,81 @@
+const UNAVAILABLE = {
+    timeframeHours: 0,
+    p50LatencyMs: -1,
+    p95LatencyMs: -1,
+    p99LatencyMs: -1,
+    slowQueryCount: -1,
+    suggestedIndexes: [
+        "Qdrant telemetry not available. Ensure the /metrics endpoint is reachable " +
+            "and telemetry is enabled in your Qdrant configuration.",
+    ],
+};
+export async function getQueryPerfReport(qdrantUrl, _collection, timeframeHours) {
+    const metricsUrl = `${qdrantUrl.replace(/\/$/, "")}/metrics`;
+    let text;
+    try {
+        const res = await fetch(metricsUrl, { signal: AbortSignal.timeout(5000) });
+        if (!res.ok)
+            return { ...UNAVAILABLE, timeframeHours };
+        text = await res.text();
+    }
+    catch {
+        return { ...UNAVAILABLE, timeframeHours };
+    }
+    const latencies = parsePrometheusHistogram(text);
+    if (latencies.length === 0) {
+        return { ...UNAVAILABLE, timeframeHours };
+    }
+    latencies.sort((a, b) => a - b);
+    const percentile = (p) => latencies[Math.floor((p / 100) * latencies.length)] ?? 0;
+    const p50 = percentile(50) * 1000;
+    const p95 = percentile(95) * 1000;
+    const p99 = percentile(99) * 1000;
+    const slowQueryCount = latencies.filter((ms) => ms * 1000 > 100).length;
+    const suggestedIndexes = [];
+    if (slowQueryCount > 0) {
+        suggestedIndexes.push(`${slowQueryCount} slow queries (>100ms) detected. Consider tuning hnsw_config ef or increasing hardware resources.`);
+    }
+    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,
+    };
+}
+/**
+ * Reconstruct a latency sample list from Prometheus histogram sum/count lines.
+ * Returns latency values in seconds.
+ */
+function parsePrometheusHistogram(text) {
+    const samples = [];
+    // Match _sum and _count lines for REST API duration metrics
+    const sumPattern = /^rest_api_response_duration_seconds_sum\{[^}]*\}\s+([\d.e+]+)/gm;
+    const countPattern = /^rest_api_response_duration_seconds_count\{[^}]*\}\s+([\d.e+]+)/gm;
+    const sums = [];
+    const counts = [];
+    for (const m of text.matchAll(sumPattern)) {
+        sums.push(parseFloat(m[1]));
+    }
+    for (const m of text.matchAll(countPattern)) {
+        counts.push(parseFloat(m[1]));
+    }
+    for (let i = 0; i < Math.min(sums.length, counts.length); i++) {
+        const count = counts[i];
+        const sum = sums[i];
+        if (count > 0 && sum >= 0) {
+            const mean = sum / count;
+            // Approximate distribution: repeat the mean `min(count, 10)` times
+            const weight = Math.min(Math.round(count), 10);
+            for (let j = 0; j < weight; j++) {
+                samples.push(mean);
+            }
+        }
+    }
+    return samples;
+}
+//# 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,WAAW,GAAoB;IACnC,cAAc,EAAE,CAAC;IACjB,YAAY,EAAE,CAAC,CAAC;IAChB,YAAY,EAAE,CAAC,CAAC;IAChB,YAAY,EAAE,CAAC,CAAC;IAChB,cAAc,EAAE,CAAC,CAAC;IAClB,gBAAgB,EAAE;QAChB,4EAA4E;YAC1E,wDAAwD;KAC3D;CACF,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,SAAiB,EACjB,WAAmB,EACnB,cAAsB;IAEtB,MAAM,UAAU,GAAG,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC;IAE7D,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,UAAU,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC3E,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO,EAAE,GAAG,WAAW,EAAE,cAAc,EAAE,CAAC;QACvD,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,GAAG,WAAW,EAAE,cAAc,EAAE,CAAC;IAC5C,CAAC;IAED,MAAM,SAAS,GAAG,wBAAwB,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,GAAG,WAAW,EAAE,cAAc,EAAE,CAAC;IAC5C,CAAC;IAED,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAEhC,MAAM,UAAU,GAAG,CAAC,CAAS,EAAU,EAAE,CACvC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC;IAE3D,MAAM,GAAG,GAAG,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IAClC,MAAM,GAAG,GAAG,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IAClC,MAAM,GAAG,GAAG,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IAClC,MAAM,cAAc,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,IAAI,GAAG,GAAG,CAAC,CAAC,MAAM,CAAC;IAExE,MAAM,gBAAgB,GAAa,EAAE,CAAC;IACtC,IAAI,cAAc,GAAG,CAAC,EAAE,CAAC;QACvB,gBAAgB,CAAC,IAAI,CACnB,GAAG,cAAc,mGAAmG,CACrH,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;AAED;;;GAGG;AACH,SAAS,wBAAwB,CAAC,IAAY;IAC5C,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,4DAA4D;IAC5D,MAAM,UAAU,GACd,iEAAiE,CAAC;IACpE,MAAM,YAAY,GAChB,mEAAmE,CAAC;IAEtE,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC1C,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QAC5C,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9D,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACxB,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACpB,IAAI,KAAK,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,GAAG,GAAG,GAAG,KAAK,CAAC;YACzB,mEAAmE;YACnE,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;YAC/C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAChC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,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,113 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { getQueryPerfReport } from "./query-perf.js";
+// Prometheus histogram text helpers
+function prometheusMetrics(entries) {
+    return entries
+        .map(({ sum, count }, i) => `rest_api_response_duration_seconds_sum{method="POST",endpoint="/search/${i}",status="200"} ${sum}\n` +
+        `rest_api_response_duration_seconds_count{method="POST",endpoint="/search/${i}",status="200"} ${count}`)
+        .join("\n");
+}
+function mockFetch(status, body) {
+    return vi.fn().mockResolvedValue({
+        ok: status >= 200 && status < 300,
+        text: vi.fn().mockResolvedValue(body),
+    });
+}
+afterEach(() => {
+    vi.unstubAllGlobals();
+});
+const UNAVAILABLE_SENTINEL = -1;
+describe("getQueryPerfReport (Qdrant)", () => {
+    describe("metrics endpoint unavailable", () => {
+        it("returns all -1 latencies when fetch throws", async () => {
+            vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("ECONNREFUSED")));
+            const report = await getQueryPerfReport("http://localhost:6333", "docs", 24);
+            expect(report.p50LatencyMs).toBe(UNAVAILABLE_SENTINEL);
+            expect(report.p95LatencyMs).toBe(UNAVAILABLE_SENTINEL);
+            expect(report.p99LatencyMs).toBe(UNAVAILABLE_SENTINEL);
+            expect(report.slowQueryCount).toBe(UNAVAILABLE_SENTINEL);
+        });
+        it("returns all -1 latencies when /metrics returns non-OK status", async () => {
+            vi.stubGlobal("fetch", mockFetch(503, "Service Unavailable"));
+            const report = await getQueryPerfReport("http://localhost:6333", "docs", 24);
+            expect(report.p50LatencyMs).toBe(UNAVAILABLE_SENTINEL);
+        });
+        it("returns all -1 latencies when /metrics body has no matching histogram lines", async () => {
+            vi.stubGlobal("fetch", mockFetch(200, "# HELP other_metric something\nother_metric 1.0\n"));
+            const report = await getQueryPerfReport("http://localhost:6333", "docs", 24);
+            expect(report.p50LatencyMs).toBe(UNAVAILABLE_SENTINEL);
+        });
+        it("includes a telemetry-not-available hint in suggestedIndexes", async () => {
+            vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("timeout")));
+            const report = await getQueryPerfReport("http://localhost:6333", "docs", 24);
+            expect(report.suggestedIndexes[0]).toMatch(/telemetry|metrics/i);
+        });
+        it("preserves timeframeHours even when unavailable", async () => {
+            vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("timeout")));
+            const report = await getQueryPerfReport("http://localhost:6333", "docs", 48);
+            expect(report.timeframeHours).toBe(48);
+        });
+    });
+    describe("metrics endpoint reachable", () => {
+        it("computes valid percentiles from Prometheus histogram (p50 ≤ p95 ≤ p99)", async () => {
+            // 5 entries, mean latencies 10ms–50ms (0.01–0.05 s)
+            const body = prometheusMetrics([
+                { sum: 0.05, count: 5 }, // mean 0.01 s = 10 ms
+                { sum: 0.06, count: 3 }, // mean 0.02 s = 20 ms
+                { sum: 0.09, count: 3 }, // mean 0.03 s = 30 ms
+                { sum: 0.16, count: 4 }, // mean 0.04 s = 40 ms
+                { sum: 0.25, count: 5 }, // mean 0.05 s = 50 ms
+            ]);
+            vi.stubGlobal("fetch", mockFetch(200, body));
+            const report = await getQueryPerfReport("http://localhost:6333", "docs", 24);
+            expect(report.p50LatencyMs).toBeGreaterThanOrEqual(0);
+            expect(report.p95LatencyMs).toBeGreaterThanOrEqual(report.p50LatencyMs);
+            expect(report.p99LatencyMs).toBeGreaterThanOrEqual(report.p95LatencyMs);
+        });
+        it("timeframeHours is passed through to the report", async () => {
+            const body = prometheusMetrics([{ sum: 0.05, count: 5 }]);
+            vi.stubGlobal("fetch", mockFetch(200, body));
+            const report = await getQueryPerfReport("http://localhost:6333", "docs", 72);
+            expect(report.timeframeHours).toBe(72);
+        });
+        it("counts slow queries when mean latency > 100 ms", async () => {
+            // 2 fast entries (10ms, 50ms) + 2 slow (150ms, 200ms)
+            const body = prometheusMetrics([
+                { sum: 0.05, count: 5 }, // 10 ms
+                { sum: 0.15, count: 3 }, // 50 ms
+                { sum: 0.45, count: 3 }, // 150 ms — slow
+                { sum: 0.4, count: 2 }, // 200 ms — slow
+            ]);
+            vi.stubGlobal("fetch", mockFetch(200, body));
+            const report = await getQueryPerfReport("http://localhost:6333", "docs", 24);
+            expect(report.slowQueryCount).toBeGreaterThan(0);
+            expect(report.suggestedIndexes[0]).toMatch(/slow|hnsw/i);
+        });
+        it("returns healthy suggestion when no slow queries", async () => {
+            const body = prometheusMetrics([
+                { sum: 0.02, count: 4 }, // 5 ms
+                { sum: 0.06, count: 3 }, // 20 ms
+            ]);
+            vi.stubGlobal("fetch", mockFetch(200, body));
+            const report = await getQueryPerfReport("http://localhost:6333", "docs", 24);
+            expect(report.slowQueryCount).toBe(0);
+            expect(report.suggestedIndexes[0]).toMatch(/healthy/i);
+        });
+        it("normalises the metrics URL by stripping a trailing slash", async () => {
+            const fetchSpy = mockFetch(200, prometheusMetrics([{ sum: 0.01, count: 2 }]));
+            vi.stubGlobal("fetch", fetchSpy);
+            await getQueryPerfReport("http://localhost:6333/", "docs", 24);
+            const calledUrl = fetchSpy.mock.calls[0][0];
+            expect(calledUrl).toBe("http://localhost:6333/metrics");
+        });
+        it("ignores histogram entries where count is 0", async () => {
+            const body = 'rest_api_response_duration_seconds_sum{method="POST"} 0\n' +
+                'rest_api_response_duration_seconds_count{method="POST"} 0\n';
+            vi.stubGlobal("fetch", mockFetch(200, body));
+            const report = await getQueryPerfReport("http://localhost:6333", "docs", 24);
+            // zero-count entry produces no samples → falls back to UNAVAILABLE
+            expect(report.p50LatencyMs).toBe(UNAVAILABLE_SENTINEL);
+        });
+    });
+});
+//# 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":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD,oCAAoC;AACpC,SAAS,iBAAiB,CAAC,OAAyC;IAClE,OAAO,OAAO;SACX,GAAG,CACF,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE,CACpB,0EAA0E,CAAC,mBAAmB,GAAG,IAAI;QACrG,4EAA4E,CAAC,mBAAmB,KAAK,EAAE,CAC1G;SACA,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,SAAS,SAAS,CAAC,MAAc,EAAE,IAAY;IAC7C,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC;QAC/B,EAAE,EAAE,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;QACjC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC;KACtC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,CAAC,GAAG,EAAE;IACb,EAAE,CAAC,gBAAgB,EAAE,CAAC;AACxB,CAAC,CAAC,CAAC;AAEH,MAAM,oBAAoB,GAAG,CAAC,CAAC,CAAC;AAEhC,QAAQ,CAAC,6BAA6B,EAAE,GAAG,EAAE;IAC3C,QAAQ,CAAC,8BAA8B,EAAE,GAAG,EAAE;QAC5C,EAAE,CAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;YAC1D,EAAE,CAAC,UAAU,CACX,OAAO,EACP,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC,CACrD,CAAC;YAEF,MAAM,MAAM,GAAG,MAAM,kBAAkB,CACrC,uBAAuB,EACvB,MAAM,EACN,EAAE,CACH,CAAC;YAEF,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;YACvD,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;YACvD,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;YACvD,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QAC3D,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,8DAA8D,EAAE,KAAK,IAAI,EAAE;YAC5E,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC,CAAC;YAE9D,MAAM,MAAM,GAAG,MAAM,kBAAkB,CACrC,uBAAuB,EACvB,MAAM,EACN,EAAE,CACH,CAAC;YAEF,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACzD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,6EAA6E,EAAE,KAAK,IAAI,EAAE;YAC3F,EAAE,CAAC,UAAU,CACX,OAAO,EACP,SAAS,CAAC,GAAG,EAAE,mDAAmD,CAAC,CACpE,CAAC;YAEF,MAAM,MAAM,GAAG,MAAM,kBAAkB,CACrC,uBAAuB,EACvB,MAAM,EACN,EAAE,CACH,CAAC;YAEF,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACzD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,6DAA6D,EAAE,KAAK,IAAI,EAAE;YAC3E,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YAExE,MAAM,MAAM,GAAG,MAAM,kBAAkB,CACrC,uBAAuB,EACvB,MAAM,EACN,EAAE,CACH,CAAC;YAEF,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;QACnE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,gDAAgD,EAAE,KAAK,IAAI,EAAE;YAC9D,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;YAExE,MAAM,MAAM,GAAG,MAAM,kBAAkB,CACrC,uBAAuB,EACvB,MAAM,EACN,EAAE,CACH,CAAC;YAEF,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,4BAA4B,EAAE,GAAG,EAAE;QAC1C,EAAE,CAAC,wEAAwE,EAAE,KAAK,IAAI,EAAE;YACtF,oDAAoD;YACpD,MAAM,IAAI,GAAG,iBAAiB,CAAC;gBAC7B,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,sBAAsB;gBAC/C,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,sBAAsB;gBAC/C,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,sBAAsB;gBAC/C,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,sBAAsB;gBAC/C,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,sBAAsB;aAChD,CAAC,CAAC;YACH,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;YAE7C,MAAM,MAAM,GAAG,MAAM,kBAAkB,CACrC,uBAAuB,EACvB,MAAM,EACN,EAAE,CACH,CAAC;YAEF,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;YACtD,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,sBAAsB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;YACxE,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,sBAAsB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;QAC1E,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,gDAAgD,EAAE,KAAK,IAAI,EAAE;YAC9D,MAAM,IAAI,GAAG,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YAC1D,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;YAE7C,MAAM,MAAM,GAAG,MAAM,kBAAkB,CACrC,uBAAuB,EACvB,MAAM,EACN,EAAE,CACH,CAAC;YAEF,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,gDAAgD,EAAE,KAAK,IAAI,EAAE;YAC9D,sDAAsD;YACtD,MAAM,IAAI,GAAG,iBAAiB,CAAC;gBAC7B,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,QAAQ;gBACjC,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,QAAQ;gBACjC,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,gBAAgB;gBACzC,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,gBAAgB;aACzC,CAAC,CAAC;YACH,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;YAE7C,MAAM,MAAM,GAAG,MAAM,kBAAkB,CACrC,uBAAuB,EACvB,MAAM,EACN,EAAE,CACH,CAAC;YAEF,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;YACjD,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QAC3D,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,iDAAiD,EAAE,KAAK,IAAI,EAAE;YAC/D,MAAM,IAAI,GAAG,iBAAiB,CAAC;gBAC7B,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,OAAO;gBAChC,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,QAAQ;aAClC,CAAC,CAAC;YACH,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;YAE7C,MAAM,MAAM,GAAG,MAAM,kBAAkB,CACrC,uBAAuB,EACvB,MAAM,EACN,EAAE,CACH,CAAC;YAEF,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACtC,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACzD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,0DAA0D,EAAE,KAAK,IAAI,EAAE;YACxE,MAAM,QAAQ,GAAG,SAAS,CACxB,GAAG,EACH,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC,CAC7C,CAAC;YACF,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;YAEjC,MAAM,kBAAkB,CAAC,wBAAwB,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;YAE/D,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAW,CAAC;YACtD,MAAM,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC;QAC1D,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;YAC1D,MAAM,IAAI,GACR,2DAA2D;gBAC3D,6DAA6D,CAAC;YAChE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;YAE7C,MAAM,MAAM,GAAG,MAAM,kBAAkB,CACrC,uBAAuB,EACvB,MAAM,EACN,EAAE,CACH,CAAC;YAEF,mEAAmE;YACnE,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACzD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/stats.d.ts

@@ -0,0 +1,4 @@
+import type { IndexStats } from "@vivantel/virage-core";
+import type { QdrantClient } from "@qdrant/js-client-rest";
+export declare function getIndexStats(client: QdrantClient, collection: string): 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;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAI3D,wBAAsB,aAAa,CACjC,MAAM,EAAE,YAAY,EACpB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,UAAU,CAAC,CA8CrB"}

package/dist/stats.js

@@ -0,0 +1,75 @@
+export async function getIndexStats(client, collection) {
+    const info = await client.getCollection(collection);
+    const suggestions = [];
+    const totalVectors = info.points_count ?? 0;
+    const segmentsCount = info.segments_count ?? 0;
+    // Qdrant always uses HNSW internally
+    const indexType = "hnsw";
+    if (info.status === "red") {
+        suggestions.push(`Collection status is RED — check Qdrant logs for errors in "${collection}"`);
+    }
+    else if (info.status === "yellow") {
+        suggestions.push(`Collection status is YELLOW — indexing may be in progress for "${collection}"`);
+    }
+    if (segmentsCount > 20) {
+        suggestions.push(`High segment count (${segmentsCount}) — consider running collection optimization to merge segments`);
+    }
+    const annRecallAt10 = await computeAnnRecall(client, collection, info, totalVectors);
+    if (suggestions.length === 0) {
+        suggestions.push("Collection looks healthy");
+    }
+    return {
+        totalVectors,
+        indexType,
+        annRecallAt10,
+        // Not applicable for Qdrant (no vacuum/dead-tuple concept)
+        indexAgeHours: 0,
+        deadTupleFraction: 0,
+        suggestions,
+    };
+}
+function extractVectorSize(info) {
+    const vectors = info.config?.params?.vectors;
+    if (!vectors)
+        return undefined;
+    // Single-vector mode: { size: number, distance: ... }
+    if ("size" in vectors &&
+        typeof vectors.size === "number") {
+        return vectors.size;
+    }
+    // Named-vector mode: { default: { size: number, ... }, ... }
+    const firstNamed = Object.values(vectors)[0];
+    return typeof firstNamed?.size === "number" ? firstNamed.size : undefined;
+}
+async function computeAnnRecall(client, collection, info, totalVectors) {
+    if (totalVectors < 10)
+        return -1;
+    const size = extractVectorSize(info);
+    if (!size)
+        return -1;
+    try {
+        const zeroVector = Array(size).fill(0);
+        const [exactResults, annResults] = await Promise.all([
+            client.search(collection, {
+                vector: zeroVector,
+                limit: 10,
+                params: { exact: true },
+                with_payload: false,
+            }),
+            client.search(collection, {
+                vector: zeroVector,
+                limit: 10,
+                params: { exact: false },
+                with_payload: false,
+            }),
+        ]);
+        const exactIds = new Set(exactResults.map((r) => String(r.id)));
+        const annIds = annResults.map((r) => String(r.id));
+        const hits = annIds.filter((id) => exactIds.has(id)).length;
+        return hits / Math.max(exactIds.size, 1);
+    }
+    catch {
+        return -1;
+    }
+}
+//# sourceMappingURL=stats.js.map

package/dist/stats.js.map

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

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,151 @@
+import { describe, it, expect, vi } from "vitest";
+import { getIndexStats } from "./stats.js";
+function makeCollectionInfo(overrides = {}) {
+    return {
+        points_count: 100,
+        segments_count: 3,
+        status: "green",
+        config: {
+            params: {
+                vectors: {
+                    size: 4,
+                    distance: "Cosine",
+                },
+                shard_number: 1,
+                replication_factor: 1,
+                write_consistency_factor: 1,
+                on_disk_payload: false,
+            },
+            optimizer_config: {},
+            wal_config: {},
+            quantization_config: null,
+        },
+        ...overrides,
+    };
+}
+function makeClient(info, searchResults = [[], []]) {
+    return {
+        getCollection: vi.fn().mockResolvedValue(info),
+        search: vi
+            .fn()
+            .mockResolvedValueOnce(searchResults[0] ?? [])
+            .mockResolvedValueOnce(searchResults[1] ?? []),
+    };
+}
+describe("getIndexStats (Qdrant)", () => {
+    describe("basic fields", () => {
+        it("always returns hnsw indexType", async () => {
+            const client = makeClient(makeCollectionInfo());
+            const stats = await getIndexStats(client, "documents");
+            expect(stats.indexType).toBe("hnsw");
+        });
+        it("reflects points_count as totalVectors", async () => {
+            const client = makeClient(makeCollectionInfo({ points_count: 4200 }));
+            const stats = await getIndexStats(client, "documents");
+            expect(stats.totalVectors).toBe(4200);
+        });
+        it("totalVectors defaults to 0 when points_count is undefined", async () => {
+            const client = makeClient(makeCollectionInfo({ points_count: undefined }));
+            const stats = await getIndexStats(client, "documents");
+            expect(stats.totalVectors).toBe(0);
+        });
+        it("always returns indexAgeHours = 0 and deadTupleFraction = 0", async () => {
+            const client = makeClient(makeCollectionInfo());
+            const stats = await getIndexStats(client, "documents");
+            expect(stats.indexAgeHours).toBe(0);
+            expect(stats.deadTupleFraction).toBe(0);
+        });
+    });
+    describe("status warnings", () => {
+        it("includes RED alert in suggestions when status is red", async () => {
+            const client = makeClient(makeCollectionInfo({ status: "red" }));
+            const stats = await getIndexStats(client, "documents");
+            expect(stats.suggestions.some((s) => /RED/i.test(s))).toBe(true);
+        });
+        it("includes YELLOW warning in suggestions when status is yellow", async () => {
+            const client = makeClient(makeCollectionInfo({ status: "yellow" }));
+            const stats = await getIndexStats(client, "documents");
+            expect(stats.suggestions.some((s) => /YELLOW/i.test(s))).toBe(true);
+        });
+        it("returns healthy suggestion when status is green and segments < 20", async () => {
+            const client = makeClient(makeCollectionInfo({ status: "green", segments_count: 5 }));
+            const stats = await getIndexStats(client, "documents");
+            expect(stats.suggestions[0]).toMatch(/healthy/i);
+        });
+    });
+    describe("segment count", () => {
+        it("suggests optimization when segments_count > 20", async () => {
+            const client = makeClient(makeCollectionInfo({ segments_count: 25 }));
+            const stats = await getIndexStats(client, "documents");
+            expect(stats.suggestions.some((s) => /segment/i.test(s))).toBe(true);
+        });
+        it("does not warn about segments when count is exactly 20", async () => {
+            const client = makeClient(makeCollectionInfo({ segments_count: 20 }));
+            const stats = await getIndexStats(client, "documents");
+            expect(stats.suggestions.every((s) => !/segment/i.test(s))).toBe(true);
+        });
+    });
+    describe("ANN recall", () => {
+        it("is -1 when totalVectors < 10", async () => {
+            const client = makeClient(makeCollectionInfo({ points_count: 5 }));
+            const stats = await getIndexStats(client, "documents");
+            expect(stats.annRecallAt10).toBe(-1);
+        });
+        it("is -1 when vector size cannot be determined (no config)", async () => {
+            const info = makeCollectionInfo({ points_count: 100 });
+            info.config = null;
+            const client = makeClient(info);
+            const stats = await getIndexStats(client, "documents");
+            expect(stats.annRecallAt10).toBe(-1);
+        });
+        it("is 1.0 when exact and ANN results are identical (single-vector mode)", async () => {
+            const ids = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+            const resultSet = ids.map((id) => ({ id, score: 0.9 }));
+            const client = makeClient(makeCollectionInfo({ points_count: 100 }), [
+                resultSet,
+                resultSet,
+            ]);
+            const stats = await getIndexStats(client, "documents");
+            expect(stats.annRecallAt10).toBe(1);
+        });
+        it("computes partial recall correctly", async () => {
+            const exactResults = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10].map((id) => ({
+                id,
+                score: 0.9,
+            }));
+            const annResults = [1, 2, 3, 4, 5, 11, 12, 13, 14, 15].map((id) => ({
+                id,
+                score: 0.85,
+            }));
+            const client = makeClient(makeCollectionInfo({ points_count: 100 }), [
+                exactResults,
+                annResults,
+            ]);
+            const stats = await getIndexStats(client, "documents");
+            expect(stats.annRecallAt10).toBeCloseTo(0.5, 5);
+        });
+        it("supports named-vector mode for vector size extraction", async () => {
+            const info = makeCollectionInfo({ points_count: 100 });
+            // Override vectors to use named-vector mode
+            info.config.params.vectors = {
+                default: { size: 4, distance: "Cosine" },
+            };
+            const ids = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+            const resultSet = ids.map((id) => ({ id, score: 0.9 }));
+            const client = makeClient(info, [resultSet, resultSet]);
+            const stats = await getIndexStats(client, "documents");
+            expect(stats.annRecallAt10).toBe(1);
+        });
+        it("is -1 when search() throws", async () => {
+            const client = {
+                getCollection: vi
+                    .fn()
+                    .mockResolvedValue(makeCollectionInfo({ points_count: 100 })),
+                search: vi.fn().mockRejectedValue(new Error("collection not found")),
+            };
+            const stats = await getIndexStats(client, "documents");
+            expect(stats.annRecallAt10).toBe(-1);
+        });
+    });
+});
+//# 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,42 @@
+import type { VectorStore, VectorDocument, VectorSearchResult, IndexStats, QueryPerfReport, Logger } from "@vivantel/virage-core";
+export interface QdrantVectorStoreOptions {
+    /**
+     * Qdrant instance URL. e.g. "http://localhost:6333" or "https://xyz.qdrant.io".
+     * Required unless `path` is provided.
+     */
+    url?: string;
+    /**
+     * Local storage directory for Qdrant data (file mode).
+     * When provided, connects to `http://localhost:<port>` — you must start Qdrant
+     * pointing at this directory, e.g.:
+     *   docker run -v <path>:/qdrant/storage -p 6333:6333 qdrant/qdrant
+     * Mutually exclusive with `url`.
+     */
+    path?: string;
+    /** Port used when `path` mode is active. Defaults to 6333. */
+    port?: number;
+    /** API key — required for Qdrant Cloud, omit for local instances. */
+    apiKey?: string;
+    /** Collection name. Defaults to "documents". */
+    collection?: string;
+    /** Vector dimensions — must match your embedder. Defaults to 1536. */
+    dimensions?: number;
+}
+export declare class QdrantVectorStore implements VectorStore {
+    readonly name = "qdrant";
+    private readonly client;
+    private readonly collection;
+    private readonly dimensions;
+    private readonly url;
+    private logger;
+    constructor(options: QdrantVectorStoreOptions);
+    setLogger(logger: Logger): void;
+    initialize(): Promise<void>;
+    upsert(documents: VectorDocument[]): Promise<void>;
+    deleteBySourceFile(sourceFiles: string[]): Promise<void>;
+    getCurrentState(): Promise<Map<string, string>>;
+    search(queryEmbedding: number[], topK: number): Promise<VectorSearchResult[]>;
+    getIndexStats(): Promise<IndexStats>;
+    getQueryPerfReport(timeframeHours: number): Promise<QueryPerfReport>;
+}
+//# 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,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,UAAU,EACV,eAAe,EACf,MAAM,EACP,MAAM,uBAAuB,CAAC;AAK/B,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAKD,qBAAa,iBAAkB,YAAW,WAAW;IACnD,QAAQ,CAAC,IAAI,YAAY;IAEzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAuB;gBAEzB,OAAO,EAAE,wBAAwB;IAe7C,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIzB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB3B,MAAM,CAAC,SAAS,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA2BlD,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAaxD,eAAe,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAoC/C,MAAM,CACV,cAAc,EAAE,MAAM,EAAE,EACxB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAwB1B,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC;IAIpC,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;CAG3E"}

package/dist/store.js

@@ -0,0 +1,129 @@
+import { QdrantClient } from "@qdrant/js-client-rest";
+import { getIndexStats } from "./stats.js";
+import { getQueryPerfReport } from "./query-perf.js";
+const UPSERT_BATCH_SIZE = 100;
+const SCROLL_PAGE_SIZE = 250;
+export class QdrantVectorStore {
+    name = "qdrant";
+    client;
+    collection;
+    dimensions;
+    url;
+    logger = null;
+    constructor(options) {
+        if (!options.url && !options.path) {
+            throw new Error("QdrantVectorStore: either url or path is required");
+        }
+        const resolvedUrl = options.url ?? `http://localhost:${options.port ?? 6333}`;
+        this.url = resolvedUrl;
+        this.collection = options.collection ?? "documents";
+        this.dimensions = options.dimensions ?? 1536;
+        this.client = new QdrantClient({
+            url: resolvedUrl,
+            apiKey: options.apiKey,
+        });
+    }
+    setLogger(logger) {
+        this.logger = logger.withTag("qdrant");
+    }
+    async initialize() {
+        this.logger?.info(`Connecting to qdrant at ${this.url}, collection: ${this.collection}`);
+        const { exists } = await this.client.collectionExists(this.collection);
+        if (!exists) {
+            await this.client.createCollection(this.collection, {
+                vectors: { size: this.dimensions, distance: "Cosine" },
+            });
+            this.logger?.debug(`Created collection "${this.collection}" (${this.dimensions}d, cosine)`);
+        }
+        else {
+            this.logger?.debug(`Collection "${this.collection}" already exists`);
+        }
+    }
+    async upsert(documents) {
+        this.logger?.verbose(`Upserting ${documents.length} docs into "${this.collection}"`);
+        for (let i = 0; i < documents.length; i += UPSERT_BATCH_SIZE) {
+            const batch = documents.slice(i, i + UPSERT_BATCH_SIZE);
+            const points = batch.map((doc) => ({
+                id: crypto.randomUUID(),
+                vector: doc.embedding,
+                payload: {
+                    content: doc.content,
+                    metadata: doc.metadata,
+                    source_file: doc.sourceFile,
+                    commit_hash: doc.commitHash,
+                    content_hash: doc.contentHash,
+                },
+            }));
+            await this.client.upsert(this.collection, {
+                wait: true,
+                points,
+            });
+            this.logger?.trace(`  Upserted IDs: ${points.map((p) => p.id.slice(0, 8)).join(", ")}`);
+        }
+    }
+    async deleteBySourceFile(sourceFiles) {
+        if (sourceFiles.length === 0)
+            return;
+        this.logger?.verbose(`Deleting docs for ${sourceFiles.length} source file(s)`);
+        await this.client.delete(this.collection, {
+            wait: true,
+            filter: {
+                must: [{ key: "source_file", match: { any: sourceFiles } }],
+            },
+        });
+    }
+    async getCurrentState() {
+        const state = new Map();
+        let offset;
+        do {
+            const response = await this.client.scroll(this.collection, {
+                with_payload: ["source_file", "commit_hash"],
+                with_vector: false,
+                limit: SCROLL_PAGE_SIZE,
+                offset,
+            });
+            for (const point of response.points) {
+                const payload = point.payload;
+                const sourceFile = typeof payload?.source_file === "string" ? payload.source_file : null;
+                const commitHash = typeof payload?.commit_hash === "string" ? payload.commit_hash : null;
+                if (sourceFile && commitHash) {
+                    state.set(sourceFile, commitHash);
+                }
+            }
+            const raw = response.next_page_offset;
+            // ExtendedPointId (string | number) means more pages; anything else stops iteration
+            offset =
+                typeof raw === "string" || typeof raw === "number" ? raw : undefined;
+        } while (offset !== undefined);
+        this.logger?.verbose(`getCurrentState: ${state.size} source version(s)`);
+        return state;
+    }
+    async search(queryEmbedding, topK) {
+        this.logger?.debug(`Search: topK=${topK}`);
+        const results = await this.client.search(this.collection, {
+            vector: queryEmbedding,
+            limit: topK,
+            with_payload: true,
+        });
+        return results.map((r) => {
+            const payload = r.payload;
+            return {
+                id: String(r.id),
+                content: typeof payload?.content === "string" ? payload.content : "",
+                metadata: payload?.metadata &&
+                    typeof payload.metadata === "object" &&
+                    !Array.isArray(payload.metadata)
+                    ? payload.metadata
+                    : {},
+                similarity: r.score,
+            };
+        });
+    }
+    async getIndexStats() {
+        return getIndexStats(this.client, this.collection);
+    }
+    async getQueryPerfReport(timeframeHours) {
+        return getQueryPerfReport(this.url, this.collection, timeframeHours);
+    }
+}
+//# 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,62 @@
+{
+  "name": "@vivantel/virage-store-qdrant",
+  "version": "0.2.0",
+  "description": "Qdrant vector store for @vivantel/rag-core (local and cloud)",
+  "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"
+  },
+  "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",
+    "qdrant",
+    "vector-database",
+    "semantic-search"
+  ],
+  "author": "Vivantel",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vivantel/virage",
+    "directory": "packages/virage-store-qdrant"
+  },
+  "dependencies": {
+    "@qdrant/js-client-rest": "^1.18.0"
+  },
+  "peerDependencies": {
+    "@vivantel/virage-core": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@vitest/coverage-v8": "^4.1.8",
+    "@vivantel/virage-core": "0.2.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}