@devilsdev/rag-pipeline-utils 2.4.5 → 2.5.0

package/README.md

@@ -1,14 +1,48 @@
-# rag-pipeline-utils
-
-**Composable RAG for Node.js — with built-in evaluation, citations, guardrails, and observability.**
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/DevilsDev/rag-pipeline-utils@main/assets/banner.svg" alt="rag-pipeline-utils: composable RAG for Node.js with grounded citations, evaluation, guardrails and a working CLI" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@devilsdev/rag-pipeline-utils"><img src="https://img.shields.io/npm/v/@devilsdev/rag-pipeline-utils.svg" alt="npm version"></a>
+  <a href="https://github.com/DevilsDev/rag-pipeline-utils/actions/workflows/ci.yml"><img src="https://github.com/DevilsDev/rag-pipeline-utils/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@devilsdev/rag-pipeline-utils"><img src="https://img.shields.io/npm/dm/@devilsdev/rag-pipeline-utils.svg" alt="Downloads"></a>
+  <a href="https://www.npmjs.com/package/@devilsdev/rag-pipeline-utils"><img src="https://img.shields.io/npm/types/@devilsdev/rag-pipeline-utils.svg" alt="TypeScript types"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/@devilsdev/rag-pipeline-utils.svg" alt="Node.js version"></a>
+  <a href="https://github.com/DevilsDev/rag-pipeline-utils/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#use-cases">Use cases</a> ·
+  <a href="#how-it-compares">How it compares</a> ·
+  <a href="https://devilsdev.github.io/rag-pipeline-utils/">Documentation</a> ·
+  <a href="https://github.com/DevilsDev/rag-pipeline-utils/tree/main/examples">Examples</a>
+</p>
 
-[![npm version](https://img.shields.io/npm/v/@devilsdev/rag-pipeline-utils.svg)](https://www.npmjs.com/package/@devilsdev/rag-pipeline-utils)
-[![Downloads](https://img.shields.io/npm/dm/@devilsdev/rag-pipeline-utils.svg)](https://www.npmjs.com/package/@devilsdev/rag-pipeline-utils)
-[![Types](https://img.shields.io/npm/types/@devilsdev/rag-pipeline-utils.svg)](https://www.npmjs.com/package/@devilsdev/rag-pipeline-utils)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node.js](https://img.shields.io/node/v/@devilsdev/rag-pipeline-utils.svg)](https://nodejs.org/)
+# rag-pipeline-utils
 
-Start small with three core primitives — **pipeline**, **plugin**, **connector** — and opt in to evaluation, citations, guardrails, agentic reasoning, and GraphRAG as you need them.
+`rag-pipeline-utils` gives you the building blocks of a RAG system as small, replaceable parts: an embedder, a retriever, an optional reranker and an LLM, wired together by one `createRagPipeline()` call. Evaluation, per-sentence citations, guardrails and agentic retrieval are opt-in layers on top. Every part follows a plain JavaScript contract, so you can swap a built-in connector for your own code without touching the rest.
+
+- **Grounded by default.** Answers come back with the passages they were built from, sentence-level citations and a groundedness score, including a check that numbers in the answer appear in the sources.
+- **Provider-neutral.** OpenAI, Anthropic, Cohere and Ollama connectors are built in, plus an offline TF-IDF embedder. Anything with an `embed()` or `generate()` method works too.
+- **Production behaviour.** AbortSignal cancellation and timeouts, retries only on transient errors, ACL filtering before generation, PII redaction, typed exports for ESM, CommonJS and TypeScript.
+- **A CLI that does real work.** `init`, `ingest`, `query` and `serve` run against a persistent local index, fully offline if you want.
+
+## Contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Command line](#command-line)
+- [Use cases](#use-cases)
+- [How it works](#how-it-works)
+- [Capabilities](#capabilities)
+- [How it compares](#how-it-compares)
+- [Connectors and plugins](#connectors-and-plugins)
+- [Experimental modules](#experimental-modules)
+- [Compatibility](#compatibility)
+- [Documentation](#documentation)
+- [Security](#security)
+- [Contributing](#contributing)
 
 ## Installation
 
@@ -16,169 +50,436 @@ Start small with three core primitives — **pipeline**, **plugin**, **connector
 npm install @devilsdev/rag-pipeline-utils
 ```
 
-## Quick Start
+Requires Node.js 18 or later. The package ships CommonJS, ESM and TypeScript declarations.
 
-```javascript
+## Quick start
+
+This example runs offline: it uses the built-in TF-IDF embedder and an in-memory vector store.
+
+```js
+import {
+  createRagPipeline,
+  LocalEmbedder,
+  MemoryRetriever,
+} from "@devilsdev/rag-pipeline-utils";
+
+const docs = [
+  {
+    id: "vacation",
+    content:
+      "Full-time employees receive twenty days of paid vacation per year.",
+  },
+  {
+    id: "remote",
+    content: "Remote work is allowed two days per week with manager approval.",
+  },
+];
+
+// 1. Fit the embedder to your corpus and index the documents.
+const embedder = new LocalEmbedder();
+embedder.train(docs.map((doc) => doc.content));
+
+const retriever = new MemoryRetriever();
+await retriever.store(
+  docs.map((doc) => ({ ...doc, vector: embedder.embed(doc.content) })),
+);
+
+// 2. Build the pipeline and ask a question.
+const pipeline = createRagPipeline({ embedder, retriever });
+const result = await pipeline.run({
+  query: "How many vacation days do I get?",
+});
+
+console.log(result.results[0].id); // "vacation"
+console.log(result.answer); // null: no LLM configured, so retrieval only
+```
+
+To generate answers, add an LLM. The same connector can also embed:
+
+```js
 import {
   createRagPipeline,
   OpenAIConnector,
   MemoryRetriever,
 } from "@devilsdev/rag-pipeline-utils";
 
+const openai = new OpenAIConnector({ apiKey: process.env.OPENAI_API_KEY });
+
+const retriever = new MemoryRetriever();
+const policy =
+  "Full-time employees receive twenty days of paid vacation per year.";
+await retriever.store([
+  { id: "vacation", content: policy, vector: await openai.embed(policy) },
+]);
+
 const pipeline = createRagPipeline({
-  retriever: new MemoryRetriever(),
-  llm: new OpenAIConnector({ apiKey: process.env.OPENAI_API_KEY }),
+  embedder: openai,
+  retriever,
+  llm: openai,
 });
-
 const result = await pipeline.run({
-  query: "What is the vacation policy?",
+  query: "How many vacation days do I get?",
   options: { citations: true, evaluate: true },
 });
 
-console.log(result.results); // retrieved documents
-console.log(result.citations.groundednessScore); // 0.85
-console.log(result.evaluation.scores); // { faithfulness, relevance, ... }
+console.log(result.answer);
+console.log(result.citations.groundednessScore); // 0..1, share of grounded sentences
+console.log(result.evaluation.scores); // { faithfulness, relevance, contextPrecision, groundedness }
+```
+
+## Command line
+
+The `rag-pipeline` CLI builds a local index from your files and answers questions against it.
+
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/DevilsDev/rag-pipeline-utils@main/assets/demo.gif" alt="Terminal recording: rag-pipeline init, ingest ./docs, then a query that returns the vacation policy as the top passage" width="720">
+</p>
+
+```bash
+npx rag-pipeline init                      # writes .ragrc.json (interactive in a terminal)
+npx rag-pipeline ingest ./docs             # indexes .md, .html, .csv and .txt files
+npx rag-pipeline query "What is the remote work policy?"
+npx rag-pipeline serve --port 3000         # local HTTP API: GET /health, POST /query
+npx rag-pipeline doctor                    # checks config, API keys, plugins and the index
 ```
 
-**Requirements:** Node.js ≥ 18 · ESM or CommonJS
+The default `local` template needs no API keys. Use `init --template openai`, `anthropic` or `ollama` to generate answers with a model. Other commands include `validate`, `hub install` for plugins and `ai benchmark` for measured latency. See the [CLI reference](https://devilsdev.github.io/rag-pipeline-utils/docs/CLI).
 
-## Who This Is For
+## Use cases
 
-Teams building **production Node.js RAG services** who need:
+### Answer questions with sources your users can check
 
-- **Grounded outputs** they can trace back to sources
-- **Modular architecture** that doesn't lock them into a single provider
-- **Operational discipline** — tracing, metrics, cost controls, guardrails
-- **A stable foundation** with clear plugin contracts that outlast any vendor
+Citations map every sentence of the answer to the passages that support it. A sentence whose facts or numbers are missing from the sources is reported as ungrounded.
 
-If you're looking for a framework you can grow into — start with retrieval, add evaluation when it matters, add guardrails when you ship to production — this is built for you.
+```js
+import { CitationTracker } from "@devilsdev/rag-pipeline-utils";
 
-## Use Cases
+const sources = [
+  {
+    id: "policy",
+    content: "Employees receive twenty days of paid vacation per year.",
+  },
+];
+const tracker = new CitationTracker();
 
-### Document Q&A with citations
+const good = tracker.track(
+  "Employees receive twenty days of paid vacation per year.",
+  sources,
+);
+const wrong = tracker.track(
+  "Employees receive thirty days of paid vacation per year.",
+  sources,
+);
 
-```javascript
-const result = await pipeline.run({
-  query: "Which policy covers remote work?",
-  options: { citations: true },
+console.log(good.groundednessScore); // 1
+console.log(wrong.groundednessScore); // 0: the number does not match the source
+```
+
+### Measure answer quality in CI
+
+`PipelineEvaluator` scores faithfulness, relevance, context precision and, when you supply a reference answer, context recall. Run it over a fixed question set and fail the build when scores drop.
+
+```js
+import { PipelineEvaluator } from "@devilsdev/rag-pipeline-utils";
+
+const evaluator = new PipelineEvaluator();
+const report = evaluator.evaluate(
+  {
+    query: "How many vacation days do employees get?",
+    answer: "Employees receive twenty days of paid vacation per year.",
+    results: [
+      { content: "Employees receive twenty days of paid vacation per year." },
+    ],
+  },
+  { referenceAnswer: "Twenty days of paid vacation per year." },
+);
+
+console.log(report.scores); // includes contextRecall because a reference was given
+if (report.scores.faithfulness < 0.8) process.exitCode = 1;
+```
+
+### Protect an internal assistant
+
+`GuardrailsPipeline` wraps any pipeline. Access control runs before the LLM sees a document, prompt-injection detection runs on the query, and PII is redacted from the answer, its citations and its evaluation details.
+
+```js
+import {
+  createRagPipeline,
+  GuardrailsPipeline,
+  OpenAIConnector,
+} from "@devilsdev/rag-pipeline-utils";
+
+const openai = new OpenAIConnector({ apiKey: process.env.OPENAI_API_KEY });
+const retriever = {
+  // Any object with retrieve() works; requiredRole drives access control.
+  async retrieve() {
+    return [
+      {
+        id: "handbook",
+        content: "The handbook covers vacation.",
+        metadata: {},
+      },
+      {
+        id: "salaries",
+        content: "Executive salaries ...",
+        metadata: { requiredRole: "exec" },
+      },
+    ];
+  },
+};
+
+const assistant = new GuardrailsPipeline(
+  createRagPipeline({ retriever, llm: openai }),
+  {
+    preRetrieval: { enableInjectionDetection: true },
+    retrieval: { enforceACL: true },
+    postGeneration: { enablePIIDetection: true },
+    strict: true, // block instead of warn
+  },
+);
+
+const result = await assistant.run({
+  query: "What does the handbook cover?",
+  context: { userPermissions: ["employee"] }, // "salaries" never reaches the LLM
 });
-// result.citations maps each answer sentence to its source documents
+console.log(result.guardrails.retrieval.removed); // [{ id: "salaries" }]
 ```
 
-### Internal knowledge assistant with evaluation
+### Combine keyword and vector search
 
-```javascript
-const result = await pipeline.run({
-  query: userQuestion,
-  options: { evaluate: true },
+`HybridRetriever` merges any retrievers with Reciprocal Rank Fusion. BM25 finds exact terms such as product codes; vectors find paraphrases.
+
+```js
+import {
+  BM25Search,
+  HybridRetriever,
+  LocalEmbedder,
+  MemoryRetriever,
+} from "@devilsdev/rag-pipeline-utils";
+
+const docs = [
+  {
+    id: "err-4012",
+    content: "Error E4012 means the API token expired. Generate a new token.",
+  },
+  {
+    id: "billing",
+    content: "Invoices are emailed on the first business day of each month.",
+  },
+];
+
+const bm25 = new BM25Search();
+bm25.index(docs);
+
+const embedder = new LocalEmbedder();
+embedder.train(docs.map((doc) => doc.content));
+const vectors = new MemoryRetriever();
+await vectors.store(
+  docs.map((doc) => ({ ...doc, vector: embedder.embed(doc.content) })),
+);
+
+const hybrid = new HybridRetriever([
+  { retriever: bm25, weight: 1, name: "bm25" },
+  { retriever: vectors, weight: 1, name: "vectors" },
+]);
+const results = await hybrid.retrieve({
+  query: "what does E4012 mean",
+  queryVector: embedder.embed("what does E4012 mean"),
+  topK: 2,
 });
-// result.evaluation.scores = { faithfulness, relevance, contextPrecision, ... }
-// Alert when faithfulness drops below threshold in production
+console.log(results[0].id); // "err-4012"
 ```
 
-### Enterprise service with guardrails
+### Answer multi-part questions
+
+`AgenticPipeline` splits compound questions into sub-queries, retrieves for each, and self-checks the answer against the sources before returning it.
+
+```js
+import {
+  AgenticPipeline,
+  MemoryRetriever,
+  OpenAIConnector,
+} from "@devilsdev/rag-pipeline-utils";
+
+const openai = new OpenAIConnector({ apiKey: process.env.OPENAI_API_KEY });
+const retriever = new MemoryRetriever();
+const policies = [
+  "Full-time employees receive twenty days of paid vacation per year.",
+  "Remote work is allowed two days per week with manager approval.",
+];
+await retriever.store(
+  await Promise.all(
+    policies.map(async (content, i) => ({
+      id: `p${i}`,
+      content,
+      vector: await openai.embed(content),
+    })),
+  ),
+);
+
+const agent = new AgenticPipeline();
+const result = await agent.run({
+  query: "How much vacation do I get, and can I work from home?",
+  retriever,
+  llm: openai,
+  embedder: openai, // each sub-query gets its own embedding
+});
+console.log(result.subQueries.map((q) => q.subQuery));
+console.log(result.answer);
+```
+
+### Keep request latency bounded
+
+Every run accepts a timeout and an `AbortSignal`. The signal is passed to the embedder, retriever, reranker and LLM, so cancelled work stops instead of running in the background.
+
+```js
+import {
+  createRagPipeline,
+  OpenAIConnector,
+  MemoryRetriever,
+} from "@devilsdev/rag-pipeline-utils";
 
-```javascript
-import { GuardrailsPipeline, createRagPipeline } from "@devilsdev/rag-pipeline-utils";
+const openai = new OpenAIConnector({ apiKey: process.env.OPENAI_API_KEY });
+const pipeline = createRagPipeline({
+  embedder: openai,
+  retriever: new MemoryRetriever(),
+  llm: openai,
+});
 
-const safePipeline = new GuardrailsPipeline(createRagPipeline({ ... }), {
-  preRetrieval:  { enableInjectionDetection: true },
-  retrieval:     { minRelevanceScore: 0.6 },
-  postGeneration:{ enablePIIDetection: true, enableGroundednessCheck: true },
+const controller = new AbortController(); // e.g. aborted when the HTTP client disconnects
+const result = await pipeline.run({
+  query: "Summarise the travel policy",
+  options: { timeout: 10_000, signal: controller.signal },
 });
+if (!result.success) console.error(result.error); // "Execution timeout" or "Execution aborted"
 ```
 
-## Architecture
+### Run fully local
 
+Pair the `LocalEmbedder` or Ollama embeddings with an Ollama model and `FileVectorStore` for a private, offline setup. The CLI's `local` and `ollama` templates set this up for you:
+
+```bash
+npx rag-pipeline init --no-interactive --template ollama
+npx rag-pipeline ingest ./docs
+npx rag-pipeline serve
 ```
-Ingestion:  Documents → Chunking → Embedder → Vector Store
 
-Query:      User Query
-              ↓
-            Guardrails      → prompt injection, topic filtering
-              ↓
-            Query Planner   → decomposes complex queries
-              ↓
-            Hybrid Retriever → vector + BM25 with Reciprocal Rank Fusion
-              ↓
-            Reranker        → BM25 / embedding / cascade
-              ↓
-            LLM             → generates answer from context
-              ↓
-            Citation Tracker → maps sentences to sources
-              ↓
-            Evaluator       → scores faithfulness & groundedness
-              ↓
-            Response { answer, citations, evaluation }
+## How it works
+
+```
+             ┌──────────────── GuardrailsPipeline (optional) ─────────────────┐
+query ──▶    │ injection check ─▶ embed ─▶ retrieve ─▶ ACL / relevance filter │
+             │   ─▶ rerank ─▶ LLM ─▶ citations ─▶ evaluation ─▶ PII redaction │ ──▶ result
+             └────────────────────────────────────────────────────────────────┘
 ```
 
-Each stage is optional, pluggable, and observable.
+`createRagPipeline()` runs embed → retrieve → rerank → generate, then citations and evaluation when requested. Each stage receives the run's `AbortSignal`, and a timeout or abort stops the remaining stages. `GuardrailsPipeline`, `AgenticPipeline` and `HybridRetriever` compose around or inside it; they are not hidden steps of the default pipeline.
 
-## Capabilities
+The result of `run()` is:
 
-Opt in only to what you need:
+```ts
+{
+  success: boolean;
+  query: string;
+  results: Array<{ id; content; score; metadata }>;
+  answer: string | null;            // null when no LLM is configured
+  citations?: { citations; groundednessScore; hallucinationReport };
+  evaluation?: { scores; details; metadata };
+  error?: string;                   // set when success is false
+}
+```
 
-| Capability     | What you get                                                             |
-| -------------- | ------------------------------------------------------------------------ |
-| **Chunking**   | 5 strategies: sentence, fixed-size, recursive, semantic, structure-aware |
-| **Retrieval**  | Hybrid vector + BM25 with Reciprocal Rank Fusion                         |
-| **Reranking**  | LLM, BM25 scoring, embedding similarity, or cascade                      |
-| **Evaluation** | Faithfulness, relevance, context precision/recall, groundedness          |
-| **Citation**   | Per-sentence source attribution, hallucination detection                 |
-| **Agentic**    | Query planning, iterative retrieval, self-critique                       |
-| **Guardrails** | Injection detection, PII filtering, ACL-aware access control             |
-| **GraphRAG**   | Knowledge graph construction with entity extraction                      |
-| **Streaming**  | SSE and WebSocket adapters with backpressure control                     |
-| **Cost**       | Token tracking, budget enforcement, provider pricing                     |
-| **Debugging**  | Execution tracing, bottleneck detection                                  |
-| **MCP**        | Expose pipelines as Model Context Protocol tools                         |
-| **Enterprise** | Multi-tenancy, SSO (SAML/OAuth2/AD/OIDC), audit logs                     |
+## Capabilities
 
-See [full documentation](https://devilsdev.github.io/rag-pipeline-utils/) for complete API reference.
+| Area           | What you get                                                                                               |
+| -------------- | ---------------------------------------------------------------------------------------------------------- |
+| **Chunking**   | `ChunkingEngine` with sentence, fixed-size, recursive, semantic and structure-aware strategies             |
+| **Retrieval**  | `MemoryRetriever`, persistent `FileVectorStore`, `BM25Search`, `HybridRetriever` (Reciprocal Rank Fusion)  |
+| **Reranking**  | `ScoringReranker`, `EmbeddingReranker` (cached), `CascadeReranker`                                         |
+| **Citations**  | Per-sentence source mapping, hallucination report, numeric-consistency check                               |
+| **Evaluation** | Faithfulness, relevance, context precision, context recall (with a reference), groundedness, BLEU/ROUGE    |
+| **Guardrails** | Injection detection with input normalisation, ACL and relevance filtering before generation, PII redaction |
+| **Agentic**    | `QueryPlanner`, `IterativeRetriever`, `SelfCritiqueChecker`, `AgenticPipeline`                             |
+| **GraphRAG**   | `KnowledgeGraph`, `EntityExtractor`, `GraphRetriever`                                                      |
+| **Streaming**  | Token streaming with a final chunk carrying citations and evaluation; `SSEAdapter`, `WebSocketAdapter`     |
+| **Cost**       | `CostTracker`, `TokenBudget`, `CostCalculator` with sourced, overridable pricing                           |
+| **Operations** | `DevServer` HTTP API, `ExecutionTracer`, `AuditLogger`, MCP tool server (`MCPServer`)                      |
+
+## How it compares
+
+A short summary of the [comparison page](https://devilsdev.github.io/rag-pipeline-utils/docs/Comparison) (competitor details as of April 2026). The other libraries are broader frameworks; this one is narrower on purpose.
+
+|                  | rag-pipeline-utils                                      | LangChain.js                          | LlamaIndex.TS                        |
+| ---------------- | ------------------------------------------------------- | ------------------------------------- | ------------------------------------ |
+| Focus            | RAG pipelines for Node.js services                      | General-purpose LLM orchestration     | Indexing-first RAG                   |
+| Evaluation       | Built in: faithfulness, relevance, context P/R          | Via LangSmith (separate, paid option) | Some metrics, evolving               |
+| Citations        | Built in: per-sentence, with groundedness score         | Possible, wired up by hand            | Possible, wired up by hand           |
+| Guardrails       | Built in: pre-retrieval, retrieval, post-generation     | Via integrations (Guardrails AI etc.) | Via integrations                     |
+| Vector stores    | Memory and file-backed, plus a plugin contract          | 50+ integrations                      | Many integrations and native indexes |
+| LLM providers    | OpenAI, Anthropic, Cohere, Ollama, plus plugins         | Largest ecosystem                     | Large ecosystem                      |
+| Agents and tools | Query planning and iterative retrieval                  | Mature agent framework                | Agent framework                      |
+| Packaging        | One package, dual ESM and CommonJS                      | Many packages, mostly ESM             | One package, mostly ESM              |
+| Stability        | Documented [SEMVER policy](SEMVER.md) with deprecations | Versioned per package                 | Versioned                            |
+
+Choose LangChain.js for the widest integration catalogue or work that goes well beyond RAG, and LlamaIndex.TS for rich index types and structured data sources. Choose this library when evaluation, citations and guardrails are requirements and you want a small surface to review.
+3
+
+## Connectors and plugins
+
+| Connector            | Embeddings | Generation | Notes                                      |
+| -------------------- | :--------: | :--------: | ------------------------------------------ |
+| `OpenAIConnector`    |     ✓      |     ✓      | `OPENAI_API_KEY`                           |
+| `AnthropicConnector` |            |     ✓      | `ANTHROPIC_API_KEY`                        |
+| `CohereConnector`    |     ✓      |            | Embeddings and reranking, `COHERE_API_KEY` |
+| `OllamaConnector`    |     ✓      |     ✓      | Local models, no key                       |
+| `LocalEmbedder`      |     ✓      |            | Offline TF-IDF, fitted to your corpus      |
+
+Connectors read API keys when they are created, retry only transient failures (network errors, 429, 5xx) with backoff, and send retrieved documents to the model as clearly delimited, untrusted reference data rather than as instructions.
+
+A plugin is any object with the method its stage needs: `embed()`, `retrieve()`/`store()`, `generate()`, `rerank()` or `load()`. Reference your own modules from `.ragrc.json`, or install packaged plugins with checksum verification and a static security scan:
 
-## Provider Connectors
+```bash
+npx rag-pipeline hub install ./my-llm-plugin        # also .tgz files, npm:<package> or a registry
+npx rag-pipeline hub certify check ./my-llm-plugin   # scores contract, security, tests and docs
+```
 
-Built-in connectors for popular providers — or implement the contract for your own:
+## Experimental modules
 
-```javascript
-import {
-  OpenAIConnector, // GPT-4, text-embedding-3
-  AnthropicConnector, // Claude 3 Opus, Sonnet, Haiku
-  CohereConnector, // Embed + Rerank
-  OllamaConnector, // Llama 3, Mistral (local, offline)
-  LocalEmbedder, // TF-IDF (offline, no API)
-  MemoryRetriever, // In-memory cosine similarity
-} from "@devilsdev/rag-pipeline-utils";
+Simulated or incomplete modules live under a separate entry point and are not covered by the stability guarantees in [SEMVER.md](SEMVER.md): model training, federated learning, multimodal processing, adaptive retrieval, SSO providers, multi-tenancy, data governance, the plugin sandbox and the plugin certification class.
+
+```js
+import { TenantManager } from "@devilsdev/rag-pipeline-utils/experimental";
 ```
 
-## Documentation
+They are still exported from the main entry in 2.5 with a one-time deprecation warning, and will be removed from it in 3.0. Do not use them for authentication, tenant isolation or compliance. The [Experimental modules](https://devilsdev.github.io/rag-pipeline-utils/docs/Experimental) page describes what each one really does.
 
-- **[Documentation site](https://devilsdev.github.io/rag-pipeline-utils/)** — guides, API reference, deployment
-- **[Architecture](https://devilsdev.github.io/rag-pipeline-utils/docs/Architecture)** — plugin contracts, pipeline internals
-- **[API reference](https://devilsdev.github.io/rag-pipeline-utils/docs/API-Reference)** — complete export index
-- **[Examples](https://devilsdev.github.io/rag-pipeline-utils/docs/Examples)** — chatbot, Q&A, code search, support
-- **[Comparison vs LangChain.js / LlamaIndex.TS](https://devilsdev.github.io/rag-pipeline-utils/docs/Comparison)** — honest decision framework
-- **[Runnable demo](examples/fastify-rag-demo)** — Fastify + OpenAI + guardrails, deployable in one command
-- **[Benchmarks & methodology](BENCHMARKS.md)** — how we measure, how you reproduce
-- **[Security policy](SECURITY.md)** — responsible disclosure, supported versions
-- **[Security capability matrix](https://devilsdev.github.io/rag-pipeline-utils/docs/Security-Capabilities)** — what's battle-tested vs. recommended vs. example
-- **[API stability policy (SEMVER.md)](SEMVER.md)** — what counts as breaking, deprecation windows
-- **[Changelog](CHANGELOG.md)** — release history
+## Compatibility
 
-## Roadmap
+|                |                                                                           |
+| -------------- | ------------------------------------------------------------------------- |
+| Node.js        | 18, 20, 22 (Node 18 support ends with 3.0)                                |
+| Module formats | CommonJS (`require`) and ESM (`import`)                                   |
+| TypeScript     | Declarations for every export, including `/experimental`                  |
+| Versioning     | Semantic versioning with a deprecation window, see [SEMVER.md](SEMVER.md) |
+| Supply chain   | Published from GitHub Actions with npm provenance                         |
+
+## Documentation
 
-**Current (v2.4):** chunking, citation, evaluation, agentic RAG, hybrid retrieval, 3-layer guardrails, GraphRAG, streaming, cost management, MCP integration, 7 provider connectors.
+- [Documentation site](https://devilsdev.github.io/rag-pipeline-utils/): guides, API reference and deployment
+- [CLI reference](https://devilsdev.github.io/rag-pipeline-utils/docs/CLI)
+- [API reference](https://devilsdev.github.io/rag-pipeline-utils/docs/API-Reference)
+- [Evaluation guide](https://devilsdev.github.io/rag-pipeline-utils/docs/Evaluation)
+- [Examples](examples/): basic pipeline, OpenAI with Pinecone, and a deployable Fastify service
+- [Changelog](CHANGELOG.md) and [benchmarks methodology](BENCHMARKS.md)
 
-**Next (v3.0):** intelligent caching, native Rust bindings, Kubernetes operator, edge deployment.
+## Security
 
-Vote on features in [GitHub Discussions](https://github.com/DevilsDev/rag-pipeline-utils/discussions/categories/roadmap).
+Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md). The [security capability matrix](https://devilsdev.github.io/rag-pipeline-utils/docs/Security-Capabilities) lists what is hardened, what is recommended configuration, and what is an example only.
 
-## Community
+## Contributing
 
-- **[GitHub Discussions](https://github.com/DevilsDev/rag-pipeline-utils/discussions)** — ask questions, share use cases
-- **[Issues](https://github.com/DevilsDev/rag-pipeline-utils/issues)** — report bugs, request features
-- **[Contributing guide](https://github.com/DevilsDev/rag-pipeline-utils/blob/main/docs/CONTRIBUTING.md)**
+Issues and pull requests are welcome. Start with the [contributing guide](docs/CONTRIBUTING.md), and use [GitHub Discussions](https://github.com/DevilsDev/rag-pipeline-utils/discussions) for questions and ideas. Run `npm test` and `npm run lint` before opening a pull request.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+[MIT](LICENSE)

package/SECURITY.md

@@ -8,11 +8,11 @@ Only the latest minor release line receives security patches. When a new
 minor version ships, the previous line receives one more patch window of
 30 days before support ends.
 
-| Version | Supported          |
-| ------- | ------------------ |
-| 2.4.x   | :white_check_mark: |
-| 2.3.x   | :x:                |
-| < 2.3   | :x:                |
+| Version | Supported                                                    |
+| ------- | ------------------------------------------------------------ |
+| 2.5.x   | :white_check_mark:                                           |
+| 2.4.x   | Security fixes for 30 days after the 2.5.0 release, then :x: |
+| < 2.4   | :x:                                                          |
 
 ## Reporting a Vulnerability
 

package/dist/experimental.cjs

@@ -0,0 +1,2 @@
+'use strict';
+module.exports = require('./index.cjs')[Symbol.for('@devilsdev/rag-pipeline-utils/experimental')];

package/dist/experimental.d.ts

@@ -0,0 +1 @@
+export * from "./types/experimental";

package/dist/experimental.mjs

@@ -0,0 +1,5 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const mod = require('./experimental.cjs');
+export const { MultiModalProcessor, AdaptiveRetrievalEngine, FederatedLearningCoordinator, ModelTrainingOrchestrator, DataGovernanceManager, DataGovernance, TenantManager, ResourceMonitor, SSOManager, SAMLProvider, OAuth2Provider, ActiveDirectoryProvider, OIDCProvider, PluginSandbox, PluginCertification } = mod;
+export default mod;