@langchain/langgraph-sdk 0.0.38 → 0.0.40

package/dist/react/stream.js

@@ -0,0 +1,407 @@
+/* __LC_ALLOW_ENTRYPOINT_SIDE_EFFECTS__ */
+"use client";
+import { Client } from "../client.js";
+import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
+import { coerceMessageLikeToMessage, convertToChunk, } from "@langchain/core/messages";
+class StreamError extends Error {
+    constructor(data) {
+        super(data.message);
+        this.name = data.name ?? data.error ?? "StreamError";
+    }
+    static isStructuredError(error) {
+        return typeof error === "object" && error != null && "message" in error;
+    }
+}
+class MessageTupleManager {
+    constructor() {
+        Object.defineProperty(this, "chunks", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        this.chunks = {};
+    }
+    add(serialized) {
+        const chunk = convertToChunk(coerceMessageLikeToMessage(serialized));
+        const id = chunk.id;
+        if (!id)
+            return null;
+        this.chunks[id] ??= {};
+        this.chunks[id].chunk = this.chunks[id]?.chunk?.concat(chunk) ?? chunk;
+        return id;
+    }
+    clear() {
+        this.chunks = {};
+    }
+    get(id, defaultIndex) {
+        if (this.chunks[id] == null)
+            return null;
+        this.chunks[id].index ??= defaultIndex;
+        return this.chunks[id];
+    }
+}
+const toMessageDict = (chunk) => {
+    const { type, data } = chunk.toDict();
+    return { ...data, type };
+};
+function unique(array) {
+    return [...new Set(array)];
+}
+function findLastIndex(array, predicate) {
+    for (let i = array.length - 1; i >= 0; i--) {
+        if (predicate(array[i]))
+            return i;
+    }
+    return -1;
+}
+function fetchHistory(client, threadId) {
+    return client.threads.getHistory(threadId, { limit: 1000 });
+}
+function useThreadHistory(threadId, client, clearCallbackRef, submittingRef) {
+    const [history, setHistory] = useState([]);
+    const fetcher = useCallback((threadId) => {
+        if (threadId != null) {
+            return fetchHistory(client, threadId).then((history) => {
+                setHistory(history);
+                return history;
+            });
+        }
+        setHistory([]);
+        clearCallbackRef.current?.();
+        return Promise.resolve([]);
+    }, []);
+    useEffect(() => {
+        if (submittingRef.current)
+            return;
+        fetcher(threadId);
+    }, [fetcher, submittingRef, threadId]);
+    return {
+        data: history,
+        mutate: (mutateId) => fetcher(mutateId ?? threadId),
+    };
+}
+export function useStream(options) {
+    const { assistantId, threadId, withMessages, onError, onFinish } = options;
+    const client = useMemo(() => new Client({ apiUrl: options.apiUrl, apiKey: options.apiKey }), [options.apiKey, options.apiUrl]);
+    const [branchPath, setBranchPath] = useState([]);
+    const [isLoading, setIsLoading] = useState(false);
+    const [_, setEvents] = useState([]);
+    const [streamError, setStreamError] = useState(undefined);
+    const [streamValues, setStreamValues] = useState(null);
+    const messageManagerRef = useRef(new MessageTupleManager());
+    const submittingRef = useRef(false);
+    const abortRef = useRef(null);
+    const trackStreamModeRef = useRef(["values", "messages-tuple"]);
+    const trackStreamMode = useCallback((mode) => {
+        if (!trackStreamModeRef.current.includes(mode))
+            trackStreamModeRef.current.push(mode);
+    }, []);
+    const hasUpdateListener = options.onUpdateEvent != null;
+    const hasCustomListener = options.onCustomEvent != null;
+    const callbackStreamMode = useMemo(() => {
+        const modes = [];
+        if (hasUpdateListener)
+            modes.push("updates");
+        if (hasCustomListener)
+            modes.push("custom");
+        return modes;
+    }, [hasUpdateListener, hasCustomListener]);
+    const clearCallbackRef = useRef(null);
+    clearCallbackRef.current = () => {
+        setStreamError(undefined);
+        setStreamValues(null);
+    };
+    // TODO: this should be done on the server to avoid pagination
+    // TODO: should we permit adapter? SWR / React Query?
+    const history = useThreadHistory(threadId, client, clearCallbackRef, submittingRef);
+    const getMessages = useMemo(() => {
+        if (withMessages == null)
+            return undefined;
+        return (value) => Array.isArray(value[withMessages])
+            ? value[withMessages]
+            : [];
+    }, [withMessages]);
+    const [sequence, pathMap] = (() => {
+        const childrenMap = {};
+        // First pass - collect nodes for each checkpoint
+        history.data.forEach((state) => {
+            const checkpointId = state.parent_checkpoint?.checkpoint_id ?? "$";
+            childrenMap[checkpointId] ??= [];
+            childrenMap[checkpointId].push(state);
+        });
+        const rootSequence = { type: "sequence", items: [] };
+        const queue = [{ id: "$", sequence: rootSequence, path: [] }];
+        const paths = [];
+        const visited = new Set();
+        while (queue.length > 0) {
+            const task = queue.shift();
+            if (visited.has(task.id))
+                continue;
+            visited.add(task.id);
+            const children = childrenMap[task.id];
+            if (children == null || children.length === 0)
+                continue;
+            // If we've encountered a fork (2+ children), push the fork
+            // to the sequence and add a new sequence for each child
+            let fork;
+            if (children.length > 1) {
+                fork = { type: "fork", items: [] };
+                task.sequence.items.push(fork);
+            }
+            for (const value of children) {
+                const id = value.checkpoint.checkpoint_id;
+                let sequence = task.sequence;
+                let path = task.path;
+                if (fork != null) {
+                    sequence = { type: "sequence", items: [] };
+                    fork.items.unshift(sequence);
+                    path = path.slice();
+                    path.push(id);
+                    paths.push(path);
+                }
+                sequence.items.push({ type: "node", value, path });
+                queue.push({ id, sequence, path });
+            }
+        }
+        // Third pass, create a map for available forks
+        const pathMap = {};
+        for (const path of paths) {
+            const parent = path.at(-2) ?? "$";
+            pathMap[parent] ??= [];
+            pathMap[parent].unshift(path);
+        }
+        return [rootSequence, pathMap];
+    })();
+    const [flatValues, flatPaths] = (() => {
+        const result = [];
+        const flatPaths = {};
+        const forkStack = branchPath.slice();
+        const queue = [...sequence.items];
+        while (queue.length > 0) {
+            const item = queue.shift();
+            if (item.type === "node") {
+                result.push(item.value);
+                flatPaths[item.value.checkpoint.checkpoint_id] = {
+                    current: item.path,
+                    branches: item.path.length > 0 ? pathMap[item.path.at(-2) ?? "$"] ?? [] : [],
+                };
+            }
+            if (item.type === "fork") {
+                const forkId = forkStack.shift();
+                const index = forkId != null
+                    ? item.items.findIndex((value) => {
+                        const firstItem = value.items.at(0);
+                        if (!firstItem || firstItem.type !== "node")
+                            return false;
+                        return firstItem.value.checkpoint.checkpoint_id === forkId;
+                    })
+                    : -1;
+                const nextItems = item.items.at(index)?.items ?? [];
+                queue.push(...nextItems);
+            }
+        }
+        return [result, flatPaths];
+    })();
+    const threadHead = flatValues.at(-1);
+    const historyValues = threadHead?.values ?? {};
+    const historyError = (() => {
+        const error = threadHead?.tasks?.at(-1)?.error;
+        if (error == null)
+            return undefined;
+        try {
+            const parsed = JSON.parse(error);
+            if (StreamError.isStructuredError(parsed)) {
+                return new StreamError(parsed);
+            }
+            return parsed;
+        }
+        catch {
+            // do nothing
+        }
+        return error;
+    })();
+    const messageMetadata = (() => {
+        if (getMessages == null)
+            return undefined;
+        const alreadyShown = new Set();
+        return getMessages(historyValues).map((message, idx) => {
+            const messageId = message.id ?? idx;
+            const firstSeenIdx = findLastIndex(history.data, (state) => getMessages(state.values)
+                .map((m, idx) => m.id ?? idx)
+                .includes(messageId));
+            const firstSeen = history.data[firstSeenIdx];
+            let branch = firstSeen
+                ? flatPaths[firstSeen.checkpoint.checkpoint_id]
+                : undefined;
+            if (!branch?.current?.length)
+                branch = undefined;
+            // serialize branches
+            const optionsShown = branch?.branches?.flat(2).join(",");
+            if (optionsShown) {
+                if (alreadyShown.has(optionsShown))
+                    branch = undefined;
+                alreadyShown.add(optionsShown);
+            }
+            return {
+                messageId: messageId.toString(),
+                firstSeenState: firstSeen,
+                branch: branch?.current?.join(">"),
+                branchOptions: branch?.branches?.map((b) => b.join(">")),
+            };
+        });
+    })();
+    const stop = useCallback(() => {
+        if (abortRef.current != null)
+            abortRef.current.abort();
+        abortRef.current = null;
+    }, []);
+    const submit = async (values, submitOptions) => {
+        try {
+            setIsLoading(true);
+            setStreamError(undefined);
+            submittingRef.current = true;
+            abortRef.current = new AbortController();
+            let usableThreadId = threadId;
+            if (!usableThreadId) {
+                const thread = await client.threads.create();
+                options?.onThreadId?.(thread.thread_id);
+                usableThreadId = thread.thread_id;
+            }
+            const streamMode = unique([
+                ...(submitOptions?.streamMode ?? []),
+                ...trackStreamModeRef.current,
+                ...callbackStreamMode,
+            ]);
+            const checkpoint = submitOptions?.checkpoint ?? threadHead?.checkpoint ?? undefined;
+            // @ts-expect-error
+            if (checkpoint != null)
+                delete checkpoint.thread_id;
+            const run = (await client.runs.stream(usableThreadId, assistantId, {
+                input: values,
+                config: submitOptions?.config,
+                command: submitOptions?.command,
+                interruptBefore: submitOptions?.interruptBefore,
+                interruptAfter: submitOptions?.interruptAfter,
+                metadata: submitOptions?.metadata,
+                multitaskStrategy: submitOptions?.multitaskStrategy,
+                onCompletion: submitOptions?.onCompletion,
+                onDisconnect: submitOptions?.onDisconnect ?? "cancel",
+                signal: abortRef.current.signal,
+                checkpoint,
+                streamMode,
+            }));
+            // Unbranch things
+            const newPath = submitOptions?.checkpoint?.checkpoint_id
+                ? flatPaths[submitOptions?.checkpoint?.checkpoint_id]?.current
+                : undefined;
+            if (newPath != null)
+                setBranchPath(newPath ?? []);
+            // Assumption: we're setting the initial value
+            // Used for instant feedback
+            setStreamValues(() => {
+                const values = { ...historyValues };
+                if (submitOptions?.optimisticValues != null) {
+                    return {
+                        ...values,
+                        ...(typeof submitOptions.optimisticValues === "function"
+                            ? submitOptions.optimisticValues(values)
+                            : submitOptions.optimisticValues),
+                    };
+                }
+                return values;
+            });
+            let streamError;
+            for await (const { event, data } of run) {
+                setEvents((events) => [...events, { event, data }]);
+                if (event === "error") {
+                    streamError = new StreamError(data);
+                    break;
+                }
+                if (event === "updates") {
+                    options.onUpdateEvent?.(data);
+                }
+                if (event === "custom") {
+                    options.onCustomEvent?.(data);
+                }
+                if (event === "metadata") {
+                    options.onMetadataEvent?.(data);
+                }
+                if (event === "values") {
+                    setStreamValues(data);
+                }
+                if (event === "messages") {
+                    if (!getMessages)
+                        continue;
+                    const [serialized] = data;
+                    const messageId = messageManagerRef.current.add(serialized);
+                    if (!messageId) {
+                        console.warn("Failed to add message to manager, no message ID found");
+                        continue;
+                    }
+                    setStreamValues((streamValues) => {
+                        const values = { ...historyValues, ...streamValues };
+                        // Assumption: we're concatenating the message
+                        const messages = getMessages(values).slice();
+                        const { chunk, index } = messageManagerRef.current.get(messageId, messages.length) ?? {};
+                        if (!chunk || index == null)
+                            return values;
+                        messages[index] = toMessageDict(chunk);
+                        return { ...values, [withMessages]: messages };
+                    });
+                }
+            }
+            // TODO: stream created checkpoints to avoid an unnecessary network request
+            const result = await history.mutate(usableThreadId);
+            // TODO: write tests verifying that stream values are properly handled lifecycle-wise
+            setStreamValues(null);
+            if (streamError != null)
+                throw streamError;
+            const lastHead = result.at(0);
+            if (lastHead)
+                onFinish?.(lastHead);
+        }
+        catch (error) {
+            if (!(error instanceof Error &&
+                (error.name === "AbortError" || error.name === "TimeoutError"))) {
+                setStreamError(error);
+                onError?.(error);
+            }
+        }
+        finally {
+            setIsLoading(false);
+            // Assumption: messages are already handled, we can clear the manager
+            messageManagerRef.current.clear();
+            submittingRef.current = false;
+            abortRef.current = null;
+        }
+    };
+    const error = isLoading ? streamError : historyError;
+    const values = streamValues ?? historyValues;
+    const setBranch = useCallback((path) => setBranchPath(path.split(">")), [setBranchPath]);
+    return {
+        get values() {
+            trackStreamMode("values");
+            return values;
+        },
+        error,
+        isLoading,
+        stop,
+        submit,
+        setBranch,
+        get messages() {
+            trackStreamMode("messages-tuple");
+            if (getMessages == null) {
+                throw new Error("No messages key provided. Make sure that `useStream` contains the `messagesKey` property.");
+            }
+            return getMessages(values);
+        },
+        getMessagesMetadata(message, index) {
+            trackStreamMode("messages-tuple");
+            if (getMessages == null) {
+                throw new Error("No messages key provided. Make sure that `useStream` contains the `messagesKey` property.");
+            }
+            return messageMetadata?.find((m) => m.messageId === (message.id ?? index));
+        },
+    };
+}

package/dist/types.d.ts

@@ -1,20 +1,10 @@
 import { Checkpoint, Config, Metadata } from "./schema.js";
-/**
- * Stream modes
- * - "values": Stream only the state values.
- * - "messages": Stream complete messages.
- * - "messages-tuple": Stream (message chunk, metadata) tuples.
- * - "updates": Stream updates to the state.
- * - "events": Stream events occurring during execution.
- * - "debug": Stream detailed debug information.
- * - "custom": Stream custom events.
- */
-export type StreamMode = "values" | "messages" | "updates" | "events" | "debug" | "custom" | "messages-tuple";
+import { StreamMode } from "./types.stream.js";
 export type MultitaskStrategy = "reject" | "interrupt" | "rollback" | "enqueue";
 export type OnConflictBehavior = "raise" | "do_nothing";
 export type OnCompletionBehavior = "complete" | "continue";
 export type DisconnectMode = "cancel" | "continue";
-export type StreamEvent = "events" | "metadata" | "debug" | "updates" | "values" | "messages/partial" | "messages/metadata" | "messages/complete" | (string & {});
+export type StreamEvent = "events" | "metadata" | "debug" | "updates" | "values" | "messages/partial" | "messages/metadata" | "messages/complete" | "messages" | (string & {});
 export interface Send {
     node: string;
     input: Record<string, unknown> | null;
@@ -23,7 +13,7 @@ export interface Command {
     /**
      * An object to update the thread state with.
      */
-    update?: Record<string, unknown> | [string, unknown][];
+    update?: Record<string, unknown> | [string, unknown][] | null;
     /**
      * The value to return from an `interrupt` function call.
      */
@@ -111,15 +101,15 @@ interface RunsInvokePayload {
      */
     command?: Command;
 }
-export interface RunsStreamPayload extends RunsInvokePayload {
+export interface RunsStreamPayload<TStreamMode extends StreamMode | StreamMode[] = [], TSubgraphs extends boolean = false> extends RunsInvokePayload {
     /**
      * One of `"values"`, `"messages"`, `"messages-tuple"`, `"updates"`, `"events"`, `"debug"`, `"custom"`.
      */
-    streamMode?: StreamMode | Array<StreamMode>;
+    streamMode?: TStreamMode;
     /**
      * Stream output from subgraphs. By default, streams only the top graph.
      */
-    streamSubgraphs?: boolean;
+    streamSubgraphs?: TSubgraphs;
     /**
      * Pass one or more feedbackKeys if you want to request short-lived signed URLs
      * for submitting feedback to LangSmith with this key for this run.

package/dist/types.messages.d.ts

@@ -0,0 +1,88 @@
+type ImageDetail = "auto" | "low" | "high";
+type MessageContentImageUrl = {
+    type: "image_url";
+    image_url: string | {
+        url: string;
+        detail?: ImageDetail | undefined;
+    };
+};
+type MessageContentText = {
+    type: "text";
+    text: string;
+};
+type MessageContentComplex = MessageContentText | MessageContentImageUrl;
+type MessageContent = string | MessageContentComplex[];
+/**
+ * Model-specific additional kwargs, which is passed back to the underlying LLM.
+ */
+type MessageAdditionalKwargs = Record<string, unknown>;
+export type HumanMessage = {
+    type: "human";
+    id?: string | undefined;
+    content: MessageContent;
+};
+export type AIMessage = {
+    type: "ai";
+    id?: string | undefined;
+    content: MessageContent;
+    tool_calls?: {
+        name: string;
+        args: {
+            [x: string]: {
+                [x: string]: any;
+            };
+        };
+        id?: string | undefined;
+        type?: "tool_call" | undefined;
+    }[] | undefined;
+    invalid_tool_calls?: {
+        name?: string | undefined;
+        args?: string | undefined;
+        id?: string | undefined;
+        error?: string | undefined;
+        type?: "invalid_tool_call" | undefined;
+    }[] | undefined;
+    usage_metadata?: {
+        input_tokens: number;
+        output_tokens: number;
+        total_tokens: number;
+        input_token_details?: {
+            audio?: number | undefined;
+            cache_read?: number | undefined;
+            cache_creation?: number | undefined;
+        } | undefined;
+        output_token_details?: {
+            audio?: number | undefined;
+            reasoning?: number | undefined;
+        } | undefined;
+    } | undefined;
+    additional_kwargs?: MessageAdditionalKwargs | undefined;
+    response_metadata?: Record<string, unknown> | undefined;
+};
+export type ToolMessage = {
+    type: "tool";
+    name?: string | undefined;
+    id?: string | undefined;
+    content: MessageContent;
+    status?: "error" | "success" | undefined;
+    tool_call_id: string;
+    additional_kwargs?: MessageAdditionalKwargs | undefined;
+    response_metadata?: Record<string, unknown> | undefined;
+};
+export type SystemMessage = {
+    type: "system";
+    id?: string | undefined;
+    content: MessageContent;
+};
+export type FunctionMessage = {
+    type: "function";
+    id?: string | undefined;
+    content: MessageContent;
+};
+export type RemoveMessage = {
+    type: "remove";
+    id: string;
+    content: MessageContent;
+};
+export type Message = HumanMessage | AIMessage | ToolMessage | SystemMessage | FunctionMessage | RemoveMessage;
+export {};

package/dist/types.stream.cjs

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });