create-rag-pipeline 0.0.0-stage → 3.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali Kahwaji
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,22 @@
-# Temporary Holding Version
+# create-rag-pipeline
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Starter projects for [`@devilsdev/rag-pipeline-utils`](https://www.npmjs.com/package/@devilsdev/rag-pipeline-utils): an app that answers questions from a folder of documents, cites the passages it used and checks every sentence of the answer against them.
+
+```bash
+npm create rag-pipeline@latest my-app -- --template next
+cd my-app
+npm install
+npm run dev
+```
+
+| Template  | What you get                                                                                                 |
+| --------- | ------------------------------------------------------------------------------------------------------------ |
+| `next`    | Next.js and the AI SDK: a question page and `POST /api/ask`, with the model wrapped in `groundingMiddleware` |
+| `mastra`  | A Mastra agent with a `search_documents` tool, a groundedness scorer and guardrails                          |
+| `workers` | A Cloudflare Worker: `GET /ask` as JSON or a token stream, with citations and a groundedness score           |
+
+Without `--template`, it asks. Each starter runs before you add an API key, returning the matching passages; copy its `.env.example` (`.dev.vars.example` for Workers) and set `ANTHROPIC_API_KEY` to get answers from Claude.
+
+The starters ask for the library version this package was released with. Node.js 22 or later.
+
+[Documentation](https://devilsdev.github.io/rag-pipeline-utils/docs/Starter-Templates) · [Source](https://github.com/DevilsDev/rag-pipeline-utils/tree/main/packages/create-rag-pipeline) · MIT

package/bin/create-rag-pipeline.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ *   npm create rag-pipeline@latest [dir] -- [--template next|mastra|workers]
+ *
+ * Without --template, asks which starter to use (or fails when not run in a
+ * terminal, so scripts and CI must pass it).
+ */
+
+const readline = require("readline/promises");
+const path = require("path");
+const { scaffold, TEMPLATES, version } = require("../lib/scaffold");
+
+const USAGE = `Usage: npm create rag-pipeline@latest [dir] -- [--template ${Object.keys(TEMPLATES).join("|")}]
+
+Templates:
+${Object.entries(TEMPLATES)
+  .map(([k, v]) => `  ${k.padEnd(8)} ${v}`)
+  .join("\n")}`;
+
+// Where each starter reads its API key from in development
+const KEY_FILE = { next: ".env.local", mastra: ".env", workers: ".dev.vars" };
+const EXAMPLE = {
+  next: ".env.example",
+  mastra: ".env.example",
+  workers: ".dev.vars.example",
+};
+const RUN = { next: "dev", mastra: "ask", workers: "dev" };
+
+function parse(argv) {
+  const out = { dir: undefined, template: undefined, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") out.help = true;
+    else if (a === "-v" || a === "--version") out.version = true;
+    else if (a === "-t" || a === "--template") out.template = argv[++i];
+    else if (a.startsWith("--template=")) out.template = a.slice(11);
+    else if (a.startsWith("-")) throw new Error(`Unknown option ${a}`);
+    else if (!out.dir) out.dir = a;
+    else throw new Error(`Unexpected argument ${a}`);
+  }
+  return out;
+}
+
+async function ask(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+async function main() {
+  const args = parse(process.argv.slice(2));
+  if (args.help) return console.log(USAGE);
+  if (args.version) return console.log(version);
+
+  const interactive = process.stdin.isTTY && process.stdout.isTTY;
+  let { dir, template } = args;
+  if (!template) {
+    if (!interactive) throw new Error(`Pass --template.\n\n${USAGE}`);
+    const keys = Object.keys(TEMPLATES);
+    console.log("Which starter?");
+    keys.forEach((k, i) => console.log(`  ${i + 1}. ${k}: ${TEMPLATES[k]}`));
+    const answer = await ask(`Number or name [1]: `);
+    template = keys[Number(answer || 1) - 1] || answer;
+  }
+  if (!dir) {
+    dir = interactive
+      ? (await ask("Directory [rag-app]: ")) || "rag-app"
+      : "rag-app";
+  }
+
+  const result = scaffold({ template, dir });
+  const rel = path.relative(process.cwd(), result.dir) || ".";
+  const pm = (process.env.npm_config_user_agent || "npm").split("/")[0];
+  const run = pm === "npm" ? "npm run" : pm;
+  console.log(`
+Created ${result.name} from the ${template} starter in ${rel}
+
+  cd ${rel}
+  ${pm} install
+  ${run} ${RUN[template]}
+
+It answers with the matching passages until you add a key: copy
+${EXAMPLE[template]} to ${KEY_FILE[template]} and set ANTHROPIC_API_KEY. See README.md.`);
+}
+
+main().catch((error) => {
+  console.error(`create-rag-pipeline: ${error.message}`);
+  process.exit(1);
+});

package/lib/scaffold.js

@@ -0,0 +1,106 @@
+"use strict";
+
+/**
+ * Copies a starter template into a new directory: `npm create rag-pipeline`.
+ *
+ * The templates pin @devilsdev/rag-pipeline-utils to this package's own
+ * version (the two are released together), so a starter never asks for an
+ * older library than the one it was written for. Node built-ins only.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const { version } = require("../package.json");
+
+const TEMPLATES_DIR = path.join(__dirname, "..", "templates");
+
+/** The starters, in the order the prompt lists them. */
+const TEMPLATES = {
+  next: "Next.js and the AI SDK: a chat page and an API route that answer from your documents, with grounding checks",
+  mastra:
+    "Mastra: an agent with a document-search tool, a groundedness scorer and guardrails",
+  workers:
+    "Cloudflare Workers: a RAG API with in-memory retrieval and streamed answers",
+};
+
+// npm drops .gitignore from published tarballs, so templates ship it under
+// another name and it is renamed on copy
+const RENAME = { _gitignore: ".gitignore" };
+
+const LIBRARY = "@devilsdev/rag-pipeline-utils";
+
+const isSeparator = (c) => c === "-" || c === "." || c === "_";
+
+/** A valid npm package name from a directory name. */
+function packageName(dir) {
+  const name = path
+    .basename(path.resolve(dir))
+    .toLowerCase()
+    .replace(/[^a-z0-9-._~]+/g, "-");
+  // Trim separators from both ends (a loop, not a regex: no backtracking)
+  let start = 0;
+  let end = name.length;
+  while (start < end && isSeparator(name[start])) start++;
+  while (end > start && isSeparator(name[end - 1])) end--;
+  return name.slice(start, end) || "rag-app";
+}
+
+function isEmptyDir(dir) {
+  return !fs.existsSync(dir) || fs.readdirSync(dir).length === 0;
+}
+
+function copyDir(from, to) {
+  fs.mkdirSync(to, { recursive: true });
+  for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+    const src = path.join(from, entry.name);
+    const dest = path.join(to, RENAME[entry.name] || entry.name);
+    if (entry.isDirectory()) copyDir(src, dest);
+    else fs.copyFileSync(src, dest);
+  }
+}
+
+/**
+ * Create a project from a template.
+ *
+ * @param {Object} options
+ * @param {string} options.template - One of the keys of TEMPLATES
+ * @param {string} options.dir - Directory to create; must be empty or missing
+ * @param {string} [options.libraryVersion] - Version range for the library (default `^<this version>`)
+ * @returns {{ dir: string, name: string, template: string }}
+ */
+function scaffold({ template, dir, libraryVersion = `^${version}` }) {
+  if (!TEMPLATES[template]) {
+    throw new Error(
+      `Unknown template "${template}". Use one of: ${Object.keys(TEMPLATES).join(", ")}`,
+    );
+  }
+  if (!dir) throw new Error("Give a directory for the new project");
+  const target = path.resolve(dir);
+  if (!isEmptyDir(target)) {
+    throw new Error(`${target} is not empty; choose a new directory`);
+  }
+
+  copyDir(path.join(TEMPLATES_DIR, template), target);
+
+  const pkgFile = path.join(target, "package.json");
+  const pkg = JSON.parse(fs.readFileSync(pkgFile, "utf8"));
+  const name = packageName(target);
+  pkg.name = name;
+  pkg.dependencies[LIBRARY] = libraryVersion;
+  fs.writeFileSync(pkgFile, `${JSON.stringify(pkg, null, 2)}\n`);
+
+  // A Worker's name is its URL on workers.dev
+  const wrangler = path.join(target, "wrangler.toml");
+  if (fs.existsSync(wrangler)) {
+    const toml = fs.readFileSync(wrangler, "utf8");
+    fs.writeFileSync(
+      wrangler,
+      toml.replace(/^name = ".*"$/m, `name = "${name}"`),
+    );
+  }
+
+  return { dir: target, name, template };
+}
+
+module.exports = { scaffold, TEMPLATES, packageName, version };

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "create-rag-pipeline",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "3.7.0",
+  "description": "npm create rag-pipeline: starter projects for @devilsdev/rag-pipeline-utils with Next.js and the AI SDK, Mastra, or Cloudflare Workers.",
+  "keywords": [
+    "rag",
+    "create",
+    "starter",
+    "template",
+    "nextjs",
+    "ai-sdk",
+    "mastra",
+    "cloudflare-workers",
+    "claude"
+  ],
+  "license": "MIT",
+  "author": "Ali Kahwaji",
+  "homepage": "https://devilsdev.github.io/rag-pipeline-utils/docs/Starter-Templates",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DevilsDev/rag-pipeline-utils.git",
+    "directory": "packages/create-rag-pipeline"
+  },
+  "bugs": {
+    "url": "https://github.com/DevilsDev/rag-pipeline-utils/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "commonjs",
+  "main": "./lib/scaffold.js",
+  "bin": {
+    "create-rag-pipeline": "bin/create-rag-pipeline.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/mastra/.env.example

@@ -0,0 +1,4 @@
+# Copy to .env. Without a key, `npm run ask` prints the matching passages.
+ANTHROPIC_API_KEY=
+# Any model Mastra's router knows, as provider/model
+MODEL=anthropic/claude-sonnet-5-5

package/templates/mastra/README.md

@@ -0,0 +1,47 @@
+# Docs agent (Mastra)
+
+A [Mastra](https://mastra.ai) agent that answers questions from the Markdown files in `docs/`, made with [`create-rag-pipeline`](https://devilsdev.github.io/rag-pipeline-utils/docs/Starter-Templates). [`@devilsdev/rag-pipeline-utils`](https://www.npmjs.com/package/@devilsdev/rag-pipeline-utils) provides the retrieval behind its `search_documents` tool, a groundedness scorer (no model calls) and guardrails: prompt-injection detection on the question, PII redaction on the answer.
+
+## Run it
+
+```bash
+npm install
+npm run ask -- "How many vacation days do I get?"
+```
+
+Without an API key it prints the matching passages. To get answers from Claude:
+
+```bash
+cp .env.example .env   # then set ANTHROPIC_API_KEY
+npm run ask -- "How many vacation days do I get?"
+```
+
+```
+Full-time employees receive 20 days of paid vacation per year. Unused days carry over until the end of March.
+
+Sources: vacation.md, expenses.md, remote-work.md
+Grounded: every sentence is supported by a passage.
+```
+
+`npm run dev` opens Mastra Studio, where you can chat with the agent and see the groundedness score of each answer.
+
+## Make it yours
+
+- **Your documents:** replace the files in `docs/` (Markdown or text), or set `DOCS_DIR`. They're indexed in memory on first use with the library's built-in TF-IDF embedder.
+- **More documents:** swap `MemoryRetriever` in `src/mastra/retrieval.ts` for `QdrantRetriever` or `PgVectorRetriever`, and `LocalEmbedder` for an embedding model.
+- **Another model:** set `MODEL` to any model Mastra's router knows (`anthropic/claude-haiku-4-5`, `openai/gpt-5`, ...).
+- **Other scores:** `createMastraScorer` also takes `metric: "faithfulness"`, `"contextPrecision"` or `"contextRecall"`.
+- **Storage:** `src/mastra/index.ts` keeps threads and scores in memory; use `@mastra/libsql` or `@mastra/pg` to keep them.
+
+## Deploy
+
+`npm run build` writes a server to `.mastra/output`; run it with `node .mastra/output/index.mjs` from the project folder (it reads `docs/`), or deploy it with one of Mastra's deployers.
+
+## Files
+
+| File                                   | What it does                                                    |
+| -------------------------------------- | --------------------------------------------------------------- |
+| `src/mastra/agents/docs-agent.ts`      | The agent: instructions, model, tool, scorer, guardrails        |
+| `src/mastra/tools/search-documents.ts` | The `search_documents` tool                                     |
+| `src/mastra/retrieval.ts`              | Indexes `docs/` in memory                                       |
+| `src/ask.ts`                           | `npm run ask`: one question, the answer and its grounding check |

package/templates/mastra/_gitignore

@@ -0,0 +1,5 @@
+node_modules/
+.mastra/
+dist/
+.env
+*.db

package/templates/mastra/docs/expenses.md

@@ -0,0 +1,3 @@
+# Expenses
+
+Submit receipts within thirty days. Meals while travelling are reimbursed up to fifty dollars per day.

package/templates/mastra/docs/remote-work.md

@@ -0,0 +1,3 @@
+# Remote work
+
+Employees may work remotely up to three days a week with manager approval. Core hours are 10:00 to 15:00.

package/templates/mastra/docs/vacation.md

@@ -0,0 +1,3 @@
+# Vacation
+
+Full-time employees receive twenty days of paid vacation per year. Unused days carry over until the end of March.

package/templates/mastra/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "rag-mastra",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "A Mastra agent that answers from your documents, with @devilsdev/rag-pipeline-utils retrieval, a groundedness scorer and guardrails.",
+  "scripts": {
+    "ask": "node --env-file-if-exists=.env --import tsx src/ask.ts",
+    "dev": "mastra dev",
+    "build": "mastra build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@devilsdev/rag-pipeline-utils": "LIBRARY_VERSION",
+    "@mastra/core": "^1.82.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "mastra": "^1.38.0",
+    "tsx": "^4.23.15",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/templates/mastra/src/ask.ts

@@ -0,0 +1,49 @@
+/**
+ *   npm run ask -- "How many vacation days do I get?"
+ *
+ * Asks the agent once and prints the answer, the passages it used and
+ * whether every sentence is supported by them. Without ANTHROPIC_API_KEY it
+ * prints the passages that match, so you can try retrieval first.
+ */
+
+import { checkAnswer } from "@devilsdev/rag-pipeline-utils";
+import { mastra } from "./mastra";
+import { searchDocuments, type Passage } from "./mastra/retrieval";
+
+const question =
+  process.argv.slice(2).join(" ").trim() || "How many vacation days do I get?";
+
+if (!process.env.ANTHROPIC_API_KEY) {
+  console.log(
+    `No ANTHROPIC_API_KEY (copy .env.example to .env). Passages for "${question}":\n`,
+  );
+  for (const p of await searchDocuments(question)) {
+    console.log(`[${p.source}] ${p.content.trim()}\n`);
+  }
+  process.exit(0);
+}
+
+const result = await mastra.getAgent("docsAgent").generate(question);
+
+// The passages the agent's search_documents calls returned
+const passages: Passage[] = (result.toolResults ?? []).flatMap((r: any) =>
+  r.payload?.toolName === "search_documents"
+    ? (r.payload.result?.passages ?? [])
+    : [],
+);
+
+const check = await checkAnswer({
+  answer: result.text,
+  sources: passages.map((p) => ({ id: p.id, content: p.content })),
+  evaluate: false,
+});
+
+console.log(result.text.trim());
+console.log(
+  `\nSources: ${[...new Set(passages.map((p) => p.source))].join(", ") || "none"}`,
+);
+console.log(
+  check.grounded
+    ? "Grounded: every sentence is supported by a passage."
+    : `Not grounded. Unsupported: ${check.unsupported.map((s: string) => `"${s}"`).join("; ")}`,
+);

package/templates/mastra/src/mastra/agents/docs-agent.ts

@@ -0,0 +1,29 @@
+import { Agent } from "@mastra/core/agent";
+import { createScorer } from "@mastra/core/evals";
+import {
+  createMastraGuardrails,
+  createMastraScorer,
+} from "@devilsdev/rag-pipeline-utils";
+import { searchDocumentsTool } from "../tools/search-documents";
+
+// Prompt-injection detection on the question, PII redaction on the answer
+const guardrails = createMastraGuardrails();
+
+export const docsAgent = new Agent({
+  id: "docs-agent",
+  name: "Docs agent",
+  instructions: `You answer questions from the user's documents.
+Always call search_documents first, then answer only from the passages it returns.
+If they don't contain the answer, say you don't know. Keep answers short.`,
+  model: process.env.MODEL || "anthropic/claude-sonnet-5-5",
+  tools: { search_documents: searchDocumentsTool },
+  inputProcessors: [guardrails],
+  outputProcessors: [guardrails],
+  // Scores each answer against the passages the tool returned: a lexical
+  // check, no model calls. See it in Mastra Studio (npm run dev)
+  scorers: {
+    groundedness: {
+      scorer: createMastraScorer({ createScorer, metric: "groundedness" }),
+    },
+  },
+});

package/templates/mastra/src/mastra/index.ts

@@ -0,0 +1,9 @@
+import { Mastra } from "@mastra/core/mastra";
+import { InMemoryStore } from "@mastra/core/storage";
+import { docsAgent } from "./agents/docs-agent";
+
+export const mastra = new Mastra({
+  agents: { docsAgent },
+  // Lost on restart: use @mastra/libsql or @mastra/pg to keep threads and scores
+  storage: new InMemoryStore(),
+});

package/templates/mastra/src/mastra/retrieval.ts

@@ -0,0 +1,80 @@
+/**
+ * Retrieval over the Markdown files in docs/: indexed in memory on first use
+ * with the library's built-in TF-IDF embedder, so there is no database and
+ * no embedding API. Swap in a vector store (QdrantRetriever,
+ * PgVectorRetriever) and an embedding model when the documents outgrow
+ * memory.
+ */
+
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { LocalEmbedder, MemoryRetriever } from "@devilsdev/rag-pipeline-utils";
+
+export interface Passage {
+  id: string;
+  content: string;
+  source?: string;
+  score?: number;
+}
+
+/**
+ * The project's docs/ folder: the nearest one at or above the working
+ * directory, since `mastra dev` and `mastra build` run from folders inside
+ * the project. Set DOCS_DIR to read another folder.
+ */
+function findDocsDir(): string {
+  if (process.env.DOCS_DIR) return path.resolve(process.env.DOCS_DIR);
+  for (let dir = process.cwd(); ; dir = path.dirname(dir)) {
+    const candidate = path.join(dir, "docs");
+    if (existsSync(candidate)) return candidate;
+    if (path.dirname(dir) === dir) return path.resolve("docs");
+  }
+}
+
+const DOCS_DIR = findDocsDir();
+
+let index: Promise<{ embedder: LocalEmbedder; retriever: MemoryRetriever }>;
+
+async function buildIndex() {
+  const files = (await readdir(DOCS_DIR)).filter((f) => /\.(md|txt)$/i.test(f));
+  const documents = await Promise.all(
+    files.map(async (file) => ({
+      id: file.replace(/\.[^.]+$/, ""),
+      content: await readFile(path.join(DOCS_DIR, file), "utf8"),
+      metadata: { source: file },
+    })),
+  );
+  const embedder = new LocalEmbedder();
+  embedder.train(documents);
+  const retriever = new MemoryRetriever();
+  await retriever.store(
+    await Promise.all(
+      documents.map(async (doc) => ({
+        ...doc,
+        vector: await embedder.embed(doc.content),
+      })),
+    ),
+  );
+  return { embedder, retriever };
+}
+
+/** The passages that best match a query. */
+export async function searchDocuments(
+  query: string,
+  topK = 3,
+): Promise<Passage[]> {
+  index ??= buildIndex();
+  const { embedder, retriever } = await index;
+  const results = await retriever.retrieve({
+    query,
+    queryVector: await embedder.embed(query),
+    topK,
+  });
+  return results.map((r: any) => ({
+    id: r.id,
+    content: r.content,
+    source: r.metadata?.source,
+    score: r.score,
+  }));
+}

package/templates/mastra/src/mastra/tools/search-documents.ts

@@ -0,0 +1,23 @@
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { searchDocuments } from "../retrieval";
+
+export const searchDocumentsTool = createTool({
+  id: "search_documents",
+  description:
+    "Search the documents. Returns the best-matching passages with their ids and source files.",
+  inputSchema: z.object({
+    query: z.string().describe("What to look for"),
+  }),
+  outputSchema: z.object({
+    passages: z.array(
+      z.object({
+        id: z.string(),
+        content: z.string(),
+        source: z.string().optional(),
+        score: z.number().optional(),
+      }),
+    ),
+  }),
+  execute: async ({ query }) => ({ passages: await searchDocuments(query) }),
+});

package/templates/mastra/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src"]
+}

package/templates/next/.env.example

@@ -0,0 +1,4 @@
+# Copy to .env.local. Without a key, the app answers with the matching passages.
+ANTHROPIC_API_KEY=
+# Optional: the Claude model
+ANTHROPIC_MODEL=claude-sonnet-5-5

package/templates/next/README.md

@@ -0,0 +1,54 @@
+# Ask your documents (Next.js + AI SDK)
+
+A Next.js app that answers questions from the Markdown files in `docs/`, made with [`create-rag-pipeline`](https://devilsdev.github.io/rag-pipeline-utils/docs/Starter-Templates). The AI SDK model is wrapped with `groundingMiddleware` from [`@devilsdev/rag-pipeline-utils`](https://www.npmjs.com/package/@devilsdev/rag-pipeline-utils): before each call it retrieves the matching passages and gives them to the model; after the call it checks every sentence of the answer against them and returns the report with the sources.
+
+## Run it
+
+```bash
+npm install
+npm run dev
+```
+
+Open http://localhost:3000 and ask "How many vacation days do I get?". Without an API key the app shows the matching passages. To get answers from Claude:
+
+```bash
+cp .env.example .env.local   # then set ANTHROPIC_API_KEY
+```
+
+Or call the API:
+
+```bash
+curl -X POST localhost:3000/api/ask -H "content-type: application/json" \
+  -d '{"question":"How many vacation days do I get?"}'
+```
+
+```json
+{
+  "answer": "Full-time employees receive twenty days of paid vacation per year…",
+  "sources": [{ "id": "vacation", "source": "vacation.md" }],
+  "grounding": { "grounded": true, "groundedness": 1, "unsupported": [] }
+}
+```
+
+`grounded: false` lists the sentences no passage supports, so you can flag or retry them.
+
+## Make it yours
+
+- **Your documents:** replace the files in `docs/` (Markdown or text). They're indexed in memory on the first request with the library's built-in TF-IDF embedder: no database, no embedding API.
+- **More documents:** swap `MemoryRetriever` in `lib/rag.ts` for `QdrantRetriever` or `PgVectorRetriever`, and `LocalEmbedder` for an embedding model (`OpenAIConnector`, or any AI SDK embedding model through `createAiSdkAdapter`).
+- **Another model:** set `ANTHROPIC_MODEL`, or replace `anthropic(...)` in `app/api/ask/route.ts` with any AI SDK provider.
+- **Paraphrases:** the check is lexical, so a correct paraphrase can be reported unsupported. Pass `judge` to `groundingMiddleware` to have a model rule on those sentences ([LLM judge](https://devilsdev.github.io/rag-pipeline-utils/docs/Evaluation#paraphrases-the-optional-llm-judge)).
+- **Guardrails:** `groundingMiddleware({ preRetrieval: true, postGeneration: true })` adds prompt-injection detection on the question and PII redaction on the answer.
+
+## Deploy
+
+On Vercel, import the repository and set `ANTHROPIC_API_KEY`. `next.config.ts` includes `docs/` in the deployment of the route that reads it.
+
+## Files
+
+| File                   | What it does                                             |
+| ---------------------- | -------------------------------------------------------- |
+| `app/api/ask/route.ts` | The API: retrieval, the model call, the grounding report |
+| `lib/rag.ts`           | Indexes `docs/` in memory, once per server process       |
+| `app/page.tsx`         | The page: a question box, the answer, its sources        |
+| `next.config.ts`       | Loads the library with Node at runtime; deploys `docs/`  |

package/templates/next/_gitignore

@@ -0,0 +1,7 @@
+node_modules/
+.next/
+out/
+next-env.d.ts
+*.tsbuildinfo
+.env*.local
+.vercel

package/templates/next/app/api/ask/route.ts

@@ -0,0 +1,80 @@
+/**
+ * POST /api/ask { question } -> { answer, sources, grounding }
+ *
+ * The AI SDK model is wrapped with groundingMiddleware: before the call it
+ * retrieves passages for the question and gives them to the model as
+ * reference data; after the call it checks every sentence of the answer
+ * against them. Without ANTHROPIC_API_KEY the route returns the passages
+ * only (answer: null).
+ */
+
+import { anthropic } from "@ai-sdk/anthropic";
+import { groundingMiddleware } from "@devilsdev/rag-pipeline-utils";
+import { generateText, wrapLanguageModel } from "ai";
+import { getIndex } from "@/lib/rag";
+
+export const runtime = "nodejs";
+
+export async function POST(request: Request) {
+  const { question } = (await request.json().catch(() => ({}))) as {
+    question?: unknown;
+  };
+  if (typeof question !== "string" || !question.trim()) {
+    return Response.json({ error: "Send { question }" }, { status: 400 });
+  }
+
+  const { embedder, retriever } = await getIndex();
+
+  if (!process.env.ANTHROPIC_API_KEY) {
+    const results = await retriever.retrieve({
+      query: question,
+      queryVector: await embedder.embed(question),
+      topK: 3,
+    });
+    return Response.json({
+      answer: null,
+      sources: results.map((r: any) => ({
+        id: r.id,
+        source: r.metadata?.source,
+        content: r.content,
+      })),
+      grounding: null,
+    });
+  }
+
+  const model = wrapLanguageModel({
+    model: anthropic(process.env.ANTHROPIC_MODEL || "claude-sonnet-5-5"),
+    middleware: groundingMiddleware({
+      retriever,
+      embedder,
+      topK: 3,
+      specificationVersion: "v4",
+    }),
+  });
+
+  try {
+    const result = await generateText({ model, prompt: question });
+    const report = result.providerMetadata?.ragPipeline as
+      | { grounded?: boolean; groundedness?: number; unsupported?: string[] }
+      | undefined;
+    return Response.json({
+      answer: result.text,
+      sources: result.sources.map((s: any) => ({
+        id: s.id,
+        source: s.title ?? s.id,
+      })),
+      grounding: report
+        ? {
+            grounded: report.grounded,
+            groundedness: report.groundedness,
+            unsupported: report.unsupported ?? [],
+          }
+        : null,
+    });
+  } catch (error) {
+    return Response.json(
+      { error: error instanceof Error ? error.message : String(error) },
+      { status: 502 },
+    );
+  }
+}

package/templates/next/app/layout.tsx

@@ -0,0 +1,24 @@
+import type { ReactNode } from "react";
+
+export const metadata = {
+  title: "Ask your documents",
+  description: "Answers from your documents, checked against them.",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body
+        style={{
+          fontFamily: "system-ui, sans-serif",
+          maxWidth: 680,
+          margin: "48px auto",
+          padding: "0 16px",
+          lineHeight: 1.5,
+        }}
+      >
+        {children}
+      </body>
+    </html>
+  );
+}

package/templates/next/app/page.tsx

@@ -0,0 +1,86 @@
+"use client";
+
+import { useState, type FormEvent } from "react";
+
+type Source = { id: string; source?: string; content?: string };
+type Answer = {
+  answer: string | null;
+  sources: Source[];
+  grounding: {
+    grounded?: boolean;
+    groundedness?: number;
+    unsupported: string[];
+  } | null;
+  error?: string;
+};
+
+export default function Home() {
+  const [question, setQuestion] = useState("How many vacation days do I get?");
+  const [result, setResult] = useState<Answer | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  async function ask(event: FormEvent) {
+    event.preventDefault();
+    setLoading(true);
+    setResult(null);
+    const response = await fetch("/api/ask", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ question }),
+    });
+    setResult(await response.json());
+    setLoading(false);
+  }
+
+  return (
+    <main>
+      <h1>Ask your documents</h1>
+      <form onSubmit={ask} style={{ display: "flex", gap: 8 }}>
+        <input
+          value={question}
+          onChange={(e) => setQuestion(e.target.value)}
+          style={{ flex: 1, padding: 8 }}
+          aria-label="Question"
+        />
+        <button disabled={loading || !question.trim()}>
+          {loading ? "Asking…" : "Ask"}
+        </button>
+      </form>
+
+      {result?.error && <p role="alert">Error: {result.error}</p>}
+
+      {result && !result.error && (
+        <section>
+          {result.answer === null ? (
+            <p>
+              <em>
+                No ANTHROPIC_API_KEY yet (see .env.example), so here are the
+                matching passages:
+              </em>
+            </p>
+          ) : (
+            <p>{result.answer}</p>
+          )}
+
+          {result.grounding && (
+            <p>
+              {result.grounding.grounded
+                ? "✓ Every sentence is supported by the sources."
+                : `⚠ Not supported by the sources: ${result.grounding.unsupported.join(" ")}`}
+            </p>
+          )}
+
+          <h2 style={{ fontSize: "1rem" }}>Sources</h2>
+          <ul>
+            {result.sources.map((s) => (
+              <li key={s.id}>
+                <strong>{s.source ?? s.id}</strong>
+                {s.content && <div>{s.content.replace(/^#.*\n+/, "")}</div>}
+              </li>
+            ))}
+          </ul>
+        </section>
+      )}
+    </main>
+  );
+}

package/templates/next/docs/expenses.md

@@ -0,0 +1,3 @@
+# Expenses
+
+Submit receipts within thirty days. Meals while travelling are reimbursed up to fifty dollars per day.

package/templates/next/docs/remote-work.md

@@ -0,0 +1,3 @@
+# Remote work
+
+Employees may work remotely up to three days a week with manager approval. Core hours are 10:00 to 15:00.

package/templates/next/docs/vacation.md

@@ -0,0 +1,3 @@
+# Vacation
+
+Full-time employees receive twenty days of paid vacation per year. Unused days carry over until the end of March.

package/templates/next/lib/rag.ts

@@ -0,0 +1,46 @@
+/**
+ * Retrieval over the Markdown files in docs/: indexed in memory on first use
+ * with the library's built-in TF-IDF embedder, so there is no database and
+ * no embedding API. Swap in a vector store (QdrantRetriever,
+ * PgVectorRetriever) and an embedding model when the documents outgrow
+ * memory.
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { LocalEmbedder, MemoryRetriever } from "@devilsdev/rag-pipeline-utils";
+
+const DOCS_DIR = path.join(process.cwd(), "docs");
+
+let index:
+  | Promise<{ embedder: LocalEmbedder; retriever: MemoryRetriever }>
+  | undefined;
+
+async function buildIndex() {
+  const files = (await readdir(DOCS_DIR)).filter((f) => /\.(md|txt)$/i.test(f));
+  const documents = await Promise.all(
+    files.map(async (file) => ({
+      id: file.replace(/\.[^.]+$/, ""),
+      content: await readFile(path.join(DOCS_DIR, file), "utf8"),
+      metadata: { source: file },
+    })),
+  );
+  const embedder = new LocalEmbedder();
+  embedder.train(documents);
+  const retriever = new MemoryRetriever();
+  await retriever.store(
+    await Promise.all(
+      documents.map(async (doc) => ({
+        ...doc,
+        vector: await embedder.embed(doc.content),
+      })),
+    ),
+  );
+  return { embedder, retriever };
+}
+
+/** The embedder and retriever, built once per server process. */
+export function getIndex() {
+  index ??= buildIndex();
+  return index;
+}

package/templates/next/next.config.ts

@@ -0,0 +1,11 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  // Loaded by Node at runtime rather than bundled: the library is CommonJS
+  // and requires its optional providers (openai, ...) only when used
+  serverExternalPackages: ["@devilsdev/rag-pipeline-utils"],
+  // Deploy the documents with the route that reads them
+  outputFileTracingIncludes: { "/api/ask": ["./docs/**"] },
+};
+
+export default nextConfig;

package/templates/next/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "rag-next",
+  "version": "0.1.0",
+  "private": true,
+  "description": "A Next.js app that answers from your documents with the AI SDK and @devilsdev/rag-pipeline-utils: retrieval, grounding checks and sources.",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^4.0.97",
+    "@devilsdev/rag-pipeline-utils": "LIBRARY_VERSION",
+    "ai": "^7.0.163",
+    "next": "^16.4.5",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/templates/next/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": ["node_modules"]
+}

package/templates/workers/.dev.vars.example

@@ -0,0 +1,3 @@
+# Copy to .dev.vars (read by `wrangler dev`). Without a key the Worker
+# returns the matching passages. In production: npx wrangler secret put ANTHROPIC_API_KEY
+ANTHROPIC_API_KEY=

package/templates/workers/README.md

@@ -0,0 +1,58 @@
+# RAG on Cloudflare Workers
+
+A Cloudflare Worker that answers questions from your documents, made with [`create-rag-pipeline`](https://devilsdev.github.io/rag-pipeline-utils/docs/Starter-Templates): retrieval in memory with the built-in TF-IDF embedder, answers from Claude with citations and a groundedness score, and streaming. It uses `@devilsdev/rag-pipeline-utils/edge`, the library's build for runtimes with Web APIs only.
+
+## Run it
+
+```bash
+npm install
+npm run dev
+```
+
+In another terminal:
+
+```bash
+curl "http://localhost:8787/ask?q=How+many+vacation+days+do+I+get%3F"
+```
+
+Without an API key the Worker returns the matching passages (`answer: null`). To get answers from Claude:
+
+```bash
+cp .dev.vars.example .dev.vars   # then set ANTHROPIC_API_KEY
+```
+
+Stream the answer as server-sent events:
+
+```bash
+curl -N "http://localhost:8787/ask?q=How+many+vacation+days+do+I+get%3F&stream=1"
+```
+
+```
+event: token
+data: "Full-time employees receive "
+...
+event: done
+data: {"groundedness":1,"timing":{"firstTokenMs":412,"totalMs":980}}
+```
+
+## Deploy
+
+```bash
+npx wrangler secret put ANTHROPIC_API_KEY
+npm run deploy
+```
+
+## API
+
+| Request                   | Response                                                                                                    |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `GET /ask?q=...`          | `{ answer, sources: [{ id, source, score }], groundedness, timing }`                                        |
+| `GET /ask?q=...&stream=1` | Server-sent events: `token` events, then `done` with `groundedness` and `timing: { firstTokenMs, totalMs }` |
+
+A missing `q` is a `400`; a failed run (for example, a provider error or the 30-second timeout) is a `502` with `{ error }`.
+
+## Make it yours
+
+- **Your documents:** `src/docs.js` holds them. Workers have no disk to read at runtime, so they're bundled with the code: replace them, or generate the file at build time.
+- **More documents:** `QdrantRetriever` works in Workers; index your documents there and give the pipeline an embedder.
+- **Settings:** `ANTHROPIC_MODEL` chooses the model; `ANTHROPIC_BASE_URL` sends requests through a gateway such as Cloudflare AI Gateway. Set them under `[vars]` in `wrangler.toml`.

package/templates/workers/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+.wrangler/
+dist/
+.dev.vars

package/templates/workers/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "rag-worker",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "A RAG API on Cloudflare Workers with @devilsdev/rag-pipeline-utils: in-memory retrieval and streamed answers from Claude.",
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "check": "wrangler deploy --dry-run --outdir dist"
+  },
+  "dependencies": {
+    "@devilsdev/rag-pipeline-utils": "LIBRARY_VERSION"
+  },
+  "devDependencies": {
+    "wrangler": "^4.157.0"
+  }
+}

package/templates/workers/src/docs.js

@@ -0,0 +1,25 @@
+/**
+ * The documents the Worker answers from. Workers have no local disk to read
+ * them from at runtime, so they are bundled with the code: replace these, or
+ * load your own at build time.
+ */
+export const documents = [
+  {
+    id: "vacation",
+    content:
+      "Full-time employees receive twenty days of paid vacation per year. Unused days carry over until the end of March.",
+    metadata: { source: "vacation.md" },
+  },
+  {
+    id: "remote-work",
+    content:
+      "Employees may work remotely up to three days a week with manager approval. Core hours are 10:00 to 15:00.",
+    metadata: { source: "remote-work.md" },
+  },
+  {
+    id: "expenses",
+    content:
+      "Submit receipts within thirty days. Meals while travelling are reimbursed up to fifty dollars per day.",
+    metadata: { source: "expenses.md" },
+  },
+];

package/templates/workers/src/worker.js

@@ -0,0 +1,136 @@
+/**
+ * A RAG API on Cloudflare Workers.
+ *
+ *   GET  /ask?q=...            answer as JSON (passages only without an API key)
+ *   GET  /ask?q=...&stream=1   answer as server-sent events, token by token
+ *
+ * The documents are bundled with the Worker (./docs.js) and indexed in
+ * memory on the first request with the built-in TF-IDF embedder, so there is
+ * no database and no embedding API. Set the ANTHROPIC_API_KEY secret to
+ * generate answers with Claude; without it the Worker returns the passages.
+ * Needs the nodejs_compat compatibility flag (see wrangler.toml).
+ */
+
+import {
+  AnthropicConnector,
+  LocalEmbedder,
+  MemoryRetriever,
+  createRagPipeline,
+} from "@devilsdev/rag-pipeline-utils/edge";
+import { documents } from "./docs.js";
+
+/** One index per isolate, built on first use. */
+let index;
+async function getIndex() {
+  if (!index) {
+    index = (async () => {
+      const embedder = new LocalEmbedder();
+      embedder.train(documents);
+      const retriever = new MemoryRetriever();
+      await retriever.store(
+        await Promise.all(
+          documents.map(async (doc) => ({
+            ...doc,
+            vector: await embedder.embed(doc.content),
+          })),
+        ),
+      );
+      return { embedder, retriever };
+    })();
+  }
+  return index;
+}
+
+function pipelineFor(env, { embedder, retriever }) {
+  const llm = env.ANTHROPIC_API_KEY
+    ? new AnthropicConnector({
+        apiKey: env.ANTHROPIC_API_KEY,
+        ...(env.ANTHROPIC_MODEL && { model: env.ANTHROPIC_MODEL }),
+        // e.g. a Cloudflare AI Gateway URL
+        ...(env.ANTHROPIC_BASE_URL && { baseURL: env.ANTHROPIC_BASE_URL }),
+        maxTokens: 512,
+      })
+    : undefined;
+  return createRagPipeline({ embedder, retriever, llm });
+}
+
+const sources = (results) =>
+  results.map((d) => ({
+    id: d.id,
+    source: d.metadata?.source,
+    score: d.score,
+  }));
+
+/** The stream as server-sent events: `token` events, then one `done`. */
+function eventStream(stream) {
+  const encoder = new TextEncoder();
+  return new ReadableStream({
+    async start(controller) {
+      const send = (event, data) =>
+        controller.enqueue(
+          encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`),
+        );
+      try {
+        for await (const chunk of stream) {
+          if (chunk.token) send("token", chunk.token);
+          if (chunk.done) {
+            send("done", {
+              ...(chunk.results && { sources: sources(chunk.results) }),
+              groundedness: chunk.citations?.groundednessScore,
+              timing: chunk.timing,
+            });
+          }
+        }
+      } catch (error) {
+        send("error", { message: String(error?.message || error) });
+      }
+      controller.close();
+    },
+  });
+}
+
+export default {
+  async fetch(request, env) {
+    const url = new URL(request.url);
+    if (url.pathname !== "/ask") {
+      return Response.json(
+        { error: "Ask with GET /ask?q=your+question" },
+        { status: 404 },
+      );
+    }
+    const query = (url.searchParams.get("q") || "").trim();
+    if (!query) {
+      return Response.json({ error: "Missing ?q=" }, { status: 400 });
+    }
+
+    const pipeline = pipelineFor(env, await getIndex());
+    const options = { topK: 3, citations: true, timeout: 30000 };
+
+    if (url.searchParams.get("stream") === "1") {
+      const stream = await pipeline.run({
+        query,
+        options: { ...options, stream: true },
+      });
+      if (stream.success === false) {
+        return Response.json({ error: stream.error }, { status: 502 });
+      }
+      return new Response(eventStream(stream), {
+        headers: {
+          "content-type": "text/event-stream; charset=utf-8",
+          "cache-control": "no-store",
+        },
+      });
+    }
+
+    const result = await pipeline.run({ query, options });
+    if (!result.success) {
+      return Response.json({ error: result.error }, { status: 502 });
+    }
+    return Response.json({
+      answer: result.answer,
+      sources: sources(result.results),
+      groundedness: result.citations?.groundednessScore,
+      timing: result.timing,
+    });
+  },
+};

package/templates/workers/wrangler.toml

@@ -0,0 +1,10 @@
+name = "rag-worker"
+main = "src/worker.js"
+compatibility_date = "2026-10-01"
+# The library uses Node.js APIs (events, crypto, buffer, ...) that Workers
+# provide under this flag.
+compatibility_flags = ["nodejs_compat"]
+
+# Optional: the Claude model (the library's default otherwise).
+# [vars]
+# ANTHROPIC_MODEL = "claude-sonnet-5-5"