langgraph-api 0.0.13__py3-none-any.whl → 0.0.15__py3-none-any.whl

langgraph_api/js/client.mts

@@ -1,9 +1,12 @@
+/// <reference types="./global.d.ts" />
+
 import { z } from "zod";
-import { Hono } from "hono";
+import { Context, Hono } from "hono";
 import { serve } from "@hono/node-server";
 import { zValidator } from "@hono/zod-validator";
 import { streamSSE } from "hono/streaming";
 import { HTTPException } from "hono/http-exception";
+import { Agent, fetch } from "undici";
 import pRetry from "p-retry";
 import {
   BaseStore,
@@ -24,11 +27,10 @@ import {
 import { createHash } from "node:crypto";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { serialiseAsDict } from "./src/utils/serde.mjs";
+import { serialiseAsDict, serializeError } from "./src/utils/serde.mjs";
 import * as importMap from "./src/utils/importMap.mjs";
 
 import { createLogger, format, transports } from "winston";
-import { Agent, fetch } from "undici";
 
 import { load } from "@langchain/core/load";
 import { BaseMessageChunk, isBaseMessage } from "@langchain/core/messages";
@@ -102,13 +104,10 @@ async function getOrExtractSchema(graphId: string) {
 }
 
 const GRAPH_SOCKET = "./graph.sock";
-const CHECKPOINTER_SOCKET = "./checkpointer.sock";
-const STORE_SOCKET = "./store.sock";
-
-const checkpointerDispatcher = new Agent({
-  connect: { socketPath: CHECKPOINTER_SOCKET },
+const REMOTE_SOCKET = "./checkpointer.sock";
+const remoteDispatcher = new Agent({
+  connect: { socketPath: REMOTE_SOCKET },
 });
-const storeDispatcher = new Agent({ connect: { socketPath: STORE_SOCKET } });
 
 const RunnableConfigSchema = z.object({
   tags: z.array(z.string()).optional(),
@@ -161,22 +160,71 @@ function tryFetch(...args: Parameters<typeof fetch>) {
   );
 }
 
-class RemoteCheckpointer extends BaseCheckpointSaver<number | string> {
-  async getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined> {
-    const res = await tryFetch("http://checkpointer/get_tuple", {
-      dispatcher: checkpointerDispatcher,
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ config }),
+async function sendRecv<T = any>(
+  method: `${"checkpointer" | "store"}_${string}`,
+  data: unknown
+): Promise<T> {
+  const res = await tryFetch(`http://remote/${method}`, {
+    dispatcher: remoteDispatcher,
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(data),
+  });
+
+  return (await load(await res.text(), {
+    importMap,
+    optionalImportEntrypoints: [],
+    optionalImportsMap: {},
+    secretsMap: {},
+  })) as T;
+}
+
+const handleInvoke = <T extends z.ZodType<any>>(
+  name: string,
+  _schema: T,
+  handler: (rawPayload: z.infer<T>) => Promise<any>
+) => {
+  return async (c: Context<any, any, { in: z.infer<T>; out: any }>) => {
+    const graphId = c.req.param("graphId");
+    const body = c.req.valid("json") as any;
+    const response = await handler({ graph_id: graphId, ...body });
+    return c.json(response);
+  };
+};
+
+const handleStream = <T extends z.ZodType<any>>(
+  name: string,
+  _schema: T,
+  handler: (rawPayload: z.infer<T>) => AsyncGenerator<any, void, unknown>
+) => {
+  return (c: Context<any, any, { in: z.infer<T>; out: any }>) => {
+    const graphId = c.req.param("graphId");
+    const body = c.req.valid("json") as any;
+    return streamSSE(c, async (stream) => {
+      try {
+        for await (const data of handler({ graph_id: graphId, ...body })) {
+          await stream.writeSSE({
+            data: serialiseAsDict(data),
+            event: name,
+          });
+        }
+      } catch (error) {
+        // Still print out the error, as the stack
+        // trace is not carried over in Python
+        logger.error(error);
+
+        await stream.writeSSE({
+          event: "error",
+          data: serialiseAsDict(serializeError(error)),
+        });
+      }
     });
+  };
+};
 
-    const text = await res.text();
-    const result = (await load(text, {
-      importMap,
-      optionalImportEntrypoints: [],
-      optionalImportsMap: {},
-      secretsMap: {},
-    })) as any;
+class RemoteCheckpointer extends BaseCheckpointSaver<number | string> {
+  async getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined> {
+    const result = await sendRecv("checkpointer_get_tuple", { config });
 
     if (!result) return undefined;
     return {
@@ -187,6 +235,7 @@ class RemoteCheckpointer extends BaseCheckpointSaver<number | string> {
       pendingWrites: result.pending_writes,
     };
   }
+
   async *list(
     config: RunnableConfig,
     options?: {
@@ -195,20 +244,7 @@ class RemoteCheckpointer extends BaseCheckpointSaver<number | string> {
       filter?: Record<string, any>;
     }
   ): AsyncGenerator<CheckpointTuple> {
-    const res = await tryFetch("http://checkpointer/list", {
-      dispatcher: checkpointerDispatcher,
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ config, ...options }),
-    });
-
-    const text = await res.text();
-    const result = (await load(text, {
-      importMap,
-      optionalImportEntrypoints: [],
-      optionalImportsMap: {},
-      secretsMap: {},
-    })) as any;
+    const result = await sendRecv("checkpointer_list", { config, ...options });
 
     for (const item of result) {
       yield {
@@ -217,28 +253,22 @@ class RemoteCheckpointer extends BaseCheckpointSaver<number | string> {
         metadata: item.metadata,
         parentConfig: item.parent_config,
         pendingWrites: item.pending_writes,
-      } satisfies CheckpointTuple;
+      };
     }
   }
+
   async put(
     config: RunnableConfig,
     checkpoint: Checkpoint,
     metadata: CheckpointMetadata,
     newVersions: ChannelVersions
   ): Promise<RunnableConfig> {
-    const response = await tryFetch("http://checkpointer/put", {
-      dispatcher: checkpointerDispatcher,
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        config,
-        checkpoint,
-        metadata,
-        new_versions: newVersions,
-      }),
+    return await sendRecv<RunnableConfig>("checkpointer_put", {
+      config,
+      checkpoint,
+      metadata,
+      new_versions: newVersions,
     });
-
-    return (await response.json()) as RunnableConfig;
   }
 
   async putWrites(
@@ -246,13 +276,7 @@ class RemoteCheckpointer extends BaseCheckpointSaver<number | string> {
     writes: [string, unknown][],
     taskId: string
   ): Promise<void> {
-    // Implementation of the inherited abstract member 'putWrites'
-    await tryFetch("http://checkpointer/put_writes", {
-      dispatcher: checkpointerDispatcher,
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ config, writes, taskId }),
-    });
+    await sendRecv("checkpointer_put_writes", { config, writes, taskId });
   }
 
   getNextVersion(
@@ -346,14 +370,10 @@ export class RemoteStore extends BaseStore {
   async batch<Op extends Operation[]>(
     operations: Op
   ): Promise<OperationResults<Op>> {
-    const response = await tryFetch("http://store/items/batch", {
-      dispatcher: storeDispatcher,
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ operations: operations.map(camelToSnake) }),
+    const results = await sendRecv<PyResult[]>("store_batch", {
+      operations: operations.map(camelToSnake),
     });
 
-    const results = (await response.json()) as PyResult[];
     return results.map((result) => {
       if (Array.isArray(result)) {
         return result.map((item) => pyItemToJs(item));
@@ -370,16 +390,10 @@ export class RemoteStore extends BaseStore {
   }
 
   async get(namespace: string[], key: string): Promise<Item | null> {
-    const queryParams = new URLSearchParams({
+    return await sendRecv<Item | null>("store_get", {
       namespace: namespace.join("."),
       key,
     });
-    const urlWithParams = `http://store/items?${queryParams.toString()}`;
-    const response = await tryFetch(urlWithParams, {
-      dispatcher: storeDispatcher,
-      method: "GET",
-    });
-    return (await response.json()) as Item | null;
   }
 
   async search(
@@ -390,13 +404,10 @@ export class RemoteStore extends BaseStore {
       offset?: number;
     }
   ): Promise<Item[]> {
-    const response = await tryFetch("http://store/items/search", {
-      dispatcher: storeDispatcher,
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ namespace_prefix: namespacePrefix, ...options }),
+    return await sendRecv<Item[]>("store_search", {
+      namespace_prefix: namespacePrefix,
+      ...options,
     });
-    return (await response.json()) as Item[];
   }
 
   async put(
@@ -404,21 +415,11 @@ export class RemoteStore extends BaseStore {
     key: string,
     value: Record<string, any>
   ): Promise<void> {
-    await tryFetch("http://store/items", {
-      dispatcher: storeDispatcher,
-      method: "PUT",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ namespace, key, value }),
-    });
+    await sendRecv("store_put", { namespace, key, value });
   }
 
   async delete(namespace: string[], key: string): Promise<void> {
-    await tryFetch("http://store/items", {
-      dispatcher: storeDispatcher,
-      method: "DELETE",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ namespace, key }),
-    });
+    await sendRecv("store_delete", { namespace, key });
   }
 
   async listNamespaces(options: {
@@ -428,14 +429,10 @@ export class RemoteStore extends BaseStore {
     limit?: number;
     offset?: number;
   }): Promise<string[][]> {
-    const response = await tryFetch("http://store/list/namespaces", {
-      dispatcher: storeDispatcher,
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ max_depth: options?.maxDepth, ...options }),
-    });
-
-    const data = (await response.json()) as { namespaces: string[][] };
+    const data = await sendRecv<{ namespaces: string[][] }>(
+      "store_list_namespaces",
+      { max_depth: options?.maxDepth, ...options }
+    );
     return data.namespaces;
   }
 }
@@ -451,6 +448,272 @@ const ExtraStreamModeSchema = z.union([
   z.literal("messages"),
 ]);
 
+const StreamEventsPayload = z.object({
+  graph_id: z.string(),
+  input: z.unknown(),
+  command: z.object({ resume: z.unknown() }).nullish(),
+  stream_mode: z
+    .union([ExtraStreamModeSchema, z.array(ExtraStreamModeSchema)])
+    .optional(),
+  config: RunnableConfigSchema.nullish(),
+  interrupt_before: z.union([z.array(z.string()), z.literal("*")]).nullish(),
+  interrupt_after: z.union([z.array(z.string()), z.literal("*")]).nullish(),
+  subgraphs: z.boolean().optional(),
+});
+
+async function* streamEventsRequest(
+  rawPayload: z.infer<typeof StreamEventsPayload>
+) {
+  const { graph_id: graphId, ...payload } = rawPayload;
+  const graph = getGraph(graphId);
+
+  const input = payload.command ? new Command(payload.command) : payload.input;
+
+  const userStreamMode =
+    payload.stream_mode == null
+      ? []
+      : Array.isArray(payload.stream_mode)
+        ? payload.stream_mode
+        : [payload.stream_mode];
+
+  const graphStreamMode: Set<"updates" | "debug" | "values"> = new Set();
+  if (payload.stream_mode) {
+    for (const mode of userStreamMode) {
+      if (mode === "messages") {
+        graphStreamMode.add("values");
+      } else {
+        graphStreamMode.add(mode);
+      }
+    }
+  }
+
+  const config = getRunnableConfig(payload.config);
+
+  const messages: Record<string, BaseMessageChunk> = {};
+  const completedIds = new Set<string>();
+
+  let interruptBefore: typeof payload.interrupt_before =
+    payload.interrupt_before ?? undefined;
+
+  if (Array.isArray(interruptBefore) && interruptBefore.length === 0)
+    interruptBefore = undefined;
+
+  let interruptAfter: typeof payload.interrupt_after =
+    payload.interrupt_after ?? undefined;
+
+  if (Array.isArray(interruptAfter) && interruptAfter.length === 0)
+    interruptAfter = undefined;
+
+  const streamMode = [...graphStreamMode];
+
+  for await (const data of graph.streamEvents(input, {
+    ...config,
+    version: "v2",
+    streamMode,
+    subgraphs: payload.subgraphs,
+    interruptBefore,
+    interruptAfter,
+  })) {
+    // TODO: upstream this fix to LangGraphJS
+    if (streamMode.length === 1 && !Array.isArray(data.data.chunk)) {
+      data.data.chunk = [streamMode[0], data.data.chunk];
+    }
+
+    if (payload.subgraphs) {
+      if (Array.isArray(data.data.chunk) && data.data.chunk.length === 2) {
+        data.data.chunk = [[], ...data.data.chunk];
+      }
+    }
+
+    yield data;
+
+    if (userStreamMode.includes("messages")) {
+      if (data.event === "on_chain_stream" && data.run_id === config.runId) {
+        const newMessages: Array<BaseMessageChunk> = [];
+        const [_, chunk]: [string, any] = data.data.chunk;
+
+        let chunkMessages: Array<BaseMessageChunk> = [];
+        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: "on_custom_event",
+            name: "messages/complete",
+            data: newMessages,
+          };
+        }
+      } else if (
+        data.event === "on_chat_model_stream" &&
+        !data.tags?.includes("nostream")
+      ) {
+        const message: BaseMessageChunk = data.data.chunk;
+
+        if (!message.id) continue;
+
+        if (messages[message.id] == null) {
+          messages[message.id] = message;
+          yield {
+            event: "on_custom_event",
+            name: "messages/metadata",
+            data: { [message.id]: { metadata: data.metadata } },
+          };
+        } else {
+          messages[message.id] = messages[message.id].concat(message);
+        }
+
+        yield {
+          event: "on_custom_event",
+          name: "messages/partial",
+          data: [messages[message.id]],
+        };
+      }
+    }
+  }
+}
+
+const GetGraphPayload = z.object({
+  graph_id: z.string(),
+  config: RunnableConfigSchema.nullish(),
+  xray: z.union([z.number(), z.boolean()]).nullish(),
+});
+
+async function getGraphRequest(rawPayload: z.infer<typeof GetGraphPayload>) {
+  const { graph_id: graphId, ...payload } = rawPayload;
+  const graph = getGraph(graphId);
+  return graph
+    .getGraph({
+      ...getRunnableConfig(payload.config),
+      xray: payload.xray ?? undefined,
+    })
+    .toJSON();
+}
+
+const GetSubgraphsPayload = z.object({
+  graph_id: z.string(),
+  namespace: z.string().nullish(),
+  recurse: z.boolean().nullish(),
+});
+
+async function getSubgraphsRequest(
+  rawPayload: z.infer<typeof GetSubgraphsPayload>
+) {
+  const { graph_id: graphId, ...payload } = rawPayload;
+  const graph = getGraph(graphId);
+  const result: Array<[name: string, Record<string, any>]> = [];
+
+  const graphSchema = await getOrExtractSchema(graphId);
+  const rootGraphId = Object.keys(graphSchema).find((i) => !i.includes("|"));
+
+  if (!rootGraphId) throw new Error("Failed to find root graph");
+
+  for (const [name] of graph.getSubgraphs(
+    payload.namespace ?? undefined,
+    payload.recurse ?? undefined
+  )) {
+    const schema =
+      graphSchema[`${rootGraphId}|${name}`] || graphSchema[rootGraphId];
+    result.push([name, schema]);
+  }
+
+  // TODO: make this a stream
+  return Object.fromEntries(result);
+}
+
+const GetStatePayload = z.object({
+  graph_id: z.string(),
+  config: RunnableConfigSchema,
+  subgraphs: z.boolean().nullish(),
+});
+
+async function getStateRequest(rawPayload: z.infer<typeof GetStatePayload>) {
+  const { graph_id: graphId, ...payload } = rawPayload;
+  const graph = getGraph(graphId);
+
+  const state = await graph.getState(getRunnableConfig(payload.config), {
+    subgraphs: payload.subgraphs ?? undefined,
+  });
+
+  // TODO: just send the JSON directly, don't ser/de twice
+  return JSON.parse(serialiseAsDict(state));
+}
+
+const UpdateStatePayload = z.object({
+  graph_id: z.string(),
+  config: RunnableConfigSchema,
+  values: z.unknown(),
+  as_node: z.string().nullish(),
+});
+
+async function updateStateRequest(
+  rawPayload: z.infer<typeof UpdateStatePayload>
+) {
+  const { graph_id: graphId, ...payload } = rawPayload;
+  const graph = getGraph(graphId);
+
+  const config = await graph.updateState(
+    getRunnableConfig(payload.config),
+    payload.values,
+    payload.as_node ?? undefined
+  );
+
+  return config;
+}
+
+const GetSchemaPayload = z.object({ graph_id: z.string() });
+
+async function getSchemaRequest(payload: z.infer<typeof GetSchemaPayload>) {
+  const { graph_id: graphId } = payload;
+  const schemas = await getOrExtractSchema(graphId);
+  const rootGraphId = Object.keys(schemas).find((i) => !i.includes("|"));
+  if (!rootGraphId) {
+    throw new Error("Failed to find root graph");
+  }
+  return schemas[rootGraphId];
+}
+
+const GetStateHistoryPayload = z.object({
+  graph_id: z.string(),
+  config: RunnableConfigSchema,
+  limit: z.number().nullish(),
+  before: RunnableConfigSchema.nullish(),
+  filter: z.record(z.unknown()).nullish(),
+});
+
+async function* getStateHistoryRequest(
+  rawPayload: z.infer<typeof GetStateHistoryPayload>
+) {
+  const { graph_id: graphId, ...payload } = rawPayload;
+  const graph = getGraph(graphId);
+
+  for await (const item of graph.getStateHistory(
+    getRunnableConfig(payload.config),
+    {
+      limit: payload.limit ?? undefined,
+      before: payload.before ? getRunnableConfig(payload.before) : undefined,
+      filter: payload.filter ?? undefined,
+    }
+  )) {
+    yield item;
+  }
+}
+
 const __dirname = new URL(".", import.meta.url).pathname;
 
 async function main() {
@@ -492,339 +755,48 @@ async function main() {
 
   app.post(
     "/:graphId/streamEvents",
-    zValidator(
-      "json",
-      z.object({
-        input: z.unknown(),
-        command: z.object({ resume: z.unknown() }).nullish(),
-        stream_mode: z
-          .union([ExtraStreamModeSchema, z.array(ExtraStreamModeSchema)])
-          .optional(),
-        config: RunnableConfigSchema.nullish(),
-        interrupt_before: z
-          .union([z.array(z.string()), z.literal("*")])
-          .nullish(),
-        interrupt_after: z
-          .union([z.array(z.string()), z.literal("*")])
-          .nullish(),
-        subgraphs: z.boolean().optional(),
-      })
-    ),
-    async (c) => {
-      const graph = getGraph(c.req.param("graphId"));
-      const payload = c.req.valid("json");
-
-      const input = payload.command
-        ? // @ts-expect-error Update LG.js to mark `resume as optional
-          new Command(payload.command)
-        : payload.input;
-
-      const userStreamMode =
-        payload.stream_mode == null
-          ? []
-          : Array.isArray(payload.stream_mode)
-            ? payload.stream_mode
-            : [payload.stream_mode];
-
-      const graphStreamMode: Set<"updates" | "debug" | "values"> = new Set();
-      if (payload.stream_mode) {
-        for (const mode of userStreamMode) {
-          if (mode === "messages") {
-            graphStreamMode.add("values");
-          } else {
-            graphStreamMode.add(mode);
-          }
-        }
-      }
-
-      const config = getRunnableConfig(payload.config);
-
-      return streamSSE(c, async (stream) => {
-        const messages: Record<string, BaseMessageChunk> = {};
-        const completedIds = new Set<string>();
-
-        let interruptBefore: typeof payload.interrupt_before =
-          payload.interrupt_before ?? undefined;
-
-        if (Array.isArray(interruptBefore) && interruptBefore.length === 0)
-          interruptBefore = undefined;
-
-        let interruptAfter: typeof payload.interrupt_after =
-          payload.interrupt_after ?? undefined;
-
-        if (Array.isArray(interruptAfter) && interruptAfter.length === 0)
-          interruptAfter = undefined;
-
-        const streamMode = [...graphStreamMode];
-
-        try {
-          for await (const data of graph.streamEvents(input, {
-            ...config,
-            version: "v2",
-            streamMode,
-            subgraphs: payload.subgraphs,
-            interruptBefore,
-            interruptAfter,
-          })) {
-            // TODO: upstream this fix to LangGraphJS
-            if (streamMode.length === 1 && !Array.isArray(data.data.chunk)) {
-              data.data.chunk = [streamMode[0], data.data.chunk];
-            }
-
-            if (payload.subgraphs) {
-              if (
-                Array.isArray(data.data.chunk) &&
-                data.data.chunk.length === 2
-              ) {
-                data.data.chunk = [[], ...data.data.chunk];
-              }
-            }
-
-            await stream.writeSSE({
-              event: "streamLog",
-              data: serialiseAsDict(data),
-            });
-
-            if (userStreamMode.includes("messages")) {
-              if (
-                data.event === "on_chain_stream" &&
-                data.run_id === config.runId
-              ) {
-                const newMessages: Array<BaseMessageChunk> = [];
-                const [_, chunk]: [string, any] = data.data.chunk;
-
-                let chunkMessages: Array<BaseMessageChunk> = [];
-                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) {
-                  await stream.writeSSE({
-                    event: "streamLog",
-                    data: serialiseAsDict({
-                      event: "on_custom_event",
-                      name: "messages/complete",
-                      data: newMessages,
-                    }),
-                  });
-                }
-              } else if (
-                data.event === "on_chat_model_stream" &&
-                !data.tags?.includes("nostream")
-              ) {
-                const message: BaseMessageChunk = data.data.chunk;
-
-                if (!message.id) continue;
-
-                if (messages[message.id] == null) {
-                  messages[message.id] = message;
-                  await stream.writeSSE({
-                    event: "streamLog",
-                    data: serialiseAsDict({
-                      event: "on_custom_event",
-                      name: "messages/metadata",
-                      data: { [message.id]: { metadata: data.metadata } },
-                    }),
-                  });
-                } else {
-                  messages[message.id] = messages[message.id].concat(message);
-                }
-
-                await stream.writeSSE({
-                  event: "streamLog",
-                  data: serialiseAsDict({
-                    event: "on_custom_event",
-                    name: "messages/partial",
-                    data: [messages[message.id]],
-                  }),
-                });
-              }
-            }
-          }
-        } catch (error) {
-          const errorName = error instanceof Error ? error.name : "Error";
-          const errorMessage =
-            error instanceof Error ? error.message : JSON.stringify(error);
-
-          await stream.writeSSE({
-            event: "error",
-            data: serialiseAsDict({
-              error: errorName,
-              message: errorMessage,
-            }),
-          });
-
-          // Still print out the error, as the stack
-          // trace is not carried over in Python
-          logger.error(error);
-        }
-      });
-    }
+    zValidator("json", StreamEventsPayload),
+    handleStream("streamEvents", StreamEventsPayload, streamEventsRequest)
   );
 
   app.post(
     "/:graphId/getGraph",
-    zValidator(
-      "json",
-      z.object({
-        config: RunnableConfigSchema.nullish(),
-        xray: z.union([z.number(), z.boolean()]).nullish(),
-      })
-    ),
-    async (c) => {
-      const graphId = c.req.param("graphId");
-      const graph = getGraph(graphId);
-      return c.json(
-        graph
-          .getGraph({
-            ...getRunnableConfig(c.req.valid("json").config),
-            xray: c.req.valid("json").xray ?? undefined,
-          })
-          .toJSON()
-      );
-    }
+    zValidator("json", GetGraphPayload),
+    handleInvoke("getGraph", GetGraphPayload, getGraphRequest)
   );
 
   app.post(
     "/:graphId/getSubgraphs",
-    zValidator(
-      "json",
-      z.object({
-        namespace: z.string().nullish(),
-        recurse: z.boolean().nullish(),
-      })
-    ),
-
-    async (c) => {
-      const graphId = c.req.param("graphId");
-      const graph = getGraph(graphId);
-
-      const payload = c.req.valid("json");
-      const result: Array<[name: string, Record<string, any>]> = [];
-
-      const graphSchema = await getOrExtractSchema(graphId);
-      const rootGraphId = Object.keys(graphSchema).find(
-        (i) => !i.includes("|")
-      );
-
-      if (!rootGraphId)
-        throw new HTTPException(500, { message: "Failed to find root graph" });
-
-      for (const [name] of graph.getSubgraphs(
-        payload.namespace ?? undefined,
-        payload.recurse ?? undefined
-      )) {
-        const schema =
-          graphSchema[`${rootGraphId}|${name}`] || graphSchema[rootGraphId];
-        result.push([name, schema]);
-      }
-
-      return c.json(Object.fromEntries(result));
-    }
+    zValidator("json", GetSubgraphsPayload),
+    handleInvoke("getSubgraphs", GetSubgraphsPayload, getSubgraphsRequest)
   );
 
   app.post(
     "/:graphId/getState",
-    zValidator(
-      "json",
-      z.object({
-        config: RunnableConfigSchema,
-        subgraphs: z.boolean().nullish(),
-      })
-    ),
-    async (c) => {
-      const graph = getGraph(c.req.param("graphId"));
-      const payload = c.req.valid("json");
-
-      const state = await graph.getState(getRunnableConfig(payload.config), {
-        subgraphs: payload.subgraphs ?? undefined,
-      });
-      // TODO: just send the JSON directly, don't ser/de twice
-      return c.json(JSON.parse(serialiseAsDict(state)));
-    }
+    zValidator("json", GetStatePayload),
+    handleInvoke("getState", GetStatePayload, getStateRequest)
   );
 
   app.post(
     "/:graphId/updateState",
-    zValidator(
-      "json",
-      z.object({
-        config: RunnableConfigSchema,
-        values: z.unknown(),
-        as_node: z.string().nullish(),
-      })
-    ),
-    async (c) => {
-      const graph = getGraph(c.req.param("graphId"));
-      const payload = c.req.valid("json");
-
-      const config = await graph.updateState(
-        getRunnableConfig(payload.config),
-        payload.values,
-        payload.as_node ?? undefined
-      );
-
-      return c.json(config);
-    }
+    zValidator("json", UpdateStatePayload),
+    handleInvoke("updateState", UpdateStatePayload, updateStateRequest)
   );
 
-  app.post("/:graphId/getSchema", async (c) => {
-    const schemas = await getOrExtractSchema(c.req.param("graphId"));
-    const rootGraphId = Object.keys(schemas).find((i) => !i.includes("|"));
-    if (!rootGraphId) {
-      throw new HTTPException(500, { message: "Failed to find root graph" });
-    }
-    return c.json(schemas[rootGraphId]);
-  });
+  app.post(
+    "/:graphId/getSchema",
+    zValidator("json", GetSchemaPayload),
+    handleInvoke("getSchema", GetSchemaPayload, getSchemaRequest)
+  );
 
   app.post(
     "/:graphId/getStateHistory",
-    zValidator(
-      "json",
-      z.object({
-        config: RunnableConfigSchema,
-        limit: z.number().nullish(),
-        before: RunnableConfigSchema.nullish(),
-        filter: z.record(z.unknown()).nullish(),
-      })
-    ),
-    async (c) => {
-      const graph = getGraph(c.req.param("graphId"));
-      const payload = c.req.valid("json");
-
-      return streamSSE(c, async (stream) => {
-        for await (const item of graph.getStateHistory(
-          getRunnableConfig(payload.config),
-          {
-            limit: payload.limit ?? undefined,
-            before: payload.before
-              ? getRunnableConfig(payload.before)
-              : undefined,
-            filter: payload.filter ?? undefined,
-          }
-        )) {
-          await stream.writeSSE({
-            data: serialiseAsDict(item),
-            event: "getStateHistory",
-          });
-        }
-      });
-    }
+    zValidator("json", GetStateHistoryPayload),
+    handleStream(
+      "getStateHistory",
+      GetStateHistoryPayload,
+      getStateHistoryRequest
+    )
   );
 
   app.get("/ok", (c) => c.json({ ok: true }));
@@ -834,7 +806,9 @@ async function main() {
     if (err instanceof HTTPException && err.status === 401) {
       return err.getResponse();
     }
-    return c.text("Internal server error", 500);
+
+    const { message } = serializeError(err);
+    return c.text(message || "Internal server error", 500);
   });
 
   await fs.unlink(GRAPH_SOCKET).catch(() => void 0);