@langchain/langgraph-cli 0.0.0-preview.4

package/dist/storage/persist.mjs

@@ -0,0 +1,69 @@
+import * as path from "node:path";
+import * as fs from "node:fs/promises";
+import * as superjson from "superjson";
+// Add custom transformers for Uint8Array
+superjson.registerCustom({
+    isApplicable: (v) => v instanceof Uint8Array,
+    serialize: (v) => Buffer.from(v).toString("base64"),
+    deserialize: (v) => new Uint8Array(Buffer.from(v, "base64")),
+}, "Uint8Array");
+export class FileSystemPersistence {
+    filepath = null;
+    data = null;
+    defaultSchema;
+    name;
+    flushTimeout = undefined;
+    constructor(name, defaultSchema) {
+        this.name = name;
+        this.defaultSchema = defaultSchema;
+    }
+    async initialize(cwd) {
+        this.filepath = path.resolve(cwd, ".langgraph_api", `${this.name}`);
+        try {
+            this.data = superjson.parse(await fs.readFile(this.filepath, "utf-8"));
+        }
+        catch {
+            this.data = this.defaultSchema();
+        }
+        await fs
+            .mkdir(path.dirname(this.filepath), { recursive: true })
+            .catch(() => void 0);
+        return this;
+    }
+    async persist() {
+        if (this.data == null || this.filepath == null)
+            return;
+        clearTimeout(this.flushTimeout);
+        await fs.writeFile(this.filepath, superjson.stringify(this.data), "utf-8");
+    }
+    schedulePersist() {
+        clearTimeout(this.flushTimeout);
+        this.flushTimeout = setTimeout(() => this.persist(), 3000);
+    }
+    async flush() {
+        await this.persist();
+    }
+    async with(fn) {
+        if (this.filepath == null || this.data == null) {
+            throw new Error(`${this.name} not initialized`);
+        }
+        try {
+            return await fn(this.data);
+        }
+        finally {
+            this.schedulePersist();
+        }
+    }
+    async *withGenerator(fn) {
+        if (this.filepath == null || this.data == null) {
+            throw new Error(`${this.name} not initialized`);
+        }
+        try {
+            const gen = typeof fn === "function" ? fn(this.data) : fn;
+            yield* gen;
+        }
+        finally {
+            this.schedulePersist();
+        }
+    }
+}

package/dist/storage/store.mjs

@@ -0,0 +1,37 @@
+import { InMemoryStore as BaseMemoryStore, } from "@langchain/langgraph";
+import { FileSystemPersistence } from "./persist.mjs";
+const conn = new FileSystemPersistence(".langgraphjs_api.store.json", () => ({
+    data: new Map(),
+    vectors: new Map(),
+}));
+class InMemoryStore extends BaseMemoryStore {
+    async initialize(cwd) {
+        await conn.initialize(cwd);
+        await conn.with(({ data, vectors }) => {
+            Object.assign(this, { data, vectors });
+        });
+        return conn;
+    }
+    async clear() {
+        await conn.with(({ data, vectors }) => {
+            data.clear();
+            vectors.clear();
+        });
+    }
+    async batch(operations) {
+        return await conn.with(() => super.batch(operations));
+    }
+    async get(...args) {
+        return await conn.with(() => super.get(...args));
+    }
+    async search(...args) {
+        return await conn.with(() => super.search(...args));
+    }
+    async put(...args) {
+        return await conn.with(() => super.put(...args));
+    }
+    async listNamespaces(...args) {
+        return await conn.with(() => super.listNamespaces(...args));
+    }
+}
+export const store = new InMemoryStore();

package/dist/stream.mjs

@@ -0,0 +1,215 @@
+import { getGraph } from "./graph/load.mjs";
+import { Client as LangSmithClient } from "langsmith";
+import { Command, Send, } from "@langchain/langgraph";
+import { runnableConfigToCheckpoint, taskRunnableConfigToCheckpoint, } from "./utils/runnableConfig.mjs";
+import { BaseMessageChunk, isBaseMessage } from "@langchain/core/messages";
+import { logger } from "./logging.mjs";
+const getLangGraphCommand = (command) => {
+    let goto = command.goto != null && !Array.isArray(command.goto)
+        ? [command.goto]
+        : command.goto;
+    return new Command({
+        goto: goto?.map((item) => {
+            if (typeof item !== "string")
+                return new Send(item.node, item.input);
+            return item;
+        }),
+        update: command.update,
+        resume: command.resume,
+    });
+};
+const isRunnableConfig = (config) => {
+    if (typeof config !== "object" || config == null)
+        return false;
+    return ("configurable" in config &&
+        typeof config.configurable === "object" &&
+        config.configurable != null);
+};
+function preprocessDebugCheckpointTask(task) {
+    if (!isRunnableConfig(task.state) ||
+        !taskRunnableConfigToCheckpoint(task.state)) {
+        return task;
+    }
+    const cloneTask = { ...task };
+    cloneTask.checkpoint = taskRunnableConfigToCheckpoint(task.state);
+    delete cloneTask.state;
+    return cloneTask;
+}
+const isConfigurablePresent = (config) => typeof config === "object" &&
+    config != null &&
+    "configurable" in config &&
+    typeof config.configurable === "object" &&
+    config.configurable != null;
+const deleteInternalConfigurableFields = (config) => {
+    if (isConfigurablePresent(config)) {
+        const newConfig = {
+            ...config,
+            configurable: Object.fromEntries(Object.entries(config.configurable).filter(([key]) => !key.startsWith("__"))),
+        };
+        delete newConfig.callbacks;
+        return newConfig;
+    }
+    return config;
+};
+function preprocessDebugCheckpoint(payload) {
+    const result = {
+        ...payload,
+        checkpoint: runnableConfigToCheckpoint(payload["config"]),
+        parent_checkpoint: runnableConfigToCheckpoint(payload["parentConfig"]),
+        tasks: payload["tasks"].map(preprocessDebugCheckpointTask),
+    };
+    // Handle LangGraph JS pascalCase vs snake_case
+    // TODO: use stream to LangGraph.JS
+    result.parent_config = payload["parentConfig"];
+    delete result.parentConfig;
+    result.config = deleteInternalConfigurableFields(result.config);
+    result.parent_config = deleteInternalConfigurableFields(result.parent_config);
+    return result;
+}
+export async function* streamState(run, attempt = 1, options) {
+    const kwargs = run.kwargs;
+    const graphId = kwargs.config?.configurable?.graph_id;
+    if (!graphId || typeof graphId !== "string") {
+        throw new Error("Invalid or missing graph_id");
+    }
+    const graph = getGraph(graphId, {
+        checkpointer: kwargs.temporary ? null : undefined,
+    });
+    const userStreamMode = kwargs.stream_mode ?? [];
+    const libStreamMode = new Set(userStreamMode.filter((mode) => mode !== "events" && mode !== "messages-tuple") ?? []);
+    if (userStreamMode.includes("messages-tuple")) {
+        libStreamMode.add("messages");
+    }
+    if (userStreamMode.includes("messages")) {
+        libStreamMode.add("values");
+    }
+    if (!libStreamMode.has("debug"))
+        libStreamMode.add("debug");
+    yield {
+        event: "metadata",
+        data: { run_id: run.run_id, attempt },
+    };
+    const metadata = {
+        ...kwargs.config?.metadata,
+        run_attempt: attempt,
+        // TODO: get langgraph version from NPM / load.hooks.mjs
+        langgraph_version: "0.2.35",
+        langgraph_plan: "developer",
+        langgraph_host: "self-hosted",
+    };
+    const events = graph.streamEvents(kwargs.command != null
+        ? getLangGraphCommand(kwargs.command)
+        : (kwargs.input ?? null), {
+        version: "v2",
+        interruptAfter: kwargs.interrupt_after,
+        interruptBefore: kwargs.interrupt_before,
+        tags: kwargs.config?.tags,
+        configurable: kwargs.config?.configurable,
+        recursionLimit: kwargs.config?.recursion_limit,
+        subgraphs: kwargs.subgraphs,
+        metadata,
+        runId: run.run_id,
+        streamMode: [...libStreamMode],
+        signal: options?.signal,
+    });
+    const messages = {};
+    const completedIds = new Set();
+    for await (const event of events) {
+        if (event.tags?.includes("langsmith:hidden"))
+            continue;
+        if (event.event === "on_chain_stream" && event.run_id === run.run_id) {
+            const [ns, mode, chunk] = (kwargs.subgraphs ? event.data.chunk : [null, ...event.data.chunk]);
+            // Listen for debug events and capture checkpoint
+            let data = chunk;
+            if (mode === "debug") {
+                const debugChunk = chunk;
+                if (debugChunk.type === "checkpoint") {
+                    const debugCheckpoint = preprocessDebugCheckpoint(debugChunk.payload);
+                    options?.onCheckpoint?.(debugCheckpoint);
+                    data = { ...debugChunk, payload: debugCheckpoint };
+                }
+                else if (debugChunk.type === "task_result") {
+                    const debugResult = preprocessDebugCheckpointTask(debugChunk.payload);
+                    options?.onTaskResult?.(debugResult);
+                    data = { ...debugChunk, payload: debugResult };
+                }
+            }
+            if (mode === "messages") {
+                if (userStreamMode.includes("messages-tuple")) {
+                    yield { event: "messages", data };
+                }
+            }
+            else if (mode === "custom") {
+                logger.warn("unhandled custom mode", { mode, chunk });
+            }
+            else if (userStreamMode.includes(mode)) {
+                if (kwargs.subgraphs && ns?.length) {
+                    yield { event: `${mode}|${ns.join("|")}`, data };
+                }
+                else {
+                    yield { event: mode, data };
+                }
+            }
+        }
+        else if (userStreamMode.includes("events")) {
+            yield { event: "events", data: event };
+        }
+        // TODO: we still rely on old messages mode based of streamMode=values
+        // In order to fully switch to library messages mode, we need to do ensure that
+        // `StreamMessagesHandler` sends the final message, which requires the following:
+        // - handleLLMEnd does not send the final message b/c handleLLMNewToken sets the this.emittedChatModelRunIds[runId] flag. Python does not do that
+        // - handleLLMEnd receives the final message as BaseMessageChunk rather than BaseMessage, which from the outside will become indistinguishable.
+        // - handleLLMEnd should not dedupe the message
+        // - Don't think there's an utility that would convert a BaseMessageChunk to a BaseMessage?
+        if (userStreamMode.includes("messages")) {
+            if (event.event === "on_chain_stream" && event.run_id === run.run_id) {
+                const newMessages = [];
+                const [_, chunk] = event.data.chunk;
+                let chunkMessages = [];
+                if (typeof chunk === "object" &&
+                    chunk != null &&
+                    "messages" in chunk &&
+                    !isBaseMessage(chunk)) {
+                    chunkMessages = chunk?.messages;
+                }
+                if (!Array.isArray(chunkMessages)) {
+                    chunkMessages = [chunkMessages];
+                }
+                for (const message of chunkMessages) {
+                    if (!message.id || completedIds.has(message.id))
+                        continue;
+                    completedIds.add(message.id);
+                    newMessages.push(message);
+                }
+                if (newMessages.length > 0) {
+                    yield { event: "messages/complete", data: newMessages };
+                }
+            }
+            else if (event.event === "on_chat_model_stream" &&
+                !event.tags?.includes("nostream")) {
+                const message = event.data.chunk;
+                if (!message.id)
+                    continue;
+                if (messages[message.id] == null) {
+                    messages[message.id] = message;
+                    yield {
+                        event: "messages/metadata",
+                        data: { [message.id]: { metadata: event.metadata } },
+                    };
+                }
+                else {
+                    messages[message.id] = messages[message.id].concat(message);
+                }
+                yield { event: "messages/partial", data: [messages[message.id]] };
+            }
+        }
+    }
+    if (kwargs.feedback_keys) {
+        const client = new LangSmithClient();
+        const data = Object.fromEntries(await Promise.all(kwargs.feedback_keys.map(async (feedback) => {
+            const { url } = await client.createPresignedFeedbackToken(run.run_id, feedback);
+            return [feedback, url];
+        })));
+        yield { event: "feedback", data };
+    }
+}

package/dist/utils/abort.mjs

@@ -0,0 +1,8 @@
+export const combineAbortSignals = (...input) => {
+    const signals = input.filter((item) => item != null);
+    if ("any" in AbortSignal)
+        return AbortSignal.any(signals);
+    const abortController = new AbortController();
+    signals.forEach((signal) => signal.addEventListener("abort", () => abortController.abort()));
+    return abortController.signal;
+};

package/dist/utils/config.mjs

@@ -0,0 +1,35 @@
+import { z } from "zod";
+const AuthConfigSchema = z.object({
+    path: z.string().optional(),
+    disable_studio_auth: z.boolean().default(false),
+});
+const IndexConfigSchema = z.object({
+    dims: z.number().optional(),
+    embed: z.string().optional(),
+    fields: z.array(z.string()).optional(),
+});
+const StoreConfigSchema = z.object({
+    index: IndexConfigSchema.optional(),
+});
+const BaseConfigSchema = z.object({
+    docker_compose_file: z.string().optional(),
+    dockerfile_lines: z.array(z.string()).default([]),
+    graphs: z.record(z.string()).default({}),
+    env: z
+        .union([z.array(z.string()), z.record(z.string()), z.string()])
+        .default({}),
+    store: StoreConfigSchema.optional(),
+    _INTERNAL_docker_tag: z.string().optional(),
+    auth: AuthConfigSchema.optional(),
+});
+export const PythonConfigSchema = BaseConfigSchema.merge(z.object({
+    python_version: z
+        .union([z.literal("3.11"), z.literal("3.12")])
+        .default("3.11"),
+    pip_config_file: z.string().optional(),
+    dependencies: z
+        .array(z.string())
+        .nonempty("You need to specify at least one dependency"),
+}));
+export const NodeConfigSchema = BaseConfigSchema.merge(z.object({ node_version: z.literal("20") }));
+export const ConfigSchema = z.union([NodeConfigSchema, PythonConfigSchema]);

package/dist/utils/error.mjs

@@ -0,0 +1 @@
+export {};

package/dist/utils/hono.mjs

@@ -0,0 +1,27 @@
+import { serialiseAsDict } from "./serde.mjs";
+import { stream } from "hono/streaming";
+import { StreamingApi } from "hono/utils/stream";
+export function jsonExtra(c, object) {
+    return new Response(serialiseAsDict(object), {
+        ...c.res,
+        headers: { ...c.res.headers, "Content-Type": "application/json" },
+    });
+}
+export function waitKeepAlive(c, promise) {
+    return stream(c, async (stream) => {
+        // keep sending newlines until we resolved the chunk
+        let keepAlive = Promise.resolve();
+        const timer = setInterval(() => {
+            keepAlive = keepAlive.then(() => stream.write("\n"));
+        }, 1000);
+        const result = await promise;
+        clearInterval(timer);
+        await keepAlive;
+        await stream.write(serialiseAsDict(result));
+    });
+}
+export const getDisconnectAbortSignal = (c, stream) => {
+    // https://github.com/honojs/hono/issues/1770
+    stream.onAbort(() => { });
+    return c.req.raw.signal;
+};

package/dist/utils/importMap.mjs

@@ -0,0 +1,55 @@
+import { PromptTemplate, AIMessagePromptTemplate, ChatMessagePromptTemplate, ChatPromptTemplate, HumanMessagePromptTemplate, MessagesPlaceholder, SystemMessagePromptTemplate, ImagePromptTemplate, PipelinePromptTemplate, } from "@langchain/core/prompts";
+import { AIMessage, AIMessageChunk, BaseMessage, BaseMessageChunk, ChatMessage, ChatMessageChunk, FunctionMessage, FunctionMessageChunk, HumanMessage, HumanMessageChunk, SystemMessage, SystemMessageChunk, ToolMessage, ToolMessageChunk, } from "@langchain/core/messages";
+import { StringPromptValue } from "@langchain/core/prompt_values";
+export const prompts__prompt = {
+    PromptTemplate,
+};
+export const schema__messages = {
+    AIMessage,
+    AIMessageChunk,
+    BaseMessage,
+    BaseMessageChunk,
+    ChatMessage,
+    ChatMessageChunk,
+    FunctionMessage,
+    FunctionMessageChunk,
+    HumanMessage,
+    HumanMessageChunk,
+    SystemMessage,
+    SystemMessageChunk,
+    ToolMessage,
+    ToolMessageChunk,
+};
+export const schema = {
+    AIMessage,
+    AIMessageChunk,
+    BaseMessage,
+    BaseMessageChunk,
+    ChatMessage,
+    ChatMessageChunk,
+    FunctionMessage,
+    FunctionMessageChunk,
+    HumanMessage,
+    HumanMessageChunk,
+    SystemMessage,
+    SystemMessageChunk,
+    ToolMessage,
+    ToolMessageChunk,
+};
+export const prompts__chat = {
+    AIMessagePromptTemplate,
+    ChatMessagePromptTemplate,
+    ChatPromptTemplate,
+    HumanMessagePromptTemplate,
+    MessagesPlaceholder,
+    SystemMessagePromptTemplate,
+};
+export const prompts__image = {
+    ImagePromptTemplate,
+};
+export const prompts__pipeline = {
+    PipelinePromptTemplate,
+};
+export const prompts__base = {
+    StringPromptValue,
+};

package/dist/utils/runnableConfig.mjs

@@ -0,0 +1,45 @@
+import { z } from "zod";
+const ConfigSchema = z.object({
+    configurable: z.object({
+        thread_id: z.string(),
+        checkpoint_id: z.string(),
+        checkpoint_ns: z.string().nullish(),
+        checkpoint_map: z.record(z.string(), z.unknown()).nullish(),
+    }),
+});
+export const runnableConfigToCheckpoint = (config) => {
+    if (!config || !config.configurable || !config.configurable.thread_id) {
+        return null;
+    }
+    const parsed = ConfigSchema.safeParse(config);
+    if (!parsed.success)
+        return null;
+    return {
+        thread_id: parsed.data.configurable.thread_id,
+        checkpoint_id: parsed.data.configurable.checkpoint_id,
+        checkpoint_ns: parsed.data.configurable.checkpoint_ns || "",
+        checkpoint_map: parsed.data.configurable.checkpoint_map || null,
+    };
+};
+const TaskConfigSchema = z.object({
+    configurable: z.object({
+        thread_id: z.string(),
+        checkpoint_id: z.string().nullish(),
+        checkpoint_ns: z.string().nullish(),
+        checkpoint_map: z.record(z.string(), z.unknown()).nullish(),
+    }),
+});
+export const taskRunnableConfigToCheckpoint = (config) => {
+    if (!config || !config.configurable || !config.configurable.thread_id) {
+        return null;
+    }
+    const parsed = TaskConfigSchema.safeParse(config);
+    if (!parsed.success)
+        return null;
+    return {
+        thread_id: parsed.data.configurable.thread_id,
+        checkpoint_id: parsed.data.configurable.checkpoint_id || null,
+        checkpoint_ns: parsed.data.configurable.checkpoint_ns || "",
+        checkpoint_map: parsed.data.configurable.checkpoint_map || null,
+    };
+};

package/dist/utils/serde.mjs

@@ -0,0 +1,20 @@
+export const serialiseAsDict = (obj) => {
+    return JSON.stringify(obj, function (key, value) {
+        const rawValue = this[key];
+        if (rawValue != null &&
+            typeof rawValue === "object" &&
+            "toDict" in rawValue &&
+            typeof rawValue.toDict === "function") {
+            // TODO: we need to upstream this to LangChainJS
+            const { type, data } = rawValue.toDict();
+            return { ...data, type };
+        }
+        return value;
+    }, 2);
+};
+export const serializeError = (error) => {
+    if (error instanceof Error) {
+        return { error: error.name, message: error.message };
+    }
+    return { error: "Error", message: JSON.stringify(error) };
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@langchain/langgraph-cli",
+  "version": "0.0.0-preview.4",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/server.mjs",
+  "bin": {
+    "langgraph": "dist/cli/cli.mjs"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "node scripts/spawn.mjs build",
+    "prepack": "pnpm run build",
+    "typecheck": "tsc --noEmit",
+    "cli": "tsx src/cli/cli.mts",
+    "cli:watch": "tsx watch src/cli/cli.mts",
+    "test:cli": "pnpm run cli dev --no-browser --config ./tests/graphs/langgraph.json",
+    "test": "vitest",
+    "test:ci": "node scripts/spawn.mjs test"
+  },
+  "dependencies": {
+    "@commander-js/extra-typings": "^13.0.0",
+    "@hono/node-server": "^1.12.0",
+    "@hono/zod-validator": "^0.2.2",
+    "@types/json-schema": "^7.0.15",
+    "@typescript/vfs": "^1.6.0",
+    "chokidar": "^4.0.3",
+    "commander": "^13.0.0",
+    "dedent": "^1.5.3",
+    "dotenv": "^16.4.7",
+    "execa": "^9.5.2",
+    "exit-hook": "^4.0.0",
+    "hono": "^4.5.4",
+    "langsmith": "^0.2.15",
+    "open": "^10.1.0",
+    "superjson": "^2.2.2",
+    "tsx": "^4.19.2",
+    "uuid": "^10.0.0",
+    "winston": "^3.17.0",
+    "winston-console-format": "^1.0.8",
+    "yaml": "^2.7.0",
+    "zod": "^3.23.8"
+  },
+  "peerDependencies": {
+    "@langchain/core": "^0.3.27",
+    "@langchain/langgraph": "^0.2.39",
+    "@langchain/langgraph-checkpoint": "^0.0.13",
+    "typescript": "^5.5.4"
+  },
+  "devDependencies": {
+    "@langchain/langgraph-sdk": "^0.0.33",
+    "@types/node": "^22.2.0",
+    "@types/uuid": "^10.0.0",
+    "postgres": "^3.4.5",
+    "prettier": "^3.3.3",
+    "vitest": "^2.1.8"
+  }
+}