@nebutra/knowledge-rag 0.2.0

package/dist/stores/pgvector.js

@@ -0,0 +1,97 @@
+// =============================================================================
+// @nebutra/knowledge-rag — pgvector store (interface-only, opt-in)
+// =============================================================================
+// This is the production store shape. It is NOT exercised by unit tests and
+// does NOT run migrations. The Prisma model + DDL live in the package README.
+//
+// Every query is parameterised by tenantId and MUST include a
+// `WHERE tenant_id = $tenantId` predicate — cross-tenant leakage via pgvector
+// is a security defect, identical to the in-memory contract.
+//
+// To activate: supply a Prisma client (or pg pool) that exposes a
+// `$queryRaw`-style executor and apply the README migration.
+// =============================================================================
+import { KnowledgeRagError } from "../errors";
+export class PgvectorStore {
+    name = "pgvector";
+    exec;
+    table;
+    dim;
+    constructor(options) {
+        if (!options?.executor) {
+            throw new KnowledgeRagError("PgvectorStore requires an `executor`", {
+                code: "E_PGVECTOR_CONFIG",
+                suggestion: "Pass a Prisma client wrapper exposing query(sql, params). See the pgvector section of the @nebutra/knowledge-rag README, or use InMemoryVectorStore for zero-config.",
+            });
+        }
+        this.exec = options.executor;
+        this.table = options.table ?? "knowledge_rag_chunk";
+        this.dim = options.embeddingDim ?? 1536;
+    }
+    vecLiteral(v) {
+        if (v.length !== this.dim) {
+            throw new KnowledgeRagError(`Embedding dim ${v.length} != table dim ${this.dim}`, {
+                code: "E_PGVECTOR_DIM",
+                suggestion: `Recreate the table with vector(${v.length}) or use an embedder producing ${this.dim}-d vectors.`,
+            });
+        }
+        return `[${v.join(",")}]`;
+    }
+    async upsert(chunks) {
+        for (const c of chunks) {
+            await this.exec.query(`INSERT INTO ${this.table}
+           (id, doc_id, tenant_id, text, ordinal, embedding, meta)
+         VALUES ($1,$2,$3,$4,$5,$6::vector,$7)
+         ON CONFLICT (id) DO UPDATE SET
+           text=EXCLUDED.text, embedding=EXCLUDED.embedding, meta=EXCLUDED.meta`, [
+                c.id,
+                c.docId,
+                c.tenantId,
+                c.text,
+                c.ordinal,
+                this.vecLiteral(c.embedding),
+                JSON.stringify(c.meta),
+            ]);
+        }
+    }
+    async queryByVector(tenantId, vector, topK) {
+        // tenant_id predicate is mandatory and first — never query without it.
+        const rows = await this.exec.query(`SELECT id, doc_id, tenant_id, text, ordinal, meta,
+              (embedding <=> $2::vector) AS distance
+         FROM ${this.table}
+        WHERE tenant_id = $1
+        ORDER BY embedding <=> $2::vector
+        LIMIT $3`, [tenantId, this.vecLiteral(vector), Math.max(0, topK)]);
+        return rows.map((r) => ({
+            score: 1 - r.distance, // cosine distance → similarity
+            chunk: {
+                id: r.id,
+                docId: r.doc_id,
+                tenantId: r.tenant_id,
+                text: r.text,
+                ordinal: r.ordinal,
+                embedding: [],
+                meta: (typeof r.meta === "string" ? JSON.parse(r.meta) : r.meta) ?? {},
+            },
+        }));
+    }
+    async deleteByDoc(docId, tenantId) {
+        const rows = await this.exec.query(`WITH d AS (
+         DELETE FROM ${this.table}
+          WHERE doc_id = $1 AND tenant_id = $2 RETURNING 1
+       ) SELECT COUNT(*)::int AS count FROM d`, [docId, tenantId]);
+        return rows[0]?.count ?? 0;
+    }
+    async health() {
+        try {
+            await this.exec.query("SELECT 1", []);
+            return { ok: true, detail: `pgvector: table ${this.table} reachable` };
+        }
+        catch (err) {
+            return {
+                ok: false,
+                detail: `pgvector unreachable: ${err?.message ?? String(err)}`,
+            };
+        }
+    }
+}

package/dist/tool.d.ts

@@ -0,0 +1,30 @@
+import type { KnowledgeRagConfig, RankedChunk } from "./types";
+export interface KnowledgeRagToolResult {
+    query: string;
+    results: Array<{
+        docId: string;
+        chunkId: string;
+        text: string;
+        score: number;
+        scores: RankedChunk["scores"];
+        source: RankedChunk["source"];
+        meta: Record<string, unknown>;
+    }>;
+}
+export interface KnowledgeRagTool {
+    name: "knowledge_search";
+    description: string;
+    /** Execute a tenant-scoped retrieval. tenantId is bound, not an argument. */
+    execute(args: {
+        query: string;
+        topK?: number;
+    }): Promise<KnowledgeRagToolResult>;
+}
+/**
+ * Build a knowledge-search tool bound to a single tenant.
+ *
+ * @param tenantId — resolved from the agent's tenant context
+ *                    (e.g. getCurrentTenant().tenantId from @nebutra/tenant).
+ */
+export declare function createKnowledgeRagTool(tenantId: string, config?: KnowledgeRagConfig): KnowledgeRagTool;
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE/D,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,KAAK,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC9B,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,CAAC;QAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,kBAAkB,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,OAAO,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CAClF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,kBAAkB,GAC1B,gBAAgB,CAgClB"}

package/dist/tool.js

@@ -0,0 +1,48 @@
+// =============================================================================
+// @nebutra/knowledge-rag — Agent tool factory
+// =============================================================================
+// Exposes the RAG pipeline as a tenant-scoped retrieval tool that
+// @nebutra/agent-runtime / @nebutra/agents can register. This is the "real
+// caller" that keeps the package at lifecycle tier `active`.
+//
+// The tenantId is bound at factory time (from the agent's tenant context) and
+// is NEVER taken from model-generated arguments — preventing a tool-call from
+// crossing tenant boundaries.
+// =============================================================================
+import { getKnowledgeRag } from "./index";
+/**
+ * Build a knowledge-search tool bound to a single tenant.
+ *
+ * @param tenantId — resolved from the agent's tenant context
+ *                    (e.g. getCurrentTenant().tenantId from @nebutra/tenant).
+ */
+export function createKnowledgeRagTool(tenantId, config) {
+    if (!tenantId) {
+        // Fail fast — a tool without a tenant binding is a security hole.
+        throw new Error("createKnowledgeRagTool requires a tenantId. Resolve it from getCurrentTenant() (@nebutra/tenant) before constructing the tool.");
+    }
+    return {
+        name: "knowledge_search",
+        description: "Search the tenant's knowledge base for passages relevant to a query. Returns ranked chunks with hybrid (vector + keyword) scores and source document IDs.",
+        async execute(args) {
+            const kb = await getKnowledgeRag(config);
+            const ranked = await kb.query({
+                query: args.query,
+                tenantId,
+                topK: args.topK ?? 5,
+            });
+            return {
+                query: args.query,
+                results: ranked.map((r) => ({
+                    docId: r.chunk.docId,
+                    chunkId: r.chunk.id,
+                    text: r.chunk.text,
+                    score: r.score,
+                    scores: r.scores,
+                    source: r.source,
+                    meta: r.chunk.meta,
+                })),
+            };
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+import { z } from "zod";
+export declare const IngestDocumentSchema: z.ZodObject<{
+    id: z.ZodString;
+    text: z.ZodString;
+    tenantId: z.ZodString;
+    meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type IngestDocument = z.infer<typeof IngestDocumentSchema>;
+/** A persisted chunk. `tenantId` is non-nullable by construction. */
+export interface KnowledgeChunk {
+    /** Stable chunk ID: `${docId}::${ordinal}`. */
+    readonly id: string;
+    readonly docId: string;
+    readonly tenantId: string;
+    readonly text: string;
+    /** 0-based position of the chunk within its source document. */
+    readonly ordinal: number;
+    readonly embedding: readonly number[];
+    readonly meta: Readonly<Record<string, unknown>>;
+}
+/** A scored retrieval result. */
+export interface RankedChunk {
+    readonly chunk: KnowledgeChunk;
+    /** Final blended score (0..1, higher is better). */
+    readonly score: number;
+    /** Per-leg scores for explainability. */
+    readonly scores: {
+        readonly vector: number;
+        readonly keyword: number;
+    };
+    /** Which legs contributed. */
+    readonly source: "hybrid" | "vector" | "keyword";
+}
+export declare const QueryInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    tenantId: z.ZodString;
+    topK: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type QueryInput = z.infer<typeof QueryInputSchema>;
+export interface Chunker {
+    /** Split text into chunk strings. Pure, deterministic. */
+    split(text: string): string[];
+}
+export interface Embedder {
+    readonly name: string;
+    /** Embed a batch of strings into fixed-length vectors. */
+    embed(texts: string[]): Promise<number[][]>;
+}
+export interface VectorStore {
+    readonly name: string;
+    upsert(chunks: KnowledgeChunk[]): Promise<void>;
+    /** MUST filter by tenantId — cross-tenant leakage is a security defect. */
+    queryByVector(tenantId: string, vector: readonly number[], topK: number): Promise<Array<{
+        chunk: KnowledgeChunk;
+        score: number;
+    }>>;
+    deleteByDoc(docId: string, tenantId: string): Promise<number>;
+    /** Health probe for doctor(). */
+    health(): Promise<{
+        ok: boolean;
+        detail: string;
+    }>;
+}
+export interface Reranker {
+    readonly name: string;
+    rerank(query: string, candidates: RankedChunk[]): Promise<RankedChunk[]>;
+}
+export interface KnowledgeRagConfig {
+    chunker?: Chunker;
+    embedder?: Embedder;
+    vectorStore?: VectorStore;
+    reranker?: Reranker;
+    /** Logical index/namespace for the keyword leg. Default: "knowledge_rag". */
+    index?: string;
+    /** Vector-leg weight in the hybrid blend (0..1). Default 0.6. */
+    vectorWeight?: number;
+    /** Disable the keyword leg even if @nebutra/search is configured. */
+    disableKeyword?: boolean;
+}
+export interface IngestResult {
+    readonly docId: string;
+    readonly tenantId: string;
+    readonly chunks: number;
+}
+export interface DoctorReport {
+    readonly ok: boolean;
+    readonly checkedAt: string;
+    readonly durationMs: number;
+    readonly components: Array<{
+        readonly name: string;
+        readonly ok: boolean;
+        readonly detail: string;
+    }>;
+}
+export interface KnowledgeRag {
+    ingest(doc: IngestDocument): Promise<IngestResult>;
+    query(input: QueryInput): Promise<RankedChunk[]>;
+    deleteByDoc(docId: string, tenantId: string): Promise<number>;
+    doctor(): Promise<DoctorReport>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,27 @@
+// =============================================================================
+// @nebutra/knowledge-rag — Public types
+// =============================================================================
+// Multi-tenant hybrid RAG: ingestion → chunk → embed → vector + keyword index
+// → hybrid retrieval → optional rerank.
+//
+// Every persisted record carries a tenantId. Tenant isolation is enforced at
+// every store/query boundary — never optional.
+// =============================================================================
+import { z } from "zod";
+// ── Documents & chunks ───────────────────────────────────────────────────────
+export const IngestDocumentSchema = z.object({
+    /** Globally unique document ID (caller-supplied). */
+    id: z.string().min(1),
+    /** Raw document text. */
+    text: z.string().min(1),
+    /** Tenant/workspace ID — REQUIRED. Every record is scoped to this. */
+    tenantId: z.string().min(1),
+    /** Arbitrary metadata propagated to every chunk and returned at query time. */
+    meta: z.record(z.string(), z.unknown()).optional(),
+});
+// ── Query ────────────────────────────────────────────────────────────────────
+export const QueryInputSchema = z.object({
+    query: z.string().min(1),
+    tenantId: z.string().min(1),
+    topK: z.number().int().min(1).max(100).optional(),
+});

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@nebutra/knowledge-rag",
+  "version": "0.2.0",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "nebutra": {
+    "status": "active",
+    "productionReady": false,
+    "requires": [
+      "(none) — zero-config: in-memory vector store + deterministic local embedder",
+      "optional: OPENAI_API_KEY or OPENROUTER_API_KEY (real embeddings via @nebutra/agents)",
+      "optional: MEILISEARCH_URL / TYPESENSE_URL / ALGOLIA_APP_ID (keyword leg via @nebutra/search)",
+      "optional: DATABASE_URL (pgvector store)"
+    ],
+    "gaps": [
+      "pgvector store is interface-only (Prisma snippet in README, not migrated)",
+      "reranker interface ships with identity impl only"
+    ]
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "zod": "^4.3.6",
+    "@nebutra/agents": "1.1.0",
+    "@nebutra/errors": "0.1.0",
+    "@nebutra/logger": "0.1.0",
+    "@nebutra/search": "0.1.0",
+    "@nebutra/tenant-store": "0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4",
+    "@vitest/coverage-v8": "^4.1.4"
+  },
+  "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/ai/knowledge-rag#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebutra/Nebutra-Sailor.git",
+    "directory": "packages/ai/knowledge-rag"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}