@nebutra/knowledge-rag 0.2.0

package/dist/keyword.js

@@ -0,0 +1,114 @@
+// =============================================================================
+// @nebutra/knowledge-rag — Keyword leg (wraps @nebutra/search)
+// =============================================================================
+// Rather than reinventing a keyword index, this WRAPS the existing
+// provider-agnostic @nebutra/search abstraction (Meilisearch / Typesense /
+// Algolia / pgvector-BM25). Each chunk is indexed as a SearchDocument carrying
+// tenantId; every query filters by { tenantId } so the keyword leg has the
+// same tenant-isolation guarantee as the vector leg.
+//
+// @nebutra/search is imported lazily so the zero-config path (keyword
+// disabled, no search backend) never needs it at module load.
+// =============================================================================
+import { KnowledgeRagError } from "./errors";
+/**
+ * KeywordIndex backed by @nebutra/search. Construct via
+ * `SearchKeywordIndex.tryCreate(indexName)` which returns `null` when no
+ * search backend is configured (so the pipeline can degrade to vector-only).
+ */
+export class SearchKeywordIndex {
+    // biome-ignore lint/suspicious/noExplicitAny: external provider type imported lazily
+    provider;
+    indexName;
+    // biome-ignore lint/suspicious/noExplicitAny: external provider type imported lazily
+    constructor(provider, indexName) {
+        this.provider = provider;
+        this.indexName = indexName;
+    }
+    /**
+     * Returns a live keyword index, or `null` when no @nebutra/search backend
+     * is genuinely reachable. The default provider auto-detects to Meilisearch
+     * even with no env; it only fails on the first network call. So we probe
+     * with a real createIndex/search call and degrade to vector-only on any
+     * failure — the zero-config path must NEVER break because a search server
+     * happens to be absent.
+     */
+    static async tryCreate(indexName) {
+        try {
+            const mod = await import("@nebutra/search");
+            const search = await mod.getSearch();
+            try {
+                await search.createIndex(indexName, {
+                    primaryKey: "id",
+                    filterableAttributes: ["tenantId", "docId"],
+                    searchableAttributes: ["text"],
+                });
+            }
+            catch {
+                // createIndex may fail because the index already exists (fine) OR
+                // because the backend is unreachable (not fine). Disambiguate with a
+                // cheap reachability probe.
+                try {
+                    await search.search(indexName, { query: "", hitsPerPage: 1 });
+                }
+                catch {
+                    return null; // backend not reachable — degrade to vector-only
+                }
+            }
+            return new SearchKeywordIndex(search, indexName);
+        }
+        catch {
+            return null;
+        }
+    }
+    async index(chunks) {
+        if (chunks.length === 0)
+            return;
+        await this.provider.indexDocuments(this.indexName, chunks.map((c) => ({
+            id: c.id,
+            tenantId: c.tenantId,
+            docId: c.docId,
+            text: c.text,
+        })));
+    }
+    async search(tenantId, query, topK) {
+        try {
+            const result = await this.provider.search(this.indexName, {
+                query,
+                tenantId,
+                filters: { tenantId },
+                hitsPerPage: Math.min(100, Math.max(1, topK)),
+            });
+            return (result.hits ?? [])
+                .filter((h) => h.doc.tenantId === tenantId)
+                .map((h) => ({
+                chunkId: h.doc.id,
+                docId: h.doc.docId,
+                tenantId: h.doc.tenantId,
+                score: h.score,
+            }));
+        }
+        catch (err) {
+            throw new KnowledgeRagError(`Keyword search failed: ${err?.message ?? String(err)}`, {
+                code: "E_KEYWORD_SEARCH",
+                cause: err,
+                suggestion: "Check the @nebutra/search backend (MEILISEARCH_URL / TYPESENSE_URL / ALGOLIA_APP_ID), or set { disableKeyword: true } for vector-only retrieval.",
+            });
+        }
+    }
+    async deleteByDoc(docId, tenantId) {
+        await this.provider.deleteByFilter(this.indexName, { docId, tenantId });
+    }
+    async health() {
+        try {
+            await this.provider.search(this.indexName, { query: "", hitsPerPage: 1 });
+            return { ok: true, detail: `@nebutra/search: index "${this.indexName}" reachable` };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                detail: `@nebutra/search unreachable: ${err?.message ?? String(err)}`,
+            };
+        }
+    }
+}

package/dist/pipeline.d.ts

@@ -0,0 +1,4 @@
+import { type KnowledgeRag, type KnowledgeRagConfig } from "./types";
+/** Synchronous factory — fully usable with zero config. */
+export declare function createKnowledgeRag(config?: KnowledgeRagConfig): KnowledgeRag;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../src/pipeline.ts"],"names":[],"mappings":"AAoBA,OAAO,EAML,KAAK,YAAY,EACjB,KAAK,kBAAkB,EAIxB,MAAM,SAAS,CAAC;AAmOjB,2DAA2D;AAC3D,wBAAgB,kBAAkB,CAAC,MAAM,GAAE,kBAAuB,GAAG,YAAY,CAEhF"}

package/dist/pipeline.js

@@ -0,0 +1,224 @@
+// =============================================================================
+// @nebutra/knowledge-rag — Pipeline
+// =============================================================================
+// ingest:  validate → chunk → embed → vector upsert + keyword index
+// query:   validate → embed query → vector leg + keyword leg → hybrid blend
+//          → optional rerank → topK
+// delete:  scoped by (docId, tenantId) across both legs
+//
+// tenantId is required on every input and threaded into every store call.
+// Tenant isolation is enforced by the stores; the pipeline never widens scope.
+// =============================================================================
+import { RecursiveCharChunker } from "./chunker";
+import { LocalHashEmbedder } from "./embedder";
+import { KnowledgeRagError } from "./errors";
+import { SearchKeywordIndex } from "./keyword";
+import { IdentityReranker } from "./reranker";
+import { hybridBlend, normalizeScores } from "./scoring";
+import { InMemoryVectorStore } from "./stores/memory";
+import { IngestDocumentSchema, QueryInputSchema, } from "./types";
+const DEFAULT_INDEX = "knowledge_rag";
+const DEFAULT_VECTOR_WEIGHT = 0.6;
+const DEFAULT_TOP_K = 8;
+class KnowledgeRagPipeline {
+    chunker;
+    embedder;
+    store;
+    reranker;
+    indexName;
+    vectorWeight;
+    disableKeyword;
+    keyword = null;
+    keywordResolved = false;
+    constructor(config = {}) {
+        this.chunker = config.chunker ?? new RecursiveCharChunker({ size: 800, overlap: 100 });
+        this.embedder = config.embedder ?? new LocalHashEmbedder(256);
+        this.store = config.vectorStore ?? new InMemoryVectorStore();
+        this.reranker = config.reranker ?? new IdentityReranker();
+        this.indexName = config.index ?? DEFAULT_INDEX;
+        this.vectorWeight = config.vectorWeight ?? DEFAULT_VECTOR_WEIGHT;
+        this.disableKeyword = config.disableKeyword ?? false;
+    }
+    /** Lazily resolve the keyword leg; null when no search backend / disabled. */
+    async keywordIndex() {
+        if (this.disableKeyword)
+            return null;
+        if (this.keywordResolved)
+            return this.keyword;
+        this.keyword = await SearchKeywordIndex.tryCreate(this.indexName);
+        this.keywordResolved = true;
+        return this.keyword;
+    }
+    async ingest(doc) {
+        const parsed = IngestDocumentSchema.safeParse(doc);
+        if (!parsed.success) {
+            throw new KnowledgeRagError(`Invalid ingest document: ${parsed.error.issues.map((i) => i.path.join(".") + " " + i.message).join("; ")}`, {
+                code: "E_INGEST_INPUT",
+                suggestion: "ingest() requires { id, text, tenantId } all non-empty. tenantId is mandatory — every record is tenant-scoped.",
+            });
+        }
+        const { id, text, tenantId, meta = {} } = parsed.data;
+        const pieces = this.chunker.split(text);
+        if (pieces.length === 0) {
+            return { docId: id, tenantId, chunks: 0 };
+        }
+        const vectors = await this.embedder.embed(pieces);
+        const chunks = pieces.map((t, ordinal) => ({
+            id: `${id}::${ordinal}`,
+            docId: id,
+            tenantId,
+            text: t,
+            ordinal,
+            embedding: vectors[ordinal],
+            meta,
+        }));
+        await this.store.upsert(chunks);
+        const kw = await this.keywordIndex();
+        if (kw)
+            await kw.index(chunks);
+        return { docId: id, tenantId, chunks: chunks.length };
+    }
+    async query(input) {
+        const parsed = QueryInputSchema.safeParse(input);
+        if (!parsed.success) {
+            throw new KnowledgeRagError(`Invalid query input: ${parsed.error.issues.map((i) => i.path.join(".") + " " + i.message).join("; ")}`, {
+                code: "E_QUERY_INPUT",
+                suggestion: "query() requires { query, tenantId } non-empty; topK is 1..100.",
+            });
+        }
+        const { query, tenantId } = parsed.data;
+        const topK = parsed.data.topK ?? DEFAULT_TOP_K;
+        const fetchK = Math.max(topK * 4, topK);
+        const [queryVec] = await this.embedder.embed([query]);
+        const vectorHits = await this.store.queryByVector(tenantId, queryVec, fetchK);
+        const kw = await this.keywordIndex();
+        const keywordHits = kw ? await kw.search(tenantId, query, fetchK) : [];
+        // Merge candidate set keyed by chunkId. Defence in depth: drop anything
+        // whose tenantId doesn't match the requested tenant.
+        const byId = new Map();
+        for (const h of vectorHits) {
+            if (h.chunk.tenantId !== tenantId)
+                continue;
+            byId.set(h.chunk.id, { chunk: h.chunk, vec: h.score, kw: 0 });
+        }
+        for (const h of keywordHits) {
+            if (h.tenantId !== tenantId)
+                continue;
+            const existing = byId.get(h.chunkId);
+            if (existing)
+                existing.kw = h.score;
+            // Keyword-only hits with no embedding context are skipped: the vector
+            // store is the source of truth for chunk bodies in this pipeline.
+        }
+        const entries = [...byId.values()];
+        if (entries.length === 0)
+            return [];
+        const normVec = normalizeScores(entries.map((e) => e.vec));
+        const normKw = normalizeScores(entries.map((e) => e.kw));
+        const hasKeyword = keywordHits.length > 0;
+        const ranked = entries.map((e, i) => {
+            const v = normVec[i];
+            const k = normKw[i];
+            const blended = hasKeyword ? hybridBlend(v, k, this.vectorWeight) : v;
+            return {
+                chunk: e.chunk,
+                score: blended,
+                scores: { vector: v, keyword: k },
+                source: hasKeyword ? "hybrid" : "vector",
+            };
+        });
+        ranked.sort((a, b) => b.score - a.score);
+        const reranked = await this.reranker.rerank(query, ranked);
+        return reranked.slice(0, topK);
+    }
+    async deleteByDoc(docId, tenantId) {
+        if (!docId || !tenantId) {
+            throw new KnowledgeRagError("deleteByDoc requires docId and tenantId", {
+                code: "E_DELETE_INPUT",
+                suggestion: "Pass both docId and tenantId — deletion is always tenant-scoped.",
+            });
+        }
+        const removed = await this.store.deleteByDoc(docId, tenantId);
+        const kw = await this.keywordIndex();
+        if (kw) {
+            try {
+                await kw.deleteByDoc(docId, tenantId);
+            }
+            catch {
+                // Keyword cleanup is best-effort; vector store is authoritative.
+            }
+        }
+        return removed;
+    }
+    async doctor() {
+        const start = Date.now();
+        const components = [];
+        components.push({
+            name: `embedder:${this.embedder.name}`,
+            ok: true,
+            detail: this.embedder.name === "local-hash"
+                ? "zero-config deterministic local embedder (no network)"
+                : "provider embedder configured",
+        });
+        try {
+            const h = await withTimeout(this.store.health(), 1500);
+            components.push({ name: `vector-store:${this.store.name}`, ok: h.ok, detail: h.detail });
+        }
+        catch (err) {
+            components.push({
+                name: `vector-store:${this.store.name}`,
+                ok: false,
+                detail: `health timed out: ${err.message}`,
+            });
+        }
+        if (this.disableKeyword) {
+            components.push({
+                name: "keyword-index",
+                ok: true,
+                detail: "disabled by config (vector-only retrieval)",
+            });
+        }
+        else {
+            try {
+                const kw = await withTimeout(this.keywordIndex(), 1500);
+                if (kw) {
+                    const h = await withTimeout(kw.health(), 1000);
+                    components.push({ name: "keyword-index:@nebutra/search", ok: h.ok, detail: h.detail });
+                }
+                else {
+                    components.push({
+                        name: "keyword-index",
+                        ok: true,
+                        detail: "no @nebutra/search backend detected — degraded to vector-only",
+                    });
+                }
+            }
+            catch (err) {
+                components.push({
+                    name: "keyword-index",
+                    ok: false,
+                    detail: `probe failed: ${err.message}`,
+                });
+            }
+        }
+        return {
+            ok: components.every((c) => c.ok),
+            checkedAt: new Date().toISOString(),
+            durationMs: Date.now() - start,
+            components,
+        };
+    }
+}
+function withTimeout(p, ms) {
+    return Promise.race([
+        p,
+        new Promise((_, reject) => setTimeout(() => reject(new KnowledgeRagError(`timeout after ${ms}ms`, {
+            code: "E_HEALTH_TIMEOUT",
+            suggestion: "External dependency is slow/unreachable; check its URL/credentials.",
+        })), ms)),
+    ]);
+}
+/** Synchronous factory — fully usable with zero config. */
+export function createKnowledgeRag(config = {}) {
+    return new KnowledgeRagPipeline(config);
+}

package/dist/reranker.d.ts

@@ -0,0 +1,17 @@
+import type { RankedChunk, Reranker } from "./types";
+/** No-op reranker — keeps the hybrid-blended order. */
+export declare class IdentityReranker implements Reranker {
+    readonly name = "identity";
+    rerank(_query: string, candidates: RankedChunk[]): Promise<RankedChunk[]>;
+}
+/**
+ * Re-orders candidates by blending the hybrid score with lexical
+ * query-term coverage. Deterministic, no external calls.
+ */
+export declare class LexicalOverlapReranker implements Reranker {
+    readonly name = "lexical-overlap";
+    private readonly weight;
+    constructor(weight?: number);
+    rerank(query: string, candidates: RankedChunk[]): Promise<RankedChunk[]>;
+}
+//# sourceMappingURL=reranker.d.ts.map

package/dist/reranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.d.ts","sourceRoot":"","sources":["../src/reranker.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAErD,uDAAuD;AACvD,qBAAa,gBAAiB,YAAW,QAAQ;IAC/C,QAAQ,CAAC,IAAI,cAAc;IAErB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;CAGhF;AAED;;;GAGG;AACH,qBAAa,sBAAuB,YAAW,QAAQ;IACrD,QAAQ,CAAC,IAAI,qBAAqB;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,SAAM;IAKlB,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;CAmB/E"}

package/dist/reranker.js

@@ -0,0 +1,48 @@
+// =============================================================================
+// @nebutra/knowledge-rag — Rerankers
+// =============================================================================
+// The Reranker interface is the seam for a cross-encoder / LLM reranker. The
+// default IdentityReranker preserves blended order (zero-config, no network).
+// A LexicalOverlapReranker provides a lightweight, dependency-free boost based
+// on query/term overlap — useful before a real cross-encoder is wired in.
+// =============================================================================
+/** No-op reranker — keeps the hybrid-blended order. */
+export class IdentityReranker {
+    name = "identity";
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async rerank(_query, candidates) {
+        return candidates;
+    }
+}
+/**
+ * Re-orders candidates by blending the hybrid score with lexical
+ * query-term coverage. Deterministic, no external calls.
+ */
+export class LexicalOverlapReranker {
+    name = "lexical-overlap";
+    weight;
+    constructor(weight = 0.3) {
+        this.weight = Math.min(1, Math.max(0, weight));
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async rerank(query, candidates) {
+        const terms = new Set(query
+            .toLowerCase()
+            .split(/[^a-z0-9]+/)
+            .filter(Boolean));
+        if (terms.size === 0)
+            return candidates;
+        const rescored = candidates.map((c) => {
+            const text = c.chunk.text.toLowerCase();
+            let hit = 0;
+            for (const t of terms)
+                if (text.includes(t))
+                    hit++;
+            const coverage = hit / terms.size;
+            const blended = (1 - this.weight) * c.score + this.weight * coverage;
+            return { ...c, score: blended };
+        });
+        rescored.sort((a, b) => b.score - a.score);
+        return rescored;
+    }
+}

package/dist/scoring.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Cosine similarity in [-1, 1]. Returns 0 for a zero-magnitude vector
+ * (never NaN). Throws on dimension mismatch.
+ */
+export declare function cosineSimilarity(a: readonly number[], b: readonly number[]): number;
+/**
+ * Min-max normalise to [0, 1]. All-equal input → all 1 (avoids divide by
+ * zero and keeps every candidate eligible). Empty input → empty.
+ */
+export declare function normalizeScores(scores: readonly number[]): number[];
+/**
+ * Weighted hybrid blend. `vectorWeight` is clamped to [0, 1]; the keyword
+ * leg receives `1 - vectorWeight`.
+ */
+export declare function hybridBlend(vectorScore: number, keywordScore: number, vectorWeight: number): number;
+//# sourceMappingURL=scoring.d.ts.map

package/dist/scoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scoring.d.ts","sourceRoot":"","sources":["../src/scoring.ts"],"names":[],"mappings":"AASA;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,SAAS,MAAM,EAAE,EAAE,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAoBnF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAWnE;AAOD;;;GAGG;AACH,wBAAgB,WAAW,CACzB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,GACnB,MAAM,CAGR"}

package/dist/scoring.js

@@ -0,0 +1,64 @@
+// =============================================================================
+// @nebutra/knowledge-rag — Scoring math
+// =============================================================================
+// Pure functions: cosine similarity, min-max normalisation, weighted hybrid
+// blend of the vector and keyword retrieval legs.
+// =============================================================================
+import { KnowledgeRagError } from "./errors";
+/**
+ * Cosine similarity in [-1, 1]. Returns 0 for a zero-magnitude vector
+ * (never NaN). Throws on dimension mismatch.
+ */
+export function cosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new KnowledgeRagError(`Vector dimension mismatch: ${a.length} vs ${b.length}`, {
+            code: "E_DIM_MISMATCH",
+            suggestion: "Ensure all chunks were embedded with the same embedder/model as the query. Re-ingest after switching embedder.",
+        });
+    }
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        const x = a[i];
+        const y = b[i];
+        dot += x * y;
+        na += x * x;
+        nb += y * y;
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+/**
+ * Min-max normalise to [0, 1]. All-equal input → all 1 (avoids divide by
+ * zero and keeps every candidate eligible). Empty input → empty.
+ */
+export function normalizeScores(scores) {
+    if (scores.length === 0)
+        return [];
+    let min = Number.POSITIVE_INFINITY;
+    let max = Number.NEGATIVE_INFINITY;
+    for (const s of scores) {
+        if (s < min)
+            min = s;
+        if (s > max)
+            max = s;
+    }
+    const range = max - min;
+    if (range === 0)
+        return scores.map(() => 1);
+    return scores.map((s) => (s - min) / range);
+}
+/** Clamp a number into [lo, hi]. */
+function clamp(x, lo, hi) {
+    return Math.min(hi, Math.max(lo, x));
+}
+/**
+ * Weighted hybrid blend. `vectorWeight` is clamped to [0, 1]; the keyword
+ * leg receives `1 - vectorWeight`.
+ */
+export function hybridBlend(vectorScore, keywordScore, vectorWeight) {
+    const w = clamp(vectorWeight, 0, 1);
+    return w * vectorScore + (1 - w) * keywordScore;
+}

package/dist/stores/memory.d.ts

@@ -0,0 +1,16 @@
+import type { KnowledgeChunk, VectorStore } from "../types";
+export declare class InMemoryVectorStore implements VectorStore {
+    readonly name = "in-memory";
+    private readonly base;
+    upsert(chunks: KnowledgeChunk[]): Promise<void>;
+    queryByVector(tenantId: string, vector: readonly number[], topK: number): Promise<Array<{
+        chunk: KnowledgeChunk;
+        score: number;
+    }>>;
+    deleteByDoc(docId: string, tenantId: string): Promise<number>;
+    health(): Promise<{
+        ok: boolean;
+        detail: string;
+    }>;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/stores/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/stores/memory.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5D,qBAAa,mBAAoB,YAAW,WAAW;IACrD,QAAQ,CAAC,IAAI,eAAe;IAC5B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA6C;IAE5D,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAM/C,aAAa,CACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,KAAK,CAAC;QAAE,KAAK,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAUrD,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAY7D,MAAM,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAGzD"}

package/dist/stores/memory.js

@@ -0,0 +1,43 @@
+// =============================================================================
+// @nebutra/knowledge-rag — InMemory vector store (default, zero-config)
+// =============================================================================
+// Storage mechanics + tenant isolation are delegated to the neutral
+// `@nebutra/tenant-store` lower layer (composite-key partition, tenant-checked
+// reads/writes/deletes). This class only adds vector-specific behaviour
+// (similarity scan, delete-by-doc). queryByVector NEVER reads outside the
+// requested tenant — guaranteed structurally by InMemoryTenantStore.
+// =============================================================================
+import { InMemoryTenantStore } from "@nebutra/tenant-store";
+import { cosineSimilarity } from "../scoring";
+export class InMemoryVectorStore {
+    name = "in-memory";
+    base = new InMemoryTenantStore();
+    async upsert(chunks) {
+        for (const chunk of chunks) {
+            await this.base.write(chunk.tenantId, chunk.id, chunk);
+        }
+    }
+    async queryByVector(tenantId, vector, topK) {
+        const chunks = await this.base.listByTenant(tenantId);
+        const scored = chunks.map((chunk) => ({
+            chunk,
+            score: cosineSimilarity(vector, chunk.embedding),
+        }));
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, Math.max(0, topK));
+    }
+    async deleteByDoc(docId, tenantId) {
+        const chunks = await this.base.listByTenant(tenantId);
+        let removed = 0;
+        for (const chunk of chunks) {
+            if (chunk.docId === docId && (await this.base.delete(tenantId, chunk.id))) {
+                removed++;
+            }
+        }
+        return removed;
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async health() {
+        return { ok: true, detail: `in-memory: ${this.base.size()} chunk(s)` };
+    }
+}

package/dist/stores/pgvector.d.ts

@@ -0,0 +1,31 @@
+import type { KnowledgeChunk, VectorStore } from "../types";
+export interface PgvectorExecutor {
+    /** Tagged-template raw query, e.g. Prisma's `$queryRaw`. */
+    query<T = unknown>(sql: string, params: unknown[]): Promise<T[]>;
+}
+export interface PgvectorStoreOptions {
+    executor: PgvectorExecutor;
+    /** Table name. Default: "knowledge_rag_chunk". */
+    table?: string;
+    /** Embedding dimension the table column was created with. Default 1536. */
+    embeddingDim?: number;
+}
+export declare class PgvectorStore implements VectorStore {
+    readonly name = "pgvector";
+    private readonly exec;
+    private readonly table;
+    private readonly dim;
+    constructor(options: PgvectorStoreOptions);
+    private vecLiteral;
+    upsert(chunks: KnowledgeChunk[]): Promise<void>;
+    queryByVector(tenantId: string, vector: readonly number[], topK: number): Promise<Array<{
+        chunk: KnowledgeChunk;
+        score: number;
+    }>>;
+    deleteByDoc(docId: string, tenantId: string): Promise<number>;
+    health(): Promise<{
+        ok: boolean;
+        detail: string;
+    }>;
+}
+//# sourceMappingURL=pgvector.d.ts.map

package/dist/stores/pgvector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pgvector.d.ts","sourceRoot":"","sources":["../../src/stores/pgvector.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;CAClE;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,aAAc,YAAW,WAAW;IAC/C,QAAQ,CAAC,IAAI,cAAc;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,OAAO,EAAE,oBAAoB;IAazC,OAAO,CAAC,UAAU;IAUZ,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB/C,aAAa,CACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,KAAK,CAAC;QAAE,KAAK,EAAE,cAAc,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAiCrD,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAW7D,MAAM,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAWzD"}