@langchain/langgraph-cli 0.0.0-preview.4

package/dist/graph/parser/schema/types.template.mts

@@ -0,0 +1,81 @@
+import type { BaseMessage } from "@langchain/core/messages";
+import type {
+  StateType,
+  UpdateType,
+  StateDefinition,
+} from "@langchain/langgraph";
+import type { Graph } from "@langchain/langgraph";
+import type { Pregel } from "@langchain/langgraph/pregel";
+
+// @ts-expect-error
+type AnyPregel = Pregel<any, any>;
+
+// @ts-expect-error
+type AnyGraph = Graph<any, any, any, any, any>;
+
+type Wrap<T> = (a: T) => void;
+type MatchBaseMessage<T> = T extends BaseMessage ? BaseMessage : never;
+type MatchBaseMessageArray<T> =
+  T extends Array<infer C>
+    ? Wrap<MatchBaseMessage<C>> extends Wrap<BaseMessage>
+      ? BaseMessage[]
+      : never
+    : never;
+
+type Defactorify<T> = T extends (...args: any[]) => infer R
+  ? Awaited<R>
+  : Awaited<T>;
+
+// @ts-expect-error
+type Inspect<T> = T extends unknown
+  ? {
+      [K in keyof T]: 0 extends 1 & T[K]
+        ? T[K]
+        : Wrap<MatchBaseMessageArray<T[K]>> extends Wrap<BaseMessage[]>
+          ? BaseMessage[]
+          : Wrap<MatchBaseMessage<T[K]>> extends Wrap<BaseMessage>
+            ? BaseMessage
+            : Inspect<T[K]>;
+    }
+  : never;
+
+type ReflectCompiled<T> = T extends { RunInput: infer S; RunOutput: infer U }
+  ? { state: S; update: U }
+  : never;
+
+// @ts-expect-error
+type Reflect<T> =
+  Defactorify<T> extends infer DT
+    ? DT extends {
+        compile(...args: any[]): infer Compiled;
+      }
+      ? ReflectCompiled<Compiled>
+      : ReflectCompiled<DT>
+    : never;
+
+type BuilderReflectCompiled<T> = T extends {
+  builder: {
+    _inputDefinition: infer I extends StateDefinition;
+    _outputDefinition: infer O extends StateDefinition;
+    _configSchema?: infer C extends StateDefinition | undefined;
+  };
+}
+  ? {
+      input: UpdateType<I>;
+      output: StateType<O>;
+      config: UpdateType<Exclude<C, undefined>>;
+    }
+  : never;
+
+// @ts-expect-error
+type BuilderReflect<T> =
+  Defactorify<T> extends infer DT
+    ? DT extends {
+        compile(...args: any[]): infer Compiled;
+      }
+      ? BuilderReflectCompiled<Compiled>
+      : BuilderReflectCompiled<DT>
+    : never;
+
+// @ts-expect-error
+type FilterAny<T> = 0 extends 1 & T ? never : T;

package/dist/logging.mjs

@@ -0,0 +1,50 @@
+import { createLogger, format, transports } from "winston";
+import { logger as honoLogger } from "hono/logger";
+import { consoleFormat } from "winston-console-format";
+const LOG_JSON = process.env.LOG_JSON === "true";
+const LOG_LEVEL = process.env.LOG_LEVEL || "debug";
+export const logger = createLogger({
+    level: LOG_LEVEL,
+    format: format.combine(format.errors({ stack: true }), format.timestamp(), format.json(), ...(!LOG_JSON
+        ? [
+            format.colorize({ all: true }),
+            format.padLevels(),
+            consoleFormat({
+                showMeta: true,
+                metaStrip: ["timestamp"],
+                inspectOptions: {
+                    depth: Infinity,
+                    colors: true,
+                    maxArrayLength: Infinity,
+                    breakLength: 120,
+                    compact: Infinity,
+                },
+            }),
+        ]
+        : [
+            format.printf((info) => {
+                const { timestamp, level, message, ...rest } = info;
+                let event;
+                if (typeof message === "string") {
+                    event = message;
+                }
+                else {
+                    event = JSON.stringify(message);
+                }
+                if (rest.stack) {
+                    rest.message = event;
+                    event = rest.stack;
+                }
+                return JSON.stringify({ timestamp, level, event, ...rest });
+            }),
+        ])),
+    transports: [
+        new transports.Console({
+            handleExceptions: true,
+            handleRejections: true,
+        }),
+    ],
+});
+export const requestLogger = () => honoLogger((message, ...rest) => {
+    logger.info(message, ...rest);
+});

package/dist/preload.mjs

@@ -0,0 +1,3 @@
+import { register } from "node:module";
+// enforce API @langchain/langgraph precedence
+register("./graph/load.hooks.mjs", import.meta.url);

package/dist/queue.mjs

@@ -0,0 +1,91 @@
+import { Runs, Threads } from "./storage/ops.mjs";
+import { streamState, } from "./stream.mjs";
+import { logger } from "./logging.mjs";
+import { serializeError } from "./utils/serde.mjs";
+const MAX_RETRY_ATTEMPTS = 3;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export const queue = async () => {
+    while (true) {
+        for await (const { run, attempt, signal } of Runs.next()) {
+            await worker(run, attempt, signal);
+        }
+        // TODO: this is very suboptimal, we should implement subscription to the run
+        await sleep(1000 * Math.random());
+    }
+};
+const worker = async (run, attempt, abortSignal) => {
+    const startedAt = new Date();
+    let checkpoint = undefined;
+    let exception = undefined;
+    const temporary = run.kwargs.temporary;
+    logger.info("Starting background run", {
+        run_id: run.run_id,
+        run_attempt: attempt,
+        run_created_at: run.created_at,
+        run_started_at: startedAt,
+        run_queue_ms: startedAt.valueOf() - run.created_at.valueOf(),
+    });
+    const onCheckpoint = (value) => {
+        checkpoint = value;
+    };
+    const onTaskResult = (result) => {
+        if (checkpoint == null)
+            return;
+        const index = checkpoint.tasks.findIndex((task) => task.id === result.id);
+        checkpoint.tasks[index] = {
+            ...checkpoint.tasks[index],
+            ...result,
+        };
+    };
+    try {
+        if (attempt > MAX_RETRY_ATTEMPTS) {
+            throw new Error(`Run ${run.run_id} exceeded max attempts`);
+        }
+        try {
+            const stream = streamState(run, attempt, {
+                signal: abortSignal,
+                ...(!temporary ? { onCheckpoint, onTaskResult } : undefined),
+            });
+            for await (const { event, data } of stream) {
+                await Runs.Stream.publish(run.run_id, event, data);
+            }
+        }
+        catch (error) {
+            await Runs.Stream.publish(run.run_id, "error", serializeError(error));
+            throw error;
+        }
+        const endedAt = new Date();
+        logger.info("Background run succeeded", {
+            run_id: run.run_id,
+            run_attempt: attempt,
+            run_created_at: run.created_at,
+            run_started_at: startedAt,
+            run_ended_at: endedAt,
+            run_exec_ms: endedAt.valueOf() - startedAt.valueOf(),
+        });
+        await Runs.setStatus(run.run_id, "success");
+    }
+    catch (error) {
+        const endedAt = new Date();
+        if (error instanceof Error)
+            exception = error;
+        logger.info("Background run failed", {
+            exc_info: error,
+            run_id: run.run_id,
+            run_attempt: attempt,
+            run_created_at: run.created_at,
+            run_started_at: startedAt,
+            run_ended_at: endedAt,
+            run_exec_ms: endedAt.valueOf() - startedAt.valueOf(),
+        });
+        await Runs.setStatus(run.run_id, "error");
+    }
+    finally {
+        if (temporary) {
+            await Threads.delete(run.thread_id);
+        }
+        else {
+            await Threads.setStatus(run.thread_id, { checkpoint, exception });
+        }
+    }
+};

package/dist/schemas.mjs

@@ -0,0 +1,399 @@
+import { z } from "zod";
+export const AssistantConfigurable = z
+    .object({
+    thread_id: z.string().optional(),
+    thread_ts: z.string().optional(),
+})
+    .catchall(z.unknown());
+export const AssistantConfig = z
+    .object({
+    tags: z.array(z.string()).optional(),
+    recursion_limit: z.number().int().optional(),
+    configurable: AssistantConfigurable.optional(),
+})
+    .catchall(z.unknown())
+    .describe("The configuration of an assistant.");
+export const Assistant = z.object({
+    assistant_id: z.string().uuid(),
+    graph_id: z.string(),
+    config: AssistantConfig,
+    created_at: z.string(),
+    updated_at: z.string(),
+    metadata: z.object({}).catchall(z.any()),
+});
+export const AssistantCreate = z
+    .object({
+    assistant_id: z
+        .string()
+        .uuid()
+        .describe("The ID of the assistant. If not provided, an ID is generated.")
+        .optional(),
+    graph_id: z.string().describe("The graph to use."),
+    config: AssistantConfig.optional(),
+    metadata: z
+        .object({})
+        .catchall(z.unknown())
+        .describe("Metadata for the assistant.")
+        .optional(),
+    if_exists: z
+        .union([z.literal("raise"), z.literal("do_nothing")])
+        .optional(),
+    name: z.string().optional(),
+})
+    .describe("Payload for creating an assistant.");
+export const AssistantPatch = z
+    .object({
+    graph_id: z.string().describe("The graph to use.").optional(),
+    config: AssistantConfig.optional(),
+    metadata: z
+        .object({})
+        .catchall(z.any())
+        .describe("Metadata to merge with existing assistant metadata.")
+        .optional(),
+})
+    .describe("Payload for updating an assistant.");
+export const Config = z.object({
+    tags: z.array(z.string()).optional(),
+    recursion_limit: z.number().int().optional(),
+    configurable: z.object({}).catchall(z.any()).optional(),
+});
+export const Cron = z.object({
+    cron_id: z.string().uuid(),
+    thread_id: z.string().uuid(),
+    end_time: z.string(),
+    schedule: z.string(),
+    created_at: z.string(),
+    updated_at: z.string(),
+    payload: z.object({}).catchall(z.any()),
+});
+export const CheckpointSchema = z.object({
+    checkpoint_id: z.string(),
+    checkpoint_ns: z.string().nullish(),
+    checkpoint_map: z.record(z.unknown()).nullish(),
+});
+export const CronCreate = z
+    .object({
+    thread_id: z.string().uuid(),
+    assistant_id: z.string().uuid(),
+    checkpoint_id: z.string().optional(),
+    input: z
+        .union([
+        z.array(z.object({}).catchall(z.any())),
+        z.object({}).catchall(z.any()),
+    ])
+        .optional(),
+    metadata: z
+        .object({})
+        .catchall(z.any())
+        .describe("Metadata for the run.")
+        .optional(),
+    config: AssistantConfig.optional(),
+    webhook: z.string().url().optional(),
+    interrupt_before: z.union([z.enum(["*"]), z.array(z.string())]).optional(),
+    interrupt_after: z.union([z.enum(["*"]), z.array(z.string())]).optional(),
+    multitask_strategy: z
+        .enum(["reject", "rollback", "interrupt", "enqueue"])
+        .optional(),
+})
+    .describe("Payload for creating a cron.");
+export const CronSearch = z
+    .object({
+    assistant_id: z.string().uuid().optional(),
+    thread_id: z.string().uuid().optional(),
+    limit: z
+        .number()
+        .int()
+        .gte(1)
+        .lte(1000)
+        .describe("Maximum number to return.")
+        .optional(),
+    offset: z
+        .number()
+        .int()
+        .gte(0)
+        .describe("Offset to start from.")
+        .optional(),
+})
+    .describe("Payload for listing crons");
+export const GraphSchema = z.object({
+    graph_id: z.string(),
+    input_schema: z.object({}).catchall(z.any()).optional(),
+    output_schema: z.object({}).catchall(z.any()).optional(),
+    state_schema: z.object({}).catchall(z.any()),
+    config_schema: z.object({}).catchall(z.any()),
+});
+export const Run = z.object({
+    run_id: z.string().uuid(),
+    thread_id: z.string().uuid(),
+    assistant_id: z.string().uuid(),
+    created_at: z.string(),
+    updated_at: z.string(),
+    status: z.enum([
+        "pending",
+        "running",
+        "error",
+        "success",
+        "timeout",
+        "interrupted",
+    ]),
+    metadata: z.object({}).catchall(z.any()),
+    kwargs: z.object({}).catchall(z.any()),
+    multitask_strategy: z.enum(["reject", "rollback", "interrupt", "enqueue"]),
+});
+export const RunCreate = z
+    .object({
+    assistant_id: z.union([z.string().uuid(), z.string()]),
+    checkpoint_id: z.string().optional(),
+    checkpoint: CheckpointSchema.optional(),
+    input: z
+        .union([
+        z.array(z.object({}).catchall(z.any())),
+        z.object({}).catchall(z.any()),
+        z.null(),
+    ])
+        .optional(),
+    command: z
+        .object({
+        goto: z
+            .union([
+            z.union([
+                z.string(),
+                z.object({ node: z.string(), input: z.unknown().optional() }),
+            ]),
+            z.array(z.union([
+                z.string(),
+                z.object({ node: z.string(), input: z.unknown().optional() }),
+            ])),
+        ])
+            .optional(),
+        update: z
+            .union([
+            z.record(z.unknown()),
+            z.array(z.tuple([z.string(), z.unknown()])),
+        ])
+            .optional(),
+        resume: z.unknown().optional(),
+    })
+        .optional(),
+    metadata: z
+        .object({})
+        .catchall(z.any())
+        .describe("Metadata for the run.")
+        .optional(),
+    config: AssistantConfig.optional(),
+    webhook: z.string().url().optional(),
+    interrupt_before: z.union([z.enum(["*"]), z.array(z.string())]).optional(),
+    interrupt_after: z.union([z.enum(["*"]), z.array(z.string())]).optional(),
+    on_disconnect: z
+        .enum(["cancel", "continue"])
+        .optional()
+        .default("continue"),
+    multitask_strategy: z
+        .enum(["reject", "rollback", "interrupt", "enqueue"])
+        .optional(),
+    stream_mode: z
+        .union([
+        z.array(z.enum(["values", "messages", "updates", "events", "debug"])),
+        z.enum(["values", "messages", "updates", "events", "debug"]),
+    ])
+        .optional(),
+    stream_subgraphs: z.boolean().optional(),
+    after_seconds: z.number().optional(),
+    if_not_exists: z.enum(["reject", "create"]).optional(),
+    on_completion: z.enum(["delete", "keep"]).optional(),
+    feedback_keys: z.array(z.string()).optional(),
+})
+    .describe("Payload for creating a stateful run.");
+export const RunBatchCreate = z
+    .array(RunCreate)
+    .min(1)
+    .describe("Payload for creating a batch of runs.");
+export const SearchResult = z
+    .object({
+    metadata: z
+        .object({})
+        .catchall(z.any())
+        .describe("Metadata to search for.")
+        .optional(),
+    limit: z
+        .number()
+        .int()
+        .gte(1)
+        .lte(1000)
+        .describe("Maximum number to return.")
+        .optional(),
+    offset: z
+        .number()
+        .int()
+        .gte(0)
+        .describe("Offset to start from.")
+        .optional(),
+})
+    .describe("Payload for listing runs.");
+export const AssistantSearchRequest = z
+    .object({
+    metadata: z
+        .object({})
+        .catchall(z.any())
+        .describe("Metadata to search for.")
+        .optional(),
+    graph_id: z.string().describe("Filter by graph ID.").optional(),
+    limit: z
+        .number()
+        .int()
+        .gte(1)
+        .lte(1000)
+        .describe("Maximum number to return.")
+        .optional(),
+    offset: z
+        .number()
+        .int()
+        .gte(0)
+        .describe("Offset to start from.")
+        .optional(),
+})
+    .describe("Payload for listing assistants.");
+export const ThreadSearchRequest = z
+    .object({
+    metadata: z
+        .record(z.unknown())
+        .describe("Metadata to search for.")
+        .optional(),
+    status: z
+        .enum(["idle", "busy", "interrupted"])
+        .describe("Filter by thread status.")
+        .optional(),
+    values: z
+        .record(z.unknown())
+        .describe("Filter by thread values.")
+        .optional(),
+    limit: z
+        .number()
+        .int()
+        .gte(1)
+        .lte(1000)
+        .describe("Maximum number to return.")
+        .optional(),
+    offset: z
+        .number()
+        .int()
+        .gte(0)
+        .describe("Offset to start from.")
+        .optional(),
+})
+    .describe("Payload for listing threads.");
+export const Thread = z.object({
+    thread_id: z.string().uuid(),
+    created_at: z.string(),
+    updated_at: z.string(),
+    metadata: z.record(z.unknown()).optional(),
+    status: z.enum(["idle", "busy", "interrupted"]).optional(),
+});
+export const ThreadCreate = z
+    .object({
+    thread_id: z
+        .string()
+        .uuid()
+        .describe("The ID of the thread. If not provided, an ID is generated.")
+        .optional(),
+    metadata: z
+        .object({})
+        .catchall(z.any())
+        .describe("Metadata for the thread.")
+        .optional(),
+    if_exists: z
+        .union([z.literal("raise"), z.literal("do_nothing")])
+        .optional(),
+})
+    .describe("Payload for creating a thread.");
+export const ThreadPatch = z
+    .object({
+    metadata: z
+        .object({})
+        .catchall(z.any())
+        .describe("Metadata to merge with existing thread metadata.")
+        .optional(),
+})
+    .describe("Payload for patching a thread.");
+export const ThreadState = z.object({
+    values: z.union([
+        z.array(z.object({}).catchall(z.any())),
+        z.object({}).catchall(z.any()),
+    ]),
+    next: z.array(z.string()),
+    checkpoint_id: z.string(),
+    metadata: z.object({}).catchall(z.any()),
+    created_at: z.string(),
+    parent_checkpoint_id: z.string(),
+});
+export const ThreadStatePatch = z
+    .object({ metadata: z.object({}).catchall(z.any()) })
+    .describe("Payload for patching state of a thread.");
+export const ThreadStateSearch = z.object({
+    limit: z
+        .number()
+        .int()
+        .gte(1)
+        .lte(1000)
+        .describe("The maximum number of states to return.")
+        .optional(),
+    before: z
+        .string()
+        .describe("Return states before this checkpoint ID.")
+        .optional(),
+    metadata: z
+        .object({})
+        .catchall(z.any())
+        .describe("Filter states by metadata key-value pairs.")
+        .optional(),
+});
+export const ThreadStateUpdate = z
+    .object({
+    values: z
+        .union([
+        z.array(z.object({}).catchall(z.any())),
+        z.object({}).catchall(z.any()),
+        z.null(),
+    ])
+        .optional(),
+    checkpoint_id: z.string().optional(),
+    as_node: z.string().optional(),
+})
+    .describe("Payload for adding state to a thread.");
+export const AssistantLatestVersion = z.object({
+    version: z.number(),
+});
+export const StoreListNamespaces = z.object({
+    prefix: z.array(z.string()).optional(),
+    suffix: z.array(z.string()).optional(),
+    max_depth: z.number().optional(),
+    limit: z.number().default(100).optional(),
+    offset: z.number().default(0).optional(),
+});
+export const StoreSearchItems = z.object({
+    namespace_prefix: z.array(z.string()),
+    filter: z.record(z.unknown()).optional(),
+    limit: z.number().default(10).optional(),
+    offset: z.number().default(0).optional(),
+    query: z.string().optional(),
+});
+export const StorePutItem = z.object({
+    namespace: z.array(z.string()),
+    key: z.string(),
+    value: z.record(z.unknown()),
+});
+export const StoreDeleteItem = z.object({
+    namespace: z.array(z.string()).optional(),
+    key: z.string(),
+});
+export const StoreGetItem = z.object({
+    namespace: z
+        .string()
+        .optional()
+        .transform((value) => value?.split(".") ?? []),
+    key: z.string(),
+});
+export const coercedBoolean = z.string().transform((val) => {
+    const lower = val.toLowerCase();
+    return lower === "true" || lower === "1" || lower === "yes";
+});

package/dist/server.mjs

@@ -0,0 +1,63 @@
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+import { registerFromEnv } from "./graph/load.mjs";
+import runs from "./api/runs.mjs";
+import threads from "./api/threads.mjs";
+import assistants from "./api/assistants.mjs";
+import store from "./api/store.mjs";
+import { truncate, conn as opsConn } from "./storage/ops.mjs";
+import { zValidator } from "@hono/zod-validator";
+import { z } from "zod";
+import { queue } from "./queue.mjs";
+import { logger, requestLogger } from "./logging.mjs";
+import { checkpointer } from "./storage/checkpoint.mjs";
+import { store as graphStore } from "./storage/store.mjs";
+const app = new Hono();
+app.use(cors());
+app.use(requestLogger());
+app.route("/", assistants);
+app.route("/", runs);
+app.route("/", threads);
+app.route("/", store);
+app.get("/info", (c) => c.json({ flags: { assistants: true, crons: false } }));
+app.post("/internal/truncate", zValidator("json", z.object({
+    runs: z.boolean().optional(),
+    threads: z.boolean().optional(),
+    assistants: z.boolean().optional(),
+    checkpointer: z.boolean().optional(),
+    store: z.boolean().optional(),
+})), (c) => {
+    const { runs, threads, assistants, checkpointer, store } = c.req.valid("json");
+    truncate({ runs, threads, assistants, checkpointer, store });
+    return c.json({ ok: true });
+});
+export const StartServerSchema = z.object({
+    port: z.number(),
+    nWorkers: z.number(),
+    host: z.string(),
+    cwd: z.string(),
+    graphs: z.record(z.string()),
+});
+export async function startServer(options) {
+    logger.info(`Initializing storage...`);
+    const callbacks = await Promise.all([
+        opsConn.initialize(options.cwd),
+        checkpointer.initialize(options.cwd),
+        graphStore.initialize(options.cwd),
+    ]);
+    const cleanup = async () => {
+        logger.info(`Flushing to persistent storage, exiting...`);
+        await Promise.all(callbacks.map((c) => c.flush()));
+    };
+    logger.info(`Registering graphs from ${options.cwd}`);
+    await registerFromEnv(options.graphs, { cwd: options.cwd });
+    logger.info(`Starting ${options.nWorkers} workers`);
+    for (let i = 0; i < options.nWorkers; i++)
+        queue();
+    return new Promise((resolve) => {
+        serve({ fetch: app.fetch, port: options.port, hostname: options.host }, (c) => {
+            resolve({ host: `${c.address}:${c.port}`, cleanup });
+        });
+    });
+}