create-langgraph-app 1.3.0 → 1.5.0

package/README.md

@@ -11,7 +11,7 @@ npx create-langgraph-app
 ## What it does
 
 1. Asks for your project name
-2. Lets you pick an LLM provider (OpenAI, Anthropic, Google, Groq, Ollama)
+2. Lets you pick an LLM provider (OpenAI, Anthropic, Google, Groq, DeepSeek, Ollama)
 3. Lets you select which agent patterns to include:
    - **Supervisor** — central coordinator + worker agents
    - **Swarm** — peer-to-peer agent handoffs

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";
@@ -52,8 +53,27 @@ const PROVIDERS = {
     google: { envKey: "GOOGLE_API_KEY", defaultModel: "gemini-2.0-flash" },
     groq: { envKey: "GROQ_API_KEY", defaultModel: "llama-3.3-70b-versatile" },
     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`,
@@ -67,10 +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`, ``, `PORT=3000`, ``, `# LangSmith tracing (optional)`, `# LANGCHAIN_TRACING_V2=true`, `# LANGSMITH_API_KEY=`, `# LANGSMITH_PROJECT=${config.name}`);
+    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",
@@ -90,8 +112,14 @@ function generatePackageJson(config) {
         google: "@langchain/google-genai",
         groq: "@langchain/groq",
         ollama: "@langchain/ollama",
+        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",
@@ -114,7 +142,7 @@ function generatePackageJson(config) {
     };
     return JSON.stringify(pkg, null, 2) + "\n";
 }
-function generateTsConfig() {
+export function generateTsConfig() {
     return JSON.stringify({
         compilerOptions: {
             target: "ES2022",
@@ -133,7 +161,7 @@ function generateTsConfig() {
 function generateEnvConfig(config) {
     return `import "dotenv/config";
 
-const VALID_PROVIDERS = ["openai", "anthropic", "google", "groq", "ollama"] as const;
+const VALID_PROVIDERS = ["openai", "anthropic", "google", "groq", "ollama", "deepseek"] as const;
 export type LlmProvider = (typeof VALID_PROVIDERS)[number];
 
 function resolveProvider(): LlmProvider {
@@ -150,6 +178,7 @@ const API_KEY_MAP: Record<LlmProvider, string> = {
   google: "GOOGLE_API_KEY",
   groq: "GROQ_API_KEY",
   ollama: "",
+  deepseek: "DEEPSEEK_API_KEY",
 };
 
 export const LLM_PROVIDER = resolveProvider();
@@ -162,6 +191,9 @@ if (requiredKey && !process.env[requiredKey]) {
 
 export const LLM_MODEL = process.env.LLM_MODEL || undefined;
 export const LLM_TEMPERATURE = Number(process.env.LLM_TEMPERATURE ?? 0);
+// Uses || rather than ?? so an empty DEEPSEEK_THINKING= in .env falls back
+// to "disabled" instead of sending an invalid thinking type to the API.
+export const DEEPSEEK_THINKING = process.env.DEEPSEEK_THINKING || "disabled";
 export const PORT = Number(process.env.PORT ?? 3000);
 `;
 }
@@ -173,11 +205,72 @@ const PROVIDER_LLM = {
     google: { pkg: "@langchain/google-genai", className: "ChatGoogleGenerativeAI", modelArg: "model", defaultModel: "gemini-2.0-flash" },
     groq: { pkg: "@langchain/groq", className: "ChatGroq", modelArg: "model", defaultModel: "llama-3.3-70b-versatile" },
     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"
+        ? "LLM_MODEL, LLM_TEMPERATURE, DEEPSEEK_THINKING"
+        : "LLM_MODEL, LLM_TEMPERATURE";
     return `import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
-import { LLM_MODEL, LLM_TEMPERATURE } from "./env";
+import { ${envImports} } from "./env";
 
 const DEFAULT_MODEL = "${p.defaultModel}";
 
@@ -191,7 +284,7 @@ async function createLlm(opts: LlmOptions = {}): Promise<BaseChatModel> {
   const temperature = opts.temperature ?? LLM_TEMPERATURE;
 
   const { ${p.className} } = await import("${p.pkg}");
-  return new ${p.className}({ ${p.modelArg}: model, temperature });
+  return new ${p.className}({ ${p.modelArg}: model, temperature${p.extraArgs ? `, ${p.extraArgs}` : ""} });
 }
 
 let _default: Promise<BaseChatModel> | undefined;
@@ -351,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";
@@ -393,8 +506,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) => {
@@ -583,7 +696,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) });
@@ -924,21 +1037,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(),
   });
 }
@@ -948,7 +1169,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);`);
@@ -984,6 +1205,7 @@ async function main() {
             { value: "anthropic", label: "Anthropic (Claude Sonnet)" },
             { value: "google", label: "Google (Gemini 2.0 Flash)" },
             { value: "groq", label: "Groq (Llama 3.3 70B)" },
+            { value: "deepseek", label: "DeepSeek (deepseek-v4-flash)" },
             { value: "ollama", label: "Ollama (local, no API key)" },
         ]);
         const patterns = await choose(rl, "Which patterns? (select multiple)", [
@@ -1035,7 +1257,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.3.0",
+  "version": "1.5.0",
   "description": "Scaffold a new LangGraph multi-agent project in seconds",
   "type": "module",
   "bin": {