@vivantel/virage-store-postgres 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { PostgresVectorStore, type PostgresVectorStoreOptions, type IndexType, type IVFFlatParams, type HNSWParams, } 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,EACL,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AAEpB,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,CAcb"}

package/dist/index.js

@@ -0,0 +1,16 @@
+export { PostgresVectorStore, } from "./store.js";
+import { PostgresVectorStore } from "./store.js";
+/** Factory used by the JSON config loader. */
+export function createVectorStore(config) {
+    const connectionString = config.connectionString;
+    if (typeof connectionString !== "string" || !connectionString) {
+        throw new Error("@vivantel/virage-store-postgres: config.connectionString is required");
+    }
+    return new PostgresVectorStore({
+        connectionString,
+        table: typeof config.table === "string" ? config.table : undefined,
+        dimensions: typeof config.dimensions === "number" ? config.dimensions : undefined,
+        ssl: typeof config.ssl === "boolean" ? config.ssl : 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,EACL,mBAAmB,GAKpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD,8CAA8C;AAC9C,MAAM,UAAU,iBAAiB,CAC/B,MAA+B;IAE/B,MAAM,gBAAgB,GAAG,MAAM,CAAC,gBAAgB,CAAC;IACjD,IAAI,OAAO,gBAAgB,KAAK,QAAQ,IAAI,CAAC,gBAAgB,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CACb,sEAAsE,CACvE,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,mBAAmB,CAAC;QAC7B,gBAAgB;QAChB,KAAK,EAAE,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;QAClE,UAAU,EACR,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;QACvE,GAAG,EAAE,OAAO,MAAM,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS;KAC9D,CAAC,CAAC;AACL,CAAC"}

package/dist/query-perf.d.ts

@@ -0,0 +1,4 @@
+import type { QueryPerfReport } from "@vivantel/virage-core";
+import pg from "pg";
+export declare function getQueryPerfReport(pool: pg.Pool, table: 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,OAAO,EAAE,MAAM,IAAI,CAAC;AAEpB,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,KAAK,EAAE,MAAM,EACb,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,eAAe,CAAC,CAkG1B"}

package/dist/query-perf.js

@@ -0,0 +1,76 @@
+export async function getQueryPerfReport(pool, table, timeframeHours) {
+    const client = await pool.connect();
+    try {
+        // Check if pg_stat_statements extension is available
+        const extRes = await client.query(`SELECT COUNT(*) AS count FROM pg_extension WHERE extname = 'pg_stat_statements'`);
+        const hasExtension = parseInt(extRes.rows[0]?.count ?? "0", 10) > 0;
+        if (!hasExtension) {
+            return {
+                timeframeHours,
+                p50LatencyMs: -1,
+                p95LatencyMs: -1,
+                p99LatencyMs: -1,
+                slowQueryCount: -1,
+                suggestedIndexes: [
+                    `Enable pg_stat_statements for query performance monitoring: ` +
+                        `ALTER SYSTEM SET shared_preload_libraries = 'pg_stat_statements'; ` +
+                        `SELECT pg_reload_conf();`,
+                ],
+            };
+        }
+        // pg_stat_statements doesn't filter by time natively, we use what's available
+        const res = await client.query(`SELECT mean_exec_time, stddev_exec_time, calls, query
+       FROM pg_stat_statements
+       WHERE query ILIKE $1
+         AND query NOT ILIKE '%pg_stat_statements%'
+         AND query NOT ILIKE '%pg_indexes%'
+       ORDER BY mean_exec_time DESC
+       LIMIT 100`, [`%${table}%`]);
+        if (res.rows.length === 0) {
+            return {
+                timeframeHours,
+                p50LatencyMs: 0,
+                p95LatencyMs: 0,
+                p99LatencyMs: 0,
+                slowQueryCount: 0,
+                suggestedIndexes: [
+                    `No queries found for table "${table}" in pg_stat_statements`,
+                ],
+            };
+        }
+        // Build latency distribution by expanding mean ± stddev approximation
+        const latencies = [];
+        for (const row of res.rows) {
+            // Include each query weighted by its call count (capped at 10 for memory)
+            const weight = Math.min(row.calls, 10);
+            for (let i = 0; i < weight; i++) {
+                latencies.push(row.mean_exec_time);
+            }
+        }
+        latencies.sort((a, b) => a - b);
+        const percentile = (p) => latencies[Math.floor((p / 100) * latencies.length)] ?? 0;
+        const slowQueryCount = res.rows.filter((r) => r.mean_exec_time > 100).length;
+        const suggestedIndexes = [];
+        if (slowQueryCount > 0) {
+            suggestedIndexes.push(`${slowQueryCount} slow queries (>100ms) found. Consider reviewing index configuration.`);
+        }
+        if (res.rows.some((r) => r.query.toLowerCase().includes("seq scan"))) {
+            suggestedIndexes.push(`Sequential scans detected. Ensure the embedding index is being used.`);
+        }
+        if (suggestedIndexes.length === 0) {
+            suggestedIndexes.push("Query performance looks healthy.");
+        }
+        return {
+            timeframeHours,
+            p50LatencyMs: Math.round(percentile(50) * 10) / 10,
+            p95LatencyMs: Math.round(percentile(95) * 10) / 10,
+            p99LatencyMs: Math.round(percentile(99) * 10) / 10,
+            slowQueryCount,
+            suggestedIndexes,
+        };
+    }
+    finally {
+        client.release();
+    }
+}
+//# 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":"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"}

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,133 @@
+import { describe, it, expect, vi } from "vitest";
+import { getQueryPerfReport } from "./query-perf.js";
+function makePool(queryResults) {
+    const client = {
+        query: vi.fn(),
+        release: vi.fn(),
+    };
+    for (const result of queryResults) {
+        client.query.mockResolvedValueOnce(result);
+    }
+    const pool = {
+        connect: vi.fn().mockResolvedValue(client),
+    };
+    return { pool, client };
+}
+const EXTENSION_ABSENT = [{ rows: [{ count: "0" }] }];
+const EXTENSION_PRESENT = { rows: [{ count: "1" }] };
+function makeStatRow(mean_exec_time, calls, query = "SELECT id FROM documents") {
+    return { mean_exec_time, stddev_exec_time: 5, calls, query };
+}
+describe("getQueryPerfReport (PostgreSQL)", () => {
+    describe("pg_stat_statements not installed", () => {
+        it("returns all -1 latencies and an enable-extension suggestion", async () => {
+            const { pool } = makePool(EXTENSION_ABSENT);
+            const report = await getQueryPerfReport(pool, "documents", 24);
+            expect(report.p50LatencyMs).toBe(-1);
+            expect(report.p95LatencyMs).toBe(-1);
+            expect(report.p99LatencyMs).toBe(-1);
+            expect(report.slowQueryCount).toBe(-1);
+            expect(report.suggestedIndexes[0]).toMatch(/pg_stat_statements/i);
+        });
+        it("preserves the requested timeframeHours in the response", async () => {
+            const { pool } = makePool(EXTENSION_ABSENT);
+            const report = await getQueryPerfReport(pool, "documents", 48);
+            expect(report.timeframeHours).toBe(48);
+        });
+    });
+    describe("pg_stat_statements installed, no rows for the table", () => {
+        it("returns zero latencies and a no-queries message", async () => {
+            const { pool } = makePool([EXTENSION_PRESENT, { rows: [] }]);
+            const report = await getQueryPerfReport(pool, "documents", 24);
+            expect(report.p50LatencyMs).toBe(0);
+            expect(report.p95LatencyMs).toBe(0);
+            expect(report.p99LatencyMs).toBe(0);
+            expect(report.slowQueryCount).toBe(0);
+            expect(report.suggestedIndexes[0]).toMatch(/No queries found/i);
+        });
+    });
+    describe("query stats present", () => {
+        it("returns valid percentiles (p50 ≤ p95 ≤ p99)", async () => {
+            const { pool } = makePool([
+                EXTENSION_PRESENT,
+                { rows: [makeStatRow(10, 5), makeStatRow(30, 3), makeStatRow(80, 8)] },
+            ]);
+            const report = await getQueryPerfReport(pool, "documents", 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 { pool } = makePool([
+                EXTENSION_PRESENT,
+                { rows: [makeStatRow(5, 1)] },
+            ]);
+            const report = await getQueryPerfReport(pool, "documents", 72);
+            expect(report.timeframeHours).toBe(72);
+        });
+        it("identifies slow queries (mean_exec_time > 100 ms)", async () => {
+            const { pool } = makePool([
+                EXTENSION_PRESENT,
+                {
+                    rows: [
+                        makeStatRow(50, 3), // fast
+                        makeStatRow(150, 2), // slow
+                        makeStatRow(200, 1), // slow
+                    ],
+                },
+            ]);
+            const report = await getQueryPerfReport(pool, "documents", 24);
+            expect(report.slowQueryCount).toBe(2);
+            expect(report.suggestedIndexes[0]).toMatch(/slow queries/i);
+        });
+        it("suggests healthy when all queries are fast", async () => {
+            const { pool } = makePool([
+                EXTENSION_PRESENT,
+                { rows: [makeStatRow(20, 5), makeStatRow(40, 3)] },
+            ]);
+            const report = await getQueryPerfReport(pool, "documents", 24);
+            expect(report.slowQueryCount).toBe(0);
+            expect(report.suggestedIndexes[0]).toMatch(/healthy/i);
+        });
+        it("detects sequential scans in query text", async () => {
+            const { pool } = makePool([
+                EXTENSION_PRESENT,
+                {
+                    rows: [
+                        {
+                            mean_exec_time: 50,
+                            stddev_exec_time: 5,
+                            calls: 1,
+                            query: "seq scan on documents",
+                        },
+                    ],
+                },
+            ]);
+            const report = await getQueryPerfReport(pool, "documents", 24);
+            expect(report.suggestedIndexes.some((s) => /sequential/i.test(s))).toBe(true);
+        });
+        it("caps per-row weight at 10 samples regardless of call count", async () => {
+            const { pool } = makePool([
+                EXTENSION_PRESENT,
+                { rows: [makeStatRow(10, 10_000)] }, // very high call count
+            ]);
+            // Should not throw or run out of memory
+            const report = await getQueryPerfReport(pool, "documents", 24);
+            expect(report.p50LatencyMs).toBeGreaterThanOrEqual(0);
+        });
+    });
+    describe("client lifecycle", () => {
+        it("releases the client even when a query throws", async () => {
+            const client = {
+                query: vi.fn().mockRejectedValue(new Error("connection reset")),
+                release: vi.fn(),
+            };
+            const pool = {
+                connect: vi.fn().mockResolvedValue(client),
+            };
+            await expect(getQueryPerfReport(pool, "documents", 24)).rejects.toThrow("connection reset");
+            expect(client.release).toHaveBeenCalledOnce();
+        });
+    });
+});
+//# 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,4 @@
+import type { IndexStats } from "@vivantel/virage-core";
+import pg from "pg";
+export declare function getIndexStats(pool: pg.Pool, table: 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,EAAE,MAAM,IAAI,CAAC;AAEpB,wBAAsB,aAAa,CACjC,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,UAAU,CAAC,CAOrB"}

package/dist/stats.js

@@ -0,0 +1,102 @@
+export async function getIndexStats(pool, table) {
+    const client = await pool.connect();
+    try {
+        return await computeIndexStats(client, table);
+    }
+    finally {
+        client.release();
+    }
+}
+async function computeIndexStats(client, table) {
+    const suggestions = [];
+    // Total vector count
+    const countRes = await client.query(`SELECT COUNT(*) AS count FROM ${table}`);
+    const totalVectors = parseInt(countRes.rows[0]?.count ?? "0", 10);
+    // Index type and definition
+    const indexRes = await client.query(`SELECT indexname, indexdef FROM pg_indexes WHERE tablename = $1`, [table]);
+    let indexType = "unknown";
+    for (const row of indexRes.rows) {
+        const def = row.indexdef.toLowerCase();
+        if (def.includes("hnsw")) {
+            indexType = "hnsw";
+            break;
+        }
+        else if (def.includes("ivfflat")) {
+            indexType = "ivfflat";
+            break;
+        }
+        else if (def.includes("btree") || def.includes("flat")) {
+            indexType = "flat";
+        }
+    }
+    // Dead tuple fraction and index age from pg_stat_user_tables
+    const statRes = await client.query(`SELECT n_live_tup, n_dead_tup, last_vacuum, last_autovacuum
+     FROM pg_stat_user_tables WHERE relname = $1`, [table]);
+    const statRow = statRes.rows[0];
+    const nLive = parseInt(statRow?.n_live_tup ?? "0", 10);
+    const nDead = parseInt(statRow?.n_dead_tup ?? "0", 10);
+    const deadTupleFraction = nLive + nDead > 0 ? nDead / (nLive + nDead) : 0;
+    const lastVacuum = statRow?.last_vacuum ?? statRow?.last_autovacuum ?? null;
+    const indexAgeHours = lastVacuum
+        ? (Date.now() - new Date(lastVacuum).getTime()) / 3_600_000
+        : -1;
+    // ANN recall@10: compare exact vs index results for a zero vector
+    const annRecallAt10 = await computeAnnRecall(client, table);
+    // Build suggestions
+    if (deadTupleFraction > 0.1) {
+        suggestions.push(`REINDEX recommended: ${(deadTupleFraction * 100).toFixed(0)}% dead tuples in "${table}"`);
+    }
+    if (indexType === "ivfflat" && totalVectors > 100_000) {
+        suggestions.push(`Consider switching to HNSW index for better recall at ${totalVectors.toLocaleString()} vectors`);
+    }
+    if (indexAgeHours > 168) {
+        suggestions.push(`Index age ${Math.round(indexAgeHours)} hours — consider VACUUM ANALYZE`);
+    }
+    if (suggestions.length === 0) {
+        suggestions.push("Index looks healthy");
+    }
+    return {
+        totalVectors,
+        indexType,
+        annRecallAt10,
+        indexAgeHours: Math.round(indexAgeHours * 10) / 10,
+        deadTupleFraction: Math.round(deadTupleFraction * 1000) / 1000,
+        suggestions,
+    };
+}
+async function computeAnnRecall(client, table) {
+    // Check if table has any rows and an embedding column
+    const colRes = await client.query(`SELECT data_type FROM information_schema.columns
+     WHERE table_name = $1 AND column_name = 'embedding'`, [table]);
+    if (colRes.rows.length === 0)
+        return -1;
+    const countRes = await client.query(`SELECT COUNT(*) AS count FROM ${table}`);
+    const total = parseInt(countRes.rows[0]?.count ?? "0", 10);
+    if (total < 10)
+        return -1; // Not enough data
+    try {
+        // Get dimension from a sample embedding
+        const sampleRes = await client.query(`SELECT array_length(embedding::real[], 1) AS dim FROM ${table} LIMIT 1`);
+        const dim = sampleRes.rows[0]?.dim;
+        if (!dim)
+            return -1;
+        // Use a zero vector for comparison
+        const zeroVec = `[${Array(dim).fill(0).join(",")}]`;
+        // Exact results (no index, brute-force)
+        const exactRes = await client.query(`SELECT id FROM ${table}
+       ORDER BY embedding::vector <=> $1::vector
+       LIMIT 10`, [zeroVec]);
+        const exactIds = new Set(exactRes.rows.map((r) => r.id));
+        // ANN results (uses index)
+        const annRes = await client.query(`SELECT id FROM ${table}
+       ORDER BY embedding <=> $1::vector
+       LIMIT 10`, [zeroVec]);
+        const annIds = annRes.rows.map((r) => 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,274 @@
+import { describe, it, expect, vi } from "vitest";
+import { getIndexStats } from "./stats.js";
+function makePool(queryResults) {
+    const client = {
+        query: vi.fn(),
+        release: vi.fn(),
+    };
+    for (const result of queryResults) {
+        client.query.mockResolvedValueOnce(result);
+    }
+    const pool = {
+        connect: vi.fn().mockResolvedValue(client),
+    };
+    return { pool, client };
+}
+const STAT_ROW_CLEAN = {
+    n_live_tup: "500",
+    n_dead_tup: "0",
+    last_vacuum: null,
+    last_autovacuum: null,
+};
+// Minimal 4-query sequence: no ANN recall (embedding column absent)
+function noAnnResponses(count, indexRows = [], statRow = STAT_ROW_CLEAN) {
+    return [
+        { rows: [{ count: String(count) }] },
+        { rows: indexRows },
+        { rows: [statRow] },
+        { rows: [] }, // no embedding column
+    ];
+}
+// 8-query sequence including full ANN recall
+function withAnnResponses(count, indexRows, statRow, dim, exactIds, annIds) {
+    return [
+        { rows: [{ count: String(count) }] },
+        { rows: indexRows },
+        { rows: [statRow] },
+        { rows: [{ data_type: "USER-DEFINED" }] }, // embedding column present
+        { rows: [{ count: String(count) }] },
+        { rows: [{ dim }] },
+        { rows: exactIds.map((id) => ({ id })) },
+        { rows: annIds.map((id) => ({ id })) },
+    ];
+}
+describe("getIndexStats (PostgreSQL)", () => {
+    describe("totalVectors", () => {
+        it("reflects the COUNT query result", async () => {
+            const { pool } = makePool(noAnnResponses(1234));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.totalVectors).toBe(1234);
+        });
+        it("is 0 when the table is empty", async () => {
+            const { pool } = makePool(noAnnResponses(0));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.totalVectors).toBe(0);
+        });
+    });
+    describe("indexType detection", () => {
+        it("detects hnsw from pg_indexes indexdef", async () => {
+            const { pool } = makePool(noAnnResponses(100, [
+                {
+                    indexname: "emb_idx",
+                    indexdef: "CREATE INDEX emb_idx USING hnsw (embedding)",
+                },
+            ]));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.indexType).toBe("hnsw");
+        });
+        it("detects ivfflat from pg_indexes indexdef", async () => {
+            const { pool } = makePool(noAnnResponses(100, [
+                {
+                    indexname: "emb_idx",
+                    indexdef: "CREATE INDEX emb_idx USING ivfflat (embedding)",
+                },
+            ]));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.indexType).toBe("ivfflat");
+        });
+        it("detects flat from btree indexdef", async () => {
+            const { pool } = makePool(noAnnResponses(100, [
+                {
+                    indexname: "pkey",
+                    indexdef: "CREATE UNIQUE INDEX pkey USING btree (id)",
+                },
+            ]));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.indexType).toBe("flat");
+        });
+        it("is unknown when pg_indexes returns no rows", async () => {
+            const { pool } = makePool(noAnnResponses(100, []));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.indexType).toBe("unknown");
+        });
+        it("uses the first matching index row (first-match order)", async () => {
+            // hnsw row comes first → detected as hnsw even though ivfflat row also present
+            const { pool } = makePool(noAnnResponses(100, [
+                {
+                    indexname: "hnsw_idx",
+                    indexdef: "CREATE INDEX USING hnsw (embedding)",
+                },
+                {
+                    indexname: "ivf_idx",
+                    indexdef: "CREATE INDEX USING ivfflat (embedding)",
+                },
+            ]));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.indexType).toBe("hnsw");
+        });
+    });
+    describe("deadTupleFraction", () => {
+        it("is computed as dead / (live + dead)", async () => {
+            const { pool } = makePool(noAnnResponses(100, [], {
+                n_live_tup: "300",
+                n_dead_tup: "100",
+                last_vacuum: null,
+                last_autovacuum: null,
+            }));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.deadTupleFraction).toBeCloseTo(0.25, 2);
+        });
+        it("is 0 when no tuples exist", async () => {
+            const { pool } = makePool(noAnnResponses(0, [], {
+                n_live_tup: "0",
+                n_dead_tup: "0",
+                last_vacuum: null,
+                last_autovacuum: null,
+            }));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.deadTupleFraction).toBe(0);
+        });
+    });
+    describe("indexAgeHours", () => {
+        it("is computed from last_vacuum when present", async () => {
+            const lastVacuum = new Date(Date.now() - 2 * 3_600_000).toISOString();
+            const { pool } = makePool(noAnnResponses(100, [], { ...STAT_ROW_CLEAN, last_vacuum: lastVacuum }));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.indexAgeHours).toBeGreaterThanOrEqual(1.9);
+            expect(stats.indexAgeHours).toBeLessThanOrEqual(2.1);
+        });
+        it("falls back to last_autovacuum when last_vacuum is null", async () => {
+            const lastAutoVacuum = new Date(Date.now() - 3 * 3_600_000).toISOString();
+            const { pool } = makePool(noAnnResponses(100, [], {
+                ...STAT_ROW_CLEAN,
+                last_vacuum: null,
+                last_autovacuum: lastAutoVacuum,
+            }));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.indexAgeHours).toBeGreaterThanOrEqual(2.9);
+            expect(stats.indexAgeHours).toBeLessThanOrEqual(3.1);
+        });
+        it("is -1 when both vacuum timestamps are null", async () => {
+            const { pool } = makePool(noAnnResponses(100));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.indexAgeHours).toBe(-1);
+        });
+    });
+    describe("ANN recall", () => {
+        it("is -1 when embedding column is absent", async () => {
+            const { pool } = makePool(noAnnResponses(500));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.annRecallAt10).toBe(-1);
+        });
+        it("is -1 when table has fewer than 10 rows", async () => {
+            const { pool } = makePool([
+                { rows: [{ count: "5" }] },
+                { rows: [] },
+                { rows: [STAT_ROW_CLEAN] },
+                { rows: [{ data_type: "USER-DEFINED" }] }, // embedding col present
+                { rows: [{ count: "5" }] }, // but count < 10
+            ]);
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.annRecallAt10).toBe(-1);
+        });
+        it("is -1 when dim query returns null", async () => {
+            const { pool } = makePool([
+                { rows: [{ count: "100" }] },
+                { rows: [] },
+                { rows: [STAT_ROW_CLEAN] },
+                { rows: [{ data_type: "USER-DEFINED" }] },
+                { rows: [{ count: "100" }] },
+                { rows: [{ dim: null }] }, // no dim
+            ]);
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.annRecallAt10).toBe(-1);
+        });
+        it("is 1.0 when ANN and exact results are identical", async () => {
+            const ids = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+            const { pool } = makePool(withAnnResponses(100, [], STAT_ROW_CLEAN, 4, ids, ids));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.annRecallAt10).toBe(1);
+        });
+        it("computes partial recall correctly", async () => {
+            const exactIds = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+            const annIds = [1, 2, 3, 4, 5, 11, 12, 13, 14, 15]; // 5 hits
+            const { pool } = makePool(withAnnResponses(100, [], STAT_ROW_CLEAN, 4, exactIds, annIds));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.annRecallAt10).toBeCloseTo(0.5, 5);
+        });
+        it("is -1 when the search query throws", async () => {
+            const client = {
+                query: vi
+                    .fn()
+                    .mockResolvedValueOnce({ rows: [{ count: "100" }] })
+                    .mockResolvedValueOnce({ rows: [] })
+                    .mockResolvedValueOnce({ rows: [STAT_ROW_CLEAN] })
+                    .mockResolvedValueOnce({ rows: [{ data_type: "USER-DEFINED" }] })
+                    .mockResolvedValueOnce({ rows: [{ count: "100" }] })
+                    .mockResolvedValueOnce({ rows: [{ dim: 4 }] })
+                    .mockRejectedValueOnce(new Error("operator does not exist")),
+                release: vi.fn(),
+            };
+            const pool = {
+                connect: vi.fn().mockResolvedValue(client),
+            };
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.annRecallAt10).toBe(-1);
+        });
+    });
+    describe("suggestions", () => {
+        it("recommends REINDEX when dead tuple fraction > 10%", async () => {
+            const { pool } = makePool(noAnnResponses(100, [], {
+                n_live_tup: "800",
+                n_dead_tup: "200",
+                last_vacuum: null,
+                last_autovacuum: null,
+            }));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.suggestions.some((s) => /REINDEX/i.test(s))).toBe(true);
+        });
+        it("suggests switching to HNSW for ivfflat index with > 100k vectors", async () => {
+            const { pool } = makePool(noAnnResponses(150_000, [
+                {
+                    indexname: "idx",
+                    indexdef: "CREATE INDEX USING ivfflat (embedding)",
+                },
+            ]));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.suggestions.some((s) => /HNSW/i.test(s))).toBe(true);
+        });
+        it("does not suggest HNSW for hnsw index with > 100k vectors", async () => {
+            const { pool } = makePool(noAnnResponses(150_000, [
+                { indexname: "idx", indexdef: "CREATE INDEX USING hnsw (embedding)" },
+            ]));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.suggestions.every((s) => !/switch.*HNSW/i.test(s))).toBe(true);
+        });
+        it("suggests VACUUM ANALYZE when index is older than 168 hours", async () => {
+            const old = new Date(Date.now() - 200 * 3_600_000).toISOString();
+            const { pool } = makePool(noAnnResponses(100, [], { ...STAT_ROW_CLEAN, last_vacuum: old }));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.suggestions.some((s) => /VACUUM/i.test(s))).toBe(true);
+        });
+        it("returns healthy suggestion when no issues detected", async () => {
+            const { pool } = makePool(noAnnResponses(100, [
+                { indexname: "idx", indexdef: "CREATE INDEX USING hnsw (embedding)" },
+            ]));
+            const stats = await getIndexStats(pool, "documents");
+            expect(stats.suggestions[0]).toMatch(/healthy/i);
+        });
+    });
+    describe("client lifecycle", () => {
+        it("releases the client even when a query throws", async () => {
+            const client = {
+                query: vi.fn().mockRejectedValue(new Error("connection lost")),
+                release: vi.fn(),
+            };
+            const pool = {
+                connect: vi.fn().mockResolvedValue(client),
+            };
+            await expect(getIndexStats(pool, "documents")).rejects.toThrow("connection lost");
+            expect(client.release).toHaveBeenCalledOnce();
+        });
+    });
+});
+//# 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":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAe3C,SAAS,QAAQ,CAAC,YAA+B;IAC/C,MAAM,MAAM,GAAG;QACb,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE;QACd,OAAO,EAAE,EAAE,CAAC,EAAE,EAAE;KACjB,CAAC;IACF,KAAK,MAAM,MAAM,IAAI,YAAY,EAAE,CAAC;QAClC,MAAM,CAAC,KAAK,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC;IACD,MAAM,IAAI,GAAG;QACX,OAAO,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,MAAM,CAAC;KACrB,CAAC;IACxB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1B,CAAC;AAED,MAAM,cAAc,GAAG;IACrB,UAAU,EAAE,KAAK;IACjB,UAAU,EAAE,GAAG;IACf,WAAW,EAAE,IAAI;IACjB,eAAe,EAAE,IAAI;CACtB,CAAC;AAEF,oEAAoE;AACpE,SAAS,cAAc,CACrB,KAAa,EACb,YAAmB,EAAE,EACrB,UAAe,cAAc;IAE7B,OAAO;QACL,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE;QACpC,EAAE,IAAI,EAAE,SAAS,EAAE;QACnB,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE;QACnB,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE,sBAAsB;KACrC,CAAC;AACJ,CAAC;AAED,6CAA6C;AAC7C,SAAS,gBAAgB,CACvB,KAAa,EACb,SAAgB,EAChB,OAAY,EACZ,GAAW,EACX,QAAkB,EAClB,MAAgB;IAEhB,OAAO;QACL,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE;QACpC,EAAE,IAAI,EAAE,SAAS,EAAE;QACnB,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE;QACnB,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,cAAc,EAAE,CAAC,EAAE,EAAE,2BAA2B;QACtE,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE;QACpC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE;QACnB,EAAE,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE;QACxC,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE;KACvC,CAAC;AACJ,CAAC;AAED,QAAQ,CAAC,4BAA4B,EAAE,GAAG,EAAE;IAC1C,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;QAC5B,EAAE,CAAC,iCAAiC,EAAE,KAAK,IAAI,EAAE;YAC/C,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC;YAEhD,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,8BAA8B,EAAE,KAAK,IAAI,EAAE;YAC5C,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;YAE7C,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE;QACnC,EAAE,CAAC,uCAAuC,EAAE,KAAK,IAAI,EAAE;YACrD,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CACvB,cAAc,CAAC,GAAG,EAAE;gBAClB;oBACE,SAAS,EAAE,SAAS;oBACpB,QAAQ,EAAE,6CAA6C;iBACxD;aACF,CAAC,CACH,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,0CAA0C,EAAE,KAAK,IAAI,EAAE;YACxD,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CACvB,cAAc,CAAC,GAAG,EAAE;gBAClB;oBACE,SAAS,EAAE,SAAS;oBACpB,QAAQ,EAAE,gDAAgD;iBAC3D;aACF,CAAC,CACH,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,kCAAkC,EAAE,KAAK,IAAI,EAAE;YAChD,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CACvB,cAAc,CAAC,GAAG,EAAE;gBAClB;oBACE,SAAS,EAAE,MAAM;oBACjB,QAAQ,EAAE,2CAA2C;iBACtD;aACF,CAAC,CACH,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;YAC1D,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,cAAc,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC;YAEnD,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,uDAAuD,EAAE,KAAK,IAAI,EAAE;YACrE,+EAA+E;YAC/E,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CACvB,cAAc,CAAC,GAAG,EAAE;gBAClB;oBACE,SAAS,EAAE,UAAU;oBACrB,QAAQ,EAAE,qCAAqC;iBAChD;gBACD;oBACE,SAAS,EAAE,SAAS;oBACpB,QAAQ,EAAE,wCAAwC;iBACnD;aACF,CAAC,CACH,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;QACjC,EAAE,CAAC,qCAAqC,EAAE,KAAK,IAAI,EAAE;YACnD,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CACvB,cAAc,CAAC,GAAG,EAAE,EAAE,EAAE;gBACtB,UAAU,EAAE,KAAK;gBACjB,UAAU,EAAE,KAAK;gBACjB,WAAW,EAAE,IAAI;gBACjB,eAAe,EAAE,IAAI;aACtB,CAAC,CACH,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACvD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,2BAA2B,EAAE,KAAK,IAAI,EAAE;YACzC,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CACvB,cAAc,CAAC,CAAC,EAAE,EAAE,EAAE;gBACpB,UAAU,EAAE,GAAG;gBACf,UAAU,EAAE,GAAG;gBACf,WAAW,EAAE,IAAI;gBACjB,eAAe,EAAE,IAAI;aACtB,CAAC,CACH,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;QAC7B,EAAE,CAAC,2CAA2C,EAAE,KAAK,IAAI,EAAE;YACzD,MAAM,UAAU,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;YACtE,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CACvB,cAAc,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,GAAG,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CACxE,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC;YACxD,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;QACvD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,wDAAwD,EAAE,KAAK,IAAI,EAAE;YACtE,MAAM,cAAc,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;YAC1E,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CACvB,cAAc,CAAC,GAAG,EAAE,EAAE,EAAE;gBACtB,GAAG,cAAc;gBACjB,WAAW,EAAE,IAAI;gBACjB,eAAe,EAAE,cAAc;aAChC,CAAC,CACH,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC;YACxD,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;QACvD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,4CAA4C,EAAE,KAAK,IAAI,EAAE;YAC1D,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;YAE/C,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;QAC1B,EAAE,CAAC,uCAAuC,EAAE,KAAK,IAAI,EAAE;YACrD,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;YAE/C,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,yCAAyC,EAAE,KAAK,IAAI,EAAE;YACvD,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC;gBACxB,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE;gBAC1B,EAAE,IAAI,EAAE,EAAE,EAAE;gBACZ,EAAE,IAAI,EAAE,CAAC,cAAc,CAAC,EAAE;gBAC1B,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,cAAc,EAAE,CAAC,EAAE,EAAE,wBAAwB;gBACnE,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,iBAAiB;aAC9C,CAAC,CAAC;YAEH,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,mCAAmC,EAAE,KAAK,IAAI,EAAE;YACjD,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC;gBACxB,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE;gBAC5B,EAAE,IAAI,EAAE,EAAE,EAAE;gBACZ,EAAE,IAAI,EAAE,CAAC,cAAc,CAAC,EAAE;gBAC1B,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,cAAc,EAAE,CAAC,EAAE;gBACzC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE;gBAC5B,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,SAAS;aACrC,CAAC,CAAC;YAEH,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,iDAAiD,EAAE,KAAK,IAAI,EAAE;YAC/D,MAAM,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;YAC5C,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CACvB,gBAAgB,CAAC,GAAG,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,CACvD,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,mCAAmC,EAAE,KAAK,IAAI,EAAE;YACjD,MAAM,QAAQ,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;YACjD,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS;YAC7D,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CACvB,gBAAgB,CAAC,GAAG,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,CAC/D,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAClD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,oCAAoC,EAAE,KAAK,IAAI,EAAE;YAClD,MAAM,MAAM,GAAG;gBACb,KAAK,EAAE,EAAE;qBACN,EAAE,EAAE;qBACJ,qBAAqB,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;qBACnD,qBAAqB,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;qBACnC,qBAAqB,CAAC,EAAE,IAAI,EAAE,CAAC,cAAc,CAAC,EAAE,CAAC;qBACjD,qBAAqB,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,cAAc,EAAE,CAAC,EAAE,CAAC;qBAChE,qBAAqB,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;qBACnD,qBAAqB,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;qBAC7C,qBAAqB,CAAC,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;gBAC9D,OAAO,EAAE,EAAE,CAAC,EAAE,EAAE;aACjB,CAAC;YACF,MAAM,IAAI,GAAG;gBACX,OAAO,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,MAAM,CAAC;aACrB,CAAC;YAExB,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;QAC3B,EAAE,CAAC,mDAAmD,EAAE,KAAK,IAAI,EAAE;YACjE,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CACvB,cAAc,CAAC,GAAG,EAAE,EAAE,EAAE;gBACtB,UAAU,EAAE,KAAK;gBACjB,UAAU,EAAE,KAAK;gBACjB,WAAW,EAAE,IAAI;gBACjB,eAAe,EAAE,IAAI;aACtB,CAAC,CACH,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,kEAAkE,EAAE,KAAK,IAAI,EAAE;YAChF,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CACvB,cAAc,CAAC,OAAO,EAAE;gBACtB;oBACE,SAAS,EAAE,KAAK;oBAChB,QAAQ,EAAE,wCAAwC;iBACnD;aACF,CAAC,CACH,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,0DAA0D,EAAE,KAAK,IAAI,EAAE;YACxE,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CACvB,cAAc,CAAC,OAAO,EAAE;gBACtB,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,qCAAqC,EAAE;aACtE,CAAC,CACH,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CACnE,IAAI,CACL,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,4DAA4D,EAAE,KAAK,IAAI,EAAE;YAC1E,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,SAAS,CAAC,CAAC,WAAW,EAAE,CAAC;YACjE,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CACvB,cAAc,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,GAAG,cAAc,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,CACjE,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtE,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,oDAAoD,EAAE,KAAK,IAAI,EAAE;YAClE,MAAM,EAAE,IAAI,EAAE,GAAG,QAAQ,CACvB,cAAc,CAAC,GAAG,EAAE;gBAClB,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,qCAAqC,EAAE;aACtE,CAAC,CACH,CAAC;YAEF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;YAErD,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACnD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;QAChC,EAAE,CAAC,8CAA8C,EAAE,KAAK,IAAI,EAAE;YAC5D,MAAM,MAAM,GAAG;gBACb,KAAK,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC;gBAC9D,OAAO,EAAE,EAAE,CAAC,EAAE,EAAE;aACjB,CAAC;YACF,MAAM,IAAI,GAAG;gBACX,OAAO,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,MAAM,CAAC;aACrB,CAAC;YAExB,MAAM,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAC5D,iBAAiB,CAClB,CAAC;YAEF,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,oBAAoB,EAAE,CAAC;QAChD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/store.d.ts

@@ -0,0 +1,54 @@
+import type { VectorStore, VectorSearchResult, IndexStats, QueryPerfReport, Logger } from "@vivantel/virage-core";
+export type IndexType = "ivfflat" | "hnsw";
+export interface IVFFlatParams {
+    /** Number of IVFFlat lists. Defaults to 100. */
+    lists?: number;
+}
+export interface HNSWParams {
+    /** HNSW M parameter (connections per layer). Defaults to 16. */
+    m?: number;
+    /** HNSW ef_construction parameter. Defaults to 64. */
+    efConstruction?: number;
+}
+export interface PostgresVectorStoreOptions {
+    connectionString: string;
+    /** Table name. Defaults to "documents". */
+    table?: string;
+    /** Vector dimensions — must match your embedder. Defaults to 1536. */
+    dimensions?: number;
+    /** Enable SSL. Defaults to false. */
+    ssl?: boolean;
+    /** Index algorithm. Defaults to "ivfflat". */
+    indexType?: IndexType;
+    /** Index-specific parameters. */
+    indexParams?: IVFFlatParams | HNSWParams;
+}
+export declare class PostgresVectorStore implements VectorStore {
+    readonly name = "postgres";
+    private readonly table;
+    private readonly dimensions;
+    private readonly connectionString;
+    private readonly ssl;
+    private readonly indexType;
+    private readonly indexParams;
+    private _pool;
+    private logger;
+    constructor(options: PostgresVectorStoreOptions);
+    setLogger(logger: Logger): void;
+    private get pool();
+    initialize(): Promise<void>;
+    upsert(docs: Array<{
+        content: string;
+        embedding: number[];
+        metadata: Record<string, unknown>;
+        sourceFile: string;
+        commitHash: string;
+    }>): Promise<void>;
+    deleteBySourceFile(files: string[]): Promise<void>;
+    getCurrentState(): Promise<Map<string, string>>;
+    private buildIndexSQL;
+    search(embedding: 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,kBAAkB,EAClB,UAAU,EACV,eAAe,EACf,MAAM,EACP,MAAM,uBAAuB,CAAC;AAQ/B,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;AAE3C,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,sDAAsD;IACtD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,8CAA8C;IAC9C,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,iCAAiC;IACjC,WAAW,CAAC,EAAE,aAAa,GAAG,UAAU,CAAC;CAC1C;AAED,qBAAa,mBAAoB,YAAW,WAAW;IACrD,QAAQ,CAAC,IAAI,cAAc;IAE3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAU;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,KAAK,CAA0C;IACvD,OAAO,CAAC,MAAM,CAAuB;gBAEzB,OAAO,EAAE,0BAA0B;IAY/C,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI/B,OAAO,KAAK,IAAI,GAQf;IAEK,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B3B,MAAM,CACV,IAAI,EAAE,KAAK,CAAC;QACV,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,MAAM,EAAE,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAClC,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC,GACD,OAAO,CAAC,IAAI,CAAC;IA2BV,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASlD,eAAe,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAUrD,OAAO,CAAC,aAAa;IAqBf,MAAM,CACV,SAAS,EAAE,MAAM,EAAE,EACnB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,kBAAkB,EAAE,CAAC;IA+B1B,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,142 @@
+import pg from "pg";
+import pgvector from "pgvector/pg";
+import { getIndexStats } from "./stats.js";
+import { getQueryPerfReport } from "./query-perf.js";
+const { Pool } = pg;
+export class PostgresVectorStore {
+    name = "postgres";
+    table;
+    dimensions;
+    connectionString;
+    ssl;
+    indexType;
+    indexParams;
+    _pool = null;
+    logger = null;
+    constructor(options) {
+        if (!options.connectionString) {
+            throw new Error("PostgresVectorStore: connectionString is required");
+        }
+        this.connectionString = options.connectionString;
+        this.table = options.table ?? "documents";
+        this.dimensions = options.dimensions ?? 1536;
+        this.ssl = options.ssl ?? false;
+        this.indexType = options.indexType ?? "ivfflat";
+        this.indexParams = options.indexParams ?? {};
+    }
+    setLogger(logger) {
+        this.logger = logger.withTag("postgres");
+    }
+    get pool() {
+        if (!this._pool) {
+            this._pool = new Pool({
+                connectionString: this.connectionString,
+                ssl: this.ssl ? { rejectUnauthorized: false } : false,
+            });
+        }
+        return this._pool;
+    }
+    async initialize() {
+        this.logger?.info(`Connecting to postgres, table: ${this.table} (${this.dimensions}d, ${this.indexType})`);
+        const client = await this.pool.connect();
+        try {
+            await pgvector.registerTypes(client);
+            await client.query("CREATE EXTENSION IF NOT EXISTS vector");
+            await client.query(`
+        CREATE TABLE IF NOT EXISTS ${this.table} (
+          id SERIAL PRIMARY KEY,
+          content TEXT NOT NULL,
+          embedding vector(${this.dimensions}),
+          metadata JSONB,
+          source_file TEXT NOT NULL,
+          commit_hash TEXT NOT NULL
+        )
+      `);
+            await client.query(this.buildIndexSQL());
+            this.logger?.debug(`Index type: ${this.indexType}, params: ${JSON.stringify(this.indexParams)}`);
+        }
+        finally {
+            client.release();
+        }
+    }
+    async upsert(docs) {
+        if (docs.length === 0)
+            return;
+        this.logger?.verbose(`Upserting ${docs.length} docs into ${this.table}`);
+        const client = await this.pool.connect();
+        try {
+            await pgvector.registerTypes(client);
+            for (const doc of docs) {
+                this.logger?.trace(`  source_file: ${doc.sourceFile}`);
+                await client.query(`INSERT INTO ${this.table} (content, embedding, metadata, source_file, commit_hash)
+           VALUES ($1, $2, $3, $4, $5)`, [
+                    doc.content,
+                    pgvector.toSql(doc.embedding),
+                    JSON.stringify(doc.metadata),
+                    doc.sourceFile,
+                    doc.commitHash,
+                ]);
+            }
+        }
+        finally {
+            client.release();
+        }
+    }
+    async deleteBySourceFile(files) {
+        if (files.length === 0)
+            return;
+        this.logger?.verbose(`Deleting docs for ${files.length} source file(s)`);
+        await this.pool.query(`DELETE FROM ${this.table} WHERE source_file = ANY($1)`, [files]);
+    }
+    async getCurrentState() {
+        const { rows } = await this.pool.query(`SELECT source_file, commit_hash FROM ${this.table}`);
+        const state = new Map(rows.map((r) => [r.source_file, r.commit_hash]));
+        this.logger?.verbose(`getCurrentState: ${state.size} source version(s)`);
+        return state;
+    }
+    buildIndexSQL() {
+        const idxName = `${this.table}_embedding_idx`;
+        if (this.indexType === "hnsw") {
+            const p = this.indexParams;
+            const m = p.m ?? 16;
+            const efConstruction = p.efConstruction ?? 64;
+            return (`CREATE INDEX IF NOT EXISTS ${idxName} ` +
+                `ON ${this.table} USING hnsw (embedding vector_cosine_ops) ` +
+                `WITH (m = ${m}, ef_construction = ${efConstruction})`);
+        }
+        const p = this.indexParams;
+        const lists = p.lists ?? 100;
+        return (`CREATE INDEX IF NOT EXISTS ${idxName} ` +
+            `ON ${this.table} USING ivfflat (embedding vector_cosine_ops) ` +
+            `WITH (lists = ${lists})`);
+    }
+    async search(embedding, topK) {
+        this.logger?.debug(`Search: topK=${topK}`);
+        const client = await this.pool.connect();
+        try {
+            await pgvector.registerTypes(client);
+            const { rows } = await client.query(`SELECT id, content, metadata, source_file,
+                1 - (embedding <=> $1) AS similarity
+         FROM ${this.table}
+         ORDER BY embedding <=> $1
+         LIMIT $2`, [pgvector.toSql(embedding), topK]);
+            return rows.map((r) => ({
+                id: String(r.id),
+                content: r.content,
+                metadata: r.metadata,
+                sourceFile: r.source_file,
+                similarity: r.similarity,
+            }));
+        }
+        finally {
+            client.release();
+        }
+    }
+    async getIndexStats() {
+        return getIndexStats(this.pool, this.table);
+    }
+    async getQueryPerfReport(timeframeHours) {
+        return getQueryPerfReport(this.pool, this.table, 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,64 @@
+{
+  "name": "@vivantel/virage-store-postgres",
+  "version": "0.2.0",
+  "description": "PostgreSQL + pgvector store for @vivantel/rag-core",
+  "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",
+    "postgres",
+    "postgresql",
+    "pgvector"
+  ],
+  "author": "Vivantel",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vivantel/virage",
+    "directory": "packages/virage-store-postgres"
+  },
+  "dependencies": {
+    "pg": "^8.0.0",
+    "pgvector": "^0.3.0"
+  },
+  "peerDependencies": {
+    "@vivantel/virage-core": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@types/pg": "^8.0.0",
+    "@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"
+  }
+}