add missing build step

* Add ast parsing to determine whether we should include result="ansi".
It's not meant to be perfect, but will hopefully catch the most common
cases. Still requires manual review.
* Ideally we could suppress output in markdown-exec in the future.

.github/workflows/codespell.yml

@@ -36,7 +36,7 @@
           - name: Codespell
             uses: codespell-project/actions-codespell@v2
             with:
-              skip: '*.ambr,*.lock,*.ipynb,*.yaml,*.zlib'
+              skip: '*.ambr,*.lock,*.ipynb,*.yaml,*.zlib,*.md'
               ignore_words_list: ${{ steps.extract_ignore_words.outputs.ignore_words_list }}
           # We do this to avoid spellchecking cell outputs
           - name: Codespell Notebooks

.github/workflows/deploy_docs.yml

@@ -48,6 +48,7 @@ jobs:
   deploy:
     # needs: run-changed-notebooks
     runs-on: ubuntu-latest
+    timeout-minutes: 10 # Job will be cancelled if it runs for more than 10 minutes
     env:
       GITHUB_TOKEN: ${{ secrets.MKDOCS_GITHUB_TOKEN }}
     steps:
@@ -55,6 +56,12 @@ jobs:
         with:
           fetch-depth: 0
 
+      - uses: actions/checkout@v4
+        with:
+          repository: langchain-ai/langchainjs
+          token: ${{ secrets.MKDOCS_GITHUB_TOKEN }}
+          path: docs/langchainjs
+
       - name: Set up Python + Poetry ${{ env.POETRY_VERSION }}
         uses: "./.github/actions/poetry_setup"
         with:
@@ -62,17 +69,39 @@ jobs:
           poetry-version: ${{ env.POETRY_VERSION }}
           cache-key: docs
 
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: "22"
+          cache: "yarn"
+          cache-dependency-path: docs/yarn.lock
+
       - name: Install dependencies
         run: |
-          poetry install --with test --no-root
+          cd langchainjs && yarn && yarn build && cd ..
+          yarn
+          poetry install --with test --with docs --no-root
           poetry run pip install -U \
             pytest \
             pytest-check-links \
-            langsmith \
-            langchain \
             GitPython \
-            "git+https://${GITHUB_TOKEN}@github.com/langchain-ai/mkdocs-material-insiders.git"
+            "git+https://github.com/benjamincburns/markdown-exec.git@cc0d39d737e5ffd4b83d23cd8729d7ea16e363c8"
 
+          # we run this installation only for internal PRs
+          # as GITHUB_TOKEN is not available for PRs from outside contributors
+          if [ -n "${GITHUB_TOKEN}" ]; then
+            poetry run pip install "git+https://${GITHUB_TOKEN}@github.com/langchain-ai/mkdocs-material-insiders.git"
+          fi
+
+          poetry run jupyter kernelspec list
+          poetry run python3 -m ipykernel install --user --name=python3
+          npm install -g tslab
+          poetry run tslab install --python=python3
+          poetry run jupyter kernelspec list
+
+      - name: Run unit tests
+        # Run unit tests on the docs build pipeline
+        run: make tests
       - name: Lint Docs
         # This step lints the docs using the existing linting set up.
         # It should be very fast and should not require any external services.
@@ -83,6 +112,8 @@ jobs:
         run: make build-docs
         env:
           MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.MKDOCS_GIT_COMMITTERS_APIKEY }}
+          OPENAI_API_KEY: sf-proj-1234567890 # fake placeholder, shouldn't actually be used
+          ANTHROPIC_API_KEY: sk-ant-api03-1234567890 # fake placeholder, shouldn't actually be used
       - name: Check links in notebooks
         env:
           LANGCHAIN_API_KEY: test
@@ -100,6 +131,7 @@ jobs:
               --check-links-ignore "/.*\.(ipynb|html)$" \
               --check-links-ignore "https://python\.langchain\.com/.*" \
               --check-links-ignore "https://openai\.com/.*" \
+              --check-links-ignore "https://www\.uber\.com/.*" \
               --check-links-ignore "https://pepy\.tech/.*" \
               --check-links $(find site -name "index.html" | grep -v 'storm/index.html')
               
@@ -132,7 +164,7 @@ jobs:
         uses: actions/configure-pages@v4
 
       - name: Upload Pages Artifact
-        if: github.ref == 'refs/heads/main'
+        # if: github.ref == 'refs/heads/main'
         uses: actions/upload-pages-artifact@v3
         with:
           path: ./docs/site/

.github/workflows/extract_ignored_words_list.py

@@ -1,6 +1,6 @@
 import toml
 
-pyproject_toml = toml.load("../libs/langgraph/pyproject.toml")
+pyproject_toml = toml.load("pyproject.toml")
 
 # Extract the ignore words list (adjust the key as per your TOML structure)
 ignore_words_list = (

.gitignore

@@ -179,3 +179,4 @@ Untitled*.ipynb
 Chinook.db
 
 .vercel
+.turbo

docs/.yarnrc.yml

@@ -0,0 +1,3 @@
+nodeLinker: node-modules
+
+yarnPath: .yarn/releases/yarn-3.5.1.cjs

docs/Makefile

@@ -1,4 +1,4 @@
-.PHONY: lint-docs format-docs build-docs serve-docs serve-clean-docs clean-docs codespell build-typedoc llms-text
+.PHONY: lint-docs format-docs build-docs serve-docs serve-clean-docs clean-docs codespell build-typedoc llms-text build-prebuilt tests
 
 build-typedoc:
 	cd ../libs/sdk-js && yarn install --include-dev && yarn typedoc
@@ -6,24 +6,60 @@ build-typedoc:
 	#  Add links to the monorepo
 	sed -e '1,10s|@langchain/langgraph-sdk|[@langchain/langgraph-sdk](https://github.com/langchain-ai/langgraph/tree/main/libs/sdk-js)|g' docs/cloud/reference/sdk/js_ts_sdk_ref.md > temp_file && mv temp_file docs/cloud/reference/sdk/js_ts_sdk_ref.md
 
-build-docs: build-typedoc
+build-prebuilt:
+	# Use to create an update to date prebuilt page.
+	# Looks up download stats for each of the prebuilt packages and
+	# generates the final prebuilt page.
+	poetry run python -m _scripts.third_party_page.get_download_stats stats.yml
+	poetry run python -m _scripts.third_party_page.create_third_party_page stats.yml docs/prebuilt.md --language python
+
+grab-langgraphjs:
+	if [ -d "langgraphjs" ]; then \
+		if [ ! -d "langgraphjs/.git" ]; then \
+			rm -rf langgraphjs; \
+		fi \
+	fi
+	if [ ! -d "langgraphjs" ]; then \
+		git clone https://github.com/langchain-ai/langgraphjs.git; \
+	else \
+		cd langgraphjs && git checkout main && git pull; \
+	fi
+	cd langgraphjs && yarn
+	cd langgraphjs && yarn build
+	yarn
+
+build-docs: build-typedoc build-prebuilt grab-langgraphjs
 	poetry run python -m mkdocs build --clean -f mkdocs.yml --strict
 
 llms-text:
-	poetry run python _scripts/generate_llms_text.py docs/llms-full.txt
+	poetry run python -m _scripts.generate_llms_text docs/llms-full.txt
 
 install-vercel-deps:
+	dnf install -y python3.11
 	curl -sSL https://install.python-poetry.org | python3 -
 	poetry self update 1.8.5
+	# don't use vercel's python - it wasn't compiled with sqlite support, and it fails when installing ipython's kernel
+	poetry env use /usr/bin/python3.11
+	poetry install --with docs --with test --no-root
+	poetry run pip install "git+https://github.com/benjamincburns/markdown-exec.git@cc0d39d737e5ffd4b83d23cd8729d7ea16e363c8"
+	poetry run python3 -m ipykernel install --name=python3
+	npm install -g tslab
+	poetry run tslab install --python=python3
+	poetry run jupyter kernelspec list
+
+tests:
+	# RUn unit tests
+	poetry run pytest tests/unit_tests
+
 
 vercel-build-docs: install-vercel-deps
-	poetry install
 	make build-docs
 
+
 serve-clean-docs: clean-docs
 	poetry run python -m mkdocs serve -c -f mkdocs.yml --strict -w ../libs/langgraph
 
-serve-docs: build-typedoc
+serve-docs: build-typedoc grab-langgraphjs
 	poetry run python -m mkdocs serve -f mkdocs.yml -w ../libs/langgraph  -w ../libs/checkpoint -w ../libs/sdk-py --dirty
 
 clean-docs:

docs/_scripts/add_translation.py

@@ -0,0 +1,157 @@
+"""Add typescript translation to a given markdown file."""
+
+import argparse
+import re
+
+import requests
+from langchain_anthropic import ChatAnthropic
+
+URL = "https://gist.githubusercontent.com/eyurtsev/e7486731415463a9bc5b4682358859c8/raw/b5a5fda9c7e3387cfcb781f25082814d43675d50/gistfile1.txt"
+response = requests.get(URL)
+response.raise_for_status()
+reference_snippets = response.text
+
+model = ChatAnthropic(model="claude-3-5-sonnet-latest")
+
+
+def _get_tqdm():
+    try:
+        from tqdm import tqdm
+    except ImportError:
+        # If not available return a simple identity function
+        def tqdm(iterable, *args, **kwargs):
+            return iterable
+
+    return tqdm
+
+
+_tqdm = _get_tqdm()
+
+opening_pattern = re.compile(r"^\s*```python(?:\s+.*)?\s*$")
+closing_pattern = re.compile(r"^\s*```\s*$")
+
+
+def extract_python_snippets(markdown: str) -> list[str]:
+    """
+    Extract all python code blocks (including their fence lines) from the markdown content.
+    A python block is defined as any block that starts with a line containing an opening fence
+    with '```python' (optionally with extra parameters) and ends with a closing fence '```'.
+    """
+    snippets = []
+    inside_block = False
+    current_snippet = []
+
+    for line in markdown.splitlines(keepends=True):
+        if not inside_block:
+            if opening_pattern.match(line):
+                inside_block = True
+                current_snippet = [line]
+        else:
+            current_snippet.append(line)
+            if closing_pattern.match(line):
+                inside_block = False
+                snippets.append("".join(current_snippet))
+                current_snippet = []
+    return snippets
+
+
+def translate_snippet(python_snippet: str) -> str:
+    """Translate a python code block into a TypeScript code block using Langchain.
+    The response is expected to be a properly fenced TypeScript code block (i.e.
+    starting with ```typescript and ending with ```).
+    """
+    ai_message = model.invoke(
+        [
+            {
+                "role": "system",
+                "content": (
+                    f"You have access to the following up-to-date example TypeScript code "
+                    f"snippets that show examples of building with langgraph "
+                    f"and langchain:\n\n{reference_snippets}\n\n"
+                    "Use this context to translate the following Python code to equivalent "
+                    "TypeScript. Ensure that your output is a valid fenced TypeScript "
+                    "code block (i.e. starts with ```typescript and ends with ```)."
+                ),
+            },
+            {
+                "role": "user",
+                "content": f"Translate this Python snippet to TypeScript:\n\n{python_snippet}",
+            },
+        ]
+    )
+
+    # Use a regular expression to search for a TypeScript code block in the response.
+    pattern = r"```typescript\s*(.*?)\s*```"
+    match = re.search(pattern, ai_message.content, re.DOTALL)
+    if match:
+        # Reconstruct the code block with proper fences.
+        typescript_code = match.group(1).strip()
+        return f"```typescript\n{typescript_code}\n```"
+    else:
+        raise ValueError("No TypeScript code block found in the model's response.")
+
+
+def insert_translations_into_markdown(
+    markdown: str, typescript_snippets: list[str]
+) -> str:
+    """Walks through the original markdown content and, after each
+    Python snippet block, inserts the corresponding translated TypeScript snippet.
+    It assumes that the ordering of the Python snippets
+    (from extract_python_snippets) matches the order they appear in the markdown.
+    """
+    output_lines = []
+    lines = markdown.splitlines(keepends=True)
+    inside_block = False
+    snippet_index = 0
+
+    for line in lines:
+        output_lines.append(line)
+        if not inside_block and opening_pattern.match(line):
+            # We've encountered the start of a python code block.
+            inside_block = True
+        elif inside_block:
+            if closing_pattern.match(line):
+                # End of a python snippet block.
+                inside_block = False
+                if snippet_index < len(typescript_snippets):
+                    # Insert an extra newline for clarity, then the translated TypeScript snippet.
+                    output_lines.append("\n")
+                    output_lines.append(typescript_snippets[snippet_index])
+                    output_lines.append("\n")
+                    snippet_index += 1
+    return "".join(output_lines)
+
+
+def main(file_path: str) -> None:
+    # Read the markdown file.
+    with open(file_path, "r") as f:
+        markdown_content = f.read()
+
+    # 1. Extract all Python snippets.
+    python_snippets = extract_python_snippets(markdown_content)[:1]
+
+    # 2. Translate each Python snippet to TypeScript.
+    typescript_snippets = []
+    # Replace with .batch() for faster translation
+    for python_snippet in _tqdm(python_snippets):
+        ts_snippet = translate_snippet(python_snippet)
+        typescript_snippets.append(ts_snippet)
+
+    # 3. Insert the TypeScript translations after their respective Python snippets.
+    updated_markdown = insert_translations_into_markdown(
+        markdown_content, typescript_snippets
+    )
+
+    # Overwrite the original markdown file with the updated content.
+    with open(file_path, "w") as f:
+        f.write(updated_markdown)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Translate Python snippets in a markdown file to TypeScript and insert them after each Python snippet."
+    )
+    parser.add_argument("file_path", type=str, help="Path to the markdown file.")
+    args = parser.parse_args()
+
+    main(args.file_path)

docs/_scripts/assets/nock_setup_preamble.ts

@@ -0,0 +1,77 @@
+import nock, { Definition } from "nock";
+import msgpack from "msgpack-lite";
+import zlib from "node:zlib";
+import fs from "node:fs/promises";
+import { Buffer } from "node:buffer";
+
+// deno style imports here because we're running this in the deno jupyter kernel
+
+interface NockCassetteData {
+  hash: string;
+  entries: Definition[];
+}
+
+// Utility functions for compression & serialization
+function compressData(data: NockCassetteData, compressionLevel = 9): string {
+  const packed = msgpack.encode(data);
+  const compressed = zlib.deflateSync(packed, { level: compressionLevel });
+  return compressed.toString("base64");
+}
+
+function decompressData(compressedString: string): NockCassetteData {
+  const decoded = Buffer.from(compressedString, "base64");
+  const decompressed = zlib.inflateSync(decoded);
+  return msgpack.decode(decompressed) as NockCassetteData;
+}
+
+class HashedCassette {
+  hash: string;
+  private recording = true;
+
+  constructor(
+    private readonly cassettePath: string,
+    hash: string
+  ) {
+    this.hash = hash;
+  }
+
+  async enter() {
+    try {
+      const rawCassette = await fs.readFile(this.cassettePath, "utf-8");
+      const data = decompressData(rawCassette);
+      if (data.hash === this.hash) {
+        this.recording = false;
+        nock.disableNetConnect();
+        nock.define(data.entries);
+        return;
+      }
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("ENOENT")) {
+        this.recording = true;
+      } else {
+        throw error;
+      }
+    }
+
+    nock.recorder.rec({
+      dont_print: true,
+      output_objects: true,
+    });
+  }
+
+  async exit() {
+    if (this.recording) {
+      const entries = nock.recorder.play() as Definition[];
+      const data = {
+        hash: this.hash,
+        entries,
+      };
+      const compressed = compressData(data);
+      await fs.writeFile(this.cassettePath, compressed);
+    } else {
+      nock.enableNetConnect();
+      nock.restore();
+      nock.cleanAll();
+    }
+  }
+}

docs/_scripts/assets/vcr_setup_preamble.py

@@ -0,0 +1,107 @@
+import base64
+import os
+import zlib
+from types import TracebackType
+from typing import Optional, Any, Type
+
+import msgpack
+import vcr
+
+os.environ.pop("LANGCHAIN_TRACING_V2", None)
+custom_vcr = vcr.VCR()
+
+
+def compress_data(data: Any, compression_level: int = 9) -> str:
+    packed = msgpack.packb(data, use_bin_type=True)
+    compressed = zlib.compress(packed, level=compression_level)
+    return base64.b64encode(compressed).decode("utf-8")
+
+
+def decompress_data(compressed_string: str) -> Any:
+    decoded = base64.b64decode(compressed_string)
+    decompressed = zlib.decompress(decoded)
+    return msgpack.unpackb(decompressed, raw=False)
+
+
+class AdvancedCompressedSerializer:
+    def serialize(self, cassette_dict: Any) -> str:
+        return compress_data(cassette_dict)
+
+    def deserialize(self, cassette_string: str) -> Any:
+        return decompress_data(cassette_string)
+
+
+custom_vcr.register_serializer("advanced_compressed", AdvancedCompressedSerializer())
+custom_vcr.serializer = "advanced_compressed"
+
+
+class HashedCassette:
+    def __init__(self, cassette_path: str, hash_value: str) -> None:
+        """A context manager for using VCR cassettes with an embedded hash value.
+
+        Args:
+            cassette_path (str): The file path of the cassette (independent of hash).
+            hash_value (str): The expected hash value (e.g. a uuid string).
+
+        This class provides a context manager for using VCR cassettes with an embedded hash value.
+        The hash value is used to ensure that the cassette matches the expected state, and if not,
+        the cassette is removed or updated with the new hash value.
+        """
+        self.cassette_path: str = cassette_path
+        self.hash_value: str = hash_value
+        self.vcr: vcr.VCR = custom_vcr
+        self.cassette_context: Optional[Any] = None
+        self.exited: bool = False
+
+    def __enter__(self) -> Any:
+        self.exited: bool = False
+        # Get the serializer instance from the VCR instance.
+        serializer = self.vcr.serializers[self.vcr.serializer]
+        # If the cassette file exists, check its embedded hash.
+        if os.path.exists(self.cassette_path):
+            with open(self.cassette_path, "r") as f:
+                content = f.read()
+            try:
+                cassette_data = serializer.deserialize(content)
+            except Exception:
+                os.remove(self.cassette_path)
+            else:
+                existing_hash = cassette_data.get("cassette_hash")
+                if existing_hash != self.hash_value:
+                    os.remove(self.cassette_path)
+        # Now enter the VCR cassette context.
+        self.cassette_context = custom_vcr.use_cassette(
+            self.cassette_path,
+            filter_headers=["x-api-key", "authorization"],
+            record_mode="once",
+            serializer="advanced_compressed",
+        )
+        return self.cassette_context.__enter__()
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]] = None,
+        exc_val: Optional[BaseException] = None,
+        exc_tb: Optional[TracebackType] = None,
+    ) -> Optional[bool]:
+        if self.exited:
+            return
+        self.exited = True
+        # Exit the VCR cassette context.
+        result = self.cassette_context.__exit__(exc_type, exc_val, exc_tb)
+        serializer = self.vcr.serializers[self.vcr.serializer]
+        # If a cassette was recorded (or updated), open and update its hash.
+        if os.path.exists(self.cassette_path):
+            with open(self.cassette_path, "r") as f:
+                content = f.read()
+            try:
+                cassette_data = serializer.deserialize(content)
+            except Exception:
+                return result
+            # Update the cassette data with the expected hash.
+            if cassette_data.get("cassette_hash") != self.hash_value:
+                cassette_data["cassette_hash"] = self.hash_value
+                serialized_data = serializer.serialize(cassette_data)
+                with open(self.cassette_path, "w") as f:
+                    f.write(serialized_data)
+        return result

docs/_scripts/generate_api_reference_links.py

@@ -1,8 +1,11 @@
 import importlib
+from importlib.machinery import ModuleSpec
+import importlib.util
 import inspect
 import logging
 import re
 from functools import lru_cache
+import sys
 from typing import List, Literal, Optional
 
 from typing_extensions import TypedDict
@@ -72,9 +75,8 @@ def _make_regular_expression(pkg_prefix: str) -> re.Pattern:
     if not pkg_prefix.isidentifier():
         raise ValueError(f"Invalid package prefix: {pkg_prefix}")
     return re.compile(
-        r"from\s+(" + pkg_prefix + "(?:_\w+)?(?:\.\w+)*?)\s+import\s+"
-        r"((?:\w+(?:,\s*)?)*"  # Match zero or more words separated by a comma+optional ws
-        r"(?:\s*\(.*?\))?)",  # Match optional parentheses block
+        r"from\s+(" + pkg_prefix + r"(?:_\w+)?(?:\.\w+)*?)\s+import\s+\(?"
+        r"((?:\w+(?:,\s*)?)*)\s*\)?",  # Match zero or more words separated by a comma+optional ws
         re.DOTALL,  # Match newlines as well
     )
 
@@ -85,22 +87,57 @@ _IMPORT_LANGGRAPH_RE = _make_regular_expression("langgraph")
 
 
 @lru_cache(maxsize=10_000)
-def _get_full_module_name(module_path: str, class_name: str) -> Optional[str]:
+def _get_full_module_name(
+    module_path: str, class_name: str | None, doc_title: str
+) -> Optional[str]:
     """Get full module name using inspect, with LRU cache to memoize results."""
     try:
-        module = importlib.import_module(module_path)
-        class_ = getattr(module, class_name)
-        module = inspect.getmodule(class_)
-        if module is None:
-            # For constants, inspect.getmodule() might return None
-            # In this case, we'll return the original module_path
-            return module_path
+        if module_path in sys.modules:
+            module = sys.modules[module_path]
+        else:
+            spec: ModuleSpec | None = importlib.util.find_spec(module_path)
+            if spec is not None:
+                module = importlib.util.module_from_spec(spec)
+                sys.modules[module_path] = module
+                spec.loader.exec_module(module)
+
+        if class_name is not None:
+            class_ = getattr(module, class_name)
+
+            if re.match(r"\w+\s+as\s+\w+", class_name):
+                # Handle cases like "A as B"
+                class_name, _ = class_name.split(" as ")
+
+            module = inspect.getmodule(class_)
+            if module is None:
+                # For constants, inspect.getmodule() might return None
+                # In this case, we'll return the original module_path
+                return module_path
         return module.__name__
     except AttributeError as e:
-        logger.warning(f"API Reference: Could not find module for {class_name}, {e}")
+        if class_name is not None:
+            # the class_name might actually be a module
+            # e.g. from langchain import hub
+            # try to import it as a module, and if that doesn't work, throw
+            if class_name is not None:
+                module_name = _get_full_module_name(
+                    f"{module_path}.{class_name}", None, doc_title
+                )
+                if module_name is not None:
+                    # return the name of the parent module, rather than the name of the class as though it were a module
+                    return module.__name__
+                logger.warning(
+                    f"API Reference: Could not find module for {class_name} in {module_path}, imported in doc {doc_title}, {e}"
+                )
+            # don't log if we're trying to import the "hub" part as though it were a module
+        logger.warning(
+            f"API Reference: Could not find module for {module_path}, imported in doc {doc_title}, {e}"
+        )
         return None
     except ImportError as e:
-        logger.warning(f"API Reference: Failed to load for class {class_name}, {e}")
+        logger.warning(
+            f"API Reference: Failed to import module {module_path} {doc_title}, {e}"
+        )
         return None
 
 
@@ -160,7 +197,22 @@ def _get_imports(
             if imp.strip()
         ]
         for class_name in imported_classes:
-            module_path = _get_full_module_name(module, class_name)
+            if module == "langchain_core.messages" and class_name == ")":
+                print("WARNING: ", file=sys.stderr)
+                print(
+                    f"WARNING: Trying to import {class_name} from {module} in doc {doc_title}",
+                    file=sys.stderr,
+                )
+                print("WARNING: ", file=sys.stderr)
+                print("WARNING:", import_match.group(0), file=sys.stderr)
+                print("WARNING: ", file=sys.stderr)
+                print(
+                    "\n".join([f"WARNING: {line}" for line in code.splitlines()]),
+                    file=sys.stderr,
+                )
+                print("WARNING: ", file=sys.stderr)
+
+            module_path = _get_full_module_name(module, class_name, doc_title)
             if not module_path:
                 continue
             if len(module_path.split(".")) < 2:
@@ -230,7 +282,7 @@ def get_imports(code: str, doc_title: str) -> List[ImportInformation]:
     return all_imports
 
 
-def update_markdown_with_imports(markdown: str) -> str:
+def update_markdown_with_imports(markdown: str, file_name: str) -> str:
     """Update markdown to include API reference links for imports in Python code blocks.
 
     This function scans the markdown content for Python code blocks, extracts any imports, and appends links to their API documentation.
@@ -250,7 +302,8 @@ def update_markdown_with_imports(markdown: str) -> str:
         This function will append an API reference link to the `TextGenerator` class from the `langchain.nlp` module if it's recognized.
     """
     code_block_pattern = re.compile(
-        r'(?P<indent>[ \t]*)```(?P<language>python|py)\n(?P<code>.*?)\n(?P=indent)```', re.DOTALL
+        r"(?P<indent>[ \t]*)```(?P<language>python|py)\n(?P<code>.*?)\n(?P=indent)```",
+        re.DOTALL,
     )
 
     def replace_code_block(match: re.Match) -> str:
@@ -262,11 +315,11 @@ def update_markdown_with_imports(markdown: str) -> str:
         Returns:
             str: The modified code block with API reference links appended if applicable.
         """
-        indent = match.group('indent')
-        code_block = match.group('code')
-        language = match.group('language')  # Preserve the language from the regex match
+        indent = match.group("indent")
+        code_block = match.group("code")
+        language = match.group("language")  # Preserve the language from the regex match
         # Retrieve import information from the code block
-        imports = get_imports(code_block, "__unused__")
+        imports = get_imports(code_block, file_name)
 
         original_code_block = match.group(0)
         # If no imports are found, return the original code block
@@ -274,11 +327,11 @@ def update_markdown_with_imports(markdown: str) -> str:
             return original_code_block
 
         # Generate API reference links for each import
-        api_links = ' | '.join(
+        api_links = " | ".join(
             f'<a href="{imp["docs"]}">{imp["imported"]}</a>' for imp in imports
         )
         # Return the code block with appended API reference links
-        return f'{original_code_block}\n\n{indent}API Reference: {api_links}'
+        return f"{original_code_block}\n\n{indent}API Reference: {api_links}"
 
     # Apply the replace_code_block function to all matches in the markdown
     updated_markdown = code_block_pattern.sub(replace_code_block, markdown)

docs/_scripts/generate_llms_text.py

@@ -2,12 +2,11 @@
 
 import glob
 import os
-import pathlib
 
 from mkdocs.structure.files import File
 from mkdocs.structure.pages import Page
 
-from notebook_hooks import _on_page_markdown_with_config
+from _scripts.notebook_hooks import _on_page_markdown_with_config
 
 HERE = os.path.dirname(os.path.abspath(__file__))
 # Get source directory (parent of HERE / docs)

docs/_scripts/hook_state.py

@@ -0,0 +1,4 @@
+hook_state = {
+    "document_filename": "__UNKNOWN__",
+    "document_content": "__UNKNOWN__",
+}

docs/_scripts/notebook_convert.py

@@ -1,30 +1,268 @@
+import argparse
+import ast
+import glob
 import os
 import re
 from pathlib import Path
+from typing import Literal, Optional
 
 import nbformat
 from nbconvert.exporters import MarkdownExporter
 from nbconvert.preprocessors import Preprocessor
 
 
+def _uses_input(source: str) -> bool:
+    """Parse the source code to determine if it uses the input() function."""
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        # If there's a syntax error, assume input() might be present to be safe.
+        return False
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call):
+            # Check if the function called is named 'input'
+            if isinstance(node.func, ast.Name) and node.func.id == "input":
+                return True
+    return False
+
+
+def _rewrite_cell_magic(code: str) -> str:
+    """Process a code block that uses cell magic.:w
+
+    - Lines starting with "%%capture" are ignored.
+    - Lines starting with "%pip" are rewritten by removing the leading "%" character.
+    - Any other non-empty line causes a NotImplementedError.
+
+    Args:
+        code (str): The original code block.
+
+    Returns:
+        str: The transformed code block.
+
+    Raises:
+        NotImplementedError: If a line doesn't start with either "%%capture" or "%pip".
+    """
+    rewritten_lines = []
+
+    for line in code.splitlines():
+        stripped = line.strip()
+        # Skip empty lines
+        if not stripped:
+            continue
+        # Ignore %%capture lines
+        if stripped.startswith("%%capture"):
+            continue
+        # Rewrite %pip lines by dropping the '%'
+        elif stripped.startswith("%pip"):
+            # Drop the leading '%' character
+            rewritten_lines.append(stripped[1:])
+        # Anything else is not supported
+        else:
+            raise NotImplementedError(f"Unhandled line: {line}")
+
+    return "\n".join(rewritten_lines)
+
+
+class PrintCallVisitor(ast.NodeVisitor):
+    """
+    This visitor sets self.has_print to True if it encounters a call
+    to a print within the global scope.
+
+    This should catch calls to print(), print_stream(), etc. (Prefixed with "print").
+
+    May have some false positives, but it's not meant to be perfect.
+
+    Temporary code for notebook conversion.
+    """
+
+    def __init__(self):
+        self.has_print = False
+        self.scope_level = 0  # counter to track whether we're inside a def/lambda
+
+    def visit_FunctionDef(self, node):
+        self.scope_level += 1
+        self.generic_visit(node)
+        self.scope_level -= 1
+
+    def visit_AsyncFunctionDef(self, node):
+        self.scope_level += 1
+        self.generic_visit(node)
+        self.scope_level -= 1
+
+    def visit_Lambda(self, node):
+        self.scope_level += 1
+        self.generic_visit(node)
+        self.scope_level -= 1
+
+    def visit_ClassDef(self, node):
+        self.scope_level += 1
+        self.generic_visit(node)
+        self.scope_level -= 1
+
+    def visit_Call(self, node):
+        # Only consider calls when not inside a function definition.
+        if self.scope_level == 0:
+            if isinstance(node.func, ast.Name) and node.func.id.startswith("print"):
+                self.has_print = True
+        self.generic_visit(node)
+
+
+def _has_output(source: str) -> bool:
+    """Determine if the code block is expected to produce output.
+
+    Args:
+        source (str): The source code of the code block.
+
+    Returns:
+        True if the code block is expected to produce output, False otherwise.
+
+        Must meet the following conditions:
+
+        1. There is a call to a printing function (name starts with "print")
+           that is not inside a function definition.
+        2. The last top-level statement is an expression that is valid if:
+         - It is any expression (including calls) AND
+         - It is NOT a call to `display(...)`.
+
+        `display` isn't handled currently by markdown-exec
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return False
+
+    # Condition (1): Check for a global print-like call.
+    visitor = PrintCallVisitor()
+    visitor.visit(tree)
+    condition_a = visitor.has_print
+
+    # Condition (2): Check the last top-level statement.
+    condition_b = False
+    if tree.body:
+        last_stmt = tree.body[-1]
+        if isinstance(last_stmt, ast.Expr):
+            # If the expression is a call, ensure it's not a call to "display"
+            if isinstance(last_stmt.value, ast.Call):
+                if (
+                    isinstance(last_stmt.value.func, ast.Name)
+                    and last_stmt.value.func.id == "display"
+                ):
+                    condition_b = False  # exclude display-wrapped expressions
+                else:
+                    condition_b = True
+            else:
+                # Any other expression qualifies.
+                condition_b = True
+
+    return condition_a or condition_b
+
+
+def _convert_links_in_markdown(markdown: str) -> str:
+    """Convert links present in notebook markdown cells to standardized format.
+
+    We want to update markdown links code cells by linking to markdown
+    files rather than assuming that the link is to the finalized HTML.
+
+    This code is needed temporarily since the markdown links that are present
+    in ipython notebooks do not follow the same conventions as regular markdown
+    files in mkdocs (which should link to a .md file).
+    """
+
+    # Define the regex pattern in parts for clarity:
+    pattern = (
+        r"(?<!!)"  # Negative lookbehind: ensure the link is not an image (i.e., doesn't start with "!")
+        r"\["  # Literal '[' indicating the start of the link text.
+        r"(?P<text>[^\]]*)"  # Named group 'text': match any characters except ']', representing the link text.
+        r"\]"  # Literal ']' indicating the end of the link text.
+        r"\("  # Literal '(' indicating the start of the URL.
+        r"(?![^\)]*//)"  # Negative lookahead: ensure that the URL does not contain '//' (skip absolute URLs).
+        r"(?P<url>[^)]*)"  # Named group 'url': match any characters except ')', representing the URL.
+        r"\)"  # Literal ')' indicating the end of the URL.
+    )
+
+    def custom_replacement(match):
+        """logic will correct the link format used in ipython notebooks
+
+        Ipython notebooks were being converted directly into HTML links
+        instead of markdown links that retain the markdown extension.
+
+        It needs to handle the following cases:
+        - optional fragments (e.g., `#section`)
+            e.g., `[text](url/#section)` -> `[text](url.md#section)`
+            e.g., `[text](url#section)` -> `[text](url.md#section)`
+        - relative paths (e.g., `../path/to/file`) need to be denested by 1 level
+        """
+        text = match.group("text")
+        url = match.group("url")
+
+        if url.startswith("../"):
+            # we strip the "../" from the start of the URL
+            # We only need to denest one level.
+            url = url[3:]
+
+        url = url.rstrip("/")  # Strip `/` from the end of the URL
+
+        # if url has a fragment
+        if "#" in url:
+            url, fragment = url.split("#")
+            url = url.rstrip("/")
+            # Strip `/` from the end of the URL
+            return f"[{text}]({url}.md#{fragment})"
+        # Otherwise add the .md extension
+        return f"[{text}]({url}.md)"
+
+    return re.sub(
+        pattern,
+        custom_replacement,
+        markdown,
+    )
+
+
 class EscapePreprocessor(Preprocessor):
+    def __init__(self, markdown_exec_migration: bool = False, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self.markdown_exec_migration = markdown_exec_migration
+
     def preprocess_cell(self, cell, resources, cell_index):
         if cell.cell_type == "markdown":
-            # rewrite markdown links to html links (excluding image links)
-            cell.source = re.sub(
-                r"(?<!!)\[([^\]]*)\]\((?![^\)]*//)([^)]*)(?:\.ipynb)?\)",
-                r'<a href="\2">\1</a>',
-                cell.source,
-            )
+            if not self.markdown_exec_migration:
+                # Old logic is to convert ipynb links to HTML links
+                cell.source = re.sub(
+                    r"(?<!!)\[([^\]]*)\]\((?![^\)]*//)([^)]*)(?:\.ipynb)?\)",
+                    r'<a href="\2">\1</a>',
+                    cell.source,
+                )
+            else:
+                cell.source = _convert_links_in_markdown(cell.source)
+
             # Fix image paths in <img> tags
             cell.source = re.sub(
                 r'<img\s+src="\.?/img/([^"]+)"', r'<img src="../img/\1"', cell.source
             )
 
         elif cell.cell_type == "code":
+            # Determine if the cell has bash or cell magic
+            source = cell.source
+            is_exec = not (
+                source.startswith("%") or source.startswith("!") or _uses_input(source)
+            )
+            cell.metadata["exec"] = is_exec
+
+            if self.markdown_exec_migration:
+                # For markdown exec migration we'll re-write cell magic as bash commands
+                if source.startswith("%%"):
+                    cell.source = _rewrite_cell_magic(source)
+                    cell.metadata["language"] = "shell"
+
+                cell.metadata["has_output"] = _has_output(source)
+
             # Remove noqa comments
-            cell.source = re.sub(r'#\s*noqa.*$', '', cell.source, flags=re.MULTILINE)
+            cell.source = re.sub(r"#\s*noqa.*$", "", cell.source, flags=re.MULTILINE)
             # escape ``` in code
+            # This is needed because the markdown exporter will wrap code blocks in
+            # triple backticks, which will break the markdown output if the code block
+            # contains triple backticks.
             cell.source = cell.source.replace("```", r"\`\`\`")
             # escape ``` in output
             if "outputs" in cell:
@@ -114,12 +352,119 @@ exporter = MarkdownExporter(
     ],
 )
 
+md_executable = MarkdownExporter(
+    preprocessors=[
+        ExtractAttachmentsPreprocessor,
+        EscapePreprocessor(markdown_exec_migration=True),
+    ],
+    template_name="md_executable",
+    extra_template_basedirs=[
+        os.path.join(os.path.dirname(__file__), "notebook_convert_templates")
+    ],
+)
+
 
 def convert_notebook(
     notebook_path: Path,
-) -> Path:
+    mode: Literal["markdown", "exec"] = "markdown",
+) -> str:
     with open(notebook_path) as f:
         nb = nbformat.read(f, as_version=4)
 
-    body, _ = exporter.from_notebook_node(nb)
+    nb.metadata.mode = mode
+    if mode == "markdown":
+        body, _ = exporter.from_notebook_node(nb)
+    else:
+        body, _ = md_executable.from_notebook_node(nb)
     return body
+
+
+HERE = Path(__file__).parent
+DOCS = HERE.parent / "docs"
+
+
+# Convert notebooks to markdown
+def _convert_notebooks(
+    *,
+    output_dir: Optional[Path] = None,
+    replace: bool = False,
+    pattern: str = "*.ipynb",
+) -> None:
+    """Converting notebooks."""
+    if not output_dir and not replace:
+        raise ValueError("Either --output_dir or --replace must be specified")
+
+    output_dir_path = DOCS if replace else Path(output_dir)
+
+    # Get the directory where the script was executed
+    base_dir = os.getcwd()
+    # Build the full search pattern using the current working directory as the base
+    full_pattern = os.path.join(base_dir, args.pattern)
+
+    # Use glob with recursive search enabled
+    matching_files = glob.glob(full_pattern, recursive=True)
+    paths = [Path(file) for file in matching_files]
+
+    file_names = [notebook.name for notebook in paths]
+
+    for notebook in paths:
+        markdown = convert_notebook(notebook, mode="exec")
+        markdown_path = output_dir_path / notebook.relative_to(DOCS).with_suffix(".md")
+        markdown_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(markdown_path, "w") as f:
+            f.write(markdown)
+        if replace:
+            notebook.unlink(missing_ok=False)
+
+    if replace:
+        # The regex will match markdown links that point to *.ipynb files.
+        # It captures:
+        #   group(1): the link text (inside the square brackets)
+        #   group(2): the file path (without the trailing .ipynb)
+        link_pattern = r"(?<!!)\[([^\]]+)\]\((?![^)]*//)([^)]+)\.ipynb\)"
+
+        def replace_link(match: re.Match) -> str:
+            link_text = match.group(1)
+            link_target = match.group(2)
+            # Reconstruct the file name with the .ipynb extension.
+            # For example, if link_target is "foo/bar", then linked_file becomes "bar.ipynb".
+            linked_file = Path(link_target).name + ".ipynb"
+            # Only update if the notebook was among those converted.
+            if linked_file in file_names:
+                # Change the extension from .ipynb to .md
+                return f"[{link_text}]({link_target}.md)"
+            # Otherwise, leave the original link intact.
+            return match.group(0)
+
+        # Process all markdown files in the output directory.
+        for path in output_dir_path.rglob("**/*.md"):
+            with open(path, "r", encoding="utf-8") as f:
+                content = f.read()
+            new_content = re.sub(link_pattern, replace_link, content)
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(new_content)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Convert notebooks to markdown")
+    parser.add_argument(
+        "--output_dir",
+        default=None,
+        help="Directory to output markdown files",
+    )
+    parser.add_argument(
+        "--replace",
+        action="store_true",
+        help="Replace original notebooks with markdown files",
+    )
+    parser.add_argument(
+        "--pattern",
+        default="*.ipynb",
+        help="Glob pattern to match notebooks to convert",
+    )
+    args = parser.parse_args()
+    _convert_notebooks(
+        replace=args.replace,
+        output_dir=args.output_dir,
+        pattern=args.pattern,
+    )

docs/_scripts/notebook_convert_templates/md_executable/conf.json

@@ -0,0 +1,5 @@
+{
+  "mimetypes": {
+    "text/markdown": true
+  }
+}

docs/_scripts/notebook_convert_templates/md_executable/index.md.j2

@@ -0,0 +1,38 @@
+{#https://github.com/rdbisme/nbconvert/blob/master/share/jupyter/nbconvert/templates/markdown/index.md.j2#}
+{% extends 'markdown/index.md.j2' %}
+
+{% block input %}
+```
+{%- if 'magics_language' in cell.metadata  -%}
+    {{ cell.metadata.magics_language}}
+{%- elif cell.metadata.get('language') == "shell" -%}
+    shell
+{%- elif 'name' in nb.metadata.get('language_info', {}) -%}
+    {{ nb.metadata.language_info.name }}{% if cell.metadata.exec|default(false) %} exec="on" source="above" session="1"{% if cell.metadata.has_output|default(false) %} result="ansi"{% endif %}{% endif %}
+{%- endif %}
+{{ cell.source}}
+```
+{% endblock input %}
+
+{%- block traceback_line -%}
+{%- endblock traceback_line -%}
+
+{%- block stream -%}
+{%- endblock stream -%}
+
+{%- block data_text scoped -%}
+{%- endblock data_text -%}
+
+{%- block data_html scoped -%}
+```html
+{{ output.data['text/html'] | safe }} 
+```
+{%- endblock data_html -%}
+
+{%- block data_jpg scoped -%}
+![](data:image/jpg;base64,{{ output.data['image/jpeg'] }})
+{%- endblock data_jpg -%}
+
+{%- block data_png scoped -%}
+![](data:image/png;base64,{{ output.data['image/png'] }})
+{%- endblock data_png -%}

docs/_scripts/notebook_hooks.py

@@ -1,14 +1,22 @@
 import logging
 import os
+import posixpath
 import re
-from typing import Any, Dict
+import traceback
+from typing import Any, Callable, Dict
 
+from markdown import Markdown
 from mkdocs.structure.files import Files, File
 from mkdocs.structure.pages import Page
-import posixpath
+from pymdownx.superfences import SuperFencesException
 
-from generate_api_reference_links import update_markdown_with_imports
-from notebook_convert import convert_notebook
+from _scripts.hook_state import hook_state
+from markdown_exec.hooks import SessionHistoryEntry
+
+
+from _scripts.generate_api_reference_links import update_markdown_with_imports
+from _scripts.notebook_convert import convert_notebook
+from _scripts.setup_vcr import get_hash_for_session, load_postamble, load_preamble, _hash_string
 
 logger = logging.getLogger(__name__)
 logging.basicConfig()
@@ -71,7 +79,7 @@ def _highlight_code_blocks(markdown: str) -> str:
     # existing hl_lines for Python and JavaScript
     # Pattern to find code blocks with highlight comments, handling optional indentation
     code_block_pattern = re.compile(
-        r"(?P<indent>[ \t]*)```(?P<language>py|python|js|javascript)(?!\s+hl_lines=)\n"
+        r"(?P<indent>[ \t]*)```(?P<language>\w+)[ ]*(?P<attributes>[^\n]*)\n"
         r"(?P<code>((?:.*\n)*?))"  # Capture the code inside the block using named group
         r"(?P=indent)```"  # Match closing backticks with the same indentation
     )
@@ -80,6 +88,13 @@ def _highlight_code_blocks(markdown: str) -> str:
         indent = match.group("indent")
         language = match.group("language")
         code_block = match.group("code")
+        attributes = match.group("attributes").rstrip()
+
+        # Account for a case where hl_lines is manually specified
+        if "hl_lines" in attributes:
+            # Return original code block
+            return match.group(0)
+
         lines = code_block.split("\n")
         highlighted_lines = []
 
@@ -105,25 +120,132 @@ def _highlight_code_blocks(markdown: str) -> str:
         # Reconstruct the new code block
         new_code_block = "\n".join(lines_to_keep)
 
+        # Construct the full code block that also includes
+        # the fenced code block syntax.
+        opening_fence = f"```{language}"
+
+        if attributes:
+            opening_fence += f" {attributes}"
+
         if highlighted_lines:
-            return (
-                f'{indent}```{language} hl_lines="{" ".join(highlighted_lines)}"\n'
-                # The indent and terminating \n is already included in the code block
-                f'{new_code_block}'
-                f'{indent}```'
-            )
-        else:
-            return (
-                f"{indent}```{language}\n"
-                # The indent and terminating \n is already included in the code block
-                f"{new_code_block}"
-                f"{indent}```"
-            )
+            opening_fence += f" hl_lines=\"{' '.join(highlighted_lines)}\""
+
+        return (
+            # The indent and opening fence
+            f"{indent}{opening_fence}\n"
+            # The indent and terminating \n is already included in the code block
+            f"{new_code_block}"
+            f"{indent}```"
+        )
 
     # Replace all code blocks in the markdown
     markdown = code_block_pattern.sub(replace_highlight_comments, markdown)
     return markdown
 
+def handle_vcr_setup(
+    *,
+    formatter: Callable,
+    language: str,
+    code: str,
+    session: str,
+    id: str,
+    md: Markdown,
+    **kwargs: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Handle VCR setup in markdown content if necessary."""
+    logger.info(f"handle_vcr_setup: {hook_state['document_filename']}")
+    try:
+        if hook_state['document_filename'] == '__UNKNOWN__':
+            raise SuperFencesException(
+                f"error while processing {language} block: document filename hasn't been set yet"
+            )
+        
+        if hook_state['document_content'] == '__UNKNOWN__':
+            raise SuperFencesException(
+                f"error while processing {language} block: document content hasn't been set yet"
+            )
+
+        if session is None or session == "" and id is None or id == "":
+            id = _hash_string(code)
+
+        if session is not None and session != "":
+            logger.info(f"new {language} session {session} on page {hook_state['document_filename']}")
+
+        cassette_prefix = hook_state['document_filename'].replace(".md", "").replace(os.path.sep, "_")
+
+        cassette_dir = os.path.abspath(
+            os.path.join(os.path.dirname(os.path.dirname(__file__)), "cassettes")
+        )
+        os.makedirs(cassette_dir, exist_ok=True)
+
+        # Build a unique cassette name.
+        cassette_name = os.path.join(
+            cassette_dir,
+            f"{cassette_prefix}_{session if session else id}_{language}.msgpack.zlib",
+        )
+
+        # Add context manager at start with explicit __enter__ and __exit__ calls
+
+        hash_ = get_hash_for_session(language, session, hook_state['document_content'])
+        wrapped_lines = [
+            load_preamble(language, hash_, cassette_name),
+            code,
+        ]
+
+        if session is None or session == "":
+            logger.info(
+                f"no session, adding postamble for {language} in {hook_state['document_filename']}"
+            )
+            wrapped_lines.append(load_postamble(language))
+
+        transformed_source = "\n".join(wrapped_lines)
+
+        # Propagate extras
+        keep_extras = {
+            key: value
+            for key, value in kwargs["extra"].items()
+            if key
+            in {
+                "hl_lines",
+            }
+        }
+
+        return dict(
+            transform_source=lambda code: (transformed_source, code),
+            id=id,
+            extra={ **keep_extras, "path": hook_state['document_filename'] },
+        )
+    except Exception as e:
+        raise SuperFencesException(traceback.format_exc()) from e
+
+
+def handle_vcr_teardown(
+    *,
+    formatter: Callable,
+    language: str,
+    session: str,
+    history: list[SessionHistoryEntry],
+):
+    code = load_postamble(language)
+    html = False
+    update_toc = False
+
+    logger.info(f"tearing down {language} {session} on {hook_state['document_filename']}")
+
+    kwargs = dict(
+        code=code,
+        session=session,
+        id=f"{id}_vcr_end",
+        md=None, # md is unused by the formatter, but it's a required argument
+        html=html,
+        update_toc=update_toc,
+        extra={},
+    )
+
+    # This doesn't actually render anything, we just call the formatter so it
+    # executes in the same context as the session of which we're disposing.
+    formatter(**kwargs)
+
 
 def _on_page_markdown_with_config(
     markdown: str,
@@ -135,24 +257,27 @@ def _on_page_markdown_with_config(
 ) -> str:
     if DISABLED:
         return markdown
+
     if page.file.src_path.endswith(".ipynb"):
-        logger.info("Processing Jupyter notebook: %s", page.file.src_path)
+        # logger.info("Processing Jupyter notebook: %s", page.file.src_path)
         markdown = convert_notebook(page.file.abs_src_path)
 
     # Append API reference links to code blocks
     if add_api_references:
-        markdown = update_markdown_with_imports(markdown)
+        markdown = update_markdown_with_imports(markdown, page.file.src_path)
     # Apply highlight comments to code blocks
     markdown = _highlight_code_blocks(markdown)
 
     if remove_base64_images:
         # Remove base64 encoded images from markdown
-        markdown = re.sub(r"!\[.*?\]\(data:image/[^;]+;base64,[^\)]+\)", "", markdown)
+        markdown = re.sub(r"!\[.*?\]\(data:image/+;base64,[^\)]+\)", "", markdown)
 
     return markdown
 
 
 def on_page_markdown(markdown: str, page: Page, **kwargs: Dict[str, Any]):
+    logger.info(f"on_page_markdown: {page.file.src_path}")
+    hook_state['document_filename'] = page.file.src_path
     return _on_page_markdown_with_config(
         markdown,
         page,
@@ -160,6 +285,7 @@ def on_page_markdown(markdown: str, page: Page, **kwargs: Dict[str, Any]):
         **kwargs,
     )
 
+
 # redirects
 
 HTML_TEMPLATE = """
@@ -213,3 +339,9 @@ def on_post_build(config):
             + suffix
         )
         write_html(config["site_dir"], old_html_path, new_html_path)
+
+def on_pre_page(page: Page, **kwargs: Dict[str, Any]):
+    logger.info(f"on_pre_page: {page.file.src_path}")
+    hook_state['document_filename'] = page.file.src_path
+    hook_state['document_content'] = page.file.content_string
+    return page

docs/_scripts/setup_vcr.py

@@ -0,0 +1,140 @@
+# A list of patterns that, if found in a code block, will cause us to leave that block unchanged.
+import hashlib
+import json
+import os
+import re
+from textwrap import dedent, indent
+
+from mistune import BlockParser, BlockState, Markdown, create_markdown
+from mistune.renderers.markdown import MarkdownRenderer
+
+preambles = {
+    "python": "vcr_setup_preamble.py",
+    "typescript": "nock_setup_preamble.ts",
+}
+
+
+def _get_python_cassette_init(cassette_name: str, hash_: str) -> str:
+    return dedent(
+        f"""
+        _cassette = HashedCassette('{cassette_name}', '{hash_}')
+        _cassette.__enter__()
+        """
+    )
+
+
+def _get_typescript_cassette_init(cassette_name: str, hash_: str) -> str:
+    return dedent(
+        f"""
+        const _cassette = new HashedCassette("{cassette_name}", "{hash_}");
+        await _cassette.enter();
+        """
+    )
+
+
+def _get_python_cassette_cleanup() -> str:
+    return "_cassette.__exit__()"
+
+
+def _get_typescript_cassette_cleanup() -> str:
+    return "await _cassette.exit();"
+
+
+preamble_inits = {
+    "python": _get_python_cassette_init,
+    "py": _get_python_cassette_init,
+    "typescript": _get_typescript_cassette_init,
+    "ts": _get_typescript_cassette_init,
+}
+
+preamble_cleanups = {
+    "python": _get_python_cassette_cleanup,
+    "py": _get_python_cassette_cleanup,
+    "typescript": _get_typescript_cassette_cleanup,
+    "ts": _get_typescript_cassette_cleanup,
+}
+
+
+def load_preamble(language: str, hash_: str, cassette_name: str) -> str:
+    """Load the source code for the preamble for a given language."""
+    _assets_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "assets")
+
+    preamble_path = os.path.join(_assets_dir, preambles[language])
+    with open(preamble_path, "r") as f:
+        lines = f.readlines()
+        lines.append(preamble_inits[language](cassette_name, hash_))
+        return "\n".join(lines).strip()
+
+
+def load_postamble(language: str) -> str:
+    """Load the source code for the postamble for a given language."""
+    return preamble_cleanups[language]()
+
+
+def _hash_string(input_string: str) -> str:
+    # Encode the input string to bytes
+    encoded_string = input_string.encode("utf-8")
+    # Create a SHA-256 hash object
+    sha256_hash = hashlib.sha256(encoded_string)
+    # Get the hexadecimal digest of the hash
+    return sha256_hash.hexdigest()
+
+
+def extract_code_blocks_for_session(language: str, session: str, content: str) -> str:
+    code_blocks_for_session = []
+
+    TAB_REGEX = r"^===!? \"(?P<title>[^\"]+)\"\n(?P<content>(?:(?P<indent>    )+[^\n]*\n)+)"
+    def parse_tabs(block: BlockParser, m: re.Match, state: BlockState) -> str:
+        state.append_token(
+            {
+                "raw": m.group(0),
+                "type": "block_tab",
+                "attrs": {
+                    "title": m.group("title"),
+                    "level": len(m.group("indent")) // 4,
+                    "content": dedent(m.group("content")).strip(),
+                },
+            }
+        )
+        return m.end()
+
+    def render_tabs(self, token: dict, state: BlockState):
+        recursive_transformer = create_markdown(renderer=DocumentRenderer())
+        recursive_transformer.block.register("block_tab", TAB_REGEX, parse_tabs, before='list')
+        recursive_transformer.renderer.register("block_tab", render_tabs)
+        return (
+            f'=== "{token["attrs"]["title"]}"\n'
+            f'{indent(recursive_transformer(token["attrs"]["content"]), "    " * token["attrs"]["level"])}\n'
+        )
+
+    class DocumentRenderer(MarkdownRenderer):
+        def block_code(self, token: dict, state: BlockState):
+            if token["style"] == "fenced":
+                if token["attrs"]["info"]:
+                    attributes = {}
+                    block_language = token["attrs"]["info"].split()[0]
+                    for match in re.finditer(r'(?P<key>\w+)=(?:(?P<value>(?:[\w]+))|"(?P<value_quoted>(?:[^"\s]+))")', token["attrs"]["info"]):
+                        attributes[match.group("key")] = match.group("value") or match.group("value_quoted")
+                    if block_language == language and "session" in attributes and attributes["session"] == session:
+                        code_blocks_for_session.append(token["raw"].rstrip())
+            return super().block_code(token, state)
+
+    transformer: Markdown = create_markdown(renderer=DocumentRenderer())
+    transformer.block.register("block_tab", TAB_REGEX, parse_tabs, before='list')
+    transformer.renderer.register("block_tab", render_tabs)
+    
+    # Parses the page content, which causes the code blocks to be added to the code_blocks_for_session list.
+    # There's probably some way to do this by using the renderer as a filter, but I would've had to NO-OP
+    # all of the default behavior, and this was easier.
+    transformer(content)
+
+    return code_blocks_for_session
+
+
+def get_hash_for_session(language: str, session: str, content: str) -> str:
+    # include the preamble in the hash so we invalidate if it changes
+    preamble_hash = _hash_string(load_preamble(language, session, "test"))
+
+    code_blocks_for_session = [preamble_hash, *extract_code_blocks_for_session(language, session, content)]
+    
+    return _hash_string("\n".join(code_blocks_for_session))

docs/_scripts/third_party_page/create_third_party_page.py

@@ -9,7 +9,7 @@ import yaml
 
 MARKDOWN = """\
 [//]: # (This file is automatically generated using a script in docs/_scripts. Do not edit this file directly!)
-# 🚀 Prebuilt Libraries
+# 🚀 Prebuilt Agents
 
 LangGraph includes a prebuilt React agent. For more information on how to use it, 
 check out our [how-to guides](https://langchain-ai.github.io/langgraph/how-tos/#prebuilt-react-agent).
@@ -19,6 +19,7 @@ below. These libraries can extend LangGraph's functionality in various ways.
 
 ## 📚 Available Libraries
 
+[//]: # (This file is automatically generated using a script in docs/_scripts. Do not edit this file directly!)
 {library_list}
 
 ## ✨ Contributing Your Library

docs/_scripts/third_party_page/packages.yml

@@ -3,3 +3,9 @@ packages:
   - name: "trustcall"
     repo: "hinthornw/trustcall"
     description: "Tenacious tool calling built on LangGraph"
+  - name: "breeze-agent"
+    repo: "andrestorres123/breeze-agent"
+    description: "A streamlined research system built inspired on STORM and built on LangGraph"
+  - name: "langgraph-supervisor"
+    repo: "langchain-ai/langgraph-supervisor"
+    description: "Build supervisor multi-agent systems with LangGraph"

docs/codespell_notebooks.sh

@@ -1,6 +1,17 @@
 ERROR_FOUND=0
 for file in $(find $1 -name "*.ipynb" | grep -v ".ipynb_checkpoints"); do
-    OUTPUT=$(cat "$file" | jupytext --from ipynb --to py:percent | codespell -)
+    # Adding regexp to ignore base64 strings
+    OUTPUT=$(cat "$file" | jupytext --from ipynb --to py:percent | codespell --ignore-regex='[A-Za-z0-9+/=]{25,}' -)
+    if [ -n "$OUTPUT" ]; then
+        echo "Errors found in $file"
+        echo "$OUTPUT"
+        ERROR_FOUND=1
+    fi
+done
+
+for file in $(find $1 -name "*.md"); do
+    # Adding regexp to ignore base64 strings
+    OUTPUT=$(cat "$file" | codespell --ignore-regex='[A-Za-z0-9+/=]{25,}' -)
     if [ -n "$OUTPUT" ]; then
         echo "Errors found in $file"
         echo "$OUTPUT"

docs/docs/adopters.md

@@ -0,0 +1,25 @@
+# 🦜🕸️ LangGraph Adopters
+
+This list of companies using LangGraph and their success stories is compiled from public sources. If your company uses LangGraph, we'd love for you to share your story and add it to the list. You’re also welcome to contribute updates based on publicly available information from other companies, such as blog posts or press releases.
+
+
+| Company | Industry | Use case | Reference |
+| --- | --- | --- | --- |
+| [AirTop](https://www.airtop.ai/) | Software & Technology (GenAI Native) | Browser automation for AI agents | [Case study, 2024](https://blog.langchain.dev/customers-airtop/) |
+| [AppFolio](https://www.appfolio.com/) | Real Estate | Copilot for domain-specific task | [Case study, 2024](https://blog.langchain.dev/customers-appfolio/) |
+| [Athena Intelligence](https://www.athenaintel.com/) | Software & Technology (GenAI Native) | Research & summarization | [Case study, 2024](https://blog.langchain.dev/customers-athena-intelligence/) |
+| [Captide](https://www.captide.co/) | Software & Technology (GenAI Native) | Data extraction | [Case study, 2025](https://blog.langchain.dev/how-captide-is-redefining-equity-research-with-agentic-workflows-built-on-langgraph-and-langsmith/) |
+| [Elastic](https://www.elastic.co/) | Software & Technology | Copilot for domain-specific task | [Blog post, 2025](https://www.elastic.co/blog/elastic-security-generative-ai-features) |
+| [GitLab](https://about.gitlab.com/) | Software & Technology | Code generation | [Duo workflow docs](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/duo_workflow/) |
+| [Infor](https://infor.com/) | Software & Technology | GenAI embedded product experiences; customer support; copilot | [Case study, 2025](https://blog.langchain.dev/customers-infor/) |
+| [Komodo Health](https://www.komodohealth.com/) | Healthcare | Copilot for domain-specific task | [Blog post](https://www.komodohealth.com/perspectives/new-gen-ai-assistant-empowers-the-enterprise/) |
+| [LinkedIn](https://www.linkedin.com/) | Social Media | Code generation; Search & discovery | [Blog post, 2025](https://www.linkedin.com/blog/engineering/ai/practical-text-to-sql-for-data-analytics); [Blog post, 2024](https://www.linkedin.com/blog/engineering/generative-ai/behind-the-platform-the-journey-to-create-the-linkedin-genai-application-tech-stack) |
+| [Minimal](https://gominimal.ai/) | E-commerce | Customer support | [Case study, 2025](https://blog.langchain.dev/how-minimal-built-a-multi-agent-customer-support-system-with-langgraph-langsmith/) |
+| [OpenRecovery](https://www.openrecovery.com/) | Healthcare | Copilot for domain-specific task | [Case study, 2024](https://blog.langchain.dev/customers-openrecovery/) |
+| [Rakuten](https://www.rakuten.com/) | E-commerce / Fintech | Copilot for domain-specific task | [Blog post, 2025](https://rakuten.today/blog/from-ai-hype-to-real-world-tools-rakuten-teams-up-with-langchain.html) |
+| [Replit](https://replit.com/) | Software & Technology | Code generation | [Blog post, 2024](https://blog.langchain.dev/customers-replit/); [Breakout agent story, 2024](https://www.langchain.com/breakoutagents/replit); [Fireside chat video, 2024](https://www.youtube.com/watch?v=ViykMqljjxU) |
+| [Rexera](https://www.rexera.com/) | Real Estate (GenAI Native) | Copilot for domain-specific task | [Case study, 2024](https://blog.langchain.dev/customers-rexera/) |
+| [Tradestack](https://www.tradestack.uk/) | Software & Technology (GenAI Native) | Copilot for domain-specific task | [Case study, 2024](https://blog.langchain.dev/customers-tradestack/) |
+| [Uber](https://www.uber.com/) | Transportation | Developer productivity; Code generation | [Presentation, 2024](https://dpe.org/sessions/ty-smith-adam-huda/this-year-in-ubers-ai-driven-developer-productivity-revolution/); [Video, 2024](https://www.youtube.com/watch?v=8rkA5vWUE4Y) |
+| [Unify](https://www.unifygtm.com/) | Software & Technology (GenAI Native) | Copilot for domain-specific task | [Blog post, 2024](https://blog.langchain.dev/unify-launches-agents-for-account-qualification-using-langgraph-and-langsmith/) |
+| [Vizient](https://www.vizientinc.com/) | Healthcare | Copilot for domain-specific task | [Case study, 2025](https://blog.langchain.dev/p/3d2cd58c-13a5-4df9-bd84-7d54ed0ed82c/) |

docs/docs/cloud/how-tos/stateless_runs.md

@@ -99,7 +99,7 @@ We can stream the results of a stateless run in an almost identical fashion to h
 
     ```bash
     curl --request POST \
-        --url <DEPLOYMENT_URL>/threads/<THREAD_ID>/runs/stream \
+        --url <DEPLOYMENT_URL>/runs/stream \
         --header 'Content-Type: application/json' \
         --data "{
             \"assistant_id\": \"agent\",
@@ -144,7 +144,7 @@ In addition to streaming, you can also wait for a stateless result by using the
 
     ```bash
     curl --request POST \
-        --url <DEPLOYMENT_URL>/runs/runs/wait \
+        --url <DEPLOYMENT_URL>/runs/wait \
         --header 'Content-Type: application/json' \
         --data '{
             "assistant_id": <ASSISTANT_IDD>,

docs/docs/cloud/how-tos/use_stream_react.md

@@ -0,0 +1,410 @@
+# How to integrate LangGraph into your React application
+
+!!! info "Prerequisites"
+    - [LangGraph Platform](../../concepts/langgraph_platform.md)
+    - [LangGraph Server](../../concepts/langgraph_server.md)
+
+The `useStream()` React hook provides a seamless way to integrate LangGraph into your React applications. It handles all the complexities of streaming, state management, and branching logic, letting you focus on building great chat experiences.
+
+Key features:
+
+- Messages streaming: Handle a stream of message chunks to form a complete message
+- Automatic state management for messages, loading states, and errors
+- Conversation branching: Create alternate conversation paths from any point in the chat history
+- UI-agnostic design - bring your own components and styling
+
+Let's explore how to use `useStream()` in your React application.
+
+The `useStream()` provides a solid foundation for creating bespoke chat experiences. For pre-built chat components and interfaces, we recommend checking out [CopilotKit](https://docs.copilotkit.ai/coagents/quickstart/langgraph) and [assistant-ui](https://github.com/langchain-ai/assistant-ui).
+
+## Example
+
+```tsx
+"use client";
+
+import { useStream } from "@langchain/langgraph-sdk/react";
+import type { Message } from "@langchain/langgraph-sdk";
+
+export default function App() {
+  const thread = useStream<{ messages: Message[] }>({
+    apiUrl: "http://localhost:2024",
+    assistantId: "agent",
+    messagesKey: "messages",
+  });
+
+  return (
+    <div>
+      <div>
+        {thread.messages.map((message) => (
+          <div key={message.id}>{message.content as string}</div>
+        ))}
+      </div>
+
+      <form
+        onSubmit={(e) => {
+          e.preventDefault();
+
+          const form = e.target as HTMLFormElement;
+          const message = new FormData(form).get("message") as string;
+
+          form.reset();
+          thread.submit({ messages: [{ type: "human", content: message }] });
+        }}
+      >
+        <input type="text" name="message" />
+
+        {thread.isLoading ? (
+          <button key="stop" type="button" onClick={() => thread.stop()}>
+            Stop
+          </button>
+        ) : (
+          <button key="submit" type="submit">
+            Send
+          </button>
+        )}
+      </form>
+    </div>
+  );
+}
+```
+
+## Customizing Your UI
+
+The `useStream()` hook takes care of all the complex state management behind the scenes, providing you with simple interfaces to build your UI. Here's what you get out of the box:
+
+- Thread state management
+- Loading and error states
+- Message handling and updates
+- Branching support
+
+Here are some examples on how to use these features effectively:
+
+### Loading States
+
+The `isLoading` property tells you when a stream is active, enabling you to:
+
+- Show a loading indicator
+- Disable input fields during processing
+- Display a cancel button
+
+```tsx
+export default function App() {
+  const { isLoading, stop } = useStream<{ messages: Message[] }>({
+    apiUrl: "http://localhost:2024",
+    assistantId: "agent",
+    messagesKey: "messages",
+  });
+
+  return (
+    <form>
+      {isLoading && (
+        <button key="stop" type="button" onClick={() => stop()}>
+          Stop
+        </button>
+      )}
+    </form>
+  );
+}
+```
+
+### Thread Management
+
+Keep track of conversations with built-in thread management. You can access the current thread ID and get notified when new threads are created:
+
+```tsx
+const [threadId, setThreadId] = useState<string | null>(null);
+
+const thread = useStream<{ messages: Message[] }>({
+  apiUrl: "http://localhost:2024",
+  assistantId: "agent",
+
+  threadId: threadId,
+  onThreadId: setThreadId,
+});
+```
+
+We recommend storing the `threadId` in your URL's query parameters to let users resume conversations after page refreshes.
+
+### Messages Handling
+
+To enable messages handling, you need to pass the `messagesKey` option to the `useStream()` hook. 
+
+When enabled, the `useStream()` hook will keep track of the message chunks received from the server and concatenate them together to form a complete message. The completed message chunks can be retrieved via the `messages` property.
+
+```tsx
+import type { Message } from "@langchain/langgraph-sdk";
+import { useStream } from "@langchain/langgraph-sdk/react";
+
+export default function HomePage() {
+  const thread = useStream<{ messages: Message[] }>({
+    apiUrl: "http://localhost:2024",
+    assistantId: "agent",
+    messagesKey: "messages",
+  });
+
+  return (
+    <div>
+      {thread.messages.map((message) => (
+        <div key={message.id}>{message.content as string}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Branching Support
+
+To enable branching, you need to enable messages handling. Pass the `messagesKey` option to the `useStream()` hook. For each message, you can use `getMessagesMetadata()` to get the first checkpoint from which the message has been first seen. You can then create a new run from the checkpoint preceding the first seen checkpoint to create a new branch in a thread.
+
+A branch can be created in following ways:
+
+1. Edit a previous user message.
+2. Request a regeneration of a previous assistant message.
+
+```tsx
+/* eslint-disable @typescript-eslint/no-floating-promises */
+"use client";
+
+import type { Message } from "@langchain/langgraph-sdk";
+import { useStream } from "@langchain/langgraph-sdk/react";
+import {
+  Annotation,
+  MessagesAnnotation,
+  type StateType,
+  type UpdateType,
+} from "@langchain/langgraph/web";
+import { useState } from "react";
+
+const AgentState = Annotation.Root({
+  ...MessagesAnnotation.spec,
+});
+
+function BranchSwitcher({
+  branch,
+  branchOptions,
+  onSelect,
+}: {
+  branch: string | undefined;
+  branchOptions: string[] | undefined;
+  onSelect: (branch: string) => void;
+}) {
+  if (!branchOptions || !branch) return null;
+  const index = branchOptions.indexOf(branch);
+
+  return (
+    <div className="flex items-center gap-2">
+      <button
+        type="button"
+        onClick={() => {
+          const prevBranch = branchOptions[index - 1];
+          if (!prevBranch) return;
+          onSelect(prevBranch);
+        }}
+      >
+        Prev
+      </button>
+      <span>
+        {index + 1} / {branchOptions.length}
+      </span>
+      <button
+        type="button"
+        onClick={() => {
+          const nextBranch = branchOptions[index + 1];
+          if (!nextBranch) return;
+          onSelect(nextBranch);
+        }}
+      >
+        Next
+      </button>
+    </div>
+  );
+}
+
+function EditMessage({
+  message,
+  onEdit,
+}: {
+  message: Message;
+  onEdit: (message: Message) => void;
+}) {
+  const [editing, setEditing] = useState(false);
+
+  if (!editing) {
+    return (
+      <button type="button" onClick={() => setEditing(true)}>
+        Edit
+      </button>
+    );
+  }
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        const form = e.target as HTMLFormElement;
+        const content = new FormData(form).get("content") as string;
+
+        form.reset();
+        onEdit({ type: "human", content });
+        setEditing(false);
+      }}
+    >
+      <input name="content" defaultValue={message.content as string} />
+      <button type="submit">Save</button>
+    </form>
+  );
+}
+
+export default function App() {
+  const thread = useStream<
+    StateType<typeof AgentState.spec>,
+    UpdateType<typeof AgentState.spec>
+  >({
+    apiUrl: "http://localhost:2024",
+    assistantId: "agent",
+    messagesKey: "messages",
+  });
+
+  return (
+    <div>
+      <div>
+        {thread.messages.map((message) => {
+          const meta = thread.getMessagesMetadata(message);
+          const parentCheckpoint = meta?.firstSeenState?.parent_checkpoint;
+
+          return (
+            <div key={message.id}>
+              <div>{message.content as string}</div>
+
+              {message.type === "human" && (
+                <EditMessage
+                  message={message}
+                  onEdit={(message) =>
+                    thread.submit(
+                      { messages: [message] },
+                      { checkpoint: parentCheckpoint }
+                    )
+                  }
+                />
+              )}
+
+              {message.type === "ai" && (
+                <button
+                  type="button"
+                  onClick={() =>
+                    thread.submit(undefined, { checkpoint: parentCheckpoint })
+                  }
+                >
+                  <span>Regenerate</span>
+                </button>
+              )}
+
+              <BranchSwitcher
+                branch={meta?.branch}
+                branchOptions={meta?.branchOptions}
+                onSelect={(branch) => thread.setBranch(branch)}
+              />
+            </div>
+          );
+        })}
+      </div>
+
+      <form
+        onSubmit={(e) => {
+          e.preventDefault();
+
+          const form = e.target as HTMLFormElement;
+          const message = new FormData(form).get("message") as string;
+
+          form.reset();
+          thread.submit({ messages: [message] });
+        }}
+      >
+        <input type="text" name="message" />
+
+        {thread.isLoading ? (
+          <button key="stop" type="button" onClick={() => thread.stop()}>
+            Stop
+          </button>
+        ) : (
+          <button key="submit" type="submit">
+            Send
+          </button>
+        )}
+      </form>
+    </div>
+  );
+}
+```
+
+### TypeScript
+
+The `useStream()` hook is fully typed to help catch errors early and provide better IDE support. You can specify types for:
+
+- State shape
+- Update format
+- Custom events
+
+```tsx
+// Define your types
+type State = {
+  messages: Message[];
+  context?: Record<string, unknown>;
+};
+
+type Update = {
+  messages: Message[] | Message;
+  context?: Record<string, unknown>;
+};
+
+type CustomEvent = {
+  type: "progress" | "debug";
+  payload: unknown;
+};
+
+// Use them with the hook
+const thread = useStream<State, Update, CustomEvent>({
+  apiUrl: "http://localhost:2024",
+  assistantId: "agent",
+  messagesKey: "messages",
+});
+```
+
+If you're using LangGraph.js, you can reuse your graph's annotation types:
+
+```tsx
+import {
+  Annotation,
+  MessagesAnnotation,
+  type StateType,
+  type UpdateType,
+} from "@langchain/langgraph/web";
+
+const AgentState = Annotation.Root({
+  ...MessagesAnnotation.spec,
+  context: Annotation.Optional(Annotation.Any()),
+});
+
+const thread = useStream<
+  StateType<typeof AgentState.spec>,
+  UpdateType<typeof AgentState.spec>
+>({
+  apiUrl: "http://localhost:2024",
+  assistantId: "agent",
+  messagesKey: "messages",
+});
+```
+
+## Event Handling
+
+The `useStream()` hook provides several callback options to help you respond to different events:
+
+- `onError`: Called when an error occurs.
+- `onFinish`: Called when the stream is finished.
+- `onUpdateEvent`: Called when an update event is received.
+- `onCustomEvent`: Called when a custom event is received. See [Custom events](../../concepts/streaming.md#custom) to learn how to stream custom events.
+- `onMetadataEvent`: Called when a metadata event is received.
+
+## Learn More
+
+- [JS/TS SDK Reference](../reference/sdk/js_ts_sdk_ref.md)

docs/docs/concepts/application_structure.md

@@ -34,10 +34,10 @@ Below are examples of directory structures for Python and JavaScript application
     │   │   ├── tools.py # tools for your graph
     │   │   ├── nodes.py # node functions for you graph
     │   │   └── state.py # state definition of your graph
-    │   ├── requirements.txt # package dependencies
     │   ├── __init__.py
     │   └── agent.py # code for constructing your graph
     ├── .env # environment variables
+    ├── requirements.txt # package dependencies
     └── langgraph.json # configuration file for LangGraph
     ```
 === "Python (pyproject.toml)"

docs/docs/concepts/auth.md

@@ -27,12 +27,19 @@ LangGraph Platform provides different security defaults:
 - Requires valid API key in `x-api-key` header
 - Can be customized with your auth handler
 
+!!! note "Custom auth"
+    Custom auth **is supported** for all plans in LangGraph Cloud.
+
 ### Self-Hosted
 
 - No default authentication
 - Complete flexibility to implement your security model
 - You control all aspects of authentication and authorization
 
+!!! note "Custom auth"
+    Custom auth is supported for **Enterprise** self-hosted plans.
+    Self-hosted lite plans do not support custom auth natively.
+
 ## System Architecture
 
 A typical authentication setup involves three main components:

docs/docs/concepts/breakpoints.md

@@ -88,7 +88,7 @@ We recommend that you [**use the `interrupt` function instead**](#the-interrupt-
 
 ??? node "`NodeInterrupt` exception"
 
-    The developer can define some *condition* that must be met for a breakpoint to be triggered. This concept of [dynamic breakpoints](./low_level.md#dynamic-breakpoints) is useful when the developer wants to halt the graph under *a particular condition*. This uses a `NodeInterrupt`, which is a special type of exception that can be raised from within a node based upon some condition. As an example, we can define a dynamic breakpoint that triggers when the `input` is longer than 5 characters.
+    The developer can define some *condition* that must be met for a breakpoint to be triggered. This concept of _dynamic breakpoints_ is useful when the developer wants to halt the graph under *a particular condition*. This uses a `NodeInterrupt`, which is a special type of exception that can be raised from within a node based upon some condition. As an example, we can define a dynamic breakpoint that triggers when the `input` is longer than 5 characters.
 
     ```python
     def my_node(state: State) -> State:

docs/docs/concepts/index.md

@@ -26,8 +26,8 @@ The conceptual guide does not cover step-by-step instructions or specific implem
 - [Human-in-the-Loop](human_in_the_loop.md): Explains different ways of integrating human feedback into a LangGraph application.
 - [Time Travel](time-travel.md): Time travel allows you to replay past actions in your LangGraph application to explore alternative paths and debug issues.
 - [Persistence](persistence.md): LangGraph has a built-in persistence layer, implemented through checkpointers. This persistence layer helps to support powerful capabilities like human-in-the-loop, memory, time travel, and fault-tolerance.
-- [Memory](memory.md): Memory in AI applications refers to the ability to process, store, and effectively recall information from past interactions. With memory, your agents can learn from feedback and adapt to users' preferences.  
-- [Streaming](streaming.md): Streaming is crucial for enhancing the responsiveness of applications built on LLMs. By displaying output progressively, even before a complete response is ready, streaming significantly improves user experience (UX), particularly when dealing with the latency of LLMs. 
+- [Memory](memory.md): Memory in AI applications refers to the ability to process, store, and effectively recall information from past interactions. With memory, your agents can learn from feedback and adapt to users' preferences.
+- [Streaming](streaming.md): Streaming is crucial for enhancing the responsiveness of applications built on LLMs. By displaying output progressively, even before a complete response is ready, streaming significantly improves user experience (UX), particularly when dealing with the latency of LLMs.
 - [Functional API (beta)](functional_api.md): An alternative to [Graph API (StateGraph)](low_level.md#stategraph) for development in LangGraph.
 - [FAQ](faq.md): Frequently asked questions about LangGraph.
 
@@ -37,7 +37,6 @@ LangGraph Platform is a commercial solution for deploying agentic applications i
 
 The LangGraph Platform offers a few different deployment options described in the [deployment options guide](./deployment_options.md).
 
-
 !!! tip
 
     * LangGraph is an MIT-licensed open-source library, which we are committed to maintaining and growing for the community.
@@ -46,6 +45,7 @@ The LangGraph Platform offers a few different deployment options described in th
 ### High Level
 
 - [Why LangGraph Platform?](./langgraph_platform.md): The LangGraph platform is an opinionated way to deploy and manage LangGraph applications. This guide provides an overview of the key features and concepts behind LangGraph Platform.
+- [Platform Architecture](./platform_architecture.md): A high-level overview of the architecture of the LangGraph Platform.
 - [Deployment Options](./deployment_options.md): LangGraph Platform offers four deployment options: [Self-Hosted Lite](./self_hosted.md#self-hosted-lite), [Self-Hosted Enterprise](./self_hosted.md#self-hosted-enterprise), [bring your own cloud (BYOC)](./bring_your_own_cloud.md), and [Cloud SaaS](./langgraph_cloud.md). This guide explains the differences between these options, and which Plans they are available on.
 - [Plans](./plans.md): LangGraph Platforms offer three different plans: Developer, Plus, Enterprise. This guide explains the differences between these options, what deployment options are available for each, and how to sign up for each one.
 - [Template Applications](./template_applications.md): Reference applications designed to help you get started quickly when building with LangGraph.
@@ -54,7 +54,7 @@ The LangGraph Platform offers a few different deployment options described in th
 
 The LangGraph Platform comprises several components that work together to support the deployment and management of LangGraph applications:
 
-- [LangGraph Server](./langgraph_server.md): The LangGraph Server is designed to support a wide range of agentic application use cases, from background processing to real-time interactions. 
+- [LangGraph Server](./langgraph_server.md): The LangGraph Server is designed to support a wide range of agentic application use cases, from background processing to real-time interactions.
 - [LangGraph Studio](./langgraph_studio.md): LangGraph Studio is a specialized IDE that can connect to a LangGraph Server to enable visualization, interaction, and debugging of the application locally.
 - [LangGraph CLI](./langgraph_cli.md): LangGraph CLI is a command-line interface that helps to interact with a local LangGraph
 - [Python/JS SDK](./sdk.md): The Python/JS SDK provides a programmatic way to interact with deployed LangGraph Applications.
@@ -71,8 +71,7 @@ The LangGraph Platform comprises several components that work together to suppor
 
 ### Deployment Options
 
-
 - [Self-Hosted Lite](./self_hosted.md): A free (up to 1 million nodes executed per year), limited version of LangGraph Platform that you can run locally or in a self-hosted manner
 - [Cloud SaaS](./langgraph_cloud.md): Hosted as part of LangSmith.
 - [Bring Your Own Cloud](./bring_your_own_cloud.md): We manage the infrastructure, so you don't have to, but the infrastructure all runs within your cloud.
-- [Self-Hosted Enterprise](./self_hosted.md): Completely managed by you.
+- [Self-Hosted Enterprise](./self_hosted.md): Completely managed by you.

docs/docs/concepts/low_level.md

@@ -213,9 +213,9 @@ builder.add_node("other_node", my_other_node)
 ...
 ```
 
-Behind the scenes, functions are converted to [RunnableLambda's](https://api.python.langchain.com/en/latest/runnables/langchain_core.runnables.base.RunnableLambda.html#langchain_core.runnables.base.RunnableLambda), which add batch and async support to your function, along with native tracing and debugging.
+Behind the scenes, functions are converted to [RunnableLambda](https://api.python.langchain.com/en/latest/runnables/langchain_core.runnables.base.RunnableLambda.html#langchain_core.runnables.base.RunnableLambda)s, which add batch and async support to your function, along with native tracing and debugging.
 
-If you add a node to graph without specifying a name, it will be given a default name equivalent to the function name.
+If you add a node to a graph without specifying a name, it will be given a default name equivalent to the function name.
 
 ```python
 builder.add_node(my_node)
@@ -224,7 +224,7 @@ builder.add_node(my_node)
 
 ### `START` Node
 
-The `START` Node is a special node that represents the node sends user input to the graph. The main purpose for referencing this node is to determine which nodes should be called first.
+The `START` Node is a special node that represents the node that sends user input to the graph. The main purpose for referencing this node is to determine which nodes should be called first.
 
 ```python
 from langgraph.graph import START
@@ -269,9 +269,9 @@ If you want to **optionally** route to 1 or more edges (or optionally terminate)
 graph.add_conditional_edges("node_a", routing_function)
 ```
 
-Similar to nodes, the `routing_function` accept the current `state` of the graph and return a value.
+Similar to nodes, the `routing_function` accepts the current `state` of the graph and returns a value.
 
-By default, the return value `routing_function` is used as the name of the node (or a list of nodes) to send the state to next. All those nodes will be run in parallel as a part of the next superstep.
+By default, the return value `routing_function` is used as the name of the node (or list of nodes) to send the state to next. All those nodes will be run in parallel as a part of the next superstep.
 
 You can optionally provide a dictionary that maps the `routing_function`'s output to the name of the next node.
 
@@ -310,7 +310,7 @@ graph.add_conditional_edges(START, routing_function, {True: "node_b", False: "no
 
 ## `Send`
 
-By default, `Nodes` and `Edges` are defined ahead of time and operate on the same shared state. However, there can be cases where the exact edges are not known ahead of time and/or you may want different versions of `State` to exist at the same time. A common of example of this is with `map-reduce` design patterns. In this design pattern, a first node may generate a list of objects, and you may want to apply some other node to all those objects. The number of objects may be unknown ahead of time (meaning the number of edges may not be known) and the input `State` to the downstream `Node` should be different (one for each generated object).
+By default, `Nodes` and `Edges` are defined ahead of time and operate on the same shared state. However, there can be cases where the exact edges are not known ahead of time and/or you may want different versions of `State` to exist at the same time. A common example of this is with `map-reduce` design patterns. In this design pattern, a first node may generate a list of objects, and you may want to apply some other node to all those objects. The number of objects may be unknown ahead of time (meaning the number of edges may not be known) and the input `State` to the downstream `Node` should be different (one for each generated object).
 
 To support this design pattern, LangGraph supports returning [`Send`][langgraph.types.Send] objects from conditional edges. `Send` takes two arguments: first is the name of the node, and second is the state to pass to that node.
 
@@ -357,7 +357,7 @@ Use [conditional edges](#conditional-edges) to route between nodes conditionally
 
 ### Navigating to a node in a parent graph
 
-If you are using [subgraphs](#subgraphs), you might want to navigate from a node a subgraph to a different subgraph (i.e. a different node in the parent graph). To do so, you can specify `graph=Command.PARENT` in `Command`:
+If you are using [subgraphs](#subgraphs), you might want to navigate from a node within a subgraph to a different subgraph (i.e. a different node in the parent graph). To do so, you can specify `graph=Command.PARENT` in `Command`:
 
 ```python
 def my_node(state: State) -> Command[Literal["my_other_node"]]:
@@ -400,7 +400,7 @@ def lookup_user_info(tool_call_id: Annotated[str, InjectedToolCallId], config: R
 !!! important
     You MUST include `messages` (or any state key used for the message history) in `Command.update` when returning `Command` from a tool and the list of messages in `messages` MUST contain a `ToolMessage`. This is necessary for the resulting message history to be valid (LLM providers require AI messages with tool calls to be followed by the tool result messages).
 
-If you are using tools that update state via `Command`, we recommend using prebuilt [`ToolNode`][langgraph.prebuilt.tool_node.ToolNode] which automatically handles tools returning `Command` objects and propagates them to the graph state. If you're writing a custom node that calls tools, you would need to manually propagate `Command` objects returned by the tools as the update from node.
+If you are using tools that update state via `Command`, we recommend using prebuilt [`ToolNode`][langgraph.prebuilt.tool_node.ToolNode] which automatically handles tools returning `Command` objects and propagates them to the graph state. If you're writing a custom node that calls tools, you would need to manually propagate `Command` objects returned by the tools as the update from the node.
 
 ### Human-in-the-loop
 
@@ -494,7 +494,7 @@ Read more about how the `interrupt` is used for **human-in-the-loop** workflows
 
 ## Breakpoints
 
-Breakpoints pause graph execution at specific points and enable stepping through execution step by step. Breakpoints are powered by LangGraph's [**persistence layer**](./persistence.md), which saves the state after each graph step. Breakpoints can also be used to enable [**human-in-the-loop**](./human_in_the_loop.md) workflows, though we recommend using the [`interrupt` function](#interrupt-function) for this purpose.
+Breakpoints pause graph execution at specific points and enable stepping through execution step by step. Breakpoints are powered by LangGraph's [**persistence layer**](./persistence.md), which saves the state after each graph step. Breakpoints can also be used to enable [**human-in-the-loop**](./human_in_the_loop.md) workflows, though we recommend using the [`interrupt` function](#interrupt) for this purpose.
 
 Read more about breakpoints in the [Breakpoints conceptual guide](./breakpoints.md).
 
@@ -531,7 +531,7 @@ Let's take a look at examples for each.
 
 ### As a compiled graph
 
-The simplest way to create subgraph nodes is by using a [compiled subgraph](#compiling-your-graph) directly. When doing so, it is **important** that the parent graph and the subgraph [state schemas](#state) share at least one key which they can use to communicate. If your graph and subgraph do not share any keys, you should use write a function [invoking the subgraph](#as-a-function) instead.
+The simplest way to create subgraph nodes is by using a [compiled subgraph](#compiling-your-graph) directly. When doing so, it is **important** that the parent graph and the subgraph [state schemas](#state) share at least one key which they can use to communicate. If your graph and subgraph do not share any keys, you should write a function [invoking the subgraph](#as-a-function) instead.
 
 !!! Note
     If you pass extra keys to the subgraph node (i.e., in addition to the shared keys), they will be ignored by the subgraph node. Similarly, if you return extra keys from the subgraph, they will be ignored by the parent graph.

docs/docs/concepts/platform_architecture.md

@@ -0,0 +1,23 @@
+# LangGraph Platform Architecture
+
+![](img/langgraph_platform_deployment_architecture.png)
+
+## How we use Postgres
+
+Postgres is the persistence layer for all user and run data in LGP. This stores both checkpoints (see more info [here](./persistence.md)) as well as the server resources (threads, runs, assistants and crons).
+
+## How we use Redis
+
+Redis is used in each LGP deployment as a way for server and queue workers to communicate, and to store ephemeral metadata, more details on both below. No user/run data is stored in Redis.
+
+### Communication
+
+All runs in LGP are executed by the pool of background workers that are part of each deployment. In order to enable some features for those runs (such as cancellation and output streaming) we need a channel for two-way communication between the server and the worker handling a particular run. We use Redis to organize that communication.
+
+1. A Redis list is used as a mechanism to wake up a worker as soon as a new run is created. Only a sentinel value is stored in this list, no actual run info. The run information is then retrieved from Postgres by the worker.
+2. A combination of a Redis string and Redis PubSub channel is used for the server to communicate a run cancellation request to the appropriate worker.
+3. A Redis PubSub channel is used by the worker to broadcast streaming output from an agent while the run is being handled. Any open `/stream` request in the server will subscribe to that channel and forward any events to the response as they arrive. No events are stored in Redis at any time.
+
+### Ephemeral metadata
+
+Runs in an LGP deployment may be retried for specific failures (currently only for transient Postgres errors encountered during the run). In order to limit the number of retries (currently limited to 3 attempts per run) we record the attempt number in a Redis string when is picked up. This contains no run-specific info other than its ID, and expires after a short delay.

docs/docs/concepts/streaming.md

@@ -1,6 +1,12 @@
 # Streaming
 
-LangGraph is built with first class support for streaming. There are several different ways to stream back outputs from a graph run
+Building a responsive app for end-users? Real-time updates are key to keeping users engaged as your app progresses.
+
+There are three main types of data you’ll want to stream:
+
+1. Workflow progress (e.g., get state updates after each graph node is executed).
+2. LLM tokens as they’re generated.
+3. Custom updates (e.g., "Fetched 10/100 records").
 
 ## Streaming graph outputs (`.stream` and `.astream`)
 
@@ -31,123 +37,6 @@ The below visualization shows the difference between the `values` and `updates`
 ![values vs updates](../static/values_vs_updates.png)
 
 
-## Streaming LLM tokens and events (`.astream_events`)
-
-In addition, you can use the `astream_events` method to stream back events that happen _inside_ nodes. This is useful for [streaming tokens of LLM calls](../how-tos/streaming-tokens.ipynb).
-
-This is a standard method on all [LangChain objects](https://python.langchain.com/docs/concepts/#runnable-interface). This means that as the graph is executed, certain events are emitted along the way and can be seen if you run the graph using `.astream_events`. 
-
-All events have (among other things) `event`, `name`, and `data` fields. What do these mean?
-
-- `event`: This is the type of event that is being emitted. You can find a detailed table of all callback events and triggers [here](https://python.langchain.com/docs/concepts/#callback-events).
-- `name`: This is the name of event.
-- `data`: This is the data associated with the event.
-
-What types of things cause events to be emitted?
-
-* each node (runnable) emits `on_chain_start` when it starts execution, `on_chain_stream` during the node execution and `on_chain_end` when the node finishes. Node events will have the node name in the event's `name` field
-* the graph will emit `on_chain_start` in the beginning of the graph execution, `on_chain_stream` after each node execution and `on_chain_end` when the graph finishes. Graph events will have the `LangGraph` in the event's `name` field
-* Any writes to state channels (i.e. anytime you update the value of one of your state keys) will emit `on_chain_start` and `on_chain_end` events
-
-Additionally, any events that are created inside your nodes (LLM events, tool events, manually emitted events, etc.) will also be visible in the output of `.astream_events`.
-
-To make this more concrete and to see what this looks like, let's see what events are returned when we run a simple graph:
-
-```python
-from langchain_openai import ChatOpenAI
-from langgraph.graph import StateGraph, MessagesState, START, END
-
-model = ChatOpenAI(model="gpt-4o-mini")
-
-
-def call_model(state: MessagesState):
-    response = model.invoke(state['messages'])
-    return {"messages": response}
-
-workflow = StateGraph(MessagesState)
-workflow.add_node(call_model)
-workflow.add_edge(START, "call_model")
-workflow.add_edge("call_model", END)
-app = workflow.compile()
-
-inputs = [{"role": "user", "content": "hi!"}]
-async for event in app.astream_events({"messages": inputs}, version="v1"):
-    kind = event["event"]
-    print(f"{kind}: {event['name']}")
-```
-```shell
-on_chain_start: LangGraph
-on_chain_start: __start__
-on_chain_end: __start__
-on_chain_start: call_model
-on_chat_model_start: ChatOpenAI
-on_chat_model_stream: ChatOpenAI
-on_chat_model_stream: ChatOpenAI
-on_chat_model_stream: ChatOpenAI
-on_chat_model_stream: ChatOpenAI
-on_chat_model_stream: ChatOpenAI
-on_chat_model_stream: ChatOpenAI
-on_chat_model_stream: ChatOpenAI
-on_chat_model_stream: ChatOpenAI
-on_chat_model_stream: ChatOpenAI
-on_chat_model_stream: ChatOpenAI
-on_chat_model_stream: ChatOpenAI
-on_chat_model_end: ChatOpenAI
-on_chain_start: ChannelWrite<call_model,messages>
-on_chain_end: ChannelWrite<call_model,messages>
-on_chain_stream: call_model
-on_chain_end: call_model
-on_chain_stream: LangGraph
-on_chain_end: LangGraph
-```
-
-We start with the overall graph start (`on_chain_start: LangGraph`). We then write to the `__start__` node (this is special node to handle input).
-We then start the `call_model` node (`on_chain_start: call_model`). We then start the chat model invocation (`on_chat_model_start: ChatOpenAI`),
-stream back token by token (`on_chat_model_stream: ChatOpenAI`) and then finish the chat model (`on_chat_model_end: ChatOpenAI`). From there, 
-we write the results back to the channel (`ChannelWrite<call_model,messages>`) and then finish the `call_model` node and then the graph as a whole.
-
-This should hopefully give you a good sense of what events are emitted in a simple graph. But what data do these events contain?
-Each type of event contains data in a different format. Let's look at what `on_chat_model_stream` events look like. This is an important type of event
-since it is needed for streaming tokens from an LLM response.
-
-These events look like:
-
-```shell
-{'event': 'on_chat_model_stream',
- 'name': 'ChatOpenAI',
- 'run_id': '3fdbf494-acce-402e-9b50-4eab46403859',
- 'tags': ['seq:step:1'],
- 'metadata': {'langgraph_step': 1,
-  'langgraph_node': 'call_model',
-  'langgraph_triggers': ['start:call_model'],
-  'langgraph_task_idx': 0,
-  'checkpoint_id': '1ef657a0-0f9d-61b8-bffe-0c39e4f9ad6c',
-  'checkpoint_ns': 'call_model',
-  'ls_provider': 'openai',
-  'ls_model_name': 'gpt-4o-mini',
-  'ls_model_type': 'chat',
-  'ls_temperature': 0.7},
- 'data': {'chunk': AIMessageChunk(content='Hello', id='run-3fdbf494-acce-402e-9b50-4eab46403859')},
- 'parent_ids': []}
-```
-We can see that we have the event type and name (which we knew from before).
-
-We also have a bunch of stuff in metadata. Noticeably, `'langgraph_node': 'call_model',` is some really helpful information
-which tells us which node this model was invoked inside of.
-
-Finally, `data` is a really important field. This contains the actual data for this event! Which in this case
-is an AIMessageChunk. This contains the `content` for the message, as well as an `id`.
-This is the ID of the overall AIMessage (not just this chunk) and is super helpful - it helps
-us track which chunks are part of the same message (so we can show them together in the UI).
-
-This information contains all that is needed for creating a UI for streaming LLM tokens. You can see a 
-guide for that [here](../how-tos/streaming-tokens.ipynb).
-
-
-!!! warning "ASYNC IN PYTHON<=3.10"
-    You may fail to see events being emitted from inside a node when using `.astream_events` in Python <= 3.10. If you're using a Langchain RunnableLambda, a RunnableGenerator, or Tool asynchronously inside your node, you will have to propagate callbacks to these objects manually. This is because LangChain cannot automatically propagate callbacks to child objects in this case.
-
-
 ## LangGraph Platform
 
 Streaming is critical for making LLM applications feel responsive to end users. When creating a streaming run, the streaming mode determines what data is streamed back to the API client. LangGraph Platform supports five streaming modes:
@@ -155,8 +44,8 @@ Streaming is critical for making LLM applications feel responsive to end users.
 - `values`: Stream the full state of the graph after each [super-step](https://langchain-ai.github.io/langgraph/concepts/low_level/#graphs) is executed. See the [how-to guide](../cloud/how-tos/stream_values.md) for streaming values.
 - `messages-tuple`: Stream LLM tokens for any messages generated inside a node. This mode is primarily meant for powering chat applications. See the [how-to guide](../cloud/how-tos/stream_messages.md) for streaming messages.
 - `updates`: Streams updates to the state of the graph after each node is executed. See the [how-to guide](../cloud/how-tos/stream_updates.md) for streaming updates.
-- `events`: Stream all events (including the state of the graph) that occur during graph execution. See the [how-to guide](../cloud/how-tos/stream_events.md) for streaming events. This can be used to do token-by-token streaming for LLMs.
 - `debug`: Stream debug events throughout graph execution. See the [how-to guide](../cloud/how-tos/stream_debug.md) for streaming debug events.
+- `events`: Stream all events (including the state of the graph) that occur during graph execution. See the [how-to guide](../cloud/how-tos/stream_events.md) for streaming events. This mode is only useful for users migrating large LCEL applications to LangGraph. Generally, this mode is not necessary for most applications.
 
 You can also specify multiple streaming modes at the same time. See the [how-to guide](../cloud/how-tos/stream_multiple.md) for configuring multiple streaming modes at the same time.
 

docs/docs/how-tos/agent-handoffs.ipynb

@@ -58,7 +58,7 @@
     "\n",
     "This guide shows how you can:\n",
     "\n",
-    "- implement handoffs using `Command`: agent node makes some decision (usually LLM-based), and explicitly returns a handoff via `Command`. These are useful when you need fine-grained control over how an agent routes to another agent. It could be well suited for implementing a supervisor agent in a supervisor architecture.\n",
+    "- implement handoffs using `Command`: agent node makes a decision on who to hand off to (usually LLM-based), and explicitly returns a handoff via `Command`. These are useful when you need fine-grained control over how an agent routes to another agent. It could be well suited for implementing a supervisor agent in a supervisor architecture.\n",
     "- implement handoffs using tools: a tool-calling agent has access to tools that can return a handoff via `Command`. The tool-executing node in the agent recognizes `Command` objects returned by the tools and routes accordingly. Handoff tool a general-purpose primitive that is useful in any multi-agent systems that contain tool-calling agents."
    ]
   },

docs/docs/how-tos/auth/custom_auth.md

@@ -13,12 +13,14 @@
   
     We currently only support custom authentication and authorization in Python deployments with `langgraph-api>=0.0.11`. Support for LangGraph.JS will be added soon.
 
+???+ note "Support by deployment type"
+
+    Custom auth is supported for all deployments in the **managed LangGraph Cloud**, as well as **Enterprise** self-hosted plans. It is not supported for **Lite** self-hosted plans.
+
 This guide shows how to add custom authentication to your LangGraph Platform application. This guide applies to both LangGraph Cloud, BYOC, and self-hosted deployments. It does not apply to isolated usage of the LangGraph open source library in your own custom server.
 
 ## 1. Implement authentication
 
-Create `auth.py` file, with a basic JWT authentication handler:
-
 ```python
 from langgraph_sdk import Auth
 

docs/docs/how-tos/index.md

@@ -11,9 +11,9 @@ Here you’ll find answers to “How do I...?” types of questions. These guide
 
 ### Graph API Basics
 
-- [How to update graph state from nodes](state-reducers.ipynb)
-- [How to create a sequence of steps](sequence.ipynb)
-- [How to create branches for parallel execution](branching.ipynb)
+- [How to update graph state from nodes](state-reducers.md)
+- [How to create a sequence of steps](sequence.md)
+- [How to create branches for parallel execution](branching.md)
 - [How to create and control loops with recursion limits](recursion-limit.ipynb)
 - [How to visualize your graph](visualization.ipynb)
 
@@ -162,7 +162,7 @@ One of the big benefits of LangGraph is that you can easily create your own agen
 
 These guides show how to use the prebuilt ReAct agent:
 
-- [How to use the pre-built ReAct agent](create-react-agent.ipynb)
+- [How to use the pre-built ReAct agent](create-react-agent.md)
 - [How to add thread-level memory to a ReAct Agent](create-react-agent-memory.ipynb)
 - [How to add a custom system prompt to a ReAct agent](create-react-agent-system-prompt.ipynb)
 - [How to add human-in-the-loop processes to a ReAct agent](create-react-agent-hitl.ipynb)
@@ -204,6 +204,7 @@ Learn how to set up your app for deployment to LangGraph Platform:
 - [How to test locally](../cloud/deployment/test_locally.md)
 - [How to rebuild graph at runtime](../cloud/deployment/graph_rebuild.md)
 - [How to use LangGraph Platform to deploy CrewAI, AutoGen, and other frameworks](autogen-langgraph-platform.ipynb)
+- [How to integrate LangGraph into your React application](../cloud/how-tos/use_stream_react.md)
 
 ### Deployment
 

docs/docs/prebuilt.md

@@ -1,5 +1,5 @@
 [//]: # (This file is automatically generated using a script in docs/_scripts. Do not edit this file directly!)
-# 🚀 Prebuilt Libraries
+# 🚀 Prebuilt Agents
 
 LangGraph includes a prebuilt React agent. For more information on how to use it, 
 check out our [how-to guides](https://langchain-ai.github.io/langgraph/how-tos/#prebuilt-react-agent).
@@ -9,9 +9,12 @@ below. These libraries can extend LangGraph's functionality in various ways.
 
 ## 📚 Available Libraries
 
+[//]: # (This file is automatically generated using a script in docs/_scripts. Do not edit this file directly!)
 | Name | GitHub URL | Description | Weekly Downloads |
 | --- | --- | --- | --- |
-| **trustcall** | [hinthornw/trustcall](https://github.com/hinthornw/trustcall) | Tenacious tool calling built on LangGraph | 7081 |
+| **trustcall** | [hinthornw/trustcall](https://github.com/hinthornw/trustcall) | Tenacious tool calling built on LangGraph | 11189 |
+| **langgraph-supervisor** | [langchain-ai/langgraph-supervisor](https://github.com/langchain-ai/langgraph-supervisor) | Build supervisor multi-agent systems with LangGraph | 1291 |
+| **breeze-agent** | [andrestorres123/breeze-agent](https://github.com/andrestorres123/breeze-agent) | A streamlined research system built inspired on STORM and built on LangGraph | 226 |
 
 ## ✨ Contributing Your Library
 

docs/docs/tutorials/auth/getting_started.md

@@ -17,6 +17,11 @@
 
     We currently only support custom authentication and authorization in Python deployments with `langgraph-api>=0.0.11`. Support for LangGraph.JS will be added soon.
 
+
+???+ note "Support by deployment type"
+
+    Custom auth is supported for all deployments in the **managed LangGraph Cloud**, as well as **Enterprise** self-hosted plans. It is not supported for **Lite** self-hosted plans.
+
 In this tutorial, we will build a chatbot that only lets specific users access it. We'll start with the LangGraph template and add token-based security step by step. By the end, you'll have a working chatbot that checks for valid tokens before allowing access.
 
 ## Setting up our project

docs/docs/tutorials/multi_agent/hierarchical_agent_teams.ipynb

@@ -197,7 +197,7 @@
     "    \"\"\"Read the specified document.\"\"\"\n",
     "    with (WORKING_DIRECTORY / file_name).open(\"r\") as file:\n",
     "        lines = file.readlines()\n",
-    "    if start is not None:\n",
+    "    if start is None:\n",
     "        start = 0\n",
     "    return \"\\n\".join(lines[start:end])\n",
     "\n",

docs/mkdocs.yml

@@ -56,6 +56,29 @@ plugins:
   - search:
       separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
   - autorefs
+  - markdown-exec:
+      ansi: required
+      hooks:
+        python:
+          pre_session:
+            - _scripts.notebook_hooks:handle_vcr_setup
+          post_session:
+            - _scripts.notebook_hooks:handle_vcr_teardown
+        py:
+          pre_session:
+            - _scripts.notebook_hooks:handle_vcr_setup
+          post_session:
+            - _scripts.notebook_hooks:handle_vcr_teardown
+        typescript:
+          pre_session:
+            - _scripts.notebook_hooks:handle_vcr_setup
+          post_session:
+            - _scripts.notebook_hooks:handle_vcr_teardown
+        ts:
+          pre_session:
+            - _scripts.notebook_hooks:handle_vcr_setup
+          post_session:
+            - _scripts.notebook_hooks:handle_vcr_teardown
   - mkdocstrings:
       handlers:
         python:
@@ -100,9 +123,9 @@ nav:
           - LangGraph: how-tos#langgraph
           - Graph API Basics:
               - Graph API Basics: how-tos#graph-api-basics
-              - how-tos/state-reducers.ipynb
-              - how-tos/sequence.ipynb
-              - how-tos/branching.ipynb
+              - how-tos/state-reducers.md
+              - how-tos/sequence.md
+              - how-tos/branching.md
               - how-tos/recursion-limit.ipynb
               - how-tos/visualization.ipynb
           - Controllability:
@@ -180,7 +203,7 @@ nav:
               - how-tos/autogen-integration-functional.ipynb
           - Prebuilt ReAct Agent:
               - Prebuilt ReAct Agent: how-tos#prebuilt-react-agent
-              - how-tos/create-react-agent.ipynb
+              - how-tos/create-react-agent.md
               - how-tos/create-react-agent-memory.ipynb
               - how-tos/create-react-agent-system-prompt.ipynb
               - how-tos/create-react-agent-hitl.ipynb
@@ -230,6 +253,7 @@ nav:
                 - cloud/how-tos/stream_events.md
                 - cloud/how-tos/stream_debug.md
                 - cloud/how-tos/stream_multiple.md
+                - cloud/how-tos/use_stream_react.md
             - Human-in-the-loop:
                 - Human-in-the-loop: how-tos#human-in-the-loop_1
                 - cloud/how-tos/human_in_the_loop_breakpoint.md
@@ -354,7 +378,8 @@ nav:
             - tutorials/auth/resource_auth.md
             - tutorials/auth/add_auth_server.md
     - Resources:
-      - Prebuilt: prebuilt.md
+      - Prebuilt Agents: prebuilt.md
+      - Adopters: adopters.md
       - FAQ: concepts/faq.md
       - Troubleshooting:
           - Troubleshooting: troubleshooting/errors/index.md

docs/package.json

@@ -2,7 +2,26 @@
   "name": "docs",
   "version": "1.0.0",
   "license": "MIT",
+  "packageManager": "yarn@3.5.1",
   "scripts": {
-    "build": "echo 'export PATH=$PATH:/vercel/.local/bin:$PATH' > ~/.bashrc && source ~/.bashrc && make vercel-build-docs"
+    "build": "make build-docs"
+  },
+  "dependencies": {
+    "@langchain/core": "^0.3.38",
+    "@langchain/langgraph": "portal:./langgraphjs/libs/langgraph",
+    "@langchain/langgraph-checkpoint": "portal:./langgraphjs/libs/checkpoint",
+    "@langchain/langgraph-checkpoint-mongodb": "portal:./langgraphjs/libs/checkpoint-mongodb",
+    "@langchain/langgraph-checkpoint-postgres": "portal:./langgraphjs/libs/checkpoint-postgres",
+    "@langchain/langgraph-checkpoint-sqlite": "portal:./langgraphjs/libs/checkpoint-sqlite",
+    "@langchain/langgraph-checkpoint-validation": "portal:./langgraphjs/libs/checkpoint-validation",
+    "@langchain/openai": "^0.4.2",
+    "msgpack-lite": "^0.1.26",
+    "nock": "^14.0.1"
+  },
+  "devDependencies": {
+    "@tsconfig/recommended": "^1.0.8",
+    "@types/msgpack-lite": "^0.1.11",
+    "@types/nock": "^11.1.0",
+    "@types/node": "^22.13.1"
   }
 }

docs/pyproject.toml

@@ -9,6 +9,8 @@ readme = "README.md"
 [tool.poetry.dependencies]
 python = "^3.10"
 aiohappyeyeballs = "2.4.3"
+hub = "^3.0.1"
+pytest = "^8.3.4"
 
 [tool.poetry.group.docs.dependencies]
 langgraph = { path = "../libs/langgraph/", develop = true }
@@ -16,6 +18,7 @@ langgraph-checkpoint = { path = "../libs/checkpoint/", develop = true }
 langgraph-checkpoint-sqlite = { path = "../libs/checkpoint-sqlite", develop = true }
 langgraph-checkpoint-postgres = { path = "../libs/checkpoint-postgres", develop = true }
 langgraph-sdk = {path = "../libs/sdk-py", develop = true}
+langchain-ollama = "^0.2.3"
 mkdocs = "^1.6.0"
 mkdocs-autorefs = ">=1.0.1,<1.1.0"
 mkdocstrings = "^0.25.1"
@@ -24,13 +27,17 @@ mkdocs-minify-plugin = "^0.8.0"
 mkdocs-rss-plugin = "^1.13.1"
 mkdocs-git-committers-plugin-2 = "^2.3.0"
 mkdocs-material = {extras = ["imaging"], version = "^9.5.27"}
-markdown-include = "^0.8.1"
 markdown-callouts = "^0.4.0"
+markdown-include = "^0.8.1"
 mkdocs-exclude = "^1.0.2"
+psycopg = {extras = ["binary"], version = "^3.2.0"}
+psycopg-pool = "^3.2.0"
+pygments-ansi-color = ">=0.3"
 vcrpy = "^6.0.1"
 click = "^8.1.7"
 ruff = "^0.6.8"
 jupyter = "^1.1.1"
+langchain-cohere = "^0.4.2"
 
 [tool.poetry.group.test.dependencies]
 langchain = "^0.3.8"
@@ -40,6 +47,7 @@ langchain-nomic = "^0.1.3"
 langchain-fireworks = "^0.2.0"
 langchain-community = "^0.3.0"
 langchain-experimental = "^0.3.2"
+langchain-mistralai = "^0.2.6"
 langgraph-checkpoint-mongodb = "^0.1.0"
 langsmith = "^0.2.0"
 chromadb = "^0.5.5"
@@ -77,3 +85,7 @@ extend-include = ["*.ipynb"]
     "E722", # allow base imports in notebooks
 ]
 
+[tool.codespell]
+# https://mypy.readthedocs.io/en/stable/config_file.html
+# comma-separated list
+ignore-words-list = "infor"

docs/tests/unit_tests/test_cassette_hash.py

@@ -0,0 +1,117 @@
+import re
+from textwrap import dedent
+
+import pytest
+from _scripts.hook_state import hook_state
+from _scripts.notebook_hooks import handle_vcr_setup
+from _scripts.setup_vcr import extract_code_blocks_for_session, get_hash_for_session
+
+INITIAL_DOCUMENT_CONTENT = dedent(
+    """
+    Blah blah blah
+
+    ```python exec="on" source="above" session="1" result="ansi"
+    print("FIRST_CODE_BLOCK")
+    ```
+
+    Blah blah blah!
+
+    ```python exec="on" source="above" session="1" result="ansi"
+    print("SECOND_CODE_BLOCK")
+    ```
+    
+    more blah blah blah
+    """
+)
+
+
+@pytest.mark.parametrize(
+    "replace_string",
+    [
+        "FIRST_CODE_BLOCK",
+        "SECOND_CODE_BLOCK",
+    ],
+)
+def test_changing_block_in_session_invalidates_hash(replace_string: str):
+    hook_state['document_filename'] = 'test.md'
+    hook_state['document_content'] = INITIAL_DOCUMENT_CONTENT
+
+    code = "print('Hello, world!')"
+
+    result1 = handle_vcr_setup(
+        formatter=lambda **kwargs: None,
+        language="python",
+        session="1",
+        id="test",
+        code=code,
+        md=None,
+        extra={},
+    )
+
+    cassette_init_expr = re.compile(r"^_cassette = HashedCassette\('[^']+', '(?P<hash>[^']+)'\)$")
+    assert result1['transform_source']
+    execute_source, display_source = result1['transform_source'](code)
+    assert display_source == code
+    cassette_init_line = [line for line in execute_source.splitlines() if line.startswith("_cassette = HashedCassette(")][0]
+    assert cassette_init_line
+    match = cassette_init_expr.match(cassette_init_line)
+    assert match
+    hash_ = str(match.group('hash'))
+
+    # change the content of the second block of code
+    hook_state['document_content'] = INITIAL_DOCUMENT_CONTENT.replace(replace_string, "world")
+    assert hook_state['document_content'] != INITIAL_DOCUMENT_CONTENT
+
+    result2 = handle_vcr_setup(
+        formatter=lambda **kwargs: None,
+        language="python",
+        session="1",
+        id="test",
+        code=code,
+        md=None,
+        extra={},
+    )
+
+    assert result2['transform_source']
+    execute_source, display_source = result2['transform_source'](code)
+    assert display_source == code
+    cassette_init_line = [line for line in execute_source.splitlines() if line.startswith("_cassette = HashedCassette(")][0]
+    assert cassette_init_line
+    match = cassette_init_expr.match(cassette_init_line)
+    assert match
+
+    # this is the important part
+    assert str(match.group('hash')) != hash_
+
+@pytest.mark.parametrize(
+    "replace_string",
+    [
+        "FIRST_CODE_BLOCK",
+        "SECOND_CODE_BLOCK",
+    ],
+)
+def test_get_hash_for_session(replace_string: str):
+    hash_ = get_hash_for_session(
+        language="python",
+        session="1",
+        content=INITIAL_DOCUMENT_CONTENT,
+    )
+    
+    content = INITIAL_DOCUMENT_CONTENT.replace(replace_string, "world")
+    assert content != INITIAL_DOCUMENT_CONTENT
+    assert get_hash_for_session(
+        language="python",
+        session="1",
+        content=INITIAL_DOCUMENT_CONTENT.replace(replace_string, "world"),
+    ) != hash_
+
+def test_get_code_blocks_for_session():
+    code_blocks = extract_code_blocks_for_session(
+        language="python",
+        session="1",
+        content=INITIAL_DOCUMENT_CONTENT,
+    )
+    assert code_blocks
+    assert len(code_blocks) == 2
+    assert code_blocks[0] == 'print("FIRST_CODE_BLOCK")'
+    assert code_blocks[1] == 'print("SECOND_CODE_BLOCK")'

docs/tests/unit_tests/test_highlights.py

@@ -0,0 +1,130 @@
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import File
+from mkdocs.structure.pages import Page
+
+from _scripts.notebook_hooks import _highlight_code_blocks, on_page_markdown
+
+NO_OP_INPUT_1 = """\
+This is a plain text without any code blocks.
+
+```python
+print("Hello, World!")
+```
+"""
+
+NO_OP_INPUT_2 = """\
+
+=== "Python"
+
+    ```python
+        def foo():
+            pass
+    print("Hello, World!")
+    ```
+"""
+
+
+def test_highlight_code_blocks_no_op() -> None:
+    assert _highlight_code_blocks(NO_OP_INPUT_1) == NO_OP_INPUT_1
+    assert _highlight_code_blocks(NO_OP_INPUT_2) == NO_OP_INPUT_2
+
+
+# Examples are written in multiline style to make sure that whitespace
+# is easy to interpret.
+INPUT_HIGHLIGHT_1 = """\
+This is a plain text without any code blocks.
+
+```python
+# highlight-next-line
+print("Hello, World!")
+```
+"""
+
+EXPECTED_HIGHLIGHT_1 = """\
+This is a plain text without any code blocks.
+
+```python hl_lines="1"
+print("Hello, World!")
+```
+"""
+
+INPUT_HIGHLIGHT_2 = """\
+This is a plain text without any code blocks.
+
+```python
+# highlight-next-line
+print("Hello, World!")
+
+x = 5
+
+# highlight-next-line
+print("Hello, World!")
+
+```
+"""
+
+EXPECTED_HIGHLIGHT_2 = """\
+This is a plain text without any code blocks.
+
+```python hl_lines="1 5"
+print("Hello, World!")
+
+x = 5
+
+print("Hello, World!")
+
+```
+"""
+
+
+# Test end-to-end behavior of on_page_markdown
+INPUT_HIGHLIGHT_3 = """\
+```python exec="on" source="below"
+print("Hello, World!")
+# highlight-next-line
+print("Hello, World!")
+```
+"""
+
+EXPECTED_HIGHLIGHT_3 = """\
+```python exec="on" source="below" hl_lines="2"
+print("Hello, World!")
+print("Hello, World!")
+```
+"""
+
+
+def test_highlight_code_blocks() -> None:
+    """Test that code blocks are highlighted correctly."""
+    assert _highlight_code_blocks(INPUT_HIGHLIGHT_1) == EXPECTED_HIGHLIGHT_1
+    assert _highlight_code_blocks(INPUT_HIGHLIGHT_2) == EXPECTED_HIGHLIGHT_2
+    assert _highlight_code_blocks(INPUT_HIGHLIGHT_3) == EXPECTED_HIGHLIGHT_3
+
+
+END_TO_END_INPUT_HIGHLIGHT_1 = """\
+```python exec="on" source="below"
+print("Hello, World!")
+# highlight-next-line
+print("Hello, World!")
+```
+"""
+
+
+END_TO_END_INPUT_HIGHLIGHT_1_EXPECT = """\
+```python exec="on" source="below" hl_lines="2"
+print("Hello, World!")
+print("Hello, World!")
+```
+"""
+
+
+def test_on_page_markdown_highlights() -> None:
+    """Test that on page markdown behaves correctly."""
+    # Create a dummy MkDocs File and Page object.
+    dummy_file = File("dummy.md", "dummy.md", "placeholder", use_directory_urls=False)
+    dummy_page = Page("Test Page", dummy_file, config=MkDocsConfig())
+
+    assert (
+        on_page_markdown(END_TO_END_INPUT_HIGHLIGHT_1, dummy_page)
+        == END_TO_END_INPUT_HIGHLIGHT_1_EXPECT
+    )

docs/tests/unit_tests/test_notebook_conversion.py

@@ -0,0 +1,105 @@
+import nbformat
+import pytest
+
+from _scripts.notebook_convert import (
+    _convert_links_in_markdown,
+    md_executable,
+    _has_output,
+)
+
+EXPECTED_OUTPUT = """\
+```python exec="on" source="above" session="1" result="ansi"
+print("Hello, world!")
+```
+"""
+
+
+def test_convert_normal_code_block() -> None:
+    notebook = nbformat.v4.new_notebook()
+    notebook.metadata.language_info = {"name": "python", "version": "3.11"}
+    notebook.cells.append(nbformat.v4.new_code_cell('print("Hello, world!")'))
+    markdown, _ = md_executable.from_notebook_node(notebook)
+    assert markdown == EXPECTED_OUTPUT
+
+
+# We treat cell magic as a non-executable code block.
+CELL_MAGIC_INPUT = """\
+%%capture
+%pip install numpy
+"""
+
+CELL_MAGIC_OUTPUT = """\
+```shell
+pip install numpy
+```
+"""
+
+
+def test_convert_cell_magic() -> None:
+    notebook = nbformat.v4.new_notebook()
+    notebook.metadata.language_info = {"name": "python", "version": "3.11"}
+    notebook.cells.append(nbformat.v4.new_code_cell(CELL_MAGIC_INPUT))
+    markdown, _ = md_executable.from_notebook_node(notebook)
+    assert markdown == CELL_MAGIC_OUTPUT
+
+
+STDIN_INPUT = """\
+input("Enter your name: ")\
+"""
+
+STDIN_OUTPUT = """\
+```python
+input("Enter your name: ")
+```
+"""
+
+
+def test_convert_input_cell() -> None:
+    notebook = nbformat.v4.new_notebook()
+    notebook.metadata.language_info = {"name": "python", "version": "3.11"}
+    notebook.cells.append(nbformat.v4.new_code_cell(STDIN_INPUT))
+    markdown, _ = md_executable.from_notebook_node(notebook)
+    assert markdown == STDIN_OUTPUT
+
+
+NO_STDOUT_EXPECTED = """\
+```python exec="on" source="above" session="1"
+display(x)
+```
+"""
+
+
+def test_convert_block_without_output() -> None:
+    notebook = nbformat.v4.new_notebook()
+    notebook.metadata.language_info = {"name": "python", "version": "3.11"}
+    notebook.cells.append(nbformat.v4.new_code_cell("display(x)"))
+    markdown, _ = md_executable.from_notebook_node(notebook)
+    assert markdown == NO_STDOUT_EXPECTED
+
+
+def test_has_output() -> None:
+    """Test if a given code block is expected to have output."""
+    assert _has_output("print('Hello, world!')") is True
+    assert _has_output("print_stream(some_iterable)") is True
+    assert _has_output("foo.y") is True
+    assert _has_output("display(x)") is False
+    assert _has_output("assert 1 == 1") is False
+    assert _has_output("def foo(): pass") is False
+    assert _has_output("import foobar") is False
+
+
+@pytest.mark.parametrize(
+    "source, expected",
+    [
+        (
+            "This is a [link](https://example.com).",
+            "This is a [link](https://example.com).",
+        ),
+        ("This is a [link](../foo).", "This is a [link](foo.md)."),
+        ("This is a [link](../foo#hello).", "This is a [link](foo.md#hello)."),
+        ("This is a [link](../foo/#hello).", "This is a [link](foo.md#hello)."),
+    ],
+)
+def test_link_conversion(source: str, expected: str) -> None:
+    """Test logic to convert links in markdown cells."""
+    assert _convert_links_in_markdown(source) == expected

docs/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "extends": "@tsconfig/recommended",
+  "compilerOptions": {
+    "rootDir": "",
+    "noEmit": true,
+    "target": "ES2021",
+    "lib": ["ES2021", "ES2022.Object", "DOM"],
+    "module": "NodeNext",
+    "moduleResolution": "nodenext",
+    "esModuleInterop": true,
+    "declaration": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "useDefineForClassFields": true,
+    "strictPropertyInitialization": false,
+    "allowJs": true,
+    "strict": true
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules"]
+}

docs/vercel.json

@@ -1,4 +1,5 @@
 {
-  "buildCommand": "yarn build",
-  "outputDirectory": "site"
+  "buildCommand": "echo 'export OPENAI_API_KEY=\"sk-proj-1234567890\"' >> ~/.bashrc && echo 'export ANTHROPIC_API_KEY=\"sk-ant-api03-1234567890\"' >> ~/.bashrc && echo 'export PATH=$PATH:/vercel/.local/bin:$PATH' >> ~/.bashrc && source ~/.bashrc && make vercel-build-docs",
+  "outputDirectory": "site",
+  "installCommand": "echo done"
 }

libs/checkpoint-postgres/langgraph/checkpoint/postgres/__init__.py

@@ -317,7 +317,17 @@ class PostgresSaver(BasePostgresSaver):
                     checkpoint["id"],
                     checkpoint_id,
                     Jsonb(self._dump_checkpoint(copy)),
-                    self._dump_metadata(metadata),
+                    self._dump_metadata(
+                        {
+                            **{
+                                k: v
+                                for k, v in config["configurable"].items()
+                                if not k.startswith("__")
+                            },
+                            **config.get("metadata", {}),
+                            **metadata,
+                        }
+                    ),
                 ),
             )
         return next_config

libs/checkpoint-postgres/langgraph/checkpoint/postgres/aio.py

@@ -275,7 +275,17 @@ class AsyncPostgresSaver(BasePostgresSaver):
                     checkpoint["id"],
                     checkpoint_id,
                     Jsonb(self._dump_checkpoint(copy)),
-                    self._dump_metadata(metadata),
+                    self._dump_metadata(
+                        {
+                            **{
+                                k: v
+                                for k, v in config["configurable"].items()
+                                if not k.startswith("__")
+                            },
+                            **config.get("metadata", {}),
+                            **metadata,
+                        }
+                    ),
                 ),
             )
         return next_config

libs/checkpoint-postgres/langgraph/checkpoint/postgres/shallow.py

@@ -423,7 +423,17 @@ class ShallowPostgresSaver(BasePostgresSaver):
                     thread_id,
                     checkpoint_ns,
                     Jsonb(self._dump_checkpoint(copy)),
-                    self._dump_metadata(metadata),
+                    self._dump_metadata(
+                        {
+                            **{
+                                k: v
+                                for k, v in config["configurable"].items()
+                                if not k.startswith("__")
+                            },
+                            **config.get("metadata", {}),
+                            **metadata,
+                        }
+                    ),
                 ),
             )
         return next_config
@@ -742,7 +752,17 @@ class AsyncShallowPostgresSaver(BasePostgresSaver):
                     thread_id,
                     checkpoint_ns,
                     Jsonb(self._dump_checkpoint(copy)),
-                    self._dump_metadata(metadata),
+                    self._dump_metadata(
+                        {
+                            **{
+                                k: v
+                                for k, v in config["configurable"].items()
+                                if not k.startswith("__")
+                            },
+                            **config.get("metadata", {}),
+                            **metadata,
+                        }
+                    ),
                 ),
             )
         return next_config

libs/checkpoint-postgres/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "langgraph-checkpoint-postgres"
-version = "2.0.13"
+version = "2.0.14"
 description = "Library with a Postgres implementation of LangGraph checkpoint saver."
 authors = []
 license = "MIT"

libs/checkpoint-postgres/tests/test_async.py

@@ -201,7 +201,35 @@ def test_data():
 
 
 @pytest.mark.parametrize("saver_name", ["base", "pool", "pipe", "shallow"])
-async def test_asearch(request, saver_name: str, test_data) -> None:
+async def test_combined_metadata(saver_name: str, test_data) -> None:
+    async with _saver(saver_name) as saver:
+        config = {
+            "configurable": {
+                "thread_id": "thread-2",
+                "checkpoint_ns": "",
+                "__super_private_key": "super_private_value",
+            },
+            "metadata": {"run_id": "my_run_id"},
+        }
+        chkpnt: Checkpoint = create_checkpoint(empty_checkpoint(), {}, 1)
+        metadata: CheckpointMetadata = {
+            "source": "loop",
+            "step": 1,
+            "writes": {"foo": "bar"},
+            "score": None,
+        }
+        await saver.aput(config, chkpnt, metadata, {})
+        checkpoint = await saver.aget_tuple(config)
+        assert checkpoint.metadata == {
+            **metadata,
+            "thread_id": "thread-2",
+            "checkpoint_ns": "",
+            "run_id": "my_run_id",
+        }
+
+
+@pytest.mark.parametrize("saver_name", ["base", "pool", "pipe", "shallow"])
+async def test_asearch(saver_name: str, test_data) -> None:
     async with _saver(saver_name) as saver:
         configs = test_data["configs"]
         checkpoints = test_data["checkpoints"]
@@ -222,11 +250,17 @@ async def test_asearch(request, saver_name: str, test_data) -> None:
 
         search_results_1 = [c async for c in saver.alist(None, filter=query_1)]
         assert len(search_results_1) == 1
-        assert search_results_1[0].metadata == metadata[0]
+        assert search_results_1[0].metadata == {
+            **configs[0]["configurable"],
+            **metadata[0],
+        }
 
         search_results_2 = [c async for c in saver.alist(None, filter=query_2)]
         assert len(search_results_2) == 1
-        assert search_results_2[0].metadata == metadata[1]
+        assert search_results_2[0].metadata == {
+            **configs[1]["configurable"],
+            **metadata[1],
+        }
 
         search_results_3 = [c async for c in saver.alist(None, filter=query_3)]
         assert len(search_results_3) == 3
@@ -246,7 +280,7 @@ async def test_asearch(request, saver_name: str, test_data) -> None:
 
 
 @pytest.mark.parametrize("saver_name", ["base", "pool", "pipe", "shallow"])
-async def test_null_chars(request, saver_name: str, test_data) -> None:
+async def test_null_chars(saver_name: str, test_data) -> None:
     async with _saver(saver_name) as saver:
         config = await saver.aput(
             test_data["configs"][0],

libs/checkpoint-postgres/tests/test_sync.py

@@ -182,6 +182,34 @@ def test_data():
     }
 
 
+@pytest.mark.parametrize("saver_name", ["base", "pool", "pipe", "shallow"])
+def test_combined_metadata(saver_name: str, test_data) -> None:
+    with _saver(saver_name) as saver:
+        config = {
+            "configurable": {
+                "thread_id": "thread-2",
+                "checkpoint_ns": "",
+                "__super_private_key": "super_private_value",
+            },
+            "metadata": {"run_id": "my_run_id"},
+        }
+        chkpnt: Checkpoint = create_checkpoint(empty_checkpoint(), {}, 1)
+        metadata: CheckpointMetadata = {
+            "source": "loop",
+            "step": 1,
+            "writes": {"foo": "bar"},
+            "score": None,
+        }
+        saver.put(config, chkpnt, metadata, {})
+        checkpoint = saver.get_tuple(config)
+        assert checkpoint.metadata == {
+            **metadata,
+            "thread_id": "thread-2",
+            "checkpoint_ns": "",
+            "run_id": "my_run_id",
+        }
+
+
 @pytest.mark.parametrize("saver_name", ["base", "pool", "pipe", "shallow"])
 def test_search(saver_name: str, test_data) -> None:
     with _saver(saver_name) as saver:
@@ -204,11 +232,17 @@ def test_search(saver_name: str, test_data) -> None:
 
         search_results_1 = list(saver.list(None, filter=query_1))
         assert len(search_results_1) == 1
-        assert search_results_1[0].metadata == metadata[0]
+        assert search_results_1[0].metadata == {
+            **configs[0]["configurable"],
+            **metadata[0],
+        }
 
         search_results_2 = list(saver.list(None, filter=query_2))
         assert len(search_results_2) == 1
-        assert search_results_2[0].metadata == metadata[1]
+        assert search_results_2[0].metadata == {
+            **configs[1]["configurable"],
+            **metadata[1],
+        }
 
         search_results_3 = list(saver.list(None, filter=query_3))
         assert len(search_results_3) == 3

libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/__init__.py

@@ -397,7 +397,17 @@ class SqliteSaver(BaseCheckpointSaver[str]):
         thread_id = config["configurable"]["thread_id"]
         checkpoint_ns = config["configurable"]["checkpoint_ns"]
         type_, serialized_checkpoint = self.serde.dumps_typed(checkpoint)
-        serialized_metadata = self.jsonplus_serde.dumps(metadata)
+        serialized_metadata = self.jsonplus_serde.dumps(
+            {
+                **{
+                    k: v
+                    for k, v in config["configurable"].items()
+                    if not k.startswith("__")
+                },
+                **config.get("metadata", {}),
+                **metadata,
+            }
+        )
         with self.cursor() as cur:
             cur.execute(
                 "INSERT OR REPLACE INTO checkpoints (thread_id, checkpoint_ns, checkpoint_id, parent_checkpoint_id, type, checkpoint, metadata) VALUES (?, ?, ?, ?, ?, ?, ?)",

libs/checkpoint-sqlite/langgraph/checkpoint/sqlite/aio.py

@@ -463,7 +463,17 @@ class AsyncSqliteSaver(BaseCheckpointSaver[str]):
         thread_id = config["configurable"]["thread_id"]
         checkpoint_ns = config["configurable"]["checkpoint_ns"]
         type_, serialized_checkpoint = self.serde.dumps_typed(checkpoint)
-        serialized_metadata = self.jsonplus_serde.dumps(metadata)
+        serialized_metadata = self.jsonplus_serde.dumps(
+            {
+                **{
+                    k: v
+                    for k, v in config["configurable"].items()
+                    if not k.startswith("__")
+                },
+                **config.get("metadata", {}),
+                **metadata,
+            }
+        )
         async with (
             self.lock,
             self.conn.execute(

libs/checkpoint-sqlite/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "langgraph-checkpoint-sqlite"
-version = "2.0.3"
+version = "2.0.4"
 description = "Library with a SQLite implementation of LangGraph checkpoint saver."
 authors = []
 license = "MIT"

libs/checkpoint-sqlite/tests/test_aiosqlite.py

@@ -57,6 +57,25 @@ class TestAsyncSqliteSaver:
         }
         self.metadata_3: CheckpointMetadata = {}
 
+    async def test_combined_metadata(self) -> None:
+        async with AsyncSqliteSaver.from_conn_string(":memory:") as saver:
+            config = {
+                "configurable": {
+                    "thread_id": "thread-2",
+                    "checkpoint_ns": "",
+                    "__super_private_key": "super_private_value",
+                },
+                "metadata": {"run_id": "my_run_id"},
+            }
+            await saver.aput(config, self.chkpnt_2, self.metadata_2, {})
+            checkpoint = await saver.aget_tuple(config)
+            assert checkpoint.metadata == {
+                **self.metadata_2,
+                "thread_id": "thread-2",
+                "checkpoint_ns": "",
+                "run_id": "my_run_id",
+            }
+
     async def test_asearch(self) -> None:
         async with AsyncSqliteSaver.from_conn_string(":memory:") as saver:
             await saver.aput(self.config_1, self.chkpnt_1, self.metadata_1, {})
@@ -74,11 +93,17 @@ class TestAsyncSqliteSaver:
 
             search_results_1 = [c async for c in saver.alist(None, filter=query_1)]
             assert len(search_results_1) == 1
-            assert search_results_1[0].metadata == self.metadata_1
+            assert search_results_1[0].metadata == {
+                **self.config_1["configurable"],
+                **self.metadata_1,
+            }
 
             search_results_2 = [c async for c in saver.alist(None, filter=query_2)]
             assert len(search_results_2) == 1
-            assert search_results_2[0].metadata == self.metadata_2
+            assert search_results_2[0].metadata == {
+                **self.config_2["configurable"],
+                **self.metadata_2,
+            }
 
             search_results_3 = [c async for c in saver.alist(None, filter=query_3)]
             assert len(search_results_3) == 3

libs/checkpoint-sqlite/tests/test_sqlite.py

@@ -58,6 +58,25 @@ class TestSqliteSaver:
         }
         self.metadata_3: CheckpointMetadata = {}
 
+    def test_combined_metadata(self) -> None:
+        with SqliteSaver.from_conn_string(":memory:") as saver:
+            config = {
+                "configurable": {
+                    "thread_id": "thread-2",
+                    "checkpoint_ns": "",
+                    "__super_private_key": "super_private_value",
+                },
+                "metadata": {"run_id": "my_run_id"},
+            }
+            saver.put(config, self.chkpnt_2, self.metadata_2, {})
+            checkpoint = saver.get_tuple(config)
+            assert checkpoint.metadata == {
+                **self.metadata_2,
+                "thread_id": "thread-2",
+                "checkpoint_ns": "",
+                "run_id": "my_run_id",
+            }
+
     def test_search(self) -> None:
         with SqliteSaver.from_conn_string(":memory:") as saver:
             # set up test
@@ -77,11 +96,17 @@ class TestSqliteSaver:
 
             search_results_1 = list(saver.list(None, filter=query_1))
             assert len(search_results_1) == 1
-            assert search_results_1[0].metadata == self.metadata_1
+            assert search_results_1[0].metadata == {
+                **self.config_1["configurable"],
+                **self.metadata_1,
+            }
 
             search_results_2 = list(saver.list(None, filter=query_2))
             assert len(search_results_2) == 1
-            assert search_results_2[0].metadata == self.metadata_2
+            assert search_results_2[0].metadata == {
+                **self.config_2["configurable"],
+                **self.metadata_2,
+            }
 
             search_results_3 = list(saver.list(None, filter=query_3))
             assert len(search_results_3) == 3

libs/checkpoint/langgraph/checkpoint/memory/__init__.py

@@ -356,7 +356,17 @@ class InMemorySaver(
             {
                 checkpoint["id"]: (
                     self.serde.dumps_typed(c),
-                    self.serde.dumps_typed(metadata),
+                    self.serde.dumps_typed(
+                        {
+                            **{
+                                k: v
+                                for k, v in config["configurable"].items()
+                                if not k.startswith("__")
+                            },
+                            **config.get("metadata", {}),
+                            **metadata,
+                        }
+                    ),
                     config["configurable"].get("checkpoint_id"),  # parent
                 )
             }

libs/checkpoint/langgraph/store/base/__init__.py

@@ -493,13 +493,14 @@ class IndexConfig(TypedDict, total=False):
         - cohere:embed-multilingual-light-v3.0: 384
     """
 
-    embed: Union[Embeddings, EmbeddingsFunc, AEmbeddingsFunc]
+    embed: Union[Embeddings, EmbeddingsFunc, AEmbeddingsFunc, str]
     """Optional function to generate embeddings from text.
     
     Can be specified in three ways:
         1. A LangChain Embeddings instance
         2. A synchronous embedding function (EmbeddingsFunc)
         3. An asynchronous embedding function (AEmbeddingsFunc)
+        4. A provider string (e.g., "openai:text-embedding-3-small")
     
     ???+ example "Examples"
         Using LangChain's initialization with InMemoryStore:

libs/checkpoint/langgraph/store/base/embed.py

@@ -7,6 +7,7 @@ asynchronous operations.
 """
 
 import asyncio
+import functools
 import json
 from typing import Any, Awaitable, Callable, Optional, Sequence, Union
 
@@ -28,7 +29,7 @@ Similar to EmbeddingsFunc, but returns an awaitable that resolves to the embeddi
 
 
 def ensure_embeddings(
-    embed: Union[Embeddings, EmbeddingsFunc, AEmbeddingsFunc, None],
+    embed: Union[Embeddings, EmbeddingsFunc, AEmbeddingsFunc, str, None],
 ) -> Embeddings:
     """Ensure that an embedding function conforms to LangChain's Embeddings interface.
 
@@ -62,9 +63,37 @@ def ensure_embeddings(
         embeddings = ensure_embeddings(my_async_fn)
         result = await embeddings.aembed_query("hello")  # Returns [0.1, 0.2]
         ```
+
+        Initialize embeddings using a provider string:
+        ```python
+        # Requires langchain>=0.3.9 and langgraph-checkpoint>=2.0.11
+        embeddings = ensure_embeddings("openai:text-embedding-3-small")
+        result = embeddings.embed_query("hello")
+        ```
     """
     if embed is None:
         raise ValueError("embed must be provided")
+    if isinstance(embed, str):
+        init_embeddings = _get_init_embeddings()
+        if init_embeddings is None:
+            from importlib.metadata import PackageNotFoundError, version
+
+            try:
+                lc_version = version("langchain")
+                version_info = f"Found langchain version {lc_version}, but"
+            except PackageNotFoundError:
+                version_info = "langchain is not installed;"
+
+            raise ValueError(
+                f"Could not load embeddings from string '{embed}'. {version_info} "
+                "loading embeddings by provider:identifier string requires langchain>=0.3.9 "
+                "as well as the provider-specific package. "
+                "Install LangChain with: pip install 'langchain>=0.3.9' "
+                "and the provider-specific package (e.g., 'langchain-openai>=0.3.0'). "
+                "Alternatively, specify 'embed' as a compatible Embeddings object or python function."
+            )
+        return init_embeddings(embed)
+
     if isinstance(embed, Embeddings):
         return embed
     return EmbeddingsLambda(embed)
@@ -373,6 +402,16 @@ def _is_async_callable(
     )
 
 
+@functools.lru_cache
+def _get_init_embeddings() -> Optional[Callable[[str], Embeddings]]:
+    try:
+        from langchain.embeddings import init_embeddings  # type: ignore
+
+        return init_embeddings
+    except ImportError:
+        return None
+
+
 __all__ = [
     "ensure_embeddings",
     "EmbeddingsFunc",

libs/checkpoint/langgraph/store/memory/__init__.py

@@ -493,7 +493,7 @@ def _cosine_similarity(X: list[float], Y: list[list[float]]) -> list[float]:
     if not Y:
         return []
     if _check_numpy():
-        import numpy as np  # type: ignore
+        import numpy as np  # type: ignore[import-not-found]
 
         X_arr = np.array(X) if not isinstance(X, np.ndarray) else X
         Y_arr = np.array(Y) if not isinstance(Y, np.ndarray) else Y

libs/checkpoint/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "langgraph-checkpoint"
-version = "2.0.11"
+version = "2.0.13"
 description = "Library with base interfaces for LangGraph checkpoint savers."
 authors = []
 license = "MIT"

libs/checkpoint/tests/test_memory.py

@@ -59,6 +59,24 @@ class TestMemorySaver:
         }
         self.metadata_3: CheckpointMetadata = {}
 
+    def test_combined_metadata(self) -> None:
+        config = {
+            "configurable": {
+                "thread_id": "thread-2",
+                "checkpoint_ns": "",
+                "__super_private_key": "super_private_value",
+            },
+            "metadata": {"run_id": "my_run_id"},
+        }
+        self.memory_saver.put(config, self.chkpnt_2, self.metadata_2, {})
+        checkpoint = self.memory_saver.get_tuple(config)
+        assert checkpoint.metadata == {
+            **self.metadata_2,
+            "thread_id": "thread-2",
+            "checkpoint_ns": "",
+            "run_id": "my_run_id",
+        }
+
     async def test_search(self) -> None:
         # set up test
         # save checkpoints
@@ -77,11 +95,17 @@ class TestMemorySaver:
 
         search_results_1 = list(self.memory_saver.list(None, filter=query_1))
         assert len(search_results_1) == 1
-        assert search_results_1[0].metadata == self.metadata_1
+        assert search_results_1[0].metadata == {
+            **self.config_1["configurable"],
+            **self.metadata_1,
+        }
 
         search_results_2 = list(self.memory_saver.list(None, filter=query_2))
         assert len(search_results_2) == 1
-        assert search_results_2[0].metadata == self.metadata_2
+        assert search_results_2[0].metadata == {
+            **self.config_2["configurable"],
+            **self.metadata_2,
+        }
 
         search_results_3 = list(self.memory_saver.list(None, filter=query_3))
         assert len(search_results_3) == 3
@@ -121,13 +145,19 @@ class TestMemorySaver:
             c async for c in self.memory_saver.alist(None, filter=query_1)
         ]
         assert len(search_results_1) == 1
-        assert search_results_1[0].metadata == self.metadata_1
+        assert search_results_1[0].metadata == {
+            **self.config_1["configurable"],
+            **self.metadata_1,
+        }
 
         search_results_2 = [
             c async for c in self.memory_saver.alist(None, filter=query_2)
         ]
         assert len(search_results_2) == 1
-        assert search_results_2[0].metadata == self.metadata_2
+        assert search_results_2[0].metadata == {
+            **self.config_2["configurable"],
+            **self.metadata_2,
+        }
 
         search_results_3 = [
             c async for c in self.memory_saver.alist(None, filter=query_3)

libs/cli/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "langgraph-cli"
-version = "0.1.70"
+version = "0.1.71"
 description = "CLI for interacting with LangGraph API"
 authors = []
 license = "MIT"

libs/langgraph/langgraph/graph/graph.py

@@ -47,7 +47,7 @@ logger = logging.getLogger(__name__)
 class NodeSpec(NamedTuple):
     runnable: Runnable
     metadata: Optional[dict[str, Any]] = None
-    ends: Optional[tuple[str, ...]] = EMPTY_SEQ
+    ends: Optional[Union[tuple[str, ...], dict[str, str]]] = EMPTY_SEQ
 
 
 class Branch(NamedTuple):
@@ -625,7 +625,10 @@ class CompiledGraph(Pregel):
                     if branch.then is not None:
                         add_edge(end, branch.then)
         for key, n in self.builder.nodes.items():
-            if n.ends:
+            if isinstance(n.ends, dict):
+                for end, label in n.ends.items():
+                    add_edge(key, end, label, conditional=True)
+            elif isinstance(n.ends, tuple):
                 for end in n.ends:
                     add_edge(key, end, conditional=True)
 

libs/langgraph/langgraph/graph/state.py

@@ -33,7 +33,7 @@ from langgraph.channels.dynamic_barrier_value import DynamicBarrierValue, WaitFo
 from langgraph.channels.ephemeral_value import EphemeralValue
 from langgraph.channels.last_value import LastValue
 from langgraph.channels.named_barrier_value import NamedBarrierValue
-from langgraph.constants import EMPTY_SEQ, NS_END, NS_SEP, SELF, TAG_HIDDEN
+from langgraph.constants import EMPTY_SEQ, MISSING, NS_END, NS_SEP, SELF, TAG_HIDDEN
 from langgraph.errors import (
     ErrorCode,
     InvalidUpdateError,
@@ -90,7 +90,7 @@ class StateNodeSpec(NamedTuple):
     metadata: Optional[dict[str, Any]]
     input: Type[Any]
     retry_policy: Optional[RetryPolicy]
-    ends: Optional[tuple[str, ...]] = EMPTY_SEQ
+    ends: Optional[Union[tuple[str, ...], dict[str, str]]] = EMPTY_SEQ
 
 
 class StateGraph(Graph):
@@ -230,6 +230,7 @@ class StateGraph(Graph):
         metadata: Optional[dict[str, Any]] = None,
         input: Optional[Type[Any]] = None,
         retry: Optional[RetryPolicy] = None,
+        destinations: Optional[Union[dict[str, str], tuple[str]]] = None,
     ) -> Self:
         """Adds a new node to the state graph.
         Will take the name of the function/runnable as the node name.
@@ -254,6 +255,7 @@ class StateGraph(Graph):
         metadata: Optional[dict[str, Any]] = None,
         input: Optional[Type[Any]] = None,
         retry: Optional[RetryPolicy] = None,
+        destinations: Optional[Union[dict[str, str], tuple[str]]] = None,
     ) -> Self:
         """Adds a new node to the state graph.
 
@@ -277,6 +279,7 @@ class StateGraph(Graph):
         metadata: Optional[dict[str, Any]] = None,
         input: Optional[Type[Any]] = None,
         retry: Optional[RetryPolicy] = None,
+        destinations: Optional[Union[dict[str, str], tuple[str]]] = None,
     ) -> Self:
         """Adds a new node to the state graph.
 
@@ -288,7 +291,11 @@ class StateGraph(Graph):
             metadata (Optional[dict[str, Any]]): The metadata associated with the node. (default: None)
             input (Optional[Type[Any]]): The input schema for the node. (default: the graph's input schema)
             retry (Optional[RetryPolicy]): The policy for retrying the node. (default: None)
-
+            destinations (Optional[Union[dict[str, str], tuple[str]]]): Destinations that indicate where a node can route to.
+                This is useful for edgeless graphs with nodes that return `Command` objects.
+                If a dict is provided, the keys will be used as the target node names and the values will be used as the labels for the edges.
+                If a tuple is provided, the values will be used as the target node names.
+                NOTE: this is only used for graph rendering and doesn't have any effect on the graph execution.
         Raises:
             ValueError: If the key is already being used as a state key.
 
@@ -357,7 +364,7 @@ class StateGraph(Graph):
                     f"'{character}' is a reserved character and is not allowed in the node names."
                 )
 
-        ends = EMPTY_SEQ
+        ends: Union[tuple[str, ...], dict[str, str]] = EMPTY_SEQ
         try:
             if (
                 isfunction(action)
@@ -401,6 +408,10 @@ class StateGraph(Graph):
                         ends = vals
         except (TypeError, StopIteration):
             pass
+
+        if destinations is not None:
+            ends = destinations
+
         if input is not None:
             self._add_schema(input)
         self.nodes[cast(str, node)] = StateNodeSpec(
@@ -680,10 +691,23 @@ class CompiledStateGraph(CompiledGraph):
                         updates.extend(_get_updates(i) or ())
                 return updates
             elif get_type_hints(type(input)):
+                # if input is a Pydantic model, only update values
+                # for the keys that have been explicitly set by the users
+                # (this is needed to avoid sending updates for fields with None defaults)
+                output_keys_ = output_keys
+                # Pydantic v2
+                if hasattr(input, "model_fields_set"):
+                    output_keys_ = [
+                        k for k in output_keys if k in input.model_fields_set
+                    ]
+                # Pydantic v1
+                elif hasattr(input, "__fields_set__"):
+                    output_keys_ = [k for k in output_keys if k in input.__fields_set__]
+
                 return [
                     (k, getattr(input, k))
-                    for k in output_keys
-                    if getattr(input, k, None) is not None
+                    for k in output_keys_
+                    if getattr(input, k, MISSING) is not MISSING
                 ]
             else:
                 msg = create_error_message(

libs/langgraph/langgraph/pregel/__init__.py

@@ -197,6 +197,79 @@ class Channel:
 
 
 class Pregel(PregelProtocol):
+    """Pregel manages the runtime behavior for LangGraph applications.
+
+    ## Channels
+
+    Channels are used to communicate between chains. Each channel has a value type,
+    an update type, and an update function – which takes a sequence of updates and
+    modifies the stored value. Channels can be used to send data from one chain to
+    another, or to send data from a chain to itself in a future step. LangGraph
+    provides a number of built-in channels:
+
+    ### Basic channels: LastValue and Topic
+
+    - `LastValue`: The default channel, stores the last value sent to the channel,
+       useful for input and output values, or for sending data from one step to the next
+    - `Topic`: A configurable PubSub Topic, useful for sending multiple values
+       between chains, or for accumulating output. Can be configured to deduplicate
+       values, and/or to accumulate values over the course of multiple steps.
+
+    ### Advanced channels: Context and BinaryOperatorAggregate
+
+    - `Context`: exposes the value of a context manager, managing its lifecycle.
+      Useful for accessing external resources that require setup and/or teardown. eg.
+      `client = Context(httpx.Client)`
+    - `BinaryOperatorAggregate`: stores a persistent value, updated by applying
+       a binary operator to the current value and each update
+       sent to the channel, useful for computing aggregates over multiple steps. eg.
+      `total = BinaryOperatorAggregate(int, operator.add)`
+
+    ## Chains
+
+    Chains are LCEL Runnables which subscribe to one or more channels, and write to
+    one or more channels. Any valid LCEL expression can be used as a chain. Chains
+    can be combined into a Pregel application, which coordinates the execution of the
+    chains across multiple steps.
+
+    ## Pregel
+
+    Pregel combines multiple chains (or actors) into a single application. It
+    coordinates the execution of the chains across multiple steps, following the
+    Pregel/Bulk Synchronous Parallel model. Each step consists of three phases:
+
+    - **Plan**: Determine which chains to execute in this step, ie. the chains that
+      subscribe to channels updated in the previous step (or, in the first step,
+      chains that subscribe to input channels)
+    - **Execution**: Execute those chains in parallel, until all complete, or one fails,
+      or a timeout is reached. Any channel updates are invisible to other
+      chains until the next step.
+     - **Update**: Update the channels with the values written by the
+      chains in this step.
+
+    Repeat until no chains are planned for execution, or a maximum number of steps
+    is reached.
+
+    Example:
+        ```python
+        from langgraph import Channel, Pregel
+
+        grow_value = (
+            Channel.subscribe_to("value")
+            | (lambda x: x + x)
+            | Channel.write_to(value=lambda x: x if len(x) < 10 else None)
+        )
+
+        app = Pregel(
+            chains={"grow_value": grow_value},
+            input="value",
+            output="value",
+        )
+
+        assert app.invoke("a") == "aaaaaaaa"
+        ```
+    """
+
     nodes: dict[str, PregelNode]
 
     channels: dict[str, Union[BaseChannel, ManagedValueSpec]]

libs/langgraph/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "langgraph"
-version = "0.2.70"
+version = "0.2.72"
 description = "Building stateful, multi-actor applications with LLMs"
 authors = []
 license = "MIT"

libs/langgraph/tests/test_large_cases_async.py

@@ -133,6 +133,8 @@ async def test_invoke_two_processes_in_out_interrupt(
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "step": 6,
@@ -156,6 +158,8 @@ async def test_invoke_two_processes_in_out_interrupt(
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "step": 5,
@@ -179,6 +183,8 @@ async def test_invoke_two_processes_in_out_interrupt(
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "input",
                     "step": 4,
@@ -200,6 +206,8 @@ async def test_invoke_two_processes_in_out_interrupt(
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "step": 3,
@@ -223,6 +231,8 @@ async def test_invoke_two_processes_in_out_interrupt(
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "input",
                     "step": 2,
@@ -244,6 +254,8 @@ async def test_invoke_two_processes_in_out_interrupt(
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "step": 1,
@@ -267,6 +279,8 @@ async def test_invoke_two_processes_in_out_interrupt(
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "step": 0,
@@ -290,6 +304,7 @@ async def test_invoke_two_processes_in_out_interrupt(
                     }
                 },
                 metadata={
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "input",
                     "step": -1,
@@ -366,6 +381,8 @@ async def test_fork_always_re_runs_nodes(
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "step": 5,
@@ -387,6 +404,8 @@ async def test_fork_always_re_runs_nodes(
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "step": 4,
@@ -408,6 +427,8 @@ async def test_fork_always_re_runs_nodes(
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "step": 3,
@@ -429,6 +450,8 @@ async def test_fork_always_re_runs_nodes(
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "step": 2,
@@ -450,6 +473,8 @@ async def test_fork_always_re_runs_nodes(
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "step": 1,
@@ -471,6 +496,8 @@ async def test_fork_always_re_runs_nodes(
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "step": 0,
@@ -494,6 +521,7 @@ async def test_fork_always_re_runs_nodes(
                     }
                 },
                 metadata={
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "input",
                     "step": -1,
@@ -834,6 +862,8 @@ async def test_conditional_graph(checkpointer_name: str) -> None:
                 await app_w_interrupt.checkpointer.aget_tuple(config)
             ).checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 0,
@@ -894,6 +924,8 @@ async def test_conditional_graph(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 1,
@@ -1018,6 +1050,8 @@ async def test_conditional_graph(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 4,
@@ -1100,6 +1134,8 @@ async def test_conditional_graph(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 0,
@@ -1160,6 +1196,8 @@ async def test_conditional_graph(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 1,
@@ -1284,6 +1322,8 @@ async def test_conditional_graph(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 4,
@@ -1366,6 +1406,8 @@ async def test_conditional_graph(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 0,
@@ -1798,6 +1840,8 @@ async def test_conditional_graph_state(
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 1,
@@ -1853,6 +1897,8 @@ async def test_conditional_graph_state(
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 2,
@@ -1943,6 +1989,8 @@ async def test_conditional_graph_state(
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 5,
@@ -2010,6 +2058,8 @@ async def test_conditional_graph_state(
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 1,
@@ -2064,6 +2114,8 @@ async def test_conditional_graph_state(
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 2,
@@ -2152,6 +2204,8 @@ async def test_conditional_graph_state(
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 5,
@@ -2768,6 +2822,8 @@ async def test_state_graph_packets(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 1,
@@ -2827,6 +2883,8 @@ async def test_state_graph_packets(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 2,
@@ -2936,6 +2994,8 @@ async def test_state_graph_packets(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 4,
@@ -3005,6 +3065,8 @@ async def test_state_graph_packets(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 5,
@@ -3079,6 +3141,8 @@ async def test_state_graph_packets(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 1,
@@ -3140,6 +3204,8 @@ async def test_state_graph_packets(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 2,
@@ -3249,6 +3315,8 @@ async def test_state_graph_packets(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 4,
@@ -3318,6 +3386,8 @@ async def test_state_graph_packets(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 5,
@@ -3575,6 +3645,8 @@ async def test_message_graph(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 1,
@@ -3629,6 +3701,8 @@ async def test_message_graph(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 2,
@@ -3719,6 +3793,8 @@ async def test_message_graph(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 4,
@@ -3779,6 +3855,8 @@ async def test_message_graph(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 5,
@@ -4087,6 +4165,8 @@ async def test_start_branch_then(checkpointer_name: str) -> None:
         if "shallow" not in checkpointer_name:
             assert [c.metadata async for c in tool_two.checkpointer.alist(thread1)] == [
                 {
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "step": 0,
@@ -4095,6 +4175,7 @@ async def test_start_branch_then(checkpointer_name: str) -> None:
                     "thread_id": "1",
                 },
                 {
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "input",
                     "step": -1,
@@ -4117,6 +4198,8 @@ async def test_start_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 0,
@@ -4150,6 +4233,8 @@ async def test_start_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 1,
@@ -4185,6 +4270,8 @@ async def test_start_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 0,
@@ -4218,6 +4305,8 @@ async def test_start_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 1,
@@ -4253,6 +4342,8 @@ async def test_start_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 0,
@@ -4283,6 +4374,8 @@ async def test_start_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 1,
@@ -4316,6 +4409,8 @@ async def test_start_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 2,
@@ -4856,6 +4951,8 @@ async def test_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 1,
@@ -4888,6 +4985,8 @@ async def test_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 3,
@@ -4922,6 +5021,8 @@ async def test_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 1,
@@ -4954,6 +5055,8 @@ async def test_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 3,
@@ -4996,6 +5099,8 @@ async def test_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 1,
@@ -5028,6 +5133,8 @@ async def test_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 3,
@@ -5062,6 +5169,8 @@ async def test_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 1,
@@ -5094,6 +5203,8 @@ async def test_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 3,
@@ -5122,6 +5233,7 @@ async def test_branch_then(checkpointer_name: str) -> None:
             config=uconfig,
             created_at=AnyStr(),
             metadata={
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 0,
@@ -5149,6 +5261,8 @@ async def test_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 1,
@@ -5175,6 +5289,8 @@ async def test_branch_then(checkpointer_name: str) -> None:
             },
             created_at=AnyStr(),
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 3,
@@ -5266,6 +5382,8 @@ async def test_nested_graph_state(checkpointer_name: str) -> None:
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "writes": {"outer_1": {"my_key": "hi my value"}},
@@ -5317,6 +5435,8 @@ async def test_nested_graph_state(checkpointer_name: str) -> None:
                             }
                         },
                         metadata={
+                            "checkpoint_id": AnyStr(),
+                            "checkpoint_map": AnyDict({"": AnyStr()}),
                             "parents": {
                                 "": AnyStr(),
                             },
@@ -5363,6 +5483,8 @@ async def test_nested_graph_state(checkpointer_name: str) -> None:
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "writes": {"outer_1": {"my_key": "hi my value"}},
@@ -5409,6 +5531,8 @@ async def test_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "writes": {"outer_1": {"my_key": "hi my value"}},
@@ -5447,6 +5571,8 @@ async def test_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "writes": None,
@@ -5481,6 +5607,7 @@ async def test_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "input",
                     "writes": {"__start__": {"my_key": "my value"}},
@@ -5516,6 +5643,8 @@ async def test_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_map": AnyDict({"": AnyStr()}),
                     "source": "loop",
                     "writes": {
                         "inner_1": {
@@ -5564,6 +5693,8 @@ async def test_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_map": AnyDict({"": AnyStr()}),
                     "source": "loop",
                     "writes": None,
                     "step": 0,
@@ -5613,6 +5744,8 @@ async def test_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": None,
+                    "checkpoint_map": AnyDict({"": AnyStr()}),
                     "source": "input",
                     "writes": {"__start__": {"my_key": "hi my value"}},
                     "step": -1,
@@ -5658,6 +5791,8 @@ async def test_nested_graph_state(checkpointer_name: str) -> None:
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "writes": {
@@ -5694,6 +5829,8 @@ async def test_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "writes": {
@@ -5736,6 +5873,8 @@ async def test_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "writes": {"inner": {"my_key": "hi my value here and there"}},
@@ -5776,6 +5915,8 @@ async def test_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "writes": {"outer_1": {"my_key": "hi my value"}},
@@ -5810,6 +5951,8 @@ async def test_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "writes": None,
@@ -5844,6 +5987,7 @@ async def test_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "input",
                     "writes": {"__start__": {"my_key": "my value"}},
@@ -5953,6 +6097,8 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "writes": {"parent_1": {"my_key": "hi my value"}},
@@ -5999,6 +6145,8 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {"": AnyStr()},
                     "source": "loop",
                     "writes": None,
@@ -6045,6 +6193,8 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_map": AnyDict({"": AnyStr(), AnyStr("child:"): AnyStr()}),
                 "parents": AnyDict(
                     {
                         "": AnyStr(),
@@ -6124,6 +6274,10 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                                         }
                                     },
                                     metadata={
+                                        "checkpoint_id": AnyStr(),
+                                        "checkpoint_map": AnyDict(
+                                            {"": AnyStr(), AnyStr("child:"): AnyStr()}
+                                        ),
                                         "parents": AnyDict(
                                             {
                                                 "": AnyStr(),
@@ -6186,6 +6340,8 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                             }
                         },
                         metadata={
+                            "checkpoint_id": AnyStr(),
+                            "checkpoint_map": AnyDict({"": AnyStr()}),
                             "parents": {"": AnyStr()},
                             "source": "loop",
                             "writes": None,
@@ -6225,6 +6381,8 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "writes": {"parent_1": {"my_key": "hi my value"}},
@@ -6273,6 +6431,8 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "writes": {
@@ -6318,6 +6478,8 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                         }
                     },
                     metadata={
+                        "checkpoint_id": AnyStr(),
+                        "checkpoint_ns": "",
                         "parents": {},
                         "source": "loop",
                         "writes": {
@@ -6348,6 +6510,8 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                         }
                     },
                     metadata={
+                        "checkpoint_id": AnyStr(),
+                        "checkpoint_ns": "",
                         "parents": {},
                         "source": "loop",
                         "writes": {"child": {"my_key": "hi my value here and there"}},
@@ -6392,6 +6556,8 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                         }
                     },
                     metadata={
+                        "checkpoint_id": AnyStr(),
+                        "checkpoint_ns": "",
                         "parents": {},
                         "source": "loop",
                         "writes": {"parent_1": {"my_key": "hi my value"}},
@@ -6449,6 +6615,7 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                         }
                     },
                     metadata={
+                        "checkpoint_ns": "",
                         "parents": {},
                         "source": "input",
                         "writes": {"my_key": "my value"},
@@ -6484,6 +6651,8 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_map": AnyDict({"": AnyStr()}),
                     "source": "loop",
                     "writes": {"child_1": {"my_key": "hi my value here and there"}},
                     "step": 1,
@@ -6523,6 +6692,8 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_map": AnyDict({"": AnyStr()}),
                     "source": "loop",
                     "writes": None,
                     "step": 0,
@@ -6575,6 +6746,8 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": None,
+                    "checkpoint_map": AnyDict({"": AnyStr()}),
                     "source": "input",
                     "writes": {"__start__": {"my_key": "hi my value"}},
                     "step": -1,
@@ -6622,6 +6795,10 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_map": AnyDict(
+                        {"": AnyStr(), AnyStr("child:"): AnyStr()}
+                    ),
                     "source": "loop",
                     "writes": {
                         "grandchild_2": {"my_key": "hi my value here and there"}
@@ -6679,6 +6856,10 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_map": AnyDict(
+                        {"": AnyStr(), AnyStr("child:"): AnyStr()}
+                    ),
                     "source": "loop",
                     "writes": {"grandchild_1": {"my_key": "hi my value here"}},
                     "step": 1,
@@ -6741,6 +6922,10 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_map": AnyDict(
+                        {"": AnyStr(), AnyStr("child:"): AnyStr()}
+                    ),
                     "source": "loop",
                     "writes": None,
                     "step": 0,
@@ -6803,6 +6988,10 @@ async def test_doubly_nested_graph_state(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": None,
+                    "checkpoint_map": AnyDict(
+                        {"": AnyStr(), AnyStr("child:"): AnyStr()}
+                    ),
                     "source": "input",
                     "writes": {"__start__": {"my_key": "hi my value"}},
                     "step": -1,
@@ -7081,6 +7270,8 @@ async def test_weather_subgraph(
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "source": "loop",
                 "writes": {"router_node": {"route": "weather"}},
                 "step": 1,
@@ -7177,6 +7368,8 @@ async def test_weather_subgraph(
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "source": "loop",
                 "writes": {"router_node": {"route": "weather"}},
                 "step": 1,
@@ -7222,6 +7415,8 @@ async def test_weather_subgraph(
                             }
                         },
                         metadata={
+                            "checkpoint_id": AnyStr(),
+                            "checkpoint_map": AnyDict({"": AnyStr()}),
                             "source": "loop",
                             "writes": {"model_node": {"city": "San Francisco"}},
                             "step": 1,
@@ -7285,6 +7480,8 @@ async def test_weather_subgraph(
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "source": "loop",
                 "writes": {"router_node": {"route": "weather"}},
                 "step": 1,
@@ -7331,6 +7528,7 @@ async def test_weather_subgraph(
                             }
                         },
                         metadata={
+                            "checkpoint_map": AnyDict({"": AnyStr()}),
                             "step": 2,
                             "source": "update",
                             "writes": {

libs/langgraph/tests/test_prebuilt.py

@@ -63,6 +63,7 @@ from langgraph.store.base import BaseStore
 from langgraph.store.memory import InMemoryStore
 from langgraph.types import Command, Interrupt, interrupt
 from langgraph.utils.config import get_stream_writer
+from tests.any_str import AnyStr
 from tests.conftest import (
     ALL_CHECKPOINTERS_ASYNC,
     ALL_CHECKPOINTERS_SYNC,
@@ -182,6 +183,8 @@ def test_no_prompt(
             "agent": "agent",
         }
         assert saved.metadata == {
+            "checkpoint_id": AnyStr(),
+            "checkpoint_ns": "",
             "parents": {},
             "source": "loop",
             "writes": {"agent": {"messages": [AIMessage(content="hi?", id="0")]}},
@@ -214,6 +217,8 @@ async def test_no_prompt_async(checkpointer_name: str) -> None:
                 "agent": "agent",
             }
             assert saved.metadata == {
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "writes": {"agent": {"messages": [AIMessage(content="hi?", id="0")]}},

libs/langgraph/tests/test_pregel.py

@@ -35,6 +35,7 @@ from langchain_core.runnables import (
     RunnableLambda,
     RunnablePassthrough,
 )
+from langchain_core.runnables.graph import Edge
 from langsmith import traceable
 from pytest_mock import MockerFixture
 from syrupy import SnapshotAssertion
@@ -1111,6 +1112,8 @@ def test_pending_writes_resume(
         PregelTask(AnyStr(), "two", (PULL, "two"), 'ConnectionError("I\'m not good")'),
     )
     assert state.metadata == {
+        "checkpoint_id": AnyStr(),
+        "checkpoint_ns": "",
         "parents": {},
         "source": "loop",
         "step": 0,
@@ -1209,6 +1212,8 @@ def test_pending_writes_resume(
             "channel_values": {"one": "one", "two": "two", "value": 6},
         },
         metadata={
+            "checkpoint_id": AnyStr(),
+            "checkpoint_ns": "",
             "parents": {},
             "step": 1,
             "source": "loop",
@@ -1259,6 +1264,8 @@ def test_pending_writes_resume(
             },
         },
         metadata={
+            "checkpoint_id": AnyStr(),
+            "checkpoint_ns": "",
             "parents": {},
             "step": 0,
             "source": "loop",
@@ -1300,6 +1307,7 @@ def test_pending_writes_resume(
             "channel_values": {"__start__": {"value": 1}},
         },
         metadata={
+            "checkpoint_ns": "",
             "parents": {},
             "step": -1,
             "source": "input",
@@ -2390,6 +2398,8 @@ def test_in_one_fan_out_state_graph_waiting_edge(
         },
         created_at=AnyStr(),
         metadata={
+            "checkpoint_id": AnyStr(),
+            "checkpoint_ns": "",
             "parents": {},
             "source": "update",
             "step": 4,
@@ -4825,6 +4835,8 @@ def test_parent_command(request: pytest.FixtureRequest, checkpointer_name: str)
             }
         },
         metadata={
+            "checkpoint_id": AnyStr(),
+            "checkpoint_ns": "",
             "source": "loop",
             "writes": {
                 "alice": {
@@ -6416,3 +6428,81 @@ def test_tags_stream_mode_messages() -> None:
             },
         )
     ]
+
+
+def test_node_destinations() -> None:
+    class State(TypedDict):
+        foo: Annotated[str, operator.add]
+
+    def node_a(state: State):
+        value = state["foo"]
+        if value == "a":
+            goto = "node_b"
+        else:
+            goto = "node_c"
+
+        return Command(
+            update={"foo": value},
+            goto=goto,
+            graph=Command.PARENT,
+        )
+
+    subgraph = StateGraph(State).add_node(node_a).add_edge(START, "node_a").compile()
+
+    # test calling subgraph inside a node function
+    def call_subgraph(state: State):
+        return subgraph.invoke(state)
+
+    def node_b(state: State):
+        return {"foo": "b"}
+
+    def node_c(state: State):
+        return {"foo": "c"}
+
+    for subgraph_node in (subgraph, call_subgraph):
+        # destinations w/ tuples
+        builder = StateGraph(State)
+        builder.add_edge(START, "child")
+        builder.add_node("child", subgraph_node, destinations=("node_b", "node_c"))
+        builder.add_node(node_b)
+        builder.add_node(node_c)
+        compiled_graph = builder.compile()
+        assert compiled_graph.invoke({"foo": ""}) == {"foo": "c"}
+
+        graph = compiled_graph.get_graph()
+        assert [
+            Edge(source="__start__", target="child", data=None, conditional=False),
+            Edge(source="child", target="node_b", data=None, conditional=True),
+            Edge(source="child", target="node_c", data=None, conditional=True),
+        ] == graph.edges
+
+        # destinations w/ dicts
+        builder = StateGraph(State)
+        builder.add_edge(START, "child")
+        builder.add_node(
+            "child", subgraph_node, destinations={"node_b": "foo", "node_c": "bar"}
+        )
+        builder.add_node(node_b)
+        builder.add_node(node_c)
+        compiled_graph = builder.compile()
+        assert compiled_graph.invoke({"foo": ""}) == {"foo": "c"}
+
+        graph = compiled_graph.get_graph()
+        assert [
+            Edge(source="__start__", target="child", data=None, conditional=False),
+            Edge(source="child", target="node_b", data="foo", conditional=True),
+            Edge(source="child", target="node_c", data="bar", conditional=True),
+        ] == graph.edges
+
+
+def test_pydantic_none_state_update() -> None:
+    from pydantic import BaseModel
+
+    class State(BaseModel):
+        foo: Optional[str]
+
+    def node_a(state: State) -> State:
+        return State(foo=None)
+
+    graph = StateGraph(State).add_node(node_a).add_edge(START, "node_a").compile()
+    assert graph.invoke({"foo": ""}) == {"foo": None}

libs/langgraph/tests/test_pregel_async.py

@@ -606,6 +606,8 @@ async def test_dynamic_interrupt(checkpointer_name: str) -> None:
         if "shallow" not in checkpointer_name:
             assert [c.metadata async for c in tool_two.checkpointer.alist(thread1)] == [
                 {
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "step": 0,
@@ -613,6 +615,7 @@ async def test_dynamic_interrupt(checkpointer_name: str) -> None:
                     "thread_id": "1",
                 },
                 {
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "input",
                     "step": -1,
@@ -641,6 +644,8 @@ async def test_dynamic_interrupt(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 0,
@@ -667,6 +672,8 @@ async def test_dynamic_interrupt(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 1,
@@ -791,6 +798,8 @@ async def test_dynamic_interrupt_subgraph(checkpointer_name: str) -> None:
                 c.metadata async for c in tool_two.checkpointer.alist(thread1root)
             ] == [
                 {
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "step": 0,
@@ -798,6 +807,7 @@ async def test_dynamic_interrupt_subgraph(checkpointer_name: str) -> None:
                     "thread_id": "1",
                 },
                 {
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "input",
                     "step": -1,
@@ -832,6 +842,8 @@ async def test_dynamic_interrupt_subgraph(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 0,
@@ -858,6 +870,8 @@ async def test_dynamic_interrupt_subgraph(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "update",
                 "step": 1,
@@ -976,6 +990,8 @@ async def test_copy_checkpoint(checkpointer_name: str) -> None:
         if "shallow" not in checkpointer_name:
             assert [c.metadata async for c in tool_two.checkpointer.alist(thread1)] == [
                 {
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "loop",
                     "step": 0,
@@ -983,6 +999,7 @@ async def test_copy_checkpoint(checkpointer_name: str) -> None:
                     "thread_id": "1",
                 },
                 {
+                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "input",
                     "step": -1,
@@ -1021,6 +1038,8 @@ async def test_copy_checkpoint(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 0,
@@ -1064,6 +1083,8 @@ async def test_copy_checkpoint(checkpointer_name: str) -> None:
             config=tup.config,
             created_at=tup.checkpoint["ts"],
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "fork",
                 "step": 1,
@@ -1230,6 +1251,8 @@ async def test_cancel_graph_astream(checkpointer_name: str) -> None:
             assert state.values == {"value": 3}  # 1 + 2
             assert state.next == ("aparallelwhile",)
             assert state.metadata == {
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 0,
@@ -1307,6 +1330,8 @@ async def test_cancel_graph_astream_events_v2(checkpointer_name: Optional[str])
             assert state.values == {"value": 2}
             assert state.next == ("awhile",)
             assert state.metadata == {
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "step": 1,
@@ -2007,6 +2032,8 @@ async def test_pending_writes_resume(
             ),
         )
         assert state.metadata == {
+            "checkpoint_id": AnyStr(),
+            "checkpoint_ns": "",
             "parents": {},
             "source": "loop",
             "step": 0,
@@ -2105,6 +2132,8 @@ async def test_pending_writes_resume(
                 "channel_values": {"one": "one", "two": "two", "value": 6},
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "step": 1,
                 "source": "loop",
@@ -2157,6 +2186,8 @@ async def test_pending_writes_resume(
                 },
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "step": 0,
                 "source": "loop",
@@ -2200,6 +2231,7 @@ async def test_pending_writes_resume(
                 "channel_values": {"__start__": {"value": 1}},
             },
             metadata={
+                "checkpoint_ns": "",
                 "parents": {},
                 "step": -1,
                 "source": "input",
@@ -2778,6 +2810,8 @@ async def test_send_dedupe_on_resume(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "source": "loop",
                     "writes": {"3": ["3"]},
                     "thread_id": "1",
@@ -2814,6 +2848,8 @@ async def test_send_dedupe_on_resume(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "source": "loop",
                     "writes": {"2": ["2|3"], "3": ["3"], "flaky": ["flaky|4"]},
                     "thread_id": "1",
@@ -2857,6 +2893,8 @@ async def test_send_dedupe_on_resume(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "source": "loop",
                     "writes": {
                         "2": [
@@ -2922,6 +2960,8 @@ async def test_send_dedupe_on_resume(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "source": "loop",
                     "writes": {"1": ["1"]},
                     "thread_id": "1",
@@ -2977,6 +3017,8 @@ async def test_send_dedupe_on_resume(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_id": AnyStr(),
+                    "checkpoint_ns": "",
                     "source": "loop",
                     "writes": None,
                     "thread_id": "1",
@@ -3014,6 +3056,7 @@ async def test_send_dedupe_on_resume(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
+                    "checkpoint_ns": "",
                     "source": "input",
                     "writes": {"__start__": ["0"]},
                     "thread_id": "1",
@@ -3186,6 +3229,8 @@ async def test_send_react_interrupt(checkpointer_name: str) -> None:
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "step": 1,
                 "source": "loop",
                 "writes": {
@@ -3257,6 +3302,8 @@ async def test_send_react_interrupt(checkpointer_name: str) -> None:
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "step": 2,
                 "source": "update",
                 "writes": {
@@ -3344,6 +3391,8 @@ async def test_send_react_interrupt(checkpointer_name: str) -> None:
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "step": 1,
                 "source": "loop",
                 "writes": {
@@ -3436,6 +3485,8 @@ async def test_send_react_interrupt(checkpointer_name: str) -> None:
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "step": 2,
                 "source": "update",
                 "writes": {
@@ -3651,6 +3702,8 @@ async def test_send_react_interrupt_control(
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "step": 1,
                 "source": "loop",
                 "writes": {
@@ -3722,6 +3775,8 @@ async def test_send_react_interrupt_control(
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "step": 2,
                 "source": "update",
                 "writes": {
@@ -4671,6 +4726,8 @@ async def test_in_one_fan_out_state_graph_waiting_edge_custom_state_class(
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "parents": {},
                 "source": "loop",
                 "writes": {"qa": {"answer": "doc1,doc2,doc3,doc4"}},
@@ -6145,6 +6202,8 @@ async def test_parent_command(checkpointer_name: str) -> None:
                 }
             },
             metadata={
+                "checkpoint_id": AnyStr(),
+                "checkpoint_ns": "",
                 "source": "loop",
                 "writes": {
                     "alice": {

libs/sdk-js/.gitignore

@@ -6,6 +6,11 @@ client.cjs
 client.js
 client.d.ts
 client.d.cts
+react.cjs
+react.js
+react.d.ts
+react.d.cts
 node_modules
 dist
 .yarn
+docs

libs/sdk-js/langchain.config.js

@@ -10,8 +10,8 @@ function abs(relativePath) {
 }
 
 export const config = {
-  internals: [],
-  entrypoints: { index: "index", client: "client" },
+  internals: [/react/],
+  entrypoints: { index: "index", client: "client", react: "react/index" },
   tsConfigPath: resolve("./tsconfig.json"),
   cjsSource: "./dist-cjs",
   cjsDestination: "./dist",

libs/sdk-js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-sdk",
-  "version": "0.0.36",
+  "version": "0.0.42",
   "description": "Client library for interacting with the LangGraph API",
   "type": "module",
   "packageManager": "yarn@1.22.19",
@@ -10,7 +10,8 @@
     "prepublish": "yarn run build",
     "format": "prettier --write src",
     "lint": "prettier --check src && tsc --noEmit",
-    "test": "NODE_OPTIONS=--experimental-vm-modules jest --testPathIgnorePatterns=\\.int\\.test.ts"
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest --testPathIgnorePatterns=\\.int\\.test.ts",
+    "typedoc": "typedoc && typedoc src/react/index.ts --out docs/react --options typedoc.react.json"
   },
   "main": "index.js",
   "license": "MIT",
@@ -22,18 +23,25 @@
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
+    "@langchain/core": "^0.3.31",
     "@langchain/scripts": "^0.1.4",
     "@tsconfig/recommended": "^1.0.2",
     "@types/jest": "^29.5.12",
     "@types/node": "^20.12.12",
     "@types/uuid": "^9.0.1",
+    "@types/react": "18.3.2",
     "concat-md": "^0.5.1",
     "jest": "^29.7.0",
     "prettier": "^3.2.5",
     "ts-jest": "^29.1.2",
-    "typedoc": "^0.26.1",
-    "typedoc-plugin-markdown": "^4.1.0",
-    "typescript": "^5.4.5"
+    "typedoc": "^0.27.7",
+    "typedoc-plugin-markdown": "^4.4.2",
+    "typescript": "^5.4.5",
+    "react": "^18.3.1"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "@langchain/core": ">=0.2.31 <0.4.0"
   },
   "exports": {
     ".": {
@@ -54,6 +62,15 @@
       "import": "./client.js",
       "require": "./client.cjs"
     },
+    "./react": {
+      "types": {
+        "import": "./react.d.ts",
+        "require": "./react.d.cts",
+        "default": "./react.d.ts"
+      },
+      "import": "./react.js",
+      "require": "./react.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -65,6 +82,10 @@
     "client.cjs",
     "client.js",
     "client.d.ts",
-    "client.d.cts"
+    "client.d.cts",
+    "react.cjs",
+    "react.js",
+    "react.d.ts",
+    "react.d.cts"
   ]
 }

libs/sdk-js/src/client.ts

@@ -22,12 +22,8 @@ import {
   CronCreateForThreadResponse,
 } from "./schema.js";
 import { AsyncCaller, AsyncCallerParams } from "./utils/async_caller.js";
-import {
-  EventSourceParser,
-  createParser,
-} from "./utils/eventsource-parser/index.js";
 import { IterableReadableStream } from "./utils/stream.js";
-import {
+import type {
   RunsCreatePayload,
   RunsStreamPayload,
   RunsWaitPayload,
@@ -38,6 +34,8 @@ import {
 import { mergeSignals } from "./utils/signals.js";
 import { getEnvironmentVariable } from "./utils/env.js";
 import { _getFetchImplementation } from "./singletons/fetch.js";
+import type { TypedAsyncGenerator, StreamMode } from "./types.stream.js";
+import { BytesLineDecoder, SSEDecoder } from "./utils/sse.js";
 /**
  * Get the API key from the environment.
  * Precedence:
@@ -67,7 +65,7 @@ export function getApiKey(apiKey?: string): string | undefined {
   return undefined;
 }
 
-interface ClientConfig {
+export interface ClientConfig {
   apiUrl?: string;
   apiKey?: string;
   callerOptions?: AsyncCallerParams;
@@ -78,7 +76,7 @@ interface ClientConfig {
 class BaseClient {
   protected asyncCaller: AsyncCaller;
 
-  protected timeoutMs: number;
+  protected timeoutMs: number | undefined;
 
   protected apiUrl: string;
 
@@ -91,7 +89,7 @@ class BaseClient {
       ...config?.callerOptions,
     });
 
-    this.timeoutMs = config?.timeoutMs || 12_000;
+    this.timeoutMs = config?.timeoutMs;
 
     // default limit being capped by Chrome
     // https://github.com/nodejs/undici/issues/1373
@@ -131,7 +129,7 @@ class BaseClient {
       if (options.timeoutMs != null) {
         timeoutSignal = AbortSignal.timeout(options.timeoutMs);
       }
-    } else {
+    } else if (this.timeoutMs != null) {
       timeoutSignal = AbortSignal.timeout(this.timeoutMs);
     }
 
@@ -164,8 +162,7 @@ class BaseClient {
       signal?: AbortSignal;
     },
   ): Promise<T> {
-    const response = await this.asyncCaller.call(
-      _getFetchImplementation(),
+    const response = await this.asyncCaller.fetch(
       ...this.prepareFetchOptions(path, options),
     );
     if (response.status === 202 || response.status === 204) {
@@ -457,15 +454,20 @@ export class AssistantsClient extends BaseClient {
   }
 }
 
-export class ThreadsClient extends BaseClient {
+export class ThreadsClient<
+  TStateType = DefaultValues,
+  TUpdateType = TStateType,
+> extends BaseClient {
   /**
    * Get a thread by ID.
    *
    * @param threadId ID of the thread.
    * @returns The thread.
    */
-  async get(threadId: string): Promise<Thread> {
-    return this.fetch<Thread>(`/threads/${threadId}`);
+  async get<ValuesType = TStateType>(
+    threadId: string,
+  ): Promise<Thread<ValuesType>> {
+    return this.fetch<Thread<ValuesType>>(`/threads/${threadId}`);
   }
 
   /**
@@ -481,8 +483,8 @@ export class ThreadsClient extends BaseClient {
     metadata?: Metadata;
     threadId?: string;
     ifExists?: OnConflictBehavior;
-  }): Promise<Thread> {
-    return this.fetch<Thread>(`/threads`, {
+  }): Promise<Thread<TStateType>> {
+    return this.fetch<Thread<TStateType>>(`/threads`, {
       method: "POST",
       json: {
         metadata: payload?.metadata,
@@ -497,8 +499,8 @@ export class ThreadsClient extends BaseClient {
    * @param threadId ID of the thread to be copied
    * @returns Newly copied thread
    */
-  async copy(threadId: string): Promise<Thread> {
-    return this.fetch<Thread>(`/threads/${threadId}/copy`, {
+  async copy(threadId: string): Promise<Thread<TStateType>> {
+    return this.fetch<Thread<TStateType>>(`/threads/${threadId}/copy`, {
       method: "POST",
     });
   }
@@ -542,7 +544,7 @@ export class ThreadsClient extends BaseClient {
    * @param query Query options
    * @returns List of threads
    */
-  async search(query?: {
+  async search<ValuesType = TStateType>(query?: {
     /**
      * Metadata to filter threads by.
      */
@@ -561,8 +563,8 @@ export class ThreadsClient extends BaseClient {
      * Must be one of 'idle', 'busy', 'interrupted' or 'error'.
      */
     status?: ThreadStatus;
-  }): Promise<Thread[]> {
-    return this.fetch<Thread[]>("/threads/search", {
+  }): Promise<Thread<ValuesType>[]> {
+    return this.fetch<Thread<ValuesType>[]>("/threads/search", {
       method: "POST",
       json: {
         metadata: query?.metadata ?? undefined,
@@ -579,7 +581,7 @@ export class ThreadsClient extends BaseClient {
    * @param threadId ID of the thread.
    * @returns Thread state.
    */
-  async getState<ValuesType = DefaultValues>(
+  async getState<ValuesType = TStateType>(
     threadId: string,
     checkpoint?: Checkpoint | string,
     options?: { subgraphs?: boolean },
@@ -613,7 +615,7 @@ export class ThreadsClient extends BaseClient {
    * @param threadId The ID of the thread.
    * @returns
    */
-  async updateState<ValuesType = DefaultValues>(
+  async updateState<ValuesType = TUpdateType>(
     threadId: string,
     options: {
       values: ValuesType;
@@ -649,7 +651,7 @@ export class ThreadsClient extends BaseClient {
     let threadId: string;
 
     if (typeof threadIdOrConfig !== "string") {
-      if (typeof threadIdOrConfig.configurable.thread_id !== "string") {
+      if (typeof threadIdOrConfig.configurable?.thread_id !== "string") {
         throw new Error(
           "Thread ID is required when updating state with a config.",
         );
@@ -672,7 +674,7 @@ export class ThreadsClient extends BaseClient {
    * @param options Additional options.
    * @returns List of thread states.
    */
-  async getHistory<ValuesType = DefaultValues>(
+  async getHistory<ValuesType = TStateType>(
     threadId: string,
     options?: {
       limit?: number;
@@ -696,24 +698,43 @@ export class ThreadsClient extends BaseClient {
   }
 }
 
-export class RunsClient extends BaseClient {
-  stream(
+export class RunsClient<
+  TStateType = DefaultValues,
+  TUpdateType = TStateType,
+  TCustomEventType = unknown,
+> extends BaseClient {
+  stream<
+    TStreamMode extends StreamMode | StreamMode[] = StreamMode,
+    TSubgraphs extends boolean = false,
+  >(
     threadId: null,
     assistantId: string,
-    payload?: Omit<RunsStreamPayload, "multitaskStrategy" | "onCompletion">,
-  ): AsyncGenerator<{
-    event: StreamEvent;
-    data: any;
-  }>;
+    payload?: Omit<
+      RunsStreamPayload<TStreamMode, TSubgraphs>,
+      "multitaskStrategy" | "onCompletion"
+    >,
+  ): TypedAsyncGenerator<
+    TStreamMode,
+    TSubgraphs,
+    TStateType,
+    TUpdateType,
+    TCustomEventType
+  >;
 
-  stream(
+  stream<
+    TStreamMode extends StreamMode | StreamMode[] = StreamMode,
+    TSubgraphs extends boolean = false,
+  >(
     threadId: string,
     assistantId: string,
-    payload?: RunsStreamPayload,
-  ): AsyncGenerator<{
-    event: StreamEvent;
-    data: any;
-  }>;
+    payload?: RunsStreamPayload<TStreamMode, TSubgraphs>,
+  ): TypedAsyncGenerator<
+    TStreamMode,
+    TSubgraphs,
+    TStateType,
+    TUpdateType,
+    TCustomEventType
+  >;
 
   /**
    * Create a run and stream the results.
@@ -722,14 +743,20 @@ export class RunsClient extends BaseClient {
    * @param assistantId Assistant ID to use for this run.
    * @param payload Payload for creating a run.
    */
-  async *stream(
+  async *stream<
+    TStreamMode extends StreamMode | StreamMode[] = StreamMode,
+    TSubgraphs extends boolean = false,
+  >(
     threadId: string | null,
     assistantId: string,
-    payload?: RunsStreamPayload,
-  ): AsyncGenerator<{
-    event: StreamEvent;
-    data: any;
-  }> {
+    payload?: RunsStreamPayload<TStreamMode, TSubgraphs>,
+  ): TypedAsyncGenerator<
+    TStreamMode,
+    TSubgraphs,
+    TStateType,
+    TUpdateType,
+    TCustomEventType
+  > {
     const json: Record<string, any> = {
       input: payload?.input,
       command: payload?.command,
@@ -753,8 +780,7 @@ export class RunsClient extends BaseClient {
 
     const endpoint =
       threadId == null ? `/runs/stream` : `/threads/${threadId}/runs/stream`;
-    const response = await this.asyncCaller.call(
-      _getFetchImplementation(),
+    const response = await this.asyncCaller.fetch(
       ...this.prepareFetchOptions(endpoint, {
         method: "POST",
         json,
@@ -763,45 +789,11 @@ export class RunsClient extends BaseClient {
       }),
     );
 
-    let parser: EventSourceParser;
-    let onEndEvent: () => void;
-    const textDecoder = new TextDecoder();
-
-    const stream: ReadableStream<{ event: string; data: any }> = (
+    const stream: ReadableStream<{ event: any; data: any }> = (
       response.body || new ReadableStream({ start: (ctrl) => ctrl.close() })
-    ).pipeThrough(
-      new TransformStream({
-        async start(ctrl) {
-          parser = createParser((event) => {
-            if (
-              (payload?.signal && payload.signal.aborted) ||
-              (event.type === "event" && event.data === "[DONE]")
-            ) {
-              ctrl.terminate();
-              return;
-            }
-
-            if ("data" in event) {
-              ctrl.enqueue({
-                event: event.event ?? "message",
-                data: JSON.parse(event.data),
-              });
-            }
-          });
-          onEndEvent = () => {
-            ctrl.enqueue({ event: "end", data: undefined });
-          };
-        },
-        async transform(chunk) {
-          const payload = textDecoder.decode(chunk);
-          parser.feed(payload);
-
-          // eventsource-parser will ignore events
-          // that are not terminated by a newline
-          if (payload.trim() === "event: end") onEndEvent();
-        },
-      }),
-    );
+    )
+      .pipeThrough(new BytesLineDecoder())
+      .pipeThrough(new SSEDecoder());
 
     yield* IterableReadableStream.fromReadableStream(stream);
   }
@@ -1046,8 +1038,7 @@ export class RunsClient extends BaseClient {
         ? { signal: options }
         : options;
 
-    const response = await this.asyncCaller.call(
-      _getFetchImplementation(),
+    const response = await this.asyncCaller.fetch(
       ...this.prepareFetchOptions(`/threads/${threadId}/runs/${runId}/stream`, {
         method: "GET",
         timeoutMs: null,
@@ -1056,45 +1047,11 @@ export class RunsClient extends BaseClient {
       }),
     );
 
-    let parser: EventSourceParser;
-    let onEndEvent: () => void;
-    const textDecoder = new TextDecoder();
-
     const stream: ReadableStream<{ event: string; data: any }> = (
       response.body || new ReadableStream({ start: (ctrl) => ctrl.close() })
-    ).pipeThrough(
-      new TransformStream({
-        async start(ctrl) {
-          parser = createParser((event) => {
-            if (
-              (opts?.signal && opts.signal.aborted) ||
-              (event.type === "event" && event.data === "[DONE]")
-            ) {
-              ctrl.terminate();
-              return;
-            }
-
-            if ("data" in event) {
-              ctrl.enqueue({
-                event: event.event ?? "message",
-                data: JSON.parse(event.data),
-              });
-            }
-          });
-          onEndEvent = () => {
-            ctrl.enqueue({ event: "end", data: undefined });
-          };
-        },
-        async transform(chunk) {
-          const payload = textDecoder.decode(chunk);
-          parser.feed(payload);
-
-          // eventsource-parser will ignore events
-          // that are not terminated by a newline
-          if (payload.trim() === "event: end") onEndEvent();
-        },
-      }),
-    );
+    )
+      .pipeThrough(new BytesLineDecoder())
+      .pipeThrough(new SSEDecoder());
 
     yield* IterableReadableStream.fromReadableStream(stream);
   }
@@ -1284,7 +1241,11 @@ export class StoreClient extends BaseClient {
   }
 }
 
-export class Client {
+export class Client<
+  TStateType = DefaultValues,
+  TUpdateType = TStateType,
+  TCustomEventType = unknown,
+> {
   /**
    * The client for interacting with assistants.
    */
@@ -1293,12 +1254,12 @@ export class Client {
   /**
    * The client for interacting with threads.
    */
-  public threads: ThreadsClient;
+  public threads: ThreadsClient<TStateType, TUpdateType>;
 
   /**
    * The client for interacting with runs.
    */
-  public runs: RunsClient;
+  public runs: RunsClient<TStateType, TUpdateType, TCustomEventType>;
 
   /**
    * The client for interacting with cron runs.

libs/sdk-js/src/index.ts

@@ -16,7 +16,35 @@ export type {
   Cron,
   Checkpoint,
   Interrupt,
+  ListNamespaceResponse,
+  Item,
+  SearchItem,
+  SearchItemsResponse,
+  CronCreateResponse,
+  CronCreateForThreadResponse,
 } from "./schema.js";
 export { overrideFetchImplementation } from "./singletons/fetch.js";
 
 export type { OnConflictBehavior, Command } from "./types.js";
+export type { StreamMode } from "./types.stream.js";
+export type {
+  ValuesStreamEvent,
+  MessagesTupleStreamEvent,
+  MetadataStreamEvent,
+  UpdatesStreamEvent,
+  CustomStreamEvent,
+  MessagesStreamEvent,
+  DebugStreamEvent,
+  EventsStreamEvent,
+  ErrorStreamEvent,
+  FeedbackStreamEvent,
+} from "./types.stream.js";
+export type {
+  Message,
+  HumanMessage,
+  AIMessage,
+  ToolMessage,
+  SystemMessage,
+  FunctionMessage,
+  RemoveMessage,
+} from "./types.messages.js";

libs/sdk-js/src/react/debug.tsx

@@ -0,0 +1,102 @@
+import { ThreadState } from "../schema.js";
+
+interface Node<StateType = any> {
+  type: "node";
+  value: ThreadState<StateType>;
+  path: string[];
+}
+
+interface Fork<StateType = any> {
+  type: "fork";
+  items: Array<Sequence<StateType>>;
+}
+
+interface Sequence<StateType = any> {
+  type: "sequence";
+  items: Array<Node<StateType> | Fork<StateType>>;
+}
+
+interface ValidFork<StateType = any> {
+  type: "fork";
+  items: Array<ValidSequence<StateType>>;
+}
+
+interface ValidSequence<StateType = any> {
+  type: "sequence";
+  items: [Node<StateType>, ...(Node<StateType> | ValidFork<StateType>)[]];
+}
+
+// forks
+export type CheckpointBranchPath = string[];
+
+export type MessageBranch = {
+  current: CheckpointBranchPath;
+  options: CheckpointBranchPath[];
+};
+
+export function DebugSegmentsView(props: {
+  sequence: ValidSequence<ThreadState>;
+}) {
+  const concatContent = (value: ThreadState<any>) => {
+    let content;
+    try {
+      content = value.values?.messages?.at(-1)?.content ?? "";
+    } catch {
+      content = JSON.stringify(value.values);
+    }
+
+    content = content.replace(/(\n|\r\n)/g, "");
+    if (content.length <= 23) return content;
+    return `${content.slice(0, 10)}...${content.slice(-10)}`;
+  };
+
+  return (
+    <div>
+      {props.sequence.items.map((item, index) => {
+        if (item.type === "fork") {
+          return (
+            <div key={index}>
+              {item.items.map((fork, idx) => {
+                const [first] = fork.items;
+                return (
+                  <details key={idx}>
+                    <summary>
+                      Fork{" "}
+                      <span className="font-mono">
+                        ...{first.path.at(-1)?.slice(-4)}
+                      </span>
+                    </summary>
+                    <div className="ml-4">
+                      <DebugSegmentsView sequence={fork} />
+                    </div>
+                  </details>
+                );
+              })}
+            </div>
+          );
+        }
+
+        if (item.type === "node") {
+          return (
+            <div key={index} className="flex items-center gap-2">
+              <pre>
+                ({item.value.metadata?.step}) ...
+                {item.value.checkpoint.checkpoint_id?.slice(-4)} (
+                {item.value.metadata?.source}): {concatContent(item.value)}
+              </pre>
+              <button
+                type="button"
+                className="border rounded-sm text-sm py-0.5 px-1 text-muted-foreground"
+                onClick={() => console.log(item.path, item.value)}
+              >
+                console.log
+              </button>
+            </div>
+          );
+        }
+
+        return null;
+      })}
+    </div>
+  );
+}

libs/sdk-js/src/react/index.ts

@@ -0,0 +1 @@
+export { useStream, type MessageMetadata } from "./stream.js";

libs/sdk-js/src/react/stream.tsx

@@ -0,0 +1,815 @@
+/* __LC_ALLOW_ENTRYPOINT_SIDE_EFFECTS__ */
+"use client";
+
+import { Client, type ClientConfig } from "../client.js";
+import type {
+  Command,
+  DisconnectMode,
+  MultitaskStrategy,
+  OnCompletionBehavior,
+} from "../types.js";
+import type { Message } from "../types.messages.js";
+import type { Checkpoint, Config, Metadata, ThreadState } from "../schema.js";
+import type {
+  CustomStreamEvent,
+  DebugStreamEvent,
+  ErrorStreamEvent,
+  EventsStreamEvent,
+  FeedbackStreamEvent,
+  MessagesStreamEvent,
+  MessagesTupleStreamEvent,
+  MetadataStreamEvent,
+  StreamMode,
+  UpdatesStreamEvent,
+  ValuesStreamEvent,
+} from "../types.stream.js";
+
+import {
+  type MutableRefObject,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import {
+  type BaseMessageChunk,
+  type BaseMessage,
+  coerceMessageLikeToMessage,
+  convertToChunk,
+} from "@langchain/core/messages";
+
+class StreamError extends Error {
+  constructor(data: { error?: string; name?: string; message: string }) {
+    super(data.message);
+    this.name = data.name ?? data.error ?? "StreamError";
+  }
+
+  static isStructuredError(error: unknown): error is {
+    error?: string;
+    name?: string;
+    message: string;
+  } {
+    return typeof error === "object" && error != null && "message" in error;
+  }
+}
+
+class MessageTupleManager {
+  chunks: Record<string, { chunk?: BaseMessageChunk; index?: number }> = {};
+
+  constructor() {
+    this.chunks = {};
+  }
+
+  add(serialized: Message): string | null {
+    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: string, defaultIndex: number) {
+    if (this.chunks[id] == null) return null;
+    this.chunks[id].index ??= defaultIndex;
+
+    return this.chunks[id];
+  }
+}
+
+const toMessageDict = (chunk: BaseMessage): Message => {
+  const { type, data } = chunk.toDict();
+  return { ...data, type } as Message;
+};
+
+function unique<T>(array: T[]) {
+  return [...new Set(array)] as T[];
+}
+
+function findLastIndex<T>(array: T[], predicate: (item: T) => boolean) {
+  for (let i = array.length - 1; i >= 0; i--) {
+    if (predicate(array[i])) return i;
+  }
+  return -1;
+}
+
+interface Node<StateType = any> {
+  type: "node";
+  value: ThreadState<StateType>;
+  path: string[];
+}
+
+interface Fork<StateType = any> {
+  type: "fork";
+  items: Array<Sequence<StateType>>;
+}
+
+interface Sequence<StateType = any> {
+  type: "sequence";
+  items: Array<Node<StateType> | Fork<StateType>>;
+}
+
+interface ValidFork<StateType = any> {
+  type: "fork";
+  items: Array<ValidSequence<StateType>>;
+}
+
+interface ValidSequence<StateType = any> {
+  type: "sequence";
+  items: [Node<StateType>, ...(Node<StateType> | ValidFork<StateType>)[]];
+}
+
+export type MessageMetadata<StateType extends Record<string, unknown>> = {
+  /**
+   * The ID of the message used.
+   */
+  messageId: string;
+
+  /**
+   * The first thread state the message was seen in.
+   */
+  firstSeenState: ThreadState<StateType> | undefined;
+
+  /**
+   * The branch of the message.
+   */
+  branch: string | undefined;
+
+  /**
+   * The list of branches this message is part of.
+   * This is useful for displaying branching controls.
+   */
+  branchOptions: string[] | undefined;
+};
+
+function getBranchSequence<StateType extends Record<string, unknown>>(
+  history: ThreadState<StateType>[],
+) {
+  const childrenMap: Record<string, ThreadState<StateType>[]> = {};
+
+  // First pass - collect nodes for each checkpoint
+  history.forEach((state) => {
+    const checkpointId = state.parent_checkpoint?.checkpoint_id ?? "$";
+    childrenMap[checkpointId] ??= [];
+    childrenMap[checkpointId].push(state);
+  });
+
+  // Second pass - create a tree of sequences
+  type Task = { id: string; sequence: Sequence; path: string[] };
+  const rootSequence: Sequence = { type: "sequence", items: [] };
+  const queue: Task[] = [{ id: "$", sequence: rootSequence, path: [] }];
+
+  const paths: string[][] = [];
+
+  const visited = new Set<string>();
+  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: Fork | undefined;
+    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 });
+    }
+  }
+
+  return { rootSequence, paths };
+}
+
+const PATH_SEP = ">";
+const ROOT_ID = "$";
+
+// Get flat view
+function getBranchView<StateType extends Record<string, unknown>>(
+  sequence: Sequence<StateType>,
+  paths: string[][],
+  branch: string,
+) {
+  const path = branch.split(PATH_SEP);
+  const pathMap: Record<string, string[][]> = {};
+
+  for (const path of paths) {
+    const parent = path.at(-2) ?? ROOT_ID;
+    pathMap[parent] ??= [];
+    pathMap[parent].unshift(path);
+  }
+
+  const history: ThreadState<StateType>[] = [];
+  const branchByCheckpoint: Record<
+    string,
+    { branch: string | undefined; branchOptions: string[] | undefined }
+  > = {};
+
+  const forkStack = path.slice();
+  const queue: (Node<StateType> | Fork<StateType>)[] = [...sequence.items];
+
+  while (queue.length > 0) {
+    const item = queue.shift()!;
+
+    if (item.type === "node") {
+      history.push(item.value);
+      branchByCheckpoint[item.value.checkpoint.checkpoint_id!] = {
+        branch: item.path.join(PATH_SEP),
+        branchOptions: (item.path.length > 0
+          ? pathMap[item.path.at(-2) ?? ROOT_ID] ?? []
+          : []
+        ).map((p) => p.join(PATH_SEP)),
+      };
+    }
+    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 { history, branchByCheckpoint };
+}
+
+function fetchHistory<StateType extends Record<string, unknown>>(
+  client: Client,
+  threadId: string,
+) {
+  return client.threads.getHistory<StateType>(threadId, { limit: 1000 });
+}
+
+function useThreadHistory<StateType extends Record<string, unknown>>(
+  threadId: string | undefined | null,
+  client: Client,
+  clearCallbackRef: MutableRefObject<(() => void) | undefined>,
+  submittingRef: MutableRefObject<boolean>,
+) {
+  const [history, setHistory] = useState<ThreadState<StateType>[]>([]);
+
+  const fetcher = useCallback(
+    (
+      threadId: string | undefined | null,
+    ): Promise<ThreadState<StateType>[]> => {
+      if (threadId != null) {
+        return fetchHistory<StateType>(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?: string) => fetcher(mutateId ?? threadId),
+  };
+}
+
+const useControllableThreadId = (options?: {
+  threadId?: string | null;
+  onThreadId?: (threadId: string) => void;
+}): [string | null, (threadId: string) => void] => {
+  const [localThreadId, _setLocalThreadId] = useState<string | null>(
+    options?.threadId ?? null,
+  );
+
+  const onThreadIdRef = useRef(options?.onThreadId);
+  onThreadIdRef.current = options?.onThreadId;
+
+  const onThreadId = useCallback((threadId: string) => {
+    _setLocalThreadId(threadId);
+    onThreadIdRef.current?.(threadId);
+  }, []);
+
+  if (typeof options?.threadId === "undefined") {
+    return [localThreadId, onThreadId];
+  }
+
+  return [options.threadId, onThreadId];
+};
+
+interface UseStreamOptions<
+  StateType extends Record<string, unknown> = Record<string, unknown>,
+  UpdateType extends Record<string, unknown> = Partial<StateType>,
+  CustomType = unknown,
+> {
+  /**
+   * The ID of the assistant to use.
+   */
+  assistantId: string;
+
+  /**
+   * The URL of the API to use.
+   */
+  apiUrl: ClientConfig["apiUrl"];
+
+  /**
+   * The API key to use.
+   */
+  apiKey?: ClientConfig["apiKey"];
+
+  /**
+   * Specify the key within the state that contains messages.
+   * Defaults to "messages".
+   *
+   * @default "messages"
+   */
+  messagesKey?: string;
+
+  /**
+   * Callback that is called when an error occurs.
+   */
+  onError?: (error: unknown) => void;
+
+  /**
+   * Callback that is called when the stream is finished.
+   */
+  onFinish?: (state: ThreadState<StateType>) => void;
+
+  /**
+   * Callback that is called when an update event is received.
+   */
+  onUpdateEvent?: (data: UpdatesStreamEvent<UpdateType>["data"]) => void;
+
+  /**
+   * Callback that is called when a custom event is received.
+   */
+  onCustomEvent?: (data: CustomStreamEvent<CustomType>["data"]) => void;
+
+  /**
+   * Callback that is called when a metadata event is received.
+   */
+  onMetadataEvent?: (data: MetadataStreamEvent["data"]) => void;
+
+  /**
+   * The ID of the thread to fetch history and current values from.
+   */
+  threadId?: string | null;
+
+  /**
+   * Callback that is called when the thread ID is updated (ie when a new thread is created).
+   */
+  onThreadId?: (threadId: string) => void;
+}
+
+interface UseStream<
+  StateType extends Record<string, unknown> = Record<string, unknown>,
+  UpdateType extends Record<string, unknown> = Partial<StateType>,
+> {
+  /**
+   * The current values of the thread.
+   */
+  values: StateType;
+
+  /**
+   * Last seen error from the thread or during streaming.
+   */
+  error: unknown;
+
+  /**
+   * Whether the stream is currently running.
+   */
+  isLoading: boolean;
+
+  /**
+   * Stops the stream.
+   */
+  stop: () => void;
+
+  /**
+   * Create and stream a run to the thread.
+   */
+  submit: (values: UpdateType, options?: SubmitOptions<StateType>) => void;
+
+  /**
+   * The current branch of the thread.
+   */
+  branch: string;
+
+  /**
+   * Set the branch of the thread.
+   */
+  setBranch: (branch: string) => void;
+
+  /**
+   * Flattened history of thread states of a thread.
+   */
+  history: ThreadState<StateType>[];
+
+  /**
+   * Tree of all branches for the thread.
+   * @experimental
+   */
+  experimental_branchTree: Sequence<StateType>;
+
+  /**
+   * Messages inferred from the thread.
+   * Will automatically update with incoming message chunks.
+   */
+  messages: Message[];
+
+  /**
+   * Get the metadata for a message, such as first thread state the message
+   * was seen in and branch information.
+   
+   * @param message - The message to get the metadata for.
+   * @param index - The index of the message in the thread.
+   * @returns The metadata for the message.
+   */
+  getMessagesMetadata: (
+    message: Message,
+    index?: number,
+  ) => MessageMetadata<StateType> | undefined;
+}
+
+interface SubmitOptions<
+  StateType extends Record<string, unknown> = Record<string, unknown>,
+> {
+  config?: Config;
+  checkpoint?: Omit<Checkpoint, "thread_id"> | null;
+  command?: Command;
+  interruptBefore?: "*" | string[];
+  interruptAfter?: "*" | string[];
+  metadata?: Metadata;
+  multitaskStrategy?: MultitaskStrategy;
+  onCompletion?: OnCompletionBehavior;
+  onDisconnect?: DisconnectMode;
+  feedbackKeys?: string[];
+  streamMode?: Array<StreamMode>;
+  optimisticValues?:
+    | Partial<StateType>
+    | ((prev: StateType) => Partial<StateType>);
+}
+
+export function useStream<
+  StateType extends Record<string, unknown> = Record<string, unknown>,
+  UpdateType extends Record<string, unknown> = Partial<StateType>,
+  CustomType = unknown,
+>(
+  options: UseStreamOptions<StateType, UpdateType, CustomType>,
+): UseStream<StateType, UpdateType> {
+  type EventStreamEvent =
+    | ValuesStreamEvent<StateType>
+    | UpdatesStreamEvent<UpdateType>
+    | CustomStreamEvent<CustomType>
+    | DebugStreamEvent
+    | MessagesStreamEvent
+    | MessagesTupleStreamEvent
+    | EventsStreamEvent
+    | MetadataStreamEvent
+    | ErrorStreamEvent
+    | FeedbackStreamEvent;
+
+  let { assistantId, messagesKey, onError, onFinish } = options;
+  messagesKey ??= "messages";
+
+  const client = useMemo(
+    () => new Client({ apiUrl: options.apiUrl, apiKey: options.apiKey }),
+    [options.apiKey, options.apiUrl],
+  );
+  const [threadId, onThreadId] = useControllableThreadId(options);
+
+  const [branch, setBranch] = useState<string>("");
+  const [isLoading, setIsLoading] = useState(false);
+
+  const [streamError, setStreamError] = useState<unknown>(undefined);
+  const [streamValues, setStreamValues] = useState<StateType | null>(null);
+
+  const messageManagerRef = useRef(new MessageTupleManager());
+  const submittingRef = useRef(false);
+  const abortRef = useRef<AbortController | null>(null);
+
+  const trackStreamModeRef = useRef<
+    Array<"values" | "updates" | "events" | "custom" | "messages-tuple">
+  >(["values", "messages-tuple"]);
+
+  const trackStreamMode = useCallback(
+    (mode: Exclude<StreamMode, "debug" | "messages">) => {
+      if (!trackStreamModeRef.current.includes(mode))
+        trackStreamModeRef.current.push(mode);
+    },
+    [],
+  );
+
+  const hasUpdateListener = options.onUpdateEvent != null;
+  const hasCustomListener = options.onCustomEvent != null;
+
+  const callbackStreamMode = useMemo(() => {
+    const modes: Exclude<StreamMode, "debug" | "messages">[] = [];
+    if (hasUpdateListener) modes.push("updates");
+    if (hasCustomListener) modes.push("custom");
+    return modes;
+  }, [hasUpdateListener, hasCustomListener]);
+
+  const clearCallbackRef = useRef<() => void>(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<StateType>(
+    threadId,
+    client,
+    clearCallbackRef,
+    submittingRef,
+  );
+
+  const getMessages = useMemo(() => {
+    return (value: StateType) =>
+      Array.isArray(value[messagesKey])
+        ? (value[messagesKey] as Message[])
+        : [];
+  }, [messagesKey]);
+
+  const { rootSequence, paths } = getBranchSequence(history.data);
+  const { history: flatHistory, branchByCheckpoint } = getBranchView(
+    rootSequence,
+    paths,
+    branch,
+  );
+
+  const threadHead: ThreadState<StateType> | undefined = flatHistory.at(-1);
+  const historyValues = threadHead?.values ?? ({} as StateType);
+  const historyError = (() => {
+    const error = threadHead?.tasks?.at(-1)?.error;
+    if (error == null) return undefined;
+    try {
+      const parsed = JSON.parse(error) as unknown;
+      if (StreamError.isStructuredError(parsed)) {
+        return new StreamError(parsed);
+      }
+
+      return parsed;
+    } catch {
+      // do nothing
+    }
+    return error;
+  })();
+
+  const messageMetadata = (() => {
+    const alreadyShown = new Set<string>();
+    return getMessages(historyValues).map(
+      (message, idx): MessageMetadata<StateType> => {
+        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] as
+          | ThreadState<StateType>
+          | undefined;
+
+        let branch = firstSeen
+          ? branchByCheckpoint[firstSeen.checkpoint.checkpoint_id!]
+          : undefined;
+
+        if (!branch?.branch?.length) branch = undefined;
+
+        // serialize branches
+        const optionsShown = branch?.branchOptions?.flat(2).join(",");
+        if (optionsShown) {
+          if (alreadyShown.has(optionsShown)) branch = undefined;
+          alreadyShown.add(optionsShown);
+        }
+
+        return {
+          messageId: messageId.toString(),
+          firstSeenState: firstSeen,
+
+          branch: branch?.branch,
+          branchOptions: branch?.branchOptions,
+        };
+      },
+    );
+  })();
+
+  const stop = useCallback(() => {
+    if (abortRef.current != null) abortRef.current.abort();
+    abortRef.current = null;
+  }, []);
+
+  const submit = async (
+    values: UpdateType | undefined,
+    submitOptions?: SubmitOptions<StateType>,
+  ) => {
+    try {
+      setIsLoading(true);
+      setStreamError(undefined);
+
+      submittingRef.current = true;
+      abortRef.current = new AbortController();
+
+      let usableThreadId = threadId;
+      if (!usableThreadId) {
+        const thread = await client.threads.create();
+        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 as Record<string, unknown>,
+        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,
+      })) as AsyncGenerator<EventStreamEvent>;
+
+      // Unbranch things
+      const newPath = submitOptions?.checkpoint?.checkpoint_id
+        ? branchByCheckpoint[submitOptions?.checkpoint?.checkpoint_id]?.branch
+        : undefined;
+
+      if (newPath != null) setBranch(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: StreamError | undefined;
+      for await (const { event, data } of run) {
+        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") {
+          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, [messagesKey!]: messages };
+          });
+        }
+      }
+
+      // TODO: stream created checkpoints to avoid an unnecessary network request
+      const result = await history.mutate(usableThreadId);
+      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;
+
+  return {
+    get values() {
+      trackStreamMode("values");
+      return values;
+    },
+
+    error,
+    isLoading,
+
+    stop,
+    submit,
+
+    branch,
+    setBranch,
+
+    history: flatHistory,
+    experimental_branchTree: rootSequence,
+
+    get messages() {
+      trackStreamMode("messages-tuple");
+      return getMessages(values);
+    },
+
+    getMessagesMetadata(
+      message: Message,
+      index?: number,
+    ): MessageMetadata<StateType> | undefined {
+      trackStreamMode("messages-tuple");
+      return messageMetadata?.find(
+        (m) => m.messageId === (message.id ?? index),
+      );
+    },
+  };
+}

libs/sdk-js/src/schema.ts

@@ -16,7 +16,7 @@ type MultitaskStrategy = "reject" | "interrupt" | "rollback" | "enqueue";
 
 export type CancelAction = "interrupt" | "rollback";
 
-export interface Config {
+export type Config = {
   /**
    * Tags for this call and any sub-calls (eg. a Chain calling an LLM).
    * You can use these to filter calls.
@@ -32,19 +32,20 @@ export interface Config {
   /**
    * Runtime values for attributes previously made configurable on this Runnable.
    */
-  configurable: {
+  configurable?: {
     /**
      * ID of the thread
      */
-    thread_id?: string;
+    thread_id?: Optional<string>;
 
     /**
      * Timestamp of the state checkpoint
      */
-    checkpoint_id?: string;
+    checkpoint_id?: Optional<string>;
+
     [key: string]: unknown;
   };
-}
+};
 
 export interface GraphSchema {
   /**
@@ -254,12 +255,12 @@ export interface Run {
   multitask_strategy: Optional<MultitaskStrategy>;
 }
 
-export interface Checkpoint {
+export type Checkpoint = {
   thread_id: string;
   checkpoint_ns: string;
   checkpoint_id: Optional<string>;
   checkpoint_map: Optional<Record<string, unknown>>;
-}
+};
 
 export interface ListNamespaceResponse {
   namespaces: string[][];

libs/sdk-js/src/tests/sse.test.ts

@@ -0,0 +1,182 @@
+import { Readable } from "node:stream";
+import { IterableReadableStream } from "../utils/stream.js";
+import { BytesLineDecoder, SSEDecoder } from "../utils/sse.js";
+
+const gather = async <T>(stream: ReadableStream<T>): Promise<T[]> => {
+  const results: T[] = [];
+  const iterator = IterableReadableStream.fromReadableStream(stream);
+  for await (const chunk of iterator) results.push(chunk);
+  return results;
+};
+
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+describe("BytesLineDecoder", () => {
+  const createStream = (chunks: Uint8Array[]) => {
+    return Readable.toWeb(Readable.from(chunks)) as ReadableStream<Uint8Array>;
+  };
+
+  test("handles single line with newline", async () => {
+    const input = createStream([textEncoder.encode("hello\n")]);
+    const decoded = input.pipeThrough(new BytesLineDecoder());
+    const results = await gather(decoded);
+
+    expect(results.length).toBe(1);
+    expect(textDecoder.decode(results[0])).toBe("hello");
+  });
+
+  test("handles multiple lines", async () => {
+    const input = createStream([textEncoder.encode("line1\nline2\nline3\n")]);
+    const decoded = input.pipeThrough(new BytesLineDecoder());
+    const results = await gather(decoded);
+
+    expect(results.length).toBe(3);
+    expect(textDecoder.decode(results[0])).toBe("line1");
+    expect(textDecoder.decode(results[1])).toBe("line2");
+    expect(textDecoder.decode(results[2])).toBe("line3");
+  });
+
+  test("handles split chunks", async () => {
+    const input = createStream([
+      textEncoder.encode("li"),
+      textEncoder.encode("ne1\nli"),
+      textEncoder.encode("ne2\n"),
+    ]);
+    const decoded = input.pipeThrough(new BytesLineDecoder());
+    const results = await gather(decoded);
+
+    expect(results.length).toBe(2);
+    expect(textDecoder.decode(results[0])).toBe("line1");
+    expect(textDecoder.decode(results[1])).toBe("line2");
+  });
+
+  test("handles CR LF line endings", async () => {
+    const input = createStream([textEncoder.encode("line1\r\nline2\r\n")]);
+    const decoded = input.pipeThrough(new BytesLineDecoder());
+    const results = await gather(decoded);
+
+    expect(results.length).toBe(2);
+    expect(textDecoder.decode(results[0])).toBe("line1");
+    expect(textDecoder.decode(results[1])).toBe("line2");
+  });
+
+  test("handles split CR LF", async () => {
+    const input = createStream([
+      textEncoder.encode("line1\r"),
+      textEncoder.encode("\nline2\r\n"),
+    ]);
+    const decoded = input.pipeThrough(new BytesLineDecoder());
+    const results = await gather(decoded);
+
+    expect(results.length).toBe(2);
+    expect(textDecoder.decode(results[0])).toBe("line1");
+    expect(textDecoder.decode(results[1])).toBe("line2");
+  });
+
+  test("handles stale line", async () => {
+    const input = createStream([textEncoder.encode("hello")]);
+    const decoded = input.pipeThrough(new BytesLineDecoder());
+    const results = await gather(decoded);
+
+    expect(results.length).toBe(1);
+    expect(textDecoder.decode(results[0])).toBe("hello");
+  });
+});
+
+describe("SSEDecoder", () => {
+  const createStream = (lines: string[]) => {
+    return Readable.toWeb(
+      Readable.from(lines.map((line) => textEncoder.encode(line))),
+    ) as ReadableStream<Uint8Array>;
+  };
+
+  test("decodes simple event", async () => {
+    const input = createStream([
+      "event: test\n",
+      'data: {"message": "hello"}\n',
+      "\n",
+    ]);
+    const decoded = input
+      .pipeThrough(new BytesLineDecoder())
+      .pipeThrough(new SSEDecoder());
+
+    const results = await gather(decoded);
+    expect(results.length).toBe(1);
+    expect(results[0]).toEqual({
+      event: "test",
+      data: { message: "hello" },
+    });
+  });
+
+  test("ignores comments", async () => {
+    const input = createStream([
+      ": this is a comment\n",
+      "event: test\n",
+      'data: {"message": "hello"}\n',
+    ]);
+    const decoded = input
+      .pipeThrough(new BytesLineDecoder())
+      .pipeThrough(new SSEDecoder());
+
+    const results = await gather(decoded);
+    expect(results.length).toBe(1);
+    expect(results[0]).toEqual({
+      event: "test",
+      data: { message: "hello" },
+    });
+  });
+
+  test("handles multiple events", async () => {
+    const input = createStream([
+      "event: test1\n",
+      'data: {"message": "hello"}\n',
+      "\n",
+      "event: test2\n",
+      'data: {"message": "world"}\n',
+      "\n",
+    ]);
+    const decoded = input
+      .pipeThrough(new BytesLineDecoder())
+      .pipeThrough(new SSEDecoder());
+
+    const results = await gather(decoded);
+    expect(results.length).toBe(2);
+    expect(results[0]).toEqual({
+      event: "test1",
+      data: { message: "hello" },
+    });
+    expect(results[1]).toEqual({
+      event: "test2",
+      data: { message: "world" },
+    });
+  });
+
+  test("end event without data", async () => {
+    const input = createStream(["event: test\n"]);
+    const decoded = input
+      .pipeThrough(new BytesLineDecoder())
+      .pipeThrough(new SSEDecoder());
+
+    const results = await gather(decoded);
+    expect(results.length).toBe(1);
+    expect(results[0]).toEqual({
+      event: "test",
+      data: null,
+    });
+  });
+
+  test("end event without newline", async () => {
+    const input = createStream(["event: end"]);
+    const decoded = input
+      .pipeThrough(new BytesLineDecoder())
+      .pipeThrough(new SSEDecoder());
+
+    const results = await gather(decoded);
+    expect(results.length).toBe(1);
+    expect(results[0]).toEqual({
+      event: "end",
+      data: null,
+    });
+  });
+});

libs/sdk-js/src/types.messages.ts

@@ -0,0 +1,99 @@
+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;