@langchain/langgraph 0.2.46 → 0.2.47

package/dist/pregel/index.cjs

@@ -25,9 +25,20 @@ const stream_js_1 = require("./stream.cjs");
 function isString(value) {
     return typeof value === "string";
 }
+/**
+ * Utility class for working with channels in the Pregel system.
+ * Provides static methods for subscribing to channels and writing to them.
+ *
+ * Channels are the communication pathways between nodes in a Pregel graph.
+ * They enable message passing and state updates between different parts of the graph.
+ */
 class Channel {
     static subscribeTo(channels, options) {
-        const { key, tags } = options ?? {};
+        const { key, tags } = {
+            key: undefined,
+            tags: undefined,
+            ...(options ?? {}),
+        };
         if (Array.isArray(channels) && key !== undefined) {
             throw new Error("Can't specify a key when subscribing to multiple channels");
         }
@@ -50,7 +61,32 @@ class Channel {
             tags,
         });
     }
-    static writeTo(channels, kwargs) {
+    /**
+     * Creates a ChannelWrite that specifies how to write values to channels.
+     * This is used to define how nodes send output to channels.
+     *
+     * @example
+     * ```typescript
+     * // Write to multiple channels
+     * const write = Channel.writeTo(["output", "state"]);
+     *
+     * // Write with specific values
+     * const write = Channel.writeTo(["output"], {
+     *   state: "completed",
+     *   result: calculateResult()
+     * });
+     *
+     * // Write with a transformation function
+     * const write = Channel.writeTo(["output"], {
+     *   result: (x) => processResult(x)
+     * });
+     * ```
+     *
+     * @param channels - Array of channel names to write to
+     * @param writes - Optional map of channel names to values or transformations
+     * @returns A ChannelWrite object that can be used to write to the specified channels
+     */
+    static writeTo(channels, writes) {
         const channelWriteEntries = [];
         for (const channel of channels) {
             channelWriteEntries.push({
@@ -59,7 +95,7 @@ class Channel {
                 skipNone: false,
             });
         }
-        for (const [key, value] of Object.entries(kwargs ?? {})) {
+        for (const [key, value] of Object.entries(writes ?? {})) {
             if (runnables_1.Runnable.isRunnable(value) || typeof value === "function") {
                 channelWriteEntries.push({
                     channel: key,
@@ -80,109 +116,222 @@ class Channel {
     }
 }
 exports.Channel = Channel;
+/**
+ * The Pregel class is the core runtime engine of LangGraph, implementing a message-passing graph computation model
+ * inspired by [Google's Pregel system](https://research.google/pubs/pregel-a-system-for-large-scale-graph-processing/).
+ * It provides the foundation for building reliable, controllable agent workflows that can evolve state over time.
+ *
+ * Key features:
+ * - Message passing between nodes in discrete "supersteps"
+ * - Built-in persistence layer through checkpointers
+ * - First-class streaming support for values, updates, and events
+ * - Human-in-the-loop capabilities via interrupts
+ * - Support for parallel node execution within supersteps
+ *
+ * The Pregel class is not intended to be instantiated directly by consumers. Instead, use the following higher-level APIs:
+ * - {@link StateGraph}: The main graph class for building agent workflows
+ *   - Compiling a {@link StateGraph} will return a {@link CompiledGraph} instance, which extends `Pregel`
+ * - Functional API: A declarative approach using tasks and entrypoints
+ *   - A `Pregel` instance is returned by the {@link entrypoint} function
+ *
+ * @example
+ * ```typescript
+ * // Using StateGraph API
+ * const graph = new StateGraph(annotation)
+ *   .addNode("nodeA", myNodeFunction)
+ *   .addEdge("nodeA", "nodeB")
+ *   .compile();
+ *
+ * // The compiled graph is a Pregel instance
+ * const result = await graph.invoke(input);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using Functional API
+ * import { task, entrypoint } from "@langchain/langgraph";
+ * import { MemorySaver } from "@langchain/langgraph-checkpoint";
+ *
+ * // Define tasks that can be composed
+ * const addOne = task("add", async (x: number) => x + 1);
+ *
+ * // Create a workflow using the entrypoint function
+ * const workflow = entrypoint({
+ *   name: "workflow",
+ *   checkpointer: new MemorySaver()
+ * }, async (numbers: number[]) => {
+ *   // Tasks can be run in parallel
+ *   const results = await Promise.all(numbers.map(n => addOne(n)));
+ *   return results;
+ * });
+ *
+ * // The workflow is a Pregel instance
+ * const result = await workflow.invoke([1, 2, 3]); // Returns [2, 3, 4]
+ * ```
+ *
+ * @typeParam Nodes - Mapping of node names to their {@link PregelNode} implementations
+ * @typeParam Channels - Mapping of channel names to their {@link BaseChannel} or {@link ManagedValueSpec} implementations
+ * @typeParam ConfigurableFieldType - Type of configurable fields that can be passed to the graph
+ * @typeParam InputType - Type of input values accepted by the graph
+ * @typeParam OutputType - Type of output values produced by the graph
+ */
 class Pregel extends runnables_1.Runnable {
+    /**
+     * Name of the class when serialized
+     * @internal
+     */
     static lc_name() {
         return "LangGraph";
     }
+    /**
+     * Constructor for Pregel - meant for internal use only.
+     *
+     * @internal
+     */
     constructor(fields) {
         super(fields);
-        // Because Pregel extends `Runnable`.
+        /** @internal LangChain namespace for serialization necessary because Pregel extends Runnable */
         Object.defineProperty(this, "lc_namespace", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: ["langgraph", "pregel"]
         });
+        /** @internal Flag indicating this is a Pregel instance - necessary for serialization */
         Object.defineProperty(this, "lg_is_pregel", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: true
         });
+        /** The nodes in the graph, mapping node names to their PregelNode instances */
         Object.defineProperty(this, "nodes", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The channels in the graph, mapping channel names to their BaseChannel or ManagedValueSpec instances */
         Object.defineProperty(this, "channels", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * The input channels for the graph. These channels receive the initial input when the graph is invoked.
+         * Can be a single channel key or an array of channel keys.
+         */
         Object.defineProperty(this, "inputChannels", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * The output channels for the graph. These channels contain the final output when the graph completes.
+         * Can be a single channel key or an array of channel keys.
+         */
         Object.defineProperty(this, "outputChannels", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Whether to automatically validate the graph structure when it is compiled. Defaults to true. */
         Object.defineProperty(this, "autoValidate", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: true
         });
+        /**
+         * The streaming modes enabled for this graph. Defaults to ["values"].
+         * Supported modes:
+         * - "values": Streams the full state after each step
+         * - "updates": Streams state updates after each step
+         * - "messages": Streams messages from within nodes
+         * - "custom": Streams custom events from within nodes
+         * - "debug": Streams events related to the execution of the graph - useful for tracing & debugging graph execution
+         */
         Object.defineProperty(this, "streamMode", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: ["values"]
         });
+        /**
+         * Optional channels to stream. If not specified, all channels will be streamed.
+         * Can be a single channel key or an array of channel keys.
+         */
         Object.defineProperty(this, "streamChannels", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * Optional array of node names or "all" to interrupt after executing these nodes.
+         * Used for implementing human-in-the-loop workflows.
+         */
         Object.defineProperty(this, "interruptAfter", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * Optional array of node names or "all" to interrupt before executing these nodes.
+         * Used for implementing human-in-the-loop workflows.
+         */
         Object.defineProperty(this, "interruptBefore", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Optional timeout in milliseconds for the execution of each superstep */
         Object.defineProperty(this, "stepTimeout", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Whether to enable debug logging. Defaults to false. */
         Object.defineProperty(this, "debug", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: false
         });
+        /**
+         * Optional checkpointer for persisting graph state.
+         * When provided, saves a checkpoint of the graph state at every superstep.
+         * When false or undefined, checkpointing is disabled, and the graph will not be able to save or restore state.
+         */
         Object.defineProperty(this, "checkpointer", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Optional retry policy for handling failures in node execution */
         Object.defineProperty(this, "retryPolicy", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The default configuration for graph execution, can be overridden on a per-invocation basis */
         Object.defineProperty(this, "config", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * Optional long-term memory store for the graph, allows for persistance & retrieval of data across threads
+         */
         Object.defineProperty(this, "store", {
             enumerable: true,
             configurable: true,
@@ -213,6 +362,25 @@ class Pregel extends runnables_1.Runnable {
             this.validate();
         }
     }
+    /**
+     * Creates a new instance of the Pregel graph with updated configuration.
+     * This method follows the immutable pattern - instead of modifying the current instance,
+     * it returns a new instance with the merged configuration.
+     *
+     * @example
+     * ```typescript
+     * // Create a new instance with debug enabled
+     * const debugGraph = graph.withConfig({ debug: true });
+     *
+     * // Create a new instance with a specific thread ID
+     * const threadGraph = graph.withConfig({
+     *   configurable: { thread_id: "123" }
+     * });
+     * ```
+     *
+     * @param config - The configuration to merge with the current configuration
+     * @returns A new Pregel instance with the merged configuration
+     */
     // eslint-disable-next-line @typescript-eslint/ban-ts-comment
     // @ts-ignore Remove ignore when we remove support for 0.2 versions of core
     withConfig(config) {
@@ -220,6 +388,16 @@ class Pregel extends runnables_1.Runnable {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         return new this.constructor({ ...this, config: mergedConfig });
     }
+    /**
+     * Validates the graph structure to ensure it is well-formed.
+     * Checks for:
+     * - No orphaned nodes
+     * - Valid input/output channel configurations
+     * - Valid interrupt configurations
+     *
+     * @returns this - The Pregel instance for method chaining
+     * @throws {GraphValidationError} If the graph structure is invalid
+     */
     validate() {
         (0, validate_js_1.validateGraph)({
             nodes: this.nodes,
@@ -232,6 +410,13 @@ class Pregel extends runnables_1.Runnable {
         });
         return this;
     }
+    /**
+     * Gets a list of all channels that should be streamed.
+     * If streamChannels is specified, returns those channels.
+     * Otherwise, returns all channels in the graph.
+     *
+     * @returns Array of channel keys to stream
+     */
     get streamChannelsList() {
         if (Array.isArray(this.streamChannels)) {
             return this.streamChannels;
@@ -243,6 +428,13 @@ class Pregel extends runnables_1.Runnable {
             return Object.keys(this.channels);
         }
     }
+    /**
+     * Gets the channels to stream in their original format.
+     * If streamChannels is specified, returns it as-is (either single key or array).
+     * Otherwise, returns all channels in the graph as an array.
+     *
+     * @returns Channel keys to stream, either as a single key or array
+     */
     get streamChannelsAsIs() {
         if (this.streamChannels) {
             return this.streamChannels;
@@ -251,10 +443,25 @@ class Pregel extends runnables_1.Runnable {
             return Object.keys(this.channels);
         }
     }
+    /**
+     * Gets a drawable representation of the graph structure.
+     * This is an async version of getGraph() and is the preferred method to use.
+     *
+     * @param config - Configuration for generating the graph visualization
+     * @returns A representation of the graph that can be visualized
+     */
     async getGraphAsync(config) {
         return this.getGraph(config);
     }
-    /** @deprecated Use getSubgraphsAsync instead. The async method will become the default in the next minor release. */
+    /**
+     * Gets all subgraphs within this graph.
+     * A subgraph is a Pregel instance that is nested within a node of this graph.
+     *
+     * @deprecated Use getSubgraphsAsync instead. The async method will become the default in the next minor release.
+     * @param namespace - Optional namespace to filter subgraphs
+     * @param recurse - Whether to recursively get subgraphs of subgraphs
+     * @returns Generator yielding tuples of [name, subgraph]
+     */
     *getSubgraphs(namespace, recurse
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     ) {
@@ -292,11 +499,29 @@ class Pregel extends runnables_1.Runnable {
             }
         }
     }
+    /**
+     * Gets all subgraphs within this graph asynchronously.
+     * A subgraph is a Pregel instance that is nested within a node of this graph.
+     *
+     * @param namespace - Optional namespace to filter subgraphs
+     * @param recurse - Whether to recursively get subgraphs of subgraphs
+     * @returns AsyncGenerator yielding tuples of [name, subgraph]
+     */
     async *getSubgraphsAsync(namespace, recurse
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     ) {
         yield* this.getSubgraphs(namespace, recurse);
     }
+    /**
+     * Prepares a state snapshot from saved checkpoint data.
+     * This is an internal method used by getState and getStateHistory.
+     *
+     * @param config - Configuration for preparing the snapshot
+     * @param saved - Optional saved checkpoint data
+     * @param subgraphCheckpointer - Optional checkpointer for subgraphs
+     * @returns A snapshot of the graph state
+     * @internal
+     */
     async _prepareStateSnapshot({ config, saved, subgraphCheckpointer, }) {
         if (saved === undefined) {
             return {
@@ -372,7 +597,13 @@ class Pregel extends runnables_1.Runnable {
         };
     }
     /**
-     * Get the current state of the graph.
+     * Gets the current state of the graph.
+     * Requires a checkpointer to be configured.
+     *
+     * @param config - Configuration for retrieving the state
+     * @param options - Additional options
+     * @returns A snapshot of the current graph state
+     * @throws {GraphValueError} If no checkpointer is configured
      */
     async getState(config, options) {
         const checkpointer = config.configurable?.[constants_js_1.CONFIG_KEY_CHECKPOINTER] ?? this.checkpointer;
@@ -406,7 +637,17 @@ class Pregel extends runnables_1.Runnable {
         return snapshot;
     }
     /**
-     * Get the history of the state of the graph.
+     * Gets the history of graph states.
+     * Requires a checkpointer to be configured.
+     * Useful for:
+     * - Debugging execution history
+     * - Implementing time travel
+     * - Analyzing graph behavior
+     *
+     * @param config - Configuration for retrieving the history
+     * @param options - Options for filtering the history
+     * @returns An async iterator of state snapshots
+     * @throws {Error} If no checkpointer is configured
      */
     async *getStateHistory(config, options) {
         const checkpointer = config.configurable?.[constants_js_1.CONFIG_KEY_CHECKPOINTER] ?? this.checkpointer;
@@ -442,9 +683,20 @@ class Pregel extends runnables_1.Runnable {
         }
     }
     /**
-     * Update the state of the graph with the given values, as if they came from
-     * node `as_node`. If `as_node` is not provided, it will be set to the last node
-     * that updated the state, if not ambiguous.
+     * Updates the state of the graph with new values.
+     * Requires a checkpointer to be configured.
+     *
+     * This method can be used for:
+     * - Implementing human-in-the-loop workflows
+     * - Modifying graph state during breakpoints
+     * - Integrating external inputs into the graph
+     *
+     * @param inputConfig - Configuration for the update
+     * @param values - The values to update the state with
+     * @param asNode - Optional node name to attribute the update to
+     * @returns Updated configuration
+     * @throws {GraphValueError} If no checkpointer is configured
+     * @throws {InvalidUpdateError} If the update cannot be attributed to a node
      */
     async updateState(inputConfig, values, asNode) {
         const checkpointer = inputConfig.configurable?.[constants_js_1.CONFIG_KEY_CHECKPOINTER] ?? this.checkpointer;
@@ -697,6 +949,24 @@ class Pregel extends runnables_1.Runnable {
         }
         return (0, index_js_1.patchCheckpointMap)(nextConfig, saved ? saved.metadata : undefined);
     }
+    /**
+     * Gets the default values for various graph configuration options.
+     * This is an internal method used to process and normalize configuration options.
+     *
+     * @param config - The input configuration options
+     * @returns A tuple containing normalized values for:
+     * - debug mode
+     * - stream modes
+     * - input keys
+     * - output keys
+     * - remaining config
+     * - interrupt before nodes
+     * - interrupt after nodes
+     * - checkpointer
+     * - store
+     * - whether stream mode is single
+     * @internal
+     */
     _defaults(config) {
         const { debug, streamMode, inputKeys, outputKeys, interruptAfter, interruptBefore, ...rest } = config;
         let streamModeSingle = true;
@@ -756,19 +1026,20 @@ class Pregel extends runnables_1.Runnable {
         ];
     }
     /**
-     * Stream graph steps for a single input.
-     * @param input The input to the graph.
-     * @param options The configuration to use for the run.
-     * @param options.streamMode The mode to stream output. Defaults to value set on initialization.
-     *   Options are "values", "updates", and "debug". Default is "values".
-     *     values: Emit the current values of the state for each step.
-     *     updates: Emit only the updates to the state for each step.
-     *         Output is a dict with the node name as key and the updated values as value.
-     *     debug: Emit debug events for each step.
-     * @param options.outputKeys The keys to stream. Defaults to all non-context channels.
-     * @param options.interruptBefore Nodes to interrupt before.
-     * @param options.interruptAfter Nodes to interrupt after.
-     * @param options.debug Whether to print debug information during execution.
+     * Streams the execution of the graph, emitting state updates as they occur.
+     * This is the primary method for observing graph execution in real-time.
+     *
+     * Stream modes:
+     * - "values": Emits complete state after each step
+     * - "updates": Emits only state changes after each step
+     * - "debug": Emits detailed debug information
+     * - "messages": Emits messages from within nodes
+     *
+     * For more details, see the [Streaming how-to guides](../../how-tos/#streaming_1).
+     *
+     * @param input - The input to start graph execution with
+     * @param options - Configuration options for streaming
+     * @returns An async iterable stream of graph state updates
      */
     async stream(input, options) {
         // The ensureConfig method called internally defaults recursionLimit to 25 if not
@@ -782,6 +1053,17 @@ class Pregel extends runnables_1.Runnable {
         };
         return super.stream(input, config);
     }
+    /**
+     * Prepares channel specifications and managed values for graph execution.
+     * This is an internal method used to set up the graph's communication channels
+     * and managed state before execution.
+     *
+     * @param config - Configuration for preparing specs
+     * @param options - Additional options
+     * @param options.skipManaged - Whether to skip initialization of managed values
+     * @returns Object containing channel specs and managed value mapping
+     * @internal
+     */
     async prepareSpecs(config, options) {
         const configForManaged = {
             ...config,
@@ -826,6 +1108,15 @@ class Pregel extends runnables_1.Runnable {
             managed,
         };
     }
+    /**
+     * Internal iterator used by stream() to generate state updates.
+     * This method handles the core logic of graph execution and streaming.
+     *
+     * @param input - The input to start graph execution with
+     * @param options - Configuration options for streaming
+     * @returns AsyncGenerator yielding state updates
+     * @internal
+     */
     async *_streamIterator(input, options) {
         const streamSubgraphs = options?.subgraphs;
         const inputConfig = (0, config_js_1.ensureLangGraphConfig)(this.config, options);
@@ -975,16 +1266,6 @@ class Pregel extends runnables_1.Runnable {
      * Run the graph with a single input and config.
      * @param input The input to the graph.
      * @param options The configuration to use for the run.
-     * @param options.streamMode The mode to stream output. Defaults to value set on initialization.
-     *   Options are "values", "updates", and "debug". Default is "values".
-     *     values: Emit the current values of the state for each step.
-     *     updates: Emit only the updates to the state for each step.
-     *         Output is a dict with the node name as key and the updated values as value.
-     *     debug: Emit debug events for each step.
-     * @param options.outputKeys The keys to stream. Defaults to all non-context channels.
-     * @param options.interruptBefore Nodes to interrupt before.
-     * @param options.interruptAfter Nodes to interrupt after.
-     * @param options.debug Whether to print debug information during execution.
      */
     async invoke(input, options) {
         const streamMode = options?.streamMode ?? "values";