@nebutra/knowledge-rag 0.2.0

package/README.md

@@ -0,0 +1,151 @@
+# @nebutra/knowledge-rag
+
+Multi-tenant **hybrid RAG** pipeline for Nebutra-Sailor.
+
+```
+ingest → semantic chunk → embed → vector store + keyword index
+       → hybrid retrieval (vector ⊕ keyword) → optional rerank
+```
+
+Every persisted record carries a **`tenantId`**. Tenant isolation is enforced
+at every store/query boundary — it is never optional. A query scoped to tenant
+A can never return tenant B's chunks.
+
+## Status
+
+`active` — exported tool factory (`createKnowledgeRagTool`) is the real caller
+(used by `@nebutra/agent-runtime` / `@nebutra/agents`). Zero-config by default.
+
+## Zero-config quick start
+
+No env vars, no external services. In-memory vector store + a deterministic
+local hash embedder (real signal — shared tokens raise cosine similarity, not
+mocked). The keyword leg auto-activates **only** if a reachable
+`@nebutra/search` backend is detected; otherwise it gracefully degrades to
+vector-only.
+
+```ts
+import { getKnowledgeRag } from "@nebutra/knowledge-rag";
+
+const kb = await getKnowledgeRag();
+
+await kb.ingest({ id: "doc1", tenantId: "org_a", text: "...", meta: { src: "wiki" } });
+
+const hits = await kb.query({ query: "how does X work?", tenantId: "org_a", topK: 5 });
+// → RankedChunk[]: { chunk, score, scores: { vector, keyword }, source }
+
+await kb.deleteByDoc("doc1", "org_a"); // tenant-scoped delete
+```
+
+## Public API
+
+| Function / method | Purpose |
+|---|---|
+| `getKnowledgeRag(config?)` | Process-wide instance (or fresh when config given). |
+| `createKnowledgeRag(config?)` | Construct an isolated instance. |
+| `kb.ingest({ id, text, tenantId, meta? })` | Chunk → embed → index. |
+| `kb.query({ query, tenantId, topK? })` | Hybrid retrieval → ranked chunks. |
+| `kb.deleteByDoc(docId, tenantId)` | Tenant-scoped removal across both legs. |
+| `kb.doctor()` / `doctor(config?)` | Structured health report, **< 3s**. |
+| `createKnowledgeRagTool(tenantId, config?)` | Tenant-bound agent tool. |
+
+All thrown errors are `KnowledgeRagError` and carry an actionable
+`.suggestion` (and `.code`); `.toJSON()` serialises both for logging.
+
+### Pluggable internals
+
+- **Chunker** — `RecursiveCharChunker({ size, overlap, separators? })`
+  (paragraph → line → sentence → word → char), configurable size/overlap.
+- **Embedder** — `LocalHashEmbedder` (default, zero-config, no network) or
+  `ProviderEmbedder` (wraps `@nebutra/agents` `embedMany()` → Vercel AI SDK
+  with the `LLM_EMBEDDING_FALLBACK_CHAIN`).
+- **VectorStore** — `InMemoryVectorStore` (default) or `PgvectorStore`
+  (interface-only, see below).
+- **Reranker** — `IdentityReranker` (default) or `LexicalOverlapReranker`.
+
+## How it wraps existing Sailor infra (no reinvention)
+
+- **Keyword leg → `@nebutra/search`.** `SearchKeywordIndex` wraps the existing
+  provider-agnostic search abstraction (`getSearch()` →
+  Meilisearch / Typesense / Algolia / pgvector-BM25). Each chunk is indexed as
+  a `SearchDocument` carrying `tenantId`; every keyword query passes
+  `filters: { tenantId }` and results are re-filtered by tenant, so the keyword
+  leg has the same isolation guarantee as the vector leg. `@nebutra/search` is
+  imported lazily and a probe call decides reachability — an absent search
+  server can never break the zero-config path.
+- **Embeddings → `@nebutra/agents`.** `ProviderEmbedder` lazily imports and
+  calls `embedMany()` (the SDK's provider/fallback chain). Vector provider
+  calls are reused, never reimplemented. With no AI env, the default
+  `LocalHashEmbedder` keeps everything running with real (non-mock) results.
+
+## pgvector store (production) — Prisma model + DDL
+
+`PgvectorStore` is interface-only here (not exercised by unit tests, no
+migrations run). To activate, apply the schema below and pass an executor.
+
+```prisma
+// Add to your Prisma schema. Requires the pgvector extension:
+//   model: see below; SQL: CREATE EXTENSION IF NOT EXISTS vector;
+
+/// One persisted RAG chunk. EVERY row is tenant-scoped.
+model KnowledgeRagChunk {
+  id        String   @id                       // `${docId}::${ordinal}`
+  docId     String   @map("doc_id")
+  tenantId  String   @map("tenant_id")          // REQUIRED — isolation key
+  text      String
+  ordinal   Int
+  /// Vector column — set the dimension to your embedder's output.
+  /// Prisma has no native vector type; declare via Unsupported + raw SQL.
+  embedding Unsupported("vector(1536)")
+  meta      Json     @default("{}")
+  createdAt DateTime @default(now()) @map("created_at")
+
+  @@index([tenantId])                            // tenant-prefix filtering
+  @@index([docId, tenantId])                     // scoped delete
+  @@map("knowledge_rag_chunk")
+}
+```
+
+Companion raw migration (run manually — this package does **not** migrate):
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+
+-- After `prisma migrate` creates knowledge_rag_chunk, add the ANN index.
+-- Cosine distance (<=>) matches the store's similarity = 1 - distance.
+CREATE INDEX IF NOT EXISTS knowledge_rag_chunk_embedding_idx
+  ON knowledge_rag_chunk
+  USING hnsw (embedding vector_cosine_ops);
+```
+
+```ts
+import { PgvectorStore } from "@nebutra/knowledge-rag";
+
+const store = new PgvectorStore({
+  executor: { query: (sql, params) => prisma.$queryRawUnsafe(sql, ...params) },
+  embeddingDim: 1536,
+});
+const kb = await getKnowledgeRag({ vectorStore: store });
+```
+
+Every `PgvectorStore` query includes a mandatory `WHERE tenant_id = $1`
+predicate; deletes are scoped `WHERE doc_id = $1 AND tenant_id = $2`.
+
+## Examples
+
+Runnable under `examples/` (`node --import tsx examples/<file>.ts`):
+
+1. `01-zero-config.ts` — ingest → query, no config.
+2. `02-tenant-isolation.ts` — identical text, zero cross-tenant leakage.
+3. `03-custom-pipeline-and-doctor.ts` — custom chunker/reranker + `doctor()`.
+4. `04-agent-tool.ts` — tenant-bound agent tool (the real caller).
+
+## Testing
+
+```bash
+pnpm --filter @nebutra/knowledge-rag test            # vitest
+pnpm --filter @nebutra/knowledge-rag exec vitest run --coverage
+```
+
+TDD-first; ≥80% coverage on core logic (chunker boundaries/overlap, hybrid
+scoring math, tenant isolation, ingest→query roundtrip).

package/dist/chunker.d.ts

@@ -0,0 +1,21 @@
+import type { Chunker } from "./types";
+export interface RecursiveCharChunkerOptions {
+    /** Maximum chunk length in characters. */
+    size: number;
+    /** Characters of overlap carried from the end of one chunk to the next. */
+    overlap: number;
+    /** Separators tried in order, coarsest first. */
+    separators?: string[];
+}
+export declare class RecursiveCharChunker implements Chunker {
+    private readonly size;
+    private readonly overlap;
+    private readonly separators;
+    constructor(options: RecursiveCharChunkerOptions);
+    split(text: string): string[];
+    /** Break text into atomic pieces each <= size, preferring coarse separators. */
+    private recursiveSplit;
+    /** Pack atomic pieces into <= size windows, carrying `overlap` chars over. */
+    private mergeWithOverlap;
+}
+//# sourceMappingURL=chunker.d.ts.map

package/dist/chunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.d.ts","sourceRoot":"","sources":["../src/chunker.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,MAAM,WAAW,2BAA2B;IAC1C,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAID,qBAAa,oBAAqB,YAAW,OAAO;IAClD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAW;gBAE1B,OAAO,EAAE,2BAA2B;IAsBhD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;IAW7B,gFAAgF;IAChF,OAAO,CAAC,cAAc;IA8BtB,8EAA8E;IAC9E,OAAO,CAAC,gBAAgB;CA2BzB"}

package/dist/chunker.js

@@ -0,0 +1,103 @@
+// =============================================================================
+// @nebutra/knowledge-rag — Recursive character chunker
+// =============================================================================
+// Splits text by trying progressively finer separators (paragraph → line →
+// sentence → word → char), packing into windows of <= `size` with `overlap`
+// carried between consecutive chunks. Pure and deterministic.
+// =============================================================================
+import { KnowledgeRagError } from "./errors";
+const DEFAULT_SEPARATORS = ["\n\n", "\n", ". ", " ", ""];
+export class RecursiveCharChunker {
+    size;
+    overlap;
+    separators;
+    constructor(options) {
+        const { size, overlap } = options;
+        if (!Number.isFinite(size) || size <= 0) {
+            throw new KnowledgeRagError(`Invalid chunker size: ${size}`, {
+                code: "E_CHUNKER_CONFIG",
+                suggestion: "Pass a positive integer `size` (e.g. { size: 800, overlap: 100 }).",
+            });
+        }
+        if (overlap < 0 || overlap >= size) {
+            throw new KnowledgeRagError(`Invalid chunker overlap: ${overlap} (must be >= 0 and < size ${size})`, {
+                code: "E_CHUNKER_CONFIG",
+                suggestion: `Set overlap to a value in [0, ${size - 1}] — typically ~10-15% of size.`,
+            });
+        }
+        this.size = size;
+        this.overlap = overlap;
+        this.separators = options.separators ?? DEFAULT_SEPARATORS;
+    }
+    split(text) {
+        if (text.trim().length === 0) {
+            return [];
+        }
+        const pieces = this.recursiveSplit(text, 0);
+        // Pieces are each <= size. If any single piece exceeds the effective
+        // step (size - overlap) we still pack greedily; the overlap is applied as
+        // a prefix carried into the *next* chunk.
+        return this.mergeWithOverlap(pieces);
+    }
+    /** Break text into atomic pieces each <= size, preferring coarse separators. */
+    recursiveSplit(text, sepIndex) {
+        if (text.length <= this.size) {
+            return text.length > 0 ? [text] : [];
+        }
+        const sep = this.separators[sepIndex] ?? "";
+        if (sep === "") {
+            // Hard character split as a last resort. Window the step at
+            // (size - overlap) so an overlap prefix can always be prepended later
+            // without exceeding `size`.
+            const step = Math.max(1, this.size - this.overlap);
+            const out = [];
+            for (let i = 0; i < text.length; i += step) {
+                out.push(text.slice(i, i + step));
+            }
+            return out;
+        }
+        const parts = text.split(sep);
+        const out = [];
+        for (let i = 0; i < parts.length; i++) {
+            const withSep = i < parts.length - 1 ? parts[i] + sep : parts[i];
+            if (withSep.length === 0)
+                continue;
+            if (withSep.length <= this.size) {
+                out.push(withSep);
+            }
+            else {
+                out.push(...this.recursiveSplit(withSep, sepIndex + 1));
+            }
+        }
+        return out;
+    }
+    /** Pack atomic pieces into <= size windows, carrying `overlap` chars over. */
+    mergeWithOverlap(pieces) {
+        const chunks = [];
+        let current = "";
+        for (const piece of pieces) {
+            if (current.length + piece.length <= this.size) {
+                current += piece;
+                continue;
+            }
+            if (current.length > 0) {
+                chunks.push(current);
+                current = this.overlap > 0 ? current.slice(-this.overlap) : "";
+            }
+            if (piece.length <= this.size) {
+                current += piece;
+            }
+            else {
+                // Oversized atomic piece — emit fixed windows directly.
+                for (let i = 0; i < piece.length; i += this.size) {
+                    chunks.push(piece.slice(i, i + this.size));
+                }
+                current = "";
+            }
+        }
+        if (current.trim().length > 0) {
+            chunks.push(current);
+        }
+        return chunks;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+/**
+ * knowledge-rag CLI — `doctor` (dependency health) and `debug <query>`
+ * (run the real zero-config pipeline and print the ranked breakdown).
+ * Mirrors the Sailor capability-CLI convention (see trace-store/src/cli.ts).
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

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

package/dist/cli.js

@@ -0,0 +1,26 @@
+/**
+ * knowledge-rag CLI — `doctor` (dependency health) and `debug <query>`
+ * (run the real zero-config pipeline and print the ranked breakdown).
+ * Mirrors the Sailor capability-CLI convention (see trace-store/src/cli.ts).
+ */
+import { doctor, getKnowledgeRag } from "./index";
+const command = process.argv[2] ?? "doctor";
+if (command === "doctor") {
+    process.stdout.write(`${JSON.stringify({ capability: "knowledge-rag", ...(await doctor()) }, null, 2)}\n`);
+}
+else if (command === "debug") {
+    const query = process.argv[3] ?? "what is the canvas capability";
+    const tenantId = "debug-tenant";
+    const kb = await getKnowledgeRag();
+    await kb.ingest({
+        id: "debug-doc",
+        tenantId,
+        text: "The canvas capability adds an interactive node-graph editor over the reel model, a multi-tenant hybrid RAG pipeline, and a CRDT collaboration layer.",
+    });
+    const hits = await kb.query({ query, tenantId, topK: 3 });
+    process.stdout.write(`${JSON.stringify({ capability: "knowledge-rag", query, hits }, null, 2)}\n`);
+}
+else {
+    process.stderr.write(`Unknown knowledge-rag command: ${command}\n`);
+    process.exitCode = 1;
+}

package/dist/embedder.d.ts

@@ -0,0 +1,20 @@
+import type { Embedder } from "./types";
+export declare class LocalHashEmbedder implements Embedder {
+    readonly name = "local-hash";
+    private readonly dim;
+    constructor(dim?: number);
+    embed(texts: string[]): Promise<number[][]>;
+    private embedOne;
+}
+/**
+ * Wraps the Sailor provider abstraction (`@nebutra/agents` → Vercel AI SDK
+ * `embedMany`, with the LLM_EMBEDDING_FALLBACK_CHAIN). Imported lazily so the
+ * zero-config path never requires the AI SDK at module load.
+ */
+export declare class ProviderEmbedder implements Embedder {
+    readonly name = "nebutra-agents";
+    private readonly model;
+    constructor(model?: string);
+    embed(texts: string[]): Promise<number[][]>;
+}
+//# sourceMappingURL=embedder.d.ts.map

package/dist/embedder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedder.d.ts","sourceRoot":"","sources":["../src/embedder.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAmBxC,qBAAa,iBAAkB,YAAW,QAAQ;IAChD,QAAQ,CAAC,IAAI,gBAAgB;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAEjB,GAAG,SAAM;IAWf,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAIjD,OAAO,CAAC,QAAQ;CA0BjB;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,QAAQ;IAC/C,QAAQ,CAAC,IAAI,oBAAoB;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;gBAE/B,KAAK,CAAC,EAAE,MAAM;IAIpB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;CA0BlD"}

package/dist/embedder.js

@@ -0,0 +1,106 @@
+// =============================================================================
+// @nebutra/knowledge-rag — Embedders
+// =============================================================================
+// - LocalHashEmbedder: deterministic, zero-config, NO network. Hashed
+//   bag-of-words (+ char bigrams) into a fixed-dim space, L2-normalised.
+//   Real (non-mock) signal: shared tokens raise cosine similarity, so
+//   semantically-overlapping texts genuinely cluster.
+// - ProviderEmbedder: wraps @nebutra/agents `embedMany()` (Vercel AI SDK
+//   fallback chain) when real embeddings are configured.
+// =============================================================================
+import { KnowledgeRagError } from "./errors";
+/** FNV-1a 32-bit hash — fast, deterministic, well-distributed. */
+function fnv1a(input) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < input.length; i++) {
+        h ^= input.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 0);
+}
+export class LocalHashEmbedder {
+    name = "local-hash";
+    dim;
+    constructor(dim = 256) {
+        if (!Number.isInteger(dim) || dim <= 0) {
+            throw new KnowledgeRagError(`Invalid embedding dimension: ${dim}`, {
+                code: "E_EMBED_DIM",
+                suggestion: "Pass a positive integer dimension, e.g. new LocalHashEmbedder(256).",
+            });
+        }
+        this.dim = dim;
+    }
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async embed(texts) {
+        return texts.map((t) => this.embedOne(t));
+    }
+    embedOne(text) {
+        const vec = new Array(this.dim).fill(0);
+        const tokens = tokenize(text);
+        for (const tok of tokens) {
+            // Signed feature hashing reduces collision bias.
+            const h = fnv1a(tok);
+            const idx = h % this.dim;
+            const sign = (h & 1) === 0 ? 1 : -1;
+            vec[idx] += sign;
+            // Character bigrams add sub-word locality (typo / morphology robustness).
+            for (let i = 0; i < tok.length - 1; i++) {
+                const bg = fnv1a(`#${tok.slice(i, i + 2)}`);
+                vec[bg % this.dim] += (bg & 1) === 0 ? 0.5 : -0.5;
+            }
+        }
+        let norm = 0;
+        for (const v of vec)
+            norm += v * v;
+        norm = Math.sqrt(norm);
+        if (norm === 0) {
+            // Empty / symbol-only text — deterministic unit vector on axis 0.
+            vec[0] = 1;
+            return vec;
+        }
+        for (let i = 0; i < vec.length; i++)
+            vec[i] /= norm;
+        return vec;
+    }
+}
+/**
+ * Wraps the Sailor provider abstraction (`@nebutra/agents` → Vercel AI SDK
+ * `embedMany`, with the LLM_EMBEDDING_FALLBACK_CHAIN). Imported lazily so the
+ * zero-config path never requires the AI SDK at module load.
+ */
+export class ProviderEmbedder {
+    name = "nebutra-agents";
+    model;
+    constructor(model) {
+        this.model = model;
+    }
+    async embed(texts) {
+        try {
+            const { embedMany } = await import("@nebutra/agents");
+            const result = await embedMany(texts, this.model ? { model: this.model } : {});
+            const embeddings = result.embeddings;
+            if (!Array.isArray(embeddings) || embeddings.length !== texts.length) {
+                throw new KnowledgeRagError("Provider returned an unexpected embedding shape", {
+                    code: "E_EMBED_SHAPE",
+                    suggestion: "Verify the embedding model in @nebutra/agents config; or omit a custom embedder to fall back to LocalHashEmbedder.",
+                });
+            }
+            return embeddings;
+        }
+        catch (err) {
+            if (err instanceof KnowledgeRagError)
+                throw err;
+            throw new KnowledgeRagError(`Provider embedding failed: ${err?.message ?? String(err)}`, {
+                code: "E_EMBED_PROVIDER",
+                cause: err,
+                suggestion: "Set OPENAI_API_KEY (or OPENROUTER_API_KEY) for @nebutra/agents, or use the zero-config LocalHashEmbedder (default).",
+            });
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+export interface KnowledgeRagErrorOptions {
+    /** Actionable "how to fix" hint. Defaults to a generic message if omitted. */
+    suggestion?: string;
+    /** Stable machine-readable code (e.g. "E_TENANT_MISSING"). */
+    code?: string;
+    /** Underlying cause, preserved for logging. */
+    cause?: unknown;
+}
+/**
+ * The single error class for this package. Always has a non-empty
+ * `.suggestion`; serialises cleanly for structured logging.
+ */
+export declare class KnowledgeRagError extends Error {
+    readonly suggestion: string;
+    readonly code: string;
+    constructor(message: string, options?: KnowledgeRagErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,wBAAwB;IACvC,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAKD;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,wBAA6B;IAWnE,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAQlC"}

package/dist/errors.js

@@ -0,0 +1,33 @@
+// =============================================================================
+// @nebutra/knowledge-rag — Error type
+// =============================================================================
+// Every thrown error MUST carry an actionable `.suggestion` so callers always
+// know how to fix it (DX acceptance criterion).
+// =============================================================================
+const DEFAULT_SUGGESTION = "Check the @nebutra/knowledge-rag README, or run getKnowledgeRag().doctor() for a structured health report.";
+/**
+ * The single error class for this package. Always has a non-empty
+ * `.suggestion`; serialises cleanly for structured logging.
+ */
+export class KnowledgeRagError extends Error {
+    suggestion;
+    code;
+    constructor(message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "KnowledgeRagError";
+        this.suggestion =
+            options.suggestion && options.suggestion.trim().length > 0
+                ? options.suggestion
+                : DEFAULT_SUGGESTION;
+        this.code = options.code ?? "E_KNOWLEDGE_RAG";
+        Object.setPrototypeOf(this, KnowledgeRagError.prototype);
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            suggestion: this.suggestion,
+            code: this.code,
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import type { DoctorReport, KnowledgeRag, KnowledgeRagConfig } from "./types";
+/**
+ * Returns a process-wide KnowledgeRag instance. Pass a config to override any
+ * pluggable internal; the first non-empty config wins for the singleton.
+ * Construct a fresh isolated instance with `createKnowledgeRag()` instead.
+ */
+export declare function getKnowledgeRag(config?: KnowledgeRagConfig): Promise<KnowledgeRag>;
+/** Standalone health probe (also available as instance method). <3s. */
+export declare function doctor(config?: KnowledgeRagConfig): Promise<DoctorReport>;
+/** Reset the singleton (tests / re-config). */
+export declare function resetKnowledgeRag(): void;
+export { RecursiveCharChunker } from "./chunker";
+export { LocalHashEmbedder, ProviderEmbedder } from "./embedder";
+export { KnowledgeRagError } from "./errors";
+export { SearchKeywordIndex } from "./keyword";
+export { createKnowledgeRag } from "./pipeline";
+export { IdentityReranker, LexicalOverlapReranker } from "./reranker";
+export { cosineSimilarity, hybridBlend, normalizeScores } from "./scoring";
+export { InMemoryVectorStore } from "./stores/memory";
+export { PgvectorStore } from "./stores/pgvector";
+export { createKnowledgeRagTool } from "./tool";
+export type { Chunker, DoctorReport, Embedder, IngestDocument, IngestResult, KnowledgeChunk, KnowledgeRag, KnowledgeRagConfig, QueryInput, RankedChunk, Reranker, VectorStore, } from "./types";
+export { IngestDocumentSchema, QueryInputSchema } from "./types";
+//# 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":"AAmBA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAI9E;;;;GAIG;AAEH,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAIxF;AAED,wEAAwE;AACxE,wBAAsB,MAAM,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAG/E;AAED,+CAA+C;AAC/C,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AACjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,EAAE,sBAAsB,EAAE,MAAM,QAAQ,CAAC;AAGhD,YAAY,EACV,OAAO,EACP,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,UAAU,EACV,WAAW,EACX,QAAQ,EACR,WAAW,GACZ,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,54 @@
+// =============================================================================
+// @nebutra/knowledge-rag — Public API
+// =============================================================================
+// Multi-tenant hybrid RAG: ingest → semantic chunk → embed → vector + keyword
+// index → hybrid retrieval → optional rerank.
+//
+// Zero-config:
+//
+//   import { getKnowledgeRag } from "@nebutra/knowledge-rag";
+//   const kb = await getKnowledgeRag();
+//   await kb.ingest({ id: "d1", tenantId: "org_a", text: "..." });
+//   const hits = await kb.query({ query: "...", tenantId: "org_a" });
+//
+// Defaults: in-memory vector store + deterministic local embedder, keyword
+// leg auto-enabled only if a @nebutra/search backend is detected. NO env
+// required. Every persisted record carries a tenantId.
+// =============================================================================
+import { createKnowledgeRag } from "./pipeline";
+let singleton = null;
+/**
+ * Returns a process-wide KnowledgeRag instance. Pass a config to override any
+ * pluggable internal; the first non-empty config wins for the singleton.
+ * Construct a fresh isolated instance with `createKnowledgeRag()` instead.
+ */
+// eslint-disable-next-line @typescript-eslint/require-await
+export async function getKnowledgeRag(config) {
+    if (config)
+        return createKnowledgeRag(config);
+    if (!singleton)
+        singleton = createKnowledgeRag();
+    return singleton;
+}
+/** Standalone health probe (also available as instance method). <3s. */
+export async function doctor(config) {
+    const kb = await getKnowledgeRag(config);
+    return kb.doctor();
+}
+/** Reset the singleton (tests / re-config). */
+export function resetKnowledgeRag() {
+    singleton = null;
+}
+export { RecursiveCharChunker } from "./chunker";
+export { LocalHashEmbedder, ProviderEmbedder } from "./embedder";
+export { KnowledgeRagError } from "./errors";
+export { SearchKeywordIndex } from "./keyword";
+// ── Building blocks (advanced / custom wiring) ───────────────────────────────
+export { createKnowledgeRag } from "./pipeline";
+export { IdentityReranker, LexicalOverlapReranker } from "./reranker";
+export { cosineSimilarity, hybridBlend, normalizeScores } from "./scoring";
+export { InMemoryVectorStore } from "./stores/memory";
+export { PgvectorStore } from "./stores/pgvector";
+// ── Tool factory (for @nebutra/agent-runtime / agents) ───────────────────────
+export { createKnowledgeRagTool } from "./tool";
+export { IngestDocumentSchema, QueryInputSchema } from "./types";

package/dist/keyword.d.ts

@@ -0,0 +1,43 @@
+import type { KnowledgeChunk } from "./types";
+export interface KeywordHit {
+    chunkId: string;
+    docId: string;
+    tenantId: string;
+    score: number;
+}
+export interface KeywordIndex {
+    index(chunks: KnowledgeChunk[]): Promise<void>;
+    search(tenantId: string, query: string, topK: number): Promise<KeywordHit[]>;
+    deleteByDoc(docId: string, tenantId: string): Promise<void>;
+    health(): Promise<{
+        ok: boolean;
+        detail: string;
+    }>;
+}
+/**
+ * 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 declare class SearchKeywordIndex implements KeywordIndex {
+    private readonly provider;
+    private readonly indexName;
+    private constructor();
+    /**
+     * 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 tryCreate(indexName: string): Promise<SearchKeywordIndex | null>;
+    index(chunks: KnowledgeChunk[]): Promise<void>;
+    search(tenantId: string, query: string, topK: number): Promise<KeywordHit[]>;
+    deleteByDoc(docId: string, tenantId: string): Promise<void>;
+    health(): Promise<{
+        ok: boolean;
+        detail: string;
+    }>;
+}
+//# sourceMappingURL=keyword.d.ts.map

package/dist/keyword.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyword.d.ts","sourceRoot":"","sources":["../src/keyword.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IAC7E,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5D,MAAM,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,YAAW,YAAY;IAErD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAM;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAGnC,OAAO;IAKP;;;;;;;OAOG;WACU,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IA0BvE,KAAK,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAa9C,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IA6B5E,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D,MAAM,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAWzD"}