@langchain/langgraph-api 0.0.10

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

@@ -0,0 +1,83 @@
+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 }
+  : T extends { "~InputType": infer InputType; "~OutputType": infer OutputType }
+    ? { state: OutputType; update: InputType }
+    : 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,100 @@
+import { createLogger, format, transports } from "winston";
+import { logger as honoLogger } from "hono/logger";
+import { consoleFormat } from "winston-console-format";
+import { parse as stacktraceParser } from "stacktrace-parser";
+import { readFileSync } from "fs";
+import { codeFrameColumns } from "@babel/code-frame";
+import path from "node:path";
+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()],
+});
+const formatStack = (stack) => {
+    if (!stack)
+        return stack;
+    const [firstFile] = stacktraceParser(stack).filter((item) => !item.file?.split(path.sep).includes("node_modules") &&
+        !item.file?.startsWith("node:"));
+    if (firstFile?.file && firstFile?.lineNumber) {
+        try {
+            const filePath = firstFile.file;
+            const line = firstFile.lineNumber;
+            const column = firstFile.column ?? 0;
+            const messageLines = stack.split("\n");
+            const spliceIndex = messageLines.findIndex((i) => i.includes(filePath));
+            const padding = " ".repeat(Math.max(0, messageLines[spliceIndex].indexOf("at")));
+            const highlightCode = process.stdout.isTTY;
+            let codeFrame = codeFrameColumns(readFileSync(filePath, "utf-8"), { start: { line, column } }, { highlightCode });
+            codeFrame = codeFrame
+                .split("\n")
+                .map((i) => padding + i + "\x1b[0m")
+                .join("\n");
+            if (highlightCode) {
+                codeFrame = "\x1b[36m" + codeFrame + "\x1b[31m";
+            }
+            // insert codeframe after the line but dont lose the stack
+            return [
+                ...messageLines.slice(0, spliceIndex + 1),
+                codeFrame,
+                ...messageLines.slice(spliceIndex + 1),
+            ].join("\n");
+        }
+        catch {
+            // pass
+        }
+    }
+    return stack;
+};
+export const logError = (error, options) => {
+    let message;
+    let context = options?.context;
+    if (error instanceof Error) {
+        message = formatStack(error.stack) || error.message;
+    }
+    else {
+        message = String(error);
+        context = { ...context, error };
+    }
+    if (options?.prefix != null)
+        message = `${options.prefix}:\n${message}`;
+    logger.error(message, ...(context != null ? [context] : []));
+};
+process.on("uncaughtException", (error) => logError(error));
+process.on("unhandledRejection", (error) => logError(error));
+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,93 @@
+import { Runs, Threads } from "./storage/ops.mjs";
+import { streamState, } from "./stream.mjs";
+import { logError, 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;
+        logError(error, {
+            prefix: "Background run failed",
+            context: {
+                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,407 @@
+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().uuid().optional(),
+    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.unknown(), 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",
+            "messages-tuple",
+            "updates",
+            "events",
+            "debug",
+        ])),
+        z.enum([
+            "values",
+            "messages",
+            "messages-tuple",
+            "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", "error"])
+        .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", "error"]).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";
+});