Composable retrieval-augmented generation (RAG) for Node.js: grounded citations, evaluation, guardrails, hybrid retrieval and a CLI.
npm install @devilsdev/rag-pipeline-utilsquery How many vacation days do I get?
Full-time employees receive twenty days of paid vacation per year. Unused days carry over to March.[1]
Why rag-pipeline-utils
One createRagPipeline() call wires an embedder, a retriever and an LLM. Everything below is an opt-in layer on top.
Each sentence of an answer is mapped to the passages that support it, with a groundedness score and a check that numbers match the sources.
const { answer, citations } = await pipeline.run({
query,
options: { citations: true },
});
Faithfulness, relevance, context precision, context recall and groundedness, per answer or over a test set.
const { evaluation } = await pipeline.run({
query,
options: { evaluate: true, referenceAnswer },
});
Prompt-injection detection before retrieval, ACL and relevance filtering before generation, PII redaction after.
const safe = new GuardrailsPipeline(pipeline, {
retrieval: { enforceACL: true },
});
AbortSignal cancellation and real timeouts, retries only on transient errors, typed ESM and CommonJS exports.
const controller = new AbortController();
await pipeline.run({
query,
options: { signal: controller.signal, timeout: 5000 },
});
Command line
rag-pipeline builds a persistent local index from Markdown, HTML, CSV and text files. The default template runs offline with no API keys; switch templates to answer with OpenAI, Anthropic or Ollama.
npx rag-pipeline init
npx rag-pipeline ingest ./docs
npx rag-pipeline query "What is the remote work policy?"
npx rag-pipeline serve --port 3000
Quick start
This example needs no API keys: it uses the built-in TF-IDF embedder and an in-memory store. Add an LLM connector to generate cited answers, or swap in your own components. Each one is a plain object with the method its stage needs.
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.",
},
];
// Fit the offline 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) })),
);
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"
Also in the box
How it compares
LangChain.js and LlamaIndex.TS are broad frameworks with large integration catalogues. This library focuses on RAG for Node.js services and ships evaluation, citations and guardrails as part of the pipeline, in one MIT package with a small surface to review.
Start offline, then add a model, citations, evaluation and guardrails as you need them.