create-langgraph-app 1.4.0 → 1.5.1

package/README.md

@@ -2,8 +2,6 @@
 
 Interactive CLI to scaffold a new LangGraph multi-agent project in seconds.
 
-## Usage
-
 ```bash
 npx create-langgraph-app
 ```
@@ -11,28 +9,68 @@ npx create-langgraph-app
 ## What it does
 
 1. Asks for your project name
-2. Lets you pick an LLM provider (OpenAI, Anthropic, Google, Groq, DeepSeek, Ollama)
+2. Lets you pick an LLM provider — OpenAI, Anthropic, Google, Groq, DeepSeek, or Ollama
 3. Lets you select which agent patterns to include:
-   - **Supervisor** — central coordinator + worker agents
+   - **Supervisor** — central coordinator delegating to worker agents
    - **Swarm** — peer-to-peer agent handoffs
    - **Human-in-the-Loop** — approval before dangerous actions
-   - **Structured Output** — typed JSON responses
-   - **RAG** — retrieval-augmented generation
-4. Generates a ready-to-run project with only the patterns you selected
+   - **Structured Output** — typed JSON responses validated by Zod
+   - **RAG** — retrieval-augmented generation over an in-memory vector store
+4. Generates a ready-to-run project containing only the patterns you picked
 5. Installs dependencies
 
+## What you get
+
+```
+src/
+├── config/      env validation, LLM factory, embeddings (with RAG)
+├── agents/      makeAgent() and the helpers your patterns need
+├── apps/        one file per selected pattern
+├── tools/       retrieval tool + vector store (with RAG)
+├── server.ts    Fastify server — invoke, stream, resume, threads
+└── index.ts     CLI demo running each pattern
+tests/           offline tests that need no API key
+```
+
+Everything is built on LangChain's `createAgent` — the **subagents** pattern for
+supervisors, **handoffs** for swarms. No deprecated packages.
+
+## RAG and embeddings
+
+Selecting RAG generates a working implementation: chunking, embedding,
+cosine-similarity search, and a retrieval tool the agent calls before answering.
+Swap `SAMPLE_DOCS` in `src/tools/rag.ts` for your own documents.
+
+Embeddings are a separate capability from chat. OpenAI, Google and Ollama have
+their own; **Anthropic, Groq and DeepSeek do not**, so those projects use OpenAI
+embeddings and need `OPENAI_API_KEY` in addition to the chat provider's key. The
+generated `.env` says so, and `EMBEDDINGS_MODEL` overrides the model.
+
+To run RAG with no API key at all, scaffold with Ollama.
+
+If embeddings are unavailable, only RAG is affected — the other patterns and
+routes keep working, and the server logs why `/rag` is disabled.
+
 ## Development
 
 ```bash
 cd create-langgraph-app
 npm install
-npm run dev  # Run locally
+npm run dev      # run the CLI locally
+npm run build    # typecheck and emit dist/
 ```
 
-## Publishing
+Generated projects are compiled in CI, so a change that breaks the output fails
+the build. See `tests/scaffolder/` in the [starter kit](https://github.com/ac12644/langgraph-starter-kit).
+
+## Releasing
+
+Publishing is automated. Bump the version in `package.json`, then push a
+matching `cli-v*` tag:
 
 ```bash
-cd create-langgraph-app
-npm run build
-npm publish
+git tag -a cli-v1.5.0 -m "create-langgraph-app v1.5.0"
+git push origin cli-v1.5.0
 ```
+
+The `Publish CLI to npm` workflow builds and publishes with provenance.

package/dist/create.d.ts

@@ -1,2 +1,13 @@
 #!/usr/bin/env node
-export {};
+export interface Config {
+    name: string;
+    provider: string;
+    patterns: string[];
+}
+export declare function generateEnv(config: Config): string;
+export declare function generatePackageJson(config: Config): string;
+export declare function generateTsConfig(): string;
+export declare function getPatternFiles(config: Config): {
+    path: string;
+    content: string;
+}[];

package/dist/create.js

@@ -4,6 +4,7 @@ import { stdin, stdout } from "node:process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { execSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
 // ── Helpers ──────────────────────────────────────────────────────────────────
 const BOLD = "\x1b[1m";
 const DIM = "\x1b[2m";
@@ -54,7 +55,25 @@ const PROVIDERS = {
     ollama: { envKey: "", defaultModel: "llama3.2" },
     deepseek: { envKey: "DEEPSEEK_API_KEY", defaultModel: "deepseek-v4-flash" },
 };
-function generateEnv(config) {
+/**
+ * Extra .env lines when RAG borrows another provider's embeddings — that key is
+ * required too, which is not obvious from the chat provider alone.
+ */
+function embeddingsEnvLines(config) {
+    if (!config.patterns.includes("rag"))
+        return [];
+    const e = embeddingsFor(config.provider);
+    if (!e.borrowed)
+        return [];
+    return [
+        `# RAG embeddings: ${config.provider} has no embeddings API, so RAG uses ${e.id}`,
+        `# and needs this key in addition to your chat provider's.`,
+        `${e.envKey}=`,
+        `# EMBEDDINGS_MODEL=${e.defaultModel}`,
+        ``,
+    ];
+}
+export function generateEnv(config) {
     const prov = PROVIDERS[config.provider];
     const lines = [
         `# LLM Provider`,
@@ -68,12 +87,12 @@ function generateEnv(config) {
     else {
         lines.push(`# No API key needed for ${config.provider}`);
     }
-    lines.push(``, `# Model (optional — defaults to ${prov.defaultModel})`, `# LLM_MODEL=${prov.defaultModel}`, `LLM_TEMPERATURE=0`, ``, ...(config.provider === "deepseek"
+    lines.push(``, `# Model (optional — defaults to ${prov.defaultModel})`, `# LLM_MODEL=${prov.defaultModel}`, `LLM_TEMPERATURE=0`, ``, ...embeddingsEnvLines(config), ...(config.provider === "deepseek"
         ? [`# DeepSeek reasoning mode (optional — "disabled" | "enabled")`, `# DEEPSEEK_THINKING=disabled`, ``]
         : []), `PORT=3000`, ``, `# LangSmith tracing (optional)`, `# LANGCHAIN_TRACING_V2=true`, `# LANGSMITH_API_KEY=`, `# LANGSMITH_PROJECT=${config.name}`);
     return lines.join("\n") + "\n";
 }
-function generatePackageJson(config) {
+export function generatePackageJson(config) {
     const deps = {
         "@langchain/core": "^1.2.3",
         "@langchain/langgraph": "^1.4.8",
@@ -96,6 +115,11 @@ function generatePackageJson(config) {
         deepseek: "@langchain/deepseek",
     };
     deps[provPkg[config.provider]] = "latest";
+    // RAG needs an embeddings SDK, which is a different package when the chat
+    // provider has no embeddings API of its own (anthropic, groq, deepseek).
+    if (config.patterns.includes("rag")) {
+        deps[embeddingsFor(config.provider).pkg] ??= "latest";
+    }
     const pkg = {
         name: config.name,
         version: "0.1.0",
@@ -118,7 +142,7 @@ function generatePackageJson(config) {
     };
     return JSON.stringify(pkg, null, 2) + "\n";
 }
-function generateTsConfig() {
+export function generateTsConfig() {
     return JSON.stringify({
         compilerOptions: {
             target: "ES2022",
@@ -183,6 +207,63 @@ const PROVIDER_LLM = {
     ollama: { pkg: "@langchain/ollama", className: "ChatOllama", modelArg: "model", defaultModel: "llama3.2" },
     deepseek: { pkg: "@langchain/deepseek", className: "ChatDeepSeek", modelArg: "model", defaultModel: "deepseek-v4-flash", extraArgs: 'modelKwargs: { thinking: { type: DEEPSEEK_THINKING } }' },
 };
+// Only these three have a native embeddings API. Anthropic, Groq and DeepSeek
+// have none, so RAG on those providers borrows OpenAI's.
+const PROVIDER_EMBEDDINGS = {
+    openai: { pkg: "@langchain/openai", className: "OpenAIEmbeddings", defaultModel: "text-embedding-3-small", envKey: "OPENAI_API_KEY" },
+    google: { pkg: "@langchain/google-genai", className: "GoogleGenerativeAIEmbeddings", defaultModel: "text-embedding-004", envKey: "GOOGLE_API_KEY" },
+    ollama: { pkg: "@langchain/ollama", className: "OllamaEmbeddings", defaultModel: "nomic-embed-text", envKey: "" },
+};
+/** Resolves which provider supplies embeddings for a given chat provider. */
+function embeddingsFor(chatProvider) {
+    const id = chatProvider in PROVIDER_EMBEDDINGS ? chatProvider : "openai";
+    return { id, borrowed: id !== chatProvider, ...PROVIDER_EMBEDDINGS[id] };
+}
+/**
+ * The scaffold installs one embeddings SDK — the one for the provider resolved
+ * at generation time — so the generated config imports only that SDK. Switching
+ * EMBEDDINGS_PROVIDER later means installing the matching package and adding a
+ * branch here.
+ */
+function generateEmbeddingsConfig(config) {
+    const e = embeddingsFor(config.provider);
+    const borrowedNote = e.borrowed
+        ? `// ${config.provider} has no embeddings API, so RAG uses ${e.id} — it needs\n` +
+            `// ${e.envKey} in addition to your chat provider's key.\n`
+        : "";
+    return `import type { Embeddings } from "@langchain/core/embeddings";
+import { ${e.className} } from "${e.pkg}";
+
+${borrowedNote}// Set EMBEDDINGS_MODEL in .env to override the default model.
+const PROVIDER = "${e.id}";
+const DEFAULT_MODEL = "${e.defaultModel}";
+const REQUIRED_KEY = "${e.envKey}";
+
+/**
+ * Builds the embeddings client for RAG.
+ *
+ * Validation happens here rather than at import time: a project that never uses
+ * RAG should not need an embeddings key, and an eager throw would take down
+ * every route rather than just the RAG one.
+ */
+export async function createEmbeddings(modelOverride?: string): Promise<Embeddings> {
+  const requested = process.env.EMBEDDINGS_PROVIDER?.trim().toLowerCase();
+  if (requested && requested !== PROVIDER) {
+    throw new Error(
+      \`EMBEDDINGS_PROVIDER="\${requested}" but this project was scaffolded with "\${PROVIDER}" embeddings. \` +
+        \`Install the matching SDK and add a branch in src/config/embeddings.ts.\`
+    );
+  }
+
+  if (REQUIRED_KEY && !process.env[REQUIRED_KEY]) {
+    throw new Error(\`\${REQUIRED_KEY} is required for "\${PROVIDER}" embeddings but is not set in .env\`);
+  }
+
+  const model = modelOverride ?? process.env.EMBEDDINGS_MODEL?.trim() ?? DEFAULT_MODEL;
+  return new ${e.className}({ model });
+}
+`;
+}
 function generateLlmConfig(config) {
     const p = PROVIDER_LLM[config.provider] ?? PROVIDER_LLM.openai;
     const envImports = config.provider === "deepseek"
@@ -363,7 +444,27 @@ function selectedApps(config) {
 function generateServer(config) {
     const apps = selectedApps(config);
     const imports = apps.map((a) => `import { ${a.fn} } from "${a.path}";`).join("\n");
-    const entries = apps.map((a) => `    "${a.route}": asApp(await ${a.fn}()),`).join("\n");
+    // RAG is the only app that can fail at startup — it needs an embeddings
+    // provider, and providers without one borrow another provider's key. Build it
+    // in a try/catch so a missing key costs /rag rather than every route.
+    const hasRag = apps.some((a) => a.route === "rag");
+    const entries = apps
+        .filter((a) => a.route !== "rag")
+        .map((a) => `    "${a.route}": asApp(await ${a.fn}()),`)
+        .join("\n");
+    const ragEntry = hasRag ? `\n    ...(ragApp ? { rag: ragApp } : {}),` : "";
+    const ragInit = hasRag
+        ? `  let ragApp: AppGraph | undefined;
+  try {
+    ragApp = asApp(await createRagApp());
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(\`RAG app unavailable (embeddings failed): \${msg}\`);
+    console.warn("  /rag routes are disabled; every other app still works.");
+  }
+
+`
+        : "";
     return `import "./config/env";
 import { fastify, type FastifyError, type FastifyReply, type FastifyRequest } from "fastify";
 import { Command } from "@langchain/langgraph";
@@ -384,19 +485,35 @@ function httpError(status: number, message: string) {
   return Object.assign(new Error(message), { statusCode: status });
 }
 
+// \`system\` is excluded: the app owns its system prompt, and accepting one
+// from the request lets any caller override it.
+const CLIENT_ROLES = ["user", "assistant"];
+
 /** Reject malformed bodies before they reach the agent. */
 function validateMessages(raw: unknown): { role: string; content: string }[] {
-  if (raw === undefined) return [];
   if (!Array.isArray(raw)) throw httpError(400, '"messages" must be an array');
+  if (raw.length === 0) throw httpError(400, '"messages" must not be empty');
   return raw.map((m, i) => {
     const { role, content } = (m ?? {}) as Record<string, unknown>;
     if (typeof role !== "string" || typeof content !== "string") {
       throw httpError(400, \`messages[\${i}] needs string "role" and "content"\`);
     }
+    if (!CLIENT_ROLES.includes(role)) {
+      throw httpError(400, \`messages[\${i}].role must be one of: \${CLIENT_ROLES.join(", ")}\`);
+    }
     return { role, content };
   });
 }
 
+/** Defaults to "default"; anything but a non-empty string is a 400, not a 500. */
+function validateThreadId(raw: unknown): string {
+  if (raw === undefined) return "default";
+  if (typeof raw !== "string" || raw.trim() === "") {
+    throw httpError(400, '"thread_id" must be a non-empty string');
+  }
+  return raw;
+}
+
 const server = fastify({ logger: false });
 
 server.setErrorHandler(async (error: FastifyError, _req: FastifyRequest, reply: FastifyReply) => {
@@ -405,8 +522,8 @@ server.setErrorHandler(async (error: FastifyError, _req: FastifyRequest, reply:
 });
 
 async function start() {
-  const apps: Record<string, AppGraph> = {
-${entries}
+${ragInit}  const apps: Record<string, AppGraph> = {
+${entries}${ragEntry}
   };
 
   const getApp = (name: string) => {
@@ -417,9 +534,9 @@ ${entries}
 
   server.post<{ Params: { app: string } }>("/:app/invoke", async (req, reply) => {
     const app = getApp(req.params.app);
-    const body = (req.body ?? {}) as { messages?: unknown; thread_id?: string };
+    const body = (req.body ?? {}) as { messages?: unknown; thread_id?: unknown };
     const messages = validateMessages(body.messages);
-    const thread_id = body.thread_id ?? "default";
+    const thread_id = validateThreadId(body.thread_id);
 
     const result = await app.invoke({ messages }, { configurable: { thread_id } });
     const last = result.messages.at(-1);
@@ -432,9 +549,9 @@ ${entries}
 
   server.post<{ Params: { app: string } }>("/:app/stream", async (req, reply) => {
     const app = getApp(req.params.app);
-    const body = (req.body ?? {}) as { messages?: unknown; thread_id?: string };
+    const body = (req.body ?? {}) as { messages?: unknown; thread_id?: unknown };
     const messages = validateMessages(body.messages);
-    const thread_id = body.thread_id ?? "default";
+    const thread_id = validateThreadId(body.thread_id);
 
     reply.raw.writeHead(200, {
       "Content-Type": "text/event-stream",
@@ -460,12 +577,13 @@ ${entries}
 
   server.post<{ Params: { app: string } }>("/:app/resume", async (req, reply) => {
     const app = getApp(req.params.app);
-    const body = (req.body ?? {}) as { thread_id?: string; decision?: string };
+    const body = (req.body ?? {}) as { thread_id?: unknown; decision?: string };
+    const thread_id = validateThreadId(body.thread_id);
     if (body.decision === undefined) {
       return reply.status(400).send({ error: '"decision" field is required' });
     }
     const result = await app.invoke(new Command({ resume: body.decision }), {
-      configurable: { thread_id: body.thread_id ?? "default" },
+      configurable: { thread_id },
     });
     const last = result.messages.at(-1);
     return reply.send({
@@ -595,7 +713,7 @@ ${supervisorTest}});
 `;
 }
 // Pattern-specific: only files for selected patterns are generated
-function getPatternFiles(config) {
+export function getPatternFiles(config) {
     const files = [];
     // Always include core files
     files.push({ path: "src/config/env.ts", content: generateEnvConfig(config) });
@@ -936,21 +1054,129 @@ export async function createAnalystApp() {
   console.log("Result:", JSON.stringify(structured ?? analysis.messages.at(-1)?.content));`);
     }
     if (config.patterns.includes("rag")) {
+        files.push({ path: "src/config/embeddings.ts", content: generateEmbeddingsConfig(config) });
+        files.push({
+            path: "src/tools/rag.ts",
+            content: `import { z } from "zod";
+import { tool } from "@langchain/core/tools";
+import type { Embeddings } from "@langchain/core/embeddings";
+import { RecursiveCharacterTextSplitter } from "@langchain/textsplitters";
+
+/** In-memory vector store — no external database required. */
+export interface InMemoryVectorStore {
+  size: number;
+  search: (query: string, k?: number) => Promise<string[]>;
+}
+
+interface Chunk {
+  content: string;
+  embedding: number[];
+}
+
+function cosineSimilarity(a: number[], b: number[]): number {
+  let dot = 0, normA = 0, normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  // Guard the zero vector: without this an empty embedding yields NaN and
+  // silently corrupts the ranking.
+  return normA === 0 || normB === 0 ? 0 : dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+export async function buildVectorStore(
+  embeddings: Embeddings,
+  documents: string[],
+  chunkSize = 500,
+  chunkOverlap = 100,
+): Promise<InMemoryVectorStore> {
+  const splitter = new RecursiveCharacterTextSplitter({ chunkSize, chunkOverlap });
+  const docs = await splitter.createDocuments(documents);
+  const texts = docs.map((d) => d.pageContent);
+  const vectors = await embeddings.embedDocuments(texts);
+  const chunks: Chunk[] = texts.map((content, i) => ({ content, embedding: vectors[i] }));
+
+  return {
+    size: chunks.length,
+    search: async (query: string, k = 4) => {
+      if (chunks.length === 0) return [];
+      const queryVector = await embeddings.embedQuery(query);
+      return chunks
+        .map((c) => ({ content: c.content, score: cosineSimilarity(queryVector, c.embedding) }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, k)
+        .map((c) => c.content);
+    },
+  };
+}
+
+export function createRetrievalTool(vectorStore: InMemoryVectorStore) {
+  return tool(
+    async ({ query, k }) => {
+      const results = await vectorStore.search(query, k);
+      if (results.length === 0) return "No relevant documents found. Try rephrasing.";
+      return results.map((r, i) => "[" + (i + 1) + "] " + r).join("\\n\\n");
+    },
+    {
+      name: "search_knowledge_base",
+      description:
+        "Search the knowledge base for relevant information. Use this to find context before answering.",
+      schema: z.object({
+        query: z.string().describe("The search query"),
+        k: z.number().optional().default(4).describe("Number of results to return"),
+      }),
+    }
+  );
+}
+
+/** Replace these with your own documents. */
+export const SAMPLE_DOCS = [
+  "LangGraph is a framework for building stateful, multi-actor applications with LLMs. It uses a graph architecture where nodes are computational steps and edges define the flow between them. Key features include persistence via checkpointing, streaming, and human-in-the-loop workflows.",
+  "The supervisor pattern uses a central coordinator that routes tasks to specialized worker agents and aggregates their results. Workers are stateless and run in isolated context windows, so the supervisor only sees each worker's final answer.",
+  "The swarm pattern lets peer agents hand off control to each other with transfer tools. Each agent is a graph node, and the active agent persists across turns, so a conversation resumes with whichever agent last held it.",
+];
+`,
+        });
         files.push({
             path: "src/apps/rag.ts",
             content: `import { MemorySaver } from "@langchain/langgraph";
 import { getLlm } from "../config/llm";
+import { createEmbeddings } from "../config/embeddings";
 import { makeAgent } from "../agents/factory";
-// TODO: Add your vector store, embeddings, and retrieval tool here.
-// See the full starter kit for a complete RAG implementation:
-// https://github.com/ac12644/langgraph-starter-kit
+import {
+  buildVectorStore,
+  createRetrievalTool,
+  SAMPLE_DOCS,
+  type InMemoryVectorStore,
+} from "../tools/rag";
+
+let _vectorStore: InMemoryVectorStore | null = null;
+
+/** Indexes the documents once; later calls reuse the same store. */
+export async function initRagStore(documents: string[] = SAMPLE_DOCS): Promise<InMemoryVectorStore> {
+  if (!_vectorStore) {
+    const embeddings = await createEmbeddings();
+    _vectorStore = await buildVectorStore(embeddings, documents);
+    console.log("RAG: indexed " + _vectorStore.size + " chunks");
+  }
+  return _vectorStore;
+}
 
-export async function createRagApp() {
+export async function createRagApp(vectorStore?: InMemoryVectorStore) {
   const llm = await getLlm();
+  const retrievalTool = createRetrievalTool(vectorStore ?? (await initRagStore()));
 
   return makeAgent({
-    name: "rag_agent", llm, tools: [],
-    system: "You are a knowledgeable assistant. Answer questions based on your knowledge.",
+    name: "rag_agent",
+    llm,
+    tools: [retrievalTool],
+    system: [
+      "You are a knowledgeable assistant with access to a knowledge base.",
+      "ALWAYS search the knowledge base before answering questions.",
+      "Base your answers on the retrieved documents. If they do not contain",
+      "the answer, say so clearly rather than guessing.",
+    ].join("\\n"),
     checkpointer: new MemorySaver(),
   });
 }
@@ -960,7 +1186,7 @@ export async function createRagApp() {
         demos.push(`  console.log("\\n=== RAG Demo ===");
   const ragApp = await createRagApp();
   const rag = await ragApp.invoke(
-    { messages: [{ role: "user", content: "What is RAG and how does it work?" }] },
+    { messages: [{ role: "user", content: "What is the supervisor pattern?" }] },
     { configurable: { thread_id: "rag-demo" } }
   );
   console.log("Result:", rag.messages.at(-1)?.content);`);
@@ -1048,7 +1274,11 @@ Provider: ${provider}${RESET}
         rl.close();
     }
 }
-main().catch((err) => {
-    console.error("Error:", err);
-    process.exit(1);
-});
+// Only run the interactive CLI when executed directly. Importing this module
+// (e.g. from the scaffolder tests) must not prompt.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    main().catch((err) => {
+        console.error("Error:", err);
+        process.exit(1);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-langgraph-app",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "Scaffold a new LangGraph multi-agent project in seconds",
   "type": "module",
   "bin": {