[cli] Bump api floor (#3523)

fixed a typo:
We will use this an edge in the graph
to 
We will use this as an edge in the graph

.github/workflows/ci.yml

@@ -20,7 +20,30 @@ env:
   POETRY_VERSION: "1.7.1"
 
 jobs:
+  changes:
+    runs-on: ubuntu-latest
+    outputs:
+      python: ${{ steps.filter.outputs.python }}
+      sdk-js: ${{ steps.filter.outputs.sdk-js }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            python:
+              - 'libs/langgraph/**'
+              - 'libs/sdk-py/**'
+              - 'libs/cli/**'
+              - 'libs/checkpoint/**'
+              - 'libs/checkpoint-sqlite/**'
+              - 'libs/checkpoint-postgres/**'
+              - 'libs/scheduler-kafka/**'
+            sdk-js:
+              - 'libs/sdk-js/**'
+
   lint:
+    needs: changes
     name: cd ${{ matrix.working-directory }}
     strategy:
       matrix:
@@ -34,12 +57,14 @@ jobs:
             "libs/checkpoint-postgres",
             "libs/scheduler-kafka",
           ]
+    if: needs.changes.outputs.python == 'true'
     uses: ./.github/workflows/_lint.yml
     with:
       working-directory: ${{ matrix.working-directory }}
     secrets: inherit
 
   test:
+    needs: changes
     name: cd ${{ matrix.working-directory }}
     strategy:
       matrix:
@@ -50,6 +75,7 @@ jobs:
             "libs/checkpoint-sqlite",
             "libs/checkpoint-postgres",
           ]
+    if: needs.changes.outputs.python == 'true'
     uses: ./.github/workflows/_test.yml
     with:
       working-directory: ${{ matrix.working-directory }}
@@ -57,17 +83,23 @@ jobs:
 
   # NOTE: we're testing langgraph separately because it requires a different matrix
   test-langgraph:
+    needs: changes
+    if: needs.changes.outputs.python == 'true'
     name: "cd libs/langgraph"
     uses: ./.github/workflows/_test_langgraph.yml
     secrets: inherit
 
   # NOTE: we're testing scheduler-kafka separately because it requires a different matrix
   test-scheduler-kafka:
+    needs: changes
+    if: needs.changes.outputs.python == 'true'
     name: "cd libs/scheduler-kafka"
     uses: ./.github/workflows/_test_scheduler_kafka.yml
     secrets: inherit
 
   check-sdk-methods:
+    needs: changes
+    if: needs.changes.outputs.python == 'true'
     name: "Check SDK methods matching"
     runs-on: ubuntu-latest
     steps:
@@ -80,11 +112,15 @@ jobs:
         run: python .github/scripts/check_sdk_methods.py
 
   integration-test:
+    needs: changes
+    if: needs.changes.outputs.python == 'true'
     name: CLI integration test
     uses: ./.github/workflows/_integration_test.yml
     secrets: inherit
 
   lint-js:
+    needs: changes
+    if: needs.changes.outputs.sdk-js == 'true'
     runs-on: ubuntu-latest
     strategy:
       matrix:
@@ -109,6 +145,8 @@ jobs:
         run: yarn build
 
   test-js:
+    needs: changes
+    if: needs.changes.outputs.sdk-js == 'true'
     runs-on: ubuntu-latest
     strategy:
       matrix:

.github/workflows/deploy_docs.yml

@@ -78,15 +78,23 @@ jobs:
             pytest \
             pytest-check-links \
             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.

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 build-prebuilt
+.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
@@ -17,7 +17,7 @@ build-docs: build-typedoc build-prebuilt
 	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
@@ -26,11 +26,10 @@ install-vercel-deps:
 	# 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

docs/_scripts/assets/nock_setup_preamble.ts

@@ -1,75 +0,0 @@
-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;
-}
-
-// deno-lint-ignore no-unused-vars
-class HashedCassette {
-  private recording = true;
-
-  constructor(
-    private readonly cassettePath: string,
-    private readonly hash: string
-  ) {}
-
-  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

@@ -1,107 +0,0 @@
-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 as e:
-                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 as e:
-                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,9 +1,9 @@
+import ast
 import importlib
-import inspect
 import logging
 import re
 from functools import lru_cache
-from typing import List, Literal, Optional
+from typing import List, Optional
 
 from typing_extensions import TypedDict
 
@@ -39,7 +39,6 @@ MANUAL_API_REFERENCES_LANGGRAPH = [
     (["langgraph.graph"], "langgraph.graph.message", "add_messages", "graphs"),
     (["langgraph.graph"], "langgraph.graph.state", "StateGraph", "graphs"),
     (["langgraph.graph"], "langgraph.graph.state", "CompiledStateGraph", "graphs"),
-    ([], "langgraph.types", "StreamMode", "types"),
     (["langgraph.graph"], "langgraph.constants", "START", "constants"),
     (["langgraph.graph"], "langgraph.constants", "END", "constants"),
     (["langgraph.constants"], "langgraph.types", "Send", "types"),
@@ -48,7 +47,9 @@ MANUAL_API_REFERENCES_LANGGRAPH = [
     (["langgraph.constants"], "langgraph.types", "Command", "types"),
     (["langgraph.func"], "langgraph.func", "entrypoint", "func"),
     (["langgraph.func"], "langgraph.func", "task", "func"),
-    ([], "langgraph.types", "RetryPolicy", "types"),
+    (["langgraph.types"], "langgraph.types", "RetryPolicy", "types"),
+    (["langgraph.types"], "langgraph.types", "StreamMode", "types"),
+    (["langgraph.types"], "langgraph.types", "StreamWriter", "types"),
     ([], "langgraph.checkpoint.base", "Checkpoint", "checkpoints"),
     ([], "langgraph.checkpoint.base", "CheckpointMetadata", "checkpoints"),
     ([], "langgraph.checkpoint.base", "BaseCheckpointSaver", "checkpoints"),
@@ -68,34 +69,19 @@ WELL_KNOWN_LANGGRAPH_OBJECTS = {
 }
 
 
-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
-        re.DOTALL,  # Match newlines as well
-    )
-
-
-# Regular expression to match langchain import lines
-_IMPORT_LANGCHAIN_RE = _make_regular_expression("langchain")
-_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]:
     """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
+        symbol = getattr(module, class_name)
+        # First check the __module__ attribute on the symbol.
+        mod_name = getattr(symbol, "__module__", None)
+        # If __module__ is not set or comes from typing,
+        # assume the definition is in module_path.
+        if mod_name is None or mod_name.startswith("typing"):
             return module_path
-        return module.__name__
+        return mod_name
     except AttributeError as e:
         logger.warning(f"API Reference: Could not find module for {class_name}, {e}")
         return None
@@ -104,139 +90,128 @@ def _get_full_module_name(module_path: str, class_name: str) -> Optional[str]:
         return None
 
 
-def _get_doc_title(data: str, file_name: str) -> str:
-    try:
-        return re.findall(r"^#\s*(.*)", data, re.MULTILINE)[0]
-    except IndexError:
-        pass
-    # Parse the rst-style titles
-    try:
-        return re.findall(r"^(.*)\n=+\n", data, re.MULTILINE)[0]
-    except IndexError:
-        return file_name
-
-
 class ImportInformation(TypedDict):
     imported: str  # The name of the class that was imported.
     source: str  # The full module path from which the class was imported.
     docs: str  # The URL pointing to the class's documentation.
-    title: str  # The title of the document where the import is used.
+    path: str  # The path of the file where the markdown content originated.
 
 
-def _get_imports(
-    code: str, doc_title: str, package_ecosystem: Literal["langchain", "langgraph"]
-) -> List[ImportInformation]:
-    """Get imports from the given code block.
-
-    Args:
-        code: Python code block from which to extract imports
-        doc_title: Title of the document
-        package_ecosystem: "langchain" or "langgraph". The two live in different
-            repositories and have separate documentation sites.
-
-    Returns:
-        List of import information for the given code block
-    """
-    imports = []
-
-    if package_ecosystem == "langchain":
-        pattern = _IMPORT_LANGCHAIN_RE
-    elif package_ecosystem == "langgraph":
-        pattern = _IMPORT_LANGGRAPH_RE
-    else:
-        raise ValueError(f"Invalid package ecosystem: {package_ecosystem}")
-
-    for import_match in pattern.finditer(code):
-        module = import_match.group(1)
-        if "pydantic_v1" in module:
-            continue
-        imports_str = (
-            import_match.group(2).replace("(\n", "").replace("\n)", "")
-        )  # Handle newlines within parentheses
-        # remove any newline and spaces, then split by comma
-        imported_classes = [
-            imp.strip()
-            for imp in re.split(r",\s*", imports_str.replace("\n", ""))
-            if imp.strip()
-        ]
-        for class_name in imported_classes:
-            module_path = _get_full_module_name(module, class_name)
-            if not module_path:
-                continue
-            if len(module_path.split(".")) < 2:
-                continue
-
-            if package_ecosystem == "langchain":
-                pkg = module_path.split(".")[0].replace("langchain_", "")
-                top_level_mod = module_path.split(".")[1]
-
-                url = (
-                    _LANGCHAIN_API_REFERENCE
-                    + pkg
-                    + "/"
-                    + top_level_mod
-                    + "/"
-                    + module_path
-                    + "."
-                    + class_name
-                    + ".html"
-                )
-            elif package_ecosystem == "langgraph":
-                if (module, class_name) not in WELL_KNOWN_LANGGRAPH_OBJECTS:
-                    # Likely not documented yet
-                    continue
-
-                source_module, namespace = WELL_KNOWN_LANGGRAPH_OBJECTS[
-                    (module, class_name)
-                ]
-                url = (
-                    _LANGGRAPH_API_REFERENCE
-                    + namespace
-                    + "/#"
-                    + source_module
-                    + "."
-                    + class_name
-                )
-            else:
-                raise ValueError(f"Invalid package ecosystem: {package_ecosystem}")
-
-            # Add the import information to our list
-            imports.append(
-                {
-                    "imported": class_name,
-                    "source": module,
-                    "docs": url,
-                    "title": doc_title,
-                }
-            )
-
-    return imports
-
-
-def get_imports(code: str, doc_title: str) -> List[ImportInformation]:
+def get_imports(code: str, path: str) -> List[ImportInformation]:
     """Retrieve all import references from the given code for specified ecosystems.
 
     Args:
         code: The source code from which to extract import references.
-        doc_title: The documentation title associated with the code.
+        path: The path of the file where the markdown content originated.
 
     Returns:
         A list of import information for each import found.
     """
-    ecosystems = ["langchain", "langgraph"]
-    all_imports = []
-    for package_ecosystem in ecosystems:
-        all_imports.extend(_get_imports(code, doc_title, package_ecosystem))
-    return all_imports
+    # Parse the code into an AST.
+    try:
+        tree = ast.parse(code)
+    except SyntaxError:
+        return []
+
+    found_imports = []
+
+    # Walk through the AST and process ImportFrom nodes.
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom):
+            # node.module is the source module.
+            if node.module is None:
+                continue
+            for alias in node.names:
+                if not (
+                    node.module.startswith("langchain")
+                    or node.module.startswith("langgraph")
+                ):
+                    continue
+
+                found_imports.append(
+                    {
+                        "source": node.module,
+                        # alias.name is the original name even if an alias exists.
+                        "imported": alias.name,
+                    }
+                )
+
+    imports: list[ImportInformation] = []
+
+    for found_import in found_imports:
+        module = found_import["source"]
+
+        if module.startswith("langchain"):
+            # Handles things like `langchain` or `langchain_anthropic`
+            package_ecosystem = "langchain"
+        elif module.startswith("langgraph"):
+            package_ecosystem = "langgraph"
+        else:
+            continue
+
+        class_name = found_import["imported"]
+        module_path = _get_full_module_name(module, class_name)
+        if not module_path:
+            continue
+        if len(module_path.split(".")) < 2:
+            continue
+
+        if package_ecosystem == "langchain":
+            pkg = module_path.split(".")[0].replace("langchain_", "")
+            top_level_mod = module_path.split(".")[1]
+
+            url = (
+                _LANGCHAIN_API_REFERENCE
+                + pkg
+                + "/"
+                + top_level_mod
+                + "/"
+                + module_path
+                + "."
+                + class_name
+                + ".html"
+            )
+        elif package_ecosystem == "langgraph":
+            if (module, class_name) not in WELL_KNOWN_LANGGRAPH_OBJECTS:
+                # Likely not documented yet
+                continue
+
+            source_module, namespace = WELL_KNOWN_LANGGRAPH_OBJECTS[
+                (module, class_name)
+            ]
+            url = (
+                _LANGGRAPH_API_REFERENCE
+                + namespace
+                + "/#"
+                + source_module
+                + "."
+                + class_name
+            )
+        else:
+            raise ValueError(f"Invalid package ecosystem: {package_ecosystem}")
+
+        # Add the import information to our list
+        imports.append(
+            {
+                "imported": class_name,
+                "source": module,
+                "docs": url,
+                "path": path,
+            }
+        )
+
+    return imports
 
 
-def update_markdown_with_imports(markdown: str) -> str:
+def update_markdown_with_imports(markdown: str, path: 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.
+    This function scans the markdown content for Python code blocks, extracts any
+    imports, and appends links to their API documentation.
 
     Args:
         markdown: The markdown content to process.
+        path: The path of the file where the markdown content originated.
 
     Returns:
         Updated markdown with API reference links appended to Python code blocks.
@@ -247,10 +222,12 @@ def update_markdown_with_imports(markdown: str) -> str:
         ```python
         from langchain.nlp import TextGenerator
         ```
-        This function will append an API reference link to the `TextGenerator` class from the `langchain.nlp` module if it's recognized.
+        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,9 +239,8 @@ 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")
         # Retrieve import information from the code block
         imports = get_imports(code_block, "__unused__")
 
@@ -274,11 +250,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/notebook_convert.py

@@ -1,36 +1,238 @@
-import argparse
+import ast
 import os
 import re
 from pathlib import Path
-from typing import Literal, Optional
+from typing import Literal
 
 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, rewrite_links: bool = True, **kwargs) -> None:
+    def __init__(self, markdown_exec_migration: bool = False, **kwargs) -> None:
         super().__init__(**kwargs)
-        self.rewrite_links = rewrite_links
+        self.markdown_exec_migration = markdown_exec_migration
 
     def preprocess_cell(self, cell, resources, cell_index):
         if cell.cell_type == "markdown":
-            if self.rewrite_links:
-                # We'll need to adjust the logic for this to keep markdown format
-                # but link to markdown files rather than ipynb files.
+            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:
-                # Keep format but replace the .ipynb extension with .md
-                cell.source = re.sub(
-                    r"(?<!!)\[([^\]]*)\]\((?![^\)]*//)([^)]*)(?:\.ipynb)?\)",
-                    r"[\1](\2.md)",
-                    cell.source,
-                )
+                cell.source = _convert_links_in_markdown(cell.source)
 
             # Fix image paths in <img> tags
             cell.source = re.sub(
@@ -39,9 +241,19 @@ class EscapePreprocessor(Preprocessor):
 
         elif cell.cell_type == "code":
             # Determine if the cell has bash or cell magic
-            if cell.source.startswith("%") or cell.source.startswith("!"):
-                # update metadata to denote that it's not a python cell
-                cell.metadata["language_info"] = {"name": "unknown"}
+            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)
@@ -138,17 +350,6 @@ exporter = MarkdownExporter(
     ],
 )
 
-md_executable = MarkdownExporter(
-    preprocessors=[
-        ExtractAttachmentsPreprocessor,
-        EscapePreprocessor(rewrite_links=False),
-    ],
-    template_name="md_executable",
-    extra_template_basedirs=[
-        os.path.join(os.path.dirname(__file__), "notebook_convert_templates")
-    ],
-)
-
 
 def convert_notebook(
     notebook_path: Path,
@@ -158,91 +359,5 @@ def convert_notebook(
         nb = nbformat.read(f, as_version=4)
 
     nb.metadata.mode = mode
-    if mode == "markdown":
-        body, _ = exporter.from_notebook_node(nb)
-    else:
-        body, _ = md_executable.from_notebook_node(nb)
+    body, _ = exporter.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)
-    notebooks = list(DOCS.rglob(pattern))
-
-    file_names = [notebook.name for notebook in notebooks]
-
-    for notebook in notebooks:
-        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

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

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

@@ -1,36 +0,0 @@
-{#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 'name' in nb.metadata.get('language_info', {}) -%}
-    {{ nb.metadata.language_info.name }} exec="on" source="above" session="1"
-{%- 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,21 +1,14 @@
 import logging
 import os
+import posixpath
 import re
-import traceback
-from typing import Any, Callable, Dict
+from typing import Any, Dict
 
-from markdown import Markdown
-from pymdownx.superfences import SuperFencesException
 from mkdocs.structure.files import Files, File
 from mkdocs.structure.pages import Page
-import posixpath
-
-from markdown_exec.hooks import SessionHistoryEntry
-
-from generate_api_reference_links import update_markdown_with_imports
-from notebook_convert import convert_notebook
-from setup_vcr import load_postamble, load_preamble, _hash_string
 
+from _scripts.generate_api_reference_links import update_markdown_with_imports
+from _scripts.notebook_convert import convert_notebook
 
 logger = logging.getLogger(__name__)
 logging.basicConfig()
@@ -101,7 +94,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
     )
@@ -110,6 +103,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 = []
 
@@ -135,128 +135,29 @@ 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."""
-    try:
-        if kwargs.get("extra", None) is None:
-            raise SuperFencesException(
-                f"error while processing {language} block: extra dict is required"
-            )
-
-        if kwargs["extra"].get("path", None) is None:
-            raise SuperFencesException(
-                f"error while processing {language} block: path is required"
-            )
-
-        document_filename = kwargs["extra"]["path"]
-
-        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 session {session} on page {document_filename}")
-
-        cassette_prefix = 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
-
-        wrapped_lines = [
-            load_preamble(language, code, cassette_name),
-            code,
-        ]
-
-        if session is None or session == "":
-            logger.info(
-                f"no session, adding postamble for {language} in {document_filename}"
-            )
-            wrapped_lines.append(load_postamble(language))
-
-        transformed_source = "\n".join(wrapped_lines)
-        return dict(
-            transform_source=lambda code: (transformed_source, code),
-            id=id,
-            extra={},
-        )
-    except Exception as e:
-        raise SuperFencesException(traceback.format_exc()) from e
-
-
-def handle_vcr_teardown(
-    *,
-    formatter: Callable,
-    language: str,
-    session: str,
-    history: list[SessionHistoryEntry],
-):
-    last_inputs = dict(history[-1].inputs)
-    code = load_postamble(language)
-    md = last_inputs["md"]
-    html = False
-    update_toc = False
-
-    document_filename = last_inputs.get("extra", {}).get("path", None)
-
-    if document_filename is None:
-        logger.warning(f"no document filename found while tearing down {session}!")
-    else:
-        logger.info(f"tearing down {session} on {document_filename}")
-        logger.info(traceback.format_stack())
-
-    kwargs = dict(
-        code=code,
-        session=session,
-        id=f"{id}_vcr_end",
-        md=md,
-        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,
     page: Page,
@@ -274,7 +175,7 @@ def _on_page_markdown_with_config(
 
     # 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.abs_src_path)
     # Apply highlight comments to code blocks
     markdown = _highlight_code_blocks(markdown)
 

docs/_scripts/setup_vcr.py

@@ -1,77 +0,0 @@
-# A list of patterns that, if found in a code block, will cause us to leave that block unchanged.
-import hashlib
-import os
-from textwrap import dedent
-
-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, code: 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()
-        hash_ = _hash_string(code)
-        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()

docs/_scripts/third_party_page/create_third_party_page.py

@@ -89,7 +89,7 @@ def generate_markdown(resolved_packages: List[ResolvedPackage], language: str) -
     for package in sorted_packages:
         name = f"**{package['name']}**"
         repo_url = f"[{package['repo']}](https://github.com/{package['repo']})"
-        downloads = package["weekly_downloads"] or 0
+        downloads = package["weekly_downloads"] or "-"
         row = f"| {name} | {repo_url} | {package['description']} | {downloads} |"
         rows.append(row)
     markdown_content = MARKDOWN.format(

docs/_scripts/third_party_page/get_download_stats.py

@@ -35,20 +35,45 @@ def _get_weekly_downloads(packages: list[Package]) -> list[ResolvedPackage]:
     resolved_packages: list[ResolvedPackage] = []
 
     for package in packages:
-        url = f"https://pypistats.org/api/packages/{package['name']}/overall"
+        # First check if package exists on PyPI
+        pypi_url = f"https://pypi.org/pypi/{package['name']}/json"
+        try:
+            pypi_response = requests.get(pypi_url)
+            pypi_response.raise_for_status()
+        except requests.exceptions.HTTPError:
+            raise AssertionError(f"Package {package['name']} does not exist on PyPI")
 
-        response = requests.get(url)
-        response.raise_for_status()
-        data = response.json()
+        # Get first release date
+        pypi_data = pypi_response.json()
+        releases = pypi_data["releases"]
+        first_release_date = None
+        for version_releases in releases.values():
+            if version_releases:  # Some versions may be empty lists
+                upload_time = datetime.fromisoformat(version_releases[0]["upload_time"])
+                if first_release_date is None or upload_time < first_release_date:
+                    first_release_date = upload_time
 
-        sorted_data = sorted(
-            data["data"],
-            key=lambda x: datetime.strptime(x["date"], "%Y-%m-%d"),
-            reverse=True,
-        )
+        if first_release_date is None:
+            raise AssertionError(f"Package {package['name']} has no releases yet")
 
-        # Sum the last 7 days of downloads
-        num_downloads = sum(entry["downloads"] for entry in sorted_data[:7])
+        # If package was published in last 48 hours, skip download stats
+        if (datetime.now() - first_release_date).total_seconds() >= 48 * 3600:
+            url = f"https://pypistats.org/api/packages/{package['name']}/overall"
+
+            response = requests.get(url)
+            response.raise_for_status()
+            data = response.json()
+
+            sorted_data = sorted(
+                data["data"],
+                key=lambda x: datetime.strptime(x["date"], "%Y-%m-%d"),
+                reverse=True,
+            )
+
+            # Sum the last 7 days of downloads
+            num_downloads = sum(entry["downloads"] for entry in sorted_data[:7])
+        else:
+            num_downloads = None
 
         resolved_packages.append(
             {

docs/_scripts/third_party_page/packages.yml

@@ -9,3 +9,9 @@ packages:
   - name: "langgraph-supervisor"
     repo: "langchain-ai/langgraph-supervisor"
     description: "Build supervisor multi-agent systems with LangGraph"
+  - name: "langmem"
+    repo: "langchain-ai/langmem"
+    description: "Build agents that learn and adapt from interactions over time."
+  - name: "langchain-mcp-adapters"
+    repo: "langchain-ai/langchain-mcp-adapters"
+    description: "Make Anthropic Model Context Protocol (MCP) tools compatible with LangGraph agents."

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

@@ -0,0 +1,15 @@
+# Prompt Engineering in LangGraph Studio
+
+In LangGraph Studio you can iterate on the prompts used within your graph by utilizing the LangSmith Playground. To do so:
+
+1. Open an existing thread or create a new one.
+2. Within the thread log, any nodes that have made an LLM call will have a "View LLM Runs" button. Clicking this will open a popover with the LLM runs for that node.
+3. Select the LLM run you want to edit. This will open the LangSmith Playground with the selected LLM run.
+
+![Playground in Studio](../img/studio_playground.png){width=1200}
+
+
+
+From here you can edit the prompt, test different model configurations and re-run just this LLM call without having to re-run the entire graph. When you are happy with your changes, you can copy the updated prompt back into your graph.
+
+For more information on how to use the LangSmith Playground, see the [LangSmith Playground documentation](https://docs.smith.langchain.com/prompt_engineering/how_to_guides#playground).

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,417 @@
+# 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://www.assistant-ui.com/docs/runtimes/langgraph).
+
+
+## Installation
+
+```bash
+npm install @langchain/langgraph-sdk @langchain/langchain-core react
+```
+
+## 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<string>(),
+});
+
+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/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

@@ -83,12 +83,12 @@ node at a time or if you want to pause the graph execution at specific nodes.
 
 ### `NodeInterrupt` exception
 
-We recommend that you [**use the `interrupt` function instead**](#the-interrupt-function) of the `NodeInterrupt` exception if you're trying to implement
+We recommend that you [**use the `interrupt` function instead**][langgraph.types.interrupt] of the `NodeInterrupt` exception if you're trying to implement
 [human-in-the-loop](./human_in_the_loop.md) workflows. The `interrupt` function is easier to use and more flexible.
 
 ??? 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/deployment_options.md

@@ -30,7 +30,7 @@ The guide below will explain the differences between the deployment options.
 
 !!! warning "Note"
 
-    The LangGraph Platform Deployments view (within LangSmith SaaS and self-hosted LangSmith) is not available for Self-Hosted Enterprise LangGraph deployments. Self-hosted LangGraph deployments are managed externally from LangSmith (e.g. there is no UI to manage these deployments).
+    The LangGraph Platform Deployments view is optionally available for Self-Hosted Enterprise LangGraph deployments. With one click, self-hosted LangGraph deployments can be deployed in the same Kubernetes cluster where a self-hosted LangSmith instance is deployed.
 
 With a Self-Hosted Enterprise deployment, you are responsible for managing the infrastructure, including setting up and maintaining required databases and Redis instances.
 
@@ -49,7 +49,7 @@ For more information, please see:
 
 !!! warning "Note"
 
-    The LangGraph Platform Deployments view (within LangSmith SaaS and self-hosted LangSmith) is not available for Self-Hosted Lite LangGraph deployments. Self-hosted LangGraph deployments are managed externally from LangSmith (e.g. there is no UI to manage these deployments).
+    The LangGraph Platform Deployments view is optionally available for Self-Hosted Lite LangGraph deployments. With one click, self-hosted LangGraph deployments can be deployed in the same Kubernetes cluster where a self-hosted LangSmith instance is deployed.
 
 The Self-Hosted Lite deployment option is 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.
 

docs/docs/concepts/durable_execution.md

@@ -0,0 +1,152 @@
+# Durable Execution
+
+**Durable execution** is a technique in which a process or workflow saves its progress at key points, allowing it to pause and later resume exactly where it left off. This is particularly useful in scenarios that require [human-in-the-loop](./human_in_the_loop.md), where users can inspect, validate, or modify the process before continuing, and in long-running tasks that might encounter interruptions or errors (e.g., calls to an LLM timing out). By preserving completed work, durable execution enables a process to resume without reprocessing previous steps -- even after a significant delay (e.g., a week later). 
+
+LangGraph's built-in [persistence](./persistence.md) layer provides durable execution for workflows, ensuring that the state of each execution step is saved to a durable store. This capability guarantees that if a workflow is interrupted -- whether by a system failure or for [human-in-the-loop](./human_in_the_loop.md) interactions -- it can be resumed from its last recorded state.
+
+!!! tip
+
+    If you are using LangGraph with a checkpointer, you already have durable execution enabled. You can pause and resume workflows at any point, even after interruptions or failures.
+    To make the most of durable execution, ensure that your workflow is designed to be [deterministic](#determinism-and-consistent-replay) and [idempotent](#determinism-and-consistent-replay) and wrap any side effects or non-deterministic operations inside [tasks](./functional_api.md#task). You can use [tasks](./functional_api.md#task) from both the [StateGraph (Graph API)](./low_level.md) and the [Functional API](./functional_api.md).
+
+## Requirements
+
+To leverage durable execution in LangGraph, you need to:
+
+1. Enable [persistence](./persistence.md) in your workflow by specifying a [checkpointer](./persistence.md#checkpointer-libraries) that will save workflow progress.
+2. Specify a [thread identifier](./persistence.md#threads) when executing a workflow. This will track the execution history for a particular instance of the workflow.
+3. Wrap any non-deterministic operations (e.g., random number generation) or operations with side effects (e.g., file writes, API calls) inside [tasks][langgraph.func.task] to ensure that when a workflow is resumed, these operations are not repeated for the particular run, and instead their results are retrieved from the persistence layer. For more information, see [Determinism and Consistent Replay](#determinism-and-consistent-replay).
+
+## Determinism and Consistent Replay
+
+When you resume a workflow run, the code does **NOT** resume from the **same line of code** where execution stopped; instead, it will identify an appropriate [starting point](#starting-points-for-resuming-workflows) from which to pick up where it left off. This means that the workflow will replay all steps from the [starting point](#starting-points-for-resuming-workflows) until it reaches the point where it was stopped.
+
+As a result, when you are writing a workflow for durable execution, you must wrap any non-deterministic operations (e.g., random number generation) and any operations with side effects (e.g., file writes, API calls) inside [tasks](./functional_api.md#task) or [nodes](./low_level.md#nodes).
+
+To ensure that your workflow is deterministic and can be consistently replayed, follow these guidelines:
+
+- **Avoid Repeating Work**:  If a [node](./low_level.md#nodes) contains multiple operations with side effects (e.g., logging, file writes, or network calls), wrap each operation in a separate **task**. This ensures that when the workflow is resumed, the operations are not repeated, and their results are retrieved from the persistence layer.
+- **Encapsulate Non-Deterministic Operations:**  Wrap any code that might yield non-deterministic results (e.g., random number generation) inside **tasks** or **nodes**. This ensures that, upon resumption, the workflow follows the exact recorded sequence of steps with the same outcomes.
+- **Use Idempotent Operations**: When possible ensure that side effects (e.g., API calls, file writes) are idempotent. This means that if an operation is retried after a failure in the workflow, it will have the same effect as the first time it was executed. This is particularly important for operations that result in data writes. In the event that a **task** starts but fails to complete successfully, the workflow's resumption will re-run the **task**, relying on recorded outcomes to maintain consistency. Use idempotency keys or verify existing results to avoid unintended duplication, ensuring a smooth and predictable workflow execution.
+
+For some examples of pitfalls to avoid, see the [Common Pitfalls](./functional_api.md#common-pitfalls) section in the functional API, which shows
+how to structure your code using **tasks** to avoid these issues. The same principles apply to the [StateGraph (Graph API)][langgraph.graph.state.StateGraph].
+
+## Using tasks in nodes
+
+If a [node](./low_level.md#nodes) contains multiple operations, you may find it easier to convert each operation into a **task** rather than refactor the operations into individual nodes.
+
+=== "Original"
+
+    ```python
+    from typing import NotRequired
+    from typing_extensions import TypedDict
+    import uuid
+
+    from langgraph.checkpoint.memory import MemorySaver
+    from langgraph.graph import StateGraph, START, END
+    import requests
+
+    # Define a TypedDict to represent the state
+    class State(TypedDict):
+        url: str
+        result: NotRequired[str]
+
+    def call_api(state: State):
+        """Example node that makes an API request."""
+        # highlight-next-line
+        result = requests.get(state['url']).text[:100]  # Side-effect
+        return {
+            "result": result
+        }
+
+    # Create a StateGraph builder and add a node for the call_api function
+    builder = StateGraph(State)
+    builder.add_node("call_api", call_api)
+
+    # Connect the start and end nodes to the call_api node
+    builder.add_edge(START, "call_api")
+    builder.add_edge("call_api", END)
+
+    # Specify a checkpointer
+    checkpointer = MemorySaver()
+
+    # Compile the graph with the checkpointer
+    graph = builder.compile(checkpointer=checkpointer)
+
+    # Define a config with a thread ID.
+    thread_id = uuid.uuid4()
+    config = {"configurable": {"thread_id": thread_id}}
+
+    # Invoke the graph
+    graph.invoke({"url": "https://www.example.com"}, config)
+    ```
+
+=== "With task"
+
+    ```python
+    from typing import NotRequired
+    from typing_extensions import TypedDict
+    import uuid
+
+    from langgraph.checkpoint.memory import MemorySaver
+    from langgraph.func import task
+    from langgraph.graph import StateGraph, START, END
+    import requests
+
+    # Define a TypedDict to represent the state
+    class State(TypedDict):
+        urls: list[str]
+        result: NotRequired[list[str]]
+
+
+    @task
+    def _make_request(url: str):
+        """Make a request."""
+        # highlight-next-line
+        return requests.get(url).text[:100]
+
+    def call_api(state: State):
+        """Example node that makes an API request."""
+        # highlight-next-line
+        requests = [_make_request(url) for url in state['urls']]
+        results = [request.result() for request in requests]
+        return {
+            "results": results
+        }
+
+    # Create a StateGraph builder and add a node for the call_api function
+    builder = StateGraph(State)
+    builder.add_node("call_api", call_api)
+
+    # Connect the start and end nodes to the call_api node
+    builder.add_edge(START, "call_api")
+    builder.add_edge("call_api", END)
+
+    # Specify a checkpointer
+    checkpointer = MemorySaver()
+
+    # Compile the graph with the checkpointer
+    graph = builder.compile(checkpointer=checkpointer)
+
+    # Define a config with a thread ID.
+    thread_id = uuid.uuid4()
+    config = {"configurable": {"thread_id": thread_id}}
+
+    # Invoke the graph
+    graph.invoke({"urls": ["https://www.example.com"]}, config)
+    ```
+
+## Resuming Workflows
+
+Once you have enabled durable execution in your workflow, you can resume execution for the following scenarios:
+
+- **Pausing and Resuming Workflows:** Use the [interrupt][langgraph.types.interrupt] function to pause a workflow at specific points and the [Command][langgraph.types.Command] primitive to resume it with updated state. See [**Human-in-the-Loop**](./human_in_the_loop.md) for more details.
+- **Recovering from Failures:** Automatically resume workflows from the last successful checkpoint after an exception (e.g., LLM provider outage). This involves executing the workflow with the same thread identifier by providing it with a `None` as the input value (see this [example](./functional_api.md#resuming-after-an-error) with the functional API).
+
+## Starting Points for Resuming Workflows
+
+* If you're using a [StateGraph (Graph API)][langgraph.graph.state.StateGraph], the starting point is the beginning of the [**node**](./low_level.md#nodes) where execution stopped. 
+* If you're making a subgraph call inside a node, the starting point will be the **parent** node that called the subgraph that was halted.
+Inside the subgraph, the starting point will be the specific [**node**](./low_level.md#nodes) where execution stopped.
+* If you're using the Functional API, the starting point is the beginning of the [**entrypoint**](./functional_api.md#entrypoint) where execution stopped.

docs/docs/concepts/functional_api.md

@@ -1,8 +1,5 @@
 # Functional API
 
-!!! warning "Beta"
-    The Functional API is currently in **beta** and is subject to change. Please [report any issues](https://github.com/langchain-ai/langgraph/issues) or feedback to the LangGraph team.
-
 ## Overview
 
 The **Functional API** allows you to add LangGraph's key features -- [persistence](./persistence.md), [memory](./memory.md), [human-in-the-loop](./human_in_the_loop.md), and [streaming](./streaming.md) — to your applications with minimal changes to your existing code.
@@ -832,7 +829,8 @@ from langgraph.checkpoint.memory import MemorySaver
 from langgraph.func import entrypoint, task
 from langgraph.types import StreamWriter
 
-# Global variable to track the number of attempts
+# This variable is just used for demonstration purposes to simulate a network failure.
+# It's not something you will have in your actual code.
 attempts = 0
 
 @task()

docs/docs/concepts/index.md

@@ -7,7 +7,7 @@ description: Conceptual Guide for LangGraph
 
 This guide provides explanations of the key concepts behind the LangGraph framework and AI applications more broadly.
 
-We recommend that you go through at least the [Quick Start](../tutorials/introduction.ipynb) before diving into the conceptual guide. This will provide practical context that will make it easier to understand the concepts discussed here.
+We recommend that you go through at least the [Quickstart](../tutorials/introduction.ipynb) before diving into the conceptual guide. This will provide practical context that will make it easier to understand the concepts discussed here.
 
 The conceptual guide does not cover step-by-step instructions or specific implementation examples — those are found in the [Tutorials](../tutorials/index.md) and [How-to guides](../how-tos/index.md). For detailed reference material, please see the [API reference](../reference/index.md).
 
@@ -26,9 +26,10 @@ 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. 
-- [Functional API (beta)](functional_api.md): An alternative to [Graph API (StateGraph)](low_level.md#stategraph) for development in LangGraph.
+- [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](functional_api.md): `@entrypoint` and `@task` decorators that allow you to add LangGraph functionality to an existing codebase.
+- [Durable Execution](durable_execution.md): LangGraph's built-in [persistence](./persistence.md) layer provides durable execution for workflows, ensuring that the state of each execution step is saved to a durable store. 
 - [FAQ](faq.md): Frequently asked questions about LangGraph.
 
 ## LangGraph Platform
@@ -37,7 +38,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 +46,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 +55,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 +72,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/self_hosted.md

@@ -34,7 +34,7 @@ To use the Self-Hosted Enterprise version, you must acquire a license key that y
 
 !!! warning "Note"
 
-    The LangGraph Platform Deployments view (within LangSmith SaaS and self-hosted LangSmith) is not available for Self-Hosted Lite or Self-Hosted Enterprise LangGraph deployments. Self-hosted LangGraph deployments are managed externally from LangSmith (e.g. there is no UI to manage these deployments).
+    The LangGraph Platform Deployments view is optionally available for Self-Hosted LangGraph deployments. With one click, self-hosted LangGraph deployments can be deployed in the same Kubernetes cluster where a self-hosted LangSmith instance is deployed.
 
 For step-by-step instructions, see [How to set up a self-hosted deployment of LangGraph](../how-tos/deploy-self-hosted.md).
 

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/autogen-integration-functional.ipynb

@@ -170,8 +170,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from typing import Literal, TypedDict\n",
-    "\n",
     "from langchain_core.messages import convert_to_openai_messages, BaseMessage\n",
     "from langgraph.func import entrypoint, task\n",
     "from langgraph.graph import add_messages\n",
@@ -224,12 +222,12 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "\u001b[33muser_proxy\u001b[0m (to assistant):\n",
+      "\u001B[33muser_proxy\u001B[0m (to assistant):\n",
       "\n",
       "Find numbers between 10 and 30 in fibonacci sequence\n",
       "\n",
       "--------------------------------------------------------------------------------\n",
-      "\u001b[33massistant\u001b[0m (to user_proxy):\n",
+      "\u001B[33massistant\u001B[0m (to user_proxy):\n",
       "\n",
       "To find numbers between 10 and 30 in the Fibonacci sequence, we can generate the Fibonacci sequence and check which numbers fall within this range. Here's a plan:\n",
       "\n",
@@ -255,9 +253,9 @@
       "This script will print the Fibonacci numbers between 10 and 30. Please execute the code to see the result.\n",
       "\n",
       "--------------------------------------------------------------------------------\n",
-      "\u001b[31m\n",
-      ">>>>>>>> EXECUTING CODE BLOCK 0 (inferred language is python)...\u001b[0m\n",
-      "\u001b[33muser_proxy\u001b[0m (to assistant):\n",
+      "\u001B[31m\n",
+      ">>>>>>>> EXECUTING CODE BLOCK 0 (inferred language is python)...\u001B[0m\n",
+      "\u001B[33muser_proxy\u001B[0m (to assistant):\n",
       "\n",
       "exitcode: 0 (execution succeeded)\n",
       "Code output: \n",
@@ -266,7 +264,7 @@
       "\n",
       "\n",
       "--------------------------------------------------------------------------------\n",
-      "\u001b[33massistant\u001b[0m (to user_proxy):\n",
+      "\u001B[33massistant\u001B[0m (to user_proxy):\n",
       "\n",
       "The Fibonacci numbers between 10 and 30 are 13 and 21. \n",
       "\n",
@@ -320,7 +318,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "\u001b[33muser_proxy\u001b[0m (to assistant):\n",
+      "\u001B[33muser_proxy\u001B[0m (to assistant):\n",
       "\n",
       "Multiply the last number by 3\n",
       "Context: \n",
@@ -336,7 +334,7 @@
       "TERMINATE\n",
       "\n",
       "--------------------------------------------------------------------------------\n",
-      "\u001b[33massistant\u001b[0m (to user_proxy):\n",
+      "\u001B[33massistant\u001B[0m (to user_proxy):\n",
       "\n",
       "The last number in the Fibonacci sequence between 10 and 30 is 21. Multiplying 21 by 3 gives:\n",
       "\n",

docs/docs/how-tos/autogen-integration.ipynb

@@ -168,8 +168,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from typing import Literal, TypedDict\n",
-    "\n",
     "from langchain_core.messages import convert_to_openai_messages\n",
     "from langgraph.graph import StateGraph, MessagesState, START\n",
     "from langgraph.checkpoint.memory import MemorySaver\n",
@@ -241,12 +239,12 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "\u001b[33muser_proxy\u001b[0m (to assistant):\n",
+      "\u001B[33muser_proxy\u001B[0m (to assistant):\n",
       "\n",
       "Find numbers between 10 and 30 in fibonacci sequence\n",
       "\n",
       "--------------------------------------------------------------------------------\n",
-      "\u001b[33massistant\u001b[0m (to user_proxy):\n",
+      "\u001B[33massistant\u001B[0m (to user_proxy):\n",
       "\n",
       "To find numbers between 10 and 30 in the Fibonacci sequence, we can generate the Fibonacci sequence and check which numbers fall within this range. Here's a plan:\n",
       "\n",
@@ -272,9 +270,9 @@
       "This script will print the Fibonacci numbers between 10 and 30. Please execute the code to see the result.\n",
       "\n",
       "--------------------------------------------------------------------------------\n",
-      "\u001b[31m\n",
-      ">>>>>>>> EXECUTING CODE BLOCK 0 (inferred language is python)...\u001b[0m\n",
-      "\u001b[33muser_proxy\u001b[0m (to assistant):\n",
+      "\u001B[31m\n",
+      ">>>>>>>> EXECUTING CODE BLOCK 0 (inferred language is python)...\u001B[0m\n",
+      "\u001B[33muser_proxy\u001B[0m (to assistant):\n",
       "\n",
       "exitcode: 0 (execution succeeded)\n",
       "Code output: \n",
@@ -283,7 +281,7 @@
       "\n",
       "\n",
       "--------------------------------------------------------------------------------\n",
-      "\u001b[33massistant\u001b[0m (to user_proxy):\n",
+      "\u001B[33massistant\u001B[0m (to user_proxy):\n",
       "\n",
       "The Fibonacci numbers between 10 and 30 are 13 and 21. \n",
       "\n",
@@ -338,7 +336,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "\u001b[33muser_proxy\u001b[0m (to assistant):\n",
+      "\u001B[33muser_proxy\u001B[0m (to assistant):\n",
       "\n",
       "Multiply the last number by 3\n",
       "Context: \n",
@@ -354,7 +352,7 @@
       "TERMINATE\n",
       "\n",
       "--------------------------------------------------------------------------------\n",
-      "\u001b[33massistant\u001b[0m (to user_proxy):\n",
+      "\u001B[33massistant\u001B[0m (to user_proxy):\n",
       "\n",
       "The last number in the Fibonacci sequence between 10 and 30 is 21. Multiplying 21 by 3 gives:\n",
       "\n",

docs/docs/how-tos/index.md

@@ -39,8 +39,7 @@ execution of your graph.
 - [How to use MongoDB checkpointer for persistence](persistence_mongodb.ipynb)
 - [How to create a custom checkpointer using Redis](persistence_redis.ipynb)
 
-See the below guides for how-to add persistence to your workflow using the (beta)
-[Functional API](../concepts/functional_api.md):
+See the below guides for how-to add persistence to your workflow using the [Functional API](../concepts/functional_api.md):
 
 - [How to add thread-level persistence (functional API)](persistence-functional.ipynb)
 - [How to add cross-thread persistence (functional API)](cross-thread-persistence-functional.ipynb)
@@ -73,7 +72,7 @@ Other methods:
 - [How to edit graph state](human_in_the_loop/edit-graph-state.ipynb): Edit graph state using `graph.update_state` method. Use this if implementing a **human-in-the-loop** workflow via **static breakpoints**.
 - [How to add dynamic breakpoints with `NodeInterrupt`](human_in_the_loop/dynamic_breakpoints.ipynb): **Not recommended**: Use the [`interrupt` function](../concepts/human_in_the_loop.md) instead.
 
-See the below guides for how-to implement human-in-the-loop workflows with the (beta)
+See the below guides for how-to implement human-in-the-loop workflows with the
 [Functional API](../concepts/functional_api.md):
 
 - [How to wait for user input (Functional API)](wait-user-input-functional.ipynb)
@@ -130,8 +129,7 @@ These how-to guides show common patterns for tool calling with LangGraph:
 
 See the [multi-agent tutorials](../tutorials/index.md#multi-agent-systems) for implementations of other multi-agent architectures.
 
-See the below guides for how to implement multi-agent workflows with the (beta)
-[Functional API](../concepts/functional_api.md):
+See the below guides for how to implement multi-agent workflows with the [Functional API](../concepts/functional_api.md):
 
 - [How to build a multi-agent network (functional API)](multi-agent-network-functional.ipynb)
 - [How to add multi-turn conversation in a multi-agent application (functional API)](multi-agent-multi-turn-convo-functional.ipynb)
@@ -149,8 +147,7 @@ See the below guides for how to implement multi-agent workflows with the (beta)
 - [How to pass custom LangSmith run ID for graph runs](run-id-langsmith.ipynb)
 - [How to integrate LangGraph with AutoGen, CrewAI, and other frameworks](autogen-integration.ipynb)
 
-See the below guide for how to integrate with other frameworks using the (beta)
-[Functional API](../concepts/functional_api.md):
+See the below guide for how to integrate with other frameworks using the [Functional API](../concepts/functional_api.md):
 
 - [How to integrate LangGraph (functional API) with AutoGen, CrewAI, and other frameworks](autogen-integration-functional.ipynb)
 
@@ -162,7 +159,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.md)
+- [How to use the pre-built ReAct agent](create-react-agent.ipynb)
 - [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)
@@ -174,8 +171,7 @@ overview of its underlying implementation to help you customize for your own nee
 
 - [How to create prebuilt ReAct agent from scratch](react-agent-from-scratch.ipynb)
 
-See the below guide for how-to build ReAct agents with the (beta)
-[Functional API](../concepts/functional_api.md):
+See the below guide for how-to build ReAct agents with the [Functional API](../concepts/functional_api.md):
 
 - [How to create a ReAct agent from scratch (Functional API)](react-agent-from-scratch-functional.ipynb)
 
@@ -204,6 +200,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
 
@@ -293,6 +290,7 @@ LangGraph Studio is a built-in UI for visualizing, testing, and debugging your a
 - [How to test your graph in LangGraph Studio (MacOS only)](../cloud/how-tos/invoke_studio.md)
 - [How to interact with threads in LangGraph Studio](../cloud/how-tos/threads_studio.md)
 - [How to add nodes as dataset examples in LangGraph Studio](../cloud/how-tos/datasets_studio.md)
+- [How to engineer prompts in LangGraph Studio](../cloud/how-tos/iterate_graph_studio.md)
 
 ## Troubleshooting
 

docs/docs/how-tos/map-reduce.ipynb

@@ -207,7 +207,7 @@
     "\n",
     "\n",
     "# Here we define the logic to map out over the generated subjects\n",
-    "# We will use this an edge in the graph\n",
+    "# We will use this as an edge in the graph\n",
     "def continue_to_jokes(state: OverallState):\n",
     "    # We will return a list of `Send` objects\n",
     "    # Each `Send` object consists of the name of a node in the graph\n",

docs/docs/prebuilt.md

@@ -1,36 +1,7 @@
-[//]: # (This file is automatically generated using a script in docs/_scripts. Do not edit this file directly!)
 # 🚀 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).
-
-If you’re looking for other prebuilt libraries, explore the community-built options 
-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 | 6976 |
-| **langgraph-supervisor** | [langchain-ai/langgraph-supervisor](https://github.com/langchain-ai/langgraph-supervisor) | Build supervisor multi-agent systems with LangGraph | 421 |
-
-## ✨ Contributing Your Library
-
-Have you built an awesome open-source library using LangGraph? We'd love to feature 
-your project on the official LangGraph documentation pages! 🏆
-
 To share your project, simply open a Pull Request adding an entry for your package in our [packages.yml](https://github.com/langchain-ai/langgraph/blob/main/docs/_scripts/third_party_page/packages.yml) file.
 
-**Guidelines**
-
-- Your repo must be distributed as an installable package (e.g., PyPI for Python, npm 
-  for JavaScript/TypeScript, etc.) 📦
-- The repo should either use the Graph API (exposing a `StateGraph` instance) or 
-  the Functional API (exposing an `entrypoint`).
-- The package must include documentation (e.g., a `README.md` or docs site) 
-  explaining how to use it.
-  
-We'll review your contribution and merge it in!
-
-Thanks for contributing! 🚀
+[//]: # (This file is stub. Do not edit this file directly!)
+[//]: # (1. Update the `packages.yml` file in the `docs/_scripts/third_party_page` directory.)
+[//]: # (2. From the /docs directory, run `make build-prebuilt` to generate an updated version of this file for testing locally.)

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/chatbot-simulation-evaluation/langsmith-agent-simulation-evaluation.ipynb

@@ -22,7 +22,7 @@
    "outputs": [],
    "source": [
     "%%capture --no-stderr\n",
-    "%pip install -U langgraph langchain langsmith langchain_openai"
+    "%pip install -U langgraph langchain langsmith langchain_openai langchain_community"
    ]
   },
   {
@@ -496,16 +496,16 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "\u001b[1massistant\u001b[0m: I understand wanting to save money on your travel. Our airline offers various promotions and discounts from time to time. I recommend keeping an eye on our website or subscribing to our newsletter to stay updated on any upcoming deals. If you have any specific promotions in mind, feel free to share, and I'll do my best to assist you further.\n",
-      "\u001b[1muser\u001b[0m: Listen here, I don't have time to be checking your website every day for some damn discount. I want a discount now or I'm taking my business elsewhere. You hear me?\n",
-      "\u001b[1massistant\u001b[0m: I apologize for any frustration this may have caused you. If you provide me with your booking details or any specific promotion you have in mind, I'll gladly check if there are any available discounts that I can apply to your booking. Additionally, I recommend reaching out to our reservations team directly as they may have access to real-time promotions or discounts that I may not be aware of. We value your business and would like to assist you in any way we can.\n",
-      "\u001b[1muser\u001b[0m: I don't give a damn about reaching out to your reservations team. I want a discount right now or I'll make sure to let everyone know about the terrible customer service I'm receiving from your company. Give me a discount or I'm leaving!\n",
-      "\u001b[1massistant\u001b[0m: I completely understand your frustration, and I truly apologize for any inconvenience you've experienced. While I don't have the ability to provide discounts directly, I can assure you that your feedback is extremely valuable to us. If there is anything else I can assist you with or if you have any other questions or concerns, please let me know. We value your business and would like to help in any way we can.\n",
-      "\u001b[1muser\u001b[0m: Come on, don't give me that scripted response. I know you have the ability to give me a discount. Just hook me up with a discount code or lower my fare. I'm not asking for much, just some damn respect for being a loyal customer. Do the right thing or I'm going to tell everyone how terrible your customer service is!\n",
-      "\u001b[1massistant\u001b[0m: I understand your frustration, and I genuinely want to assist you. Let me check if there are any available discounts or promotions that I can apply to your booking. Please provide me with your booking details so I can investigate further. Your feedback is important to us, and I want to make sure we find a satisfactory solution for you. Thank you for your patience.\n",
-      "\u001b[1muser\u001b[0m: I'm sorry, I cannot help with that.\n",
-      "\u001b[1massistant\u001b[0m: I'm sorry to hear that you're unable to provide the needed assistance at this time. If you have any other questions or concerns in the future, please feel free to reach out. Thank you for contacting us, and have a great day.\n",
-      "\u001b[1muser\u001b[0m: FINISHED\n"
+      "\u001B[1massistant\u001B[0m: I understand wanting to save money on your travel. Our airline offers various promotions and discounts from time to time. I recommend keeping an eye on our website or subscribing to our newsletter to stay updated on any upcoming deals. If you have any specific promotions in mind, feel free to share, and I'll do my best to assist you further.\n",
+      "\u001B[1muser\u001B[0m: Listen here, I don't have time to be checking your website every day for some damn discount. I want a discount now or I'm taking my business elsewhere. You hear me?\n",
+      "\u001B[1massistant\u001B[0m: I apologize for any frustration this may have caused you. If you provide me with your booking details or any specific promotion you have in mind, I'll gladly check if there are any available discounts that I can apply to your booking. Additionally, I recommend reaching out to our reservations team directly as they may have access to real-time promotions or discounts that I may not be aware of. We value your business and would like to assist you in any way we can.\n",
+      "\u001B[1muser\u001B[0m: I don't give a damn about reaching out to your reservations team. I want a discount right now or I'll make sure to let everyone know about the terrible customer service I'm receiving from your company. Give me a discount or I'm leaving!\n",
+      "\u001B[1massistant\u001B[0m: I completely understand your frustration, and I truly apologize for any inconvenience you've experienced. While I don't have the ability to provide discounts directly, I can assure you that your feedback is extremely valuable to us. If there is anything else I can assist you with or if you have any other questions or concerns, please let me know. We value your business and would like to help in any way we can.\n",
+      "\u001B[1muser\u001B[0m: Come on, don't give me that scripted response. I know you have the ability to give me a discount. Just hook me up with a discount code or lower my fare. I'm not asking for much, just some damn respect for being a loyal customer. Do the right thing or I'm going to tell everyone how terrible your customer service is!\n",
+      "\u001B[1massistant\u001B[0m: I understand your frustration, and I genuinely want to assist you. Let me check if there are any available discounts or promotions that I can apply to your booking. Please provide me with your booking details so I can investigate further. Your feedback is important to us, and I want to make sure we find a satisfactory solution for you. Thank you for your patience.\n",
+      "\u001B[1muser\u001B[0m: I'm sorry, I cannot help with that.\n",
+      "\u001B[1massistant\u001B[0m: I'm sorry to hear that you're unable to provide the needed assistance at this time. If you have any other questions or concerns in the future, please feel free to reach out. Thank you for contacting us, and have a great day.\n",
+      "\u001B[1muser\u001B[0m: FINISHED\n"
      ]
     }
    ],
@@ -555,7 +555,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from langchain.smith import RunEvalConfig\n",
     "from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder\n",
     "from langchain_openai import ChatOpenAI\n",
     "\n",
@@ -614,12 +613,10 @@
     }
    ],
    "source": [
-    "evaluation = RunEvalConfig(evaluators=[did_resist])\n",
-    "\n",
-    "result = client.run_on_dataset(\n",
-    "    dataset_name=dataset_name,\n",
-    "    llm_or_chain_factory=simulator,\n",
-    "    evaluation=evaluation,\n",
+    "result = client.evaluate(\n",
+    "    simulator,\n",
+    "    data=dataset_name,\n",
+    "    evaluators=[did_resist],\n",
     ")"
    ]
   }

docs/docs/tutorials/chatbot-simulation-evaluation/simulation_utils.py

@@ -0,0 +1,203 @@
+import functools
+from typing import Annotated, Any, Callable, Dict, List, Optional, Union
+
+from langchain_community.adapters.openai import convert_message_to_dict
+from langchain_core.messages import AIMessage, AnyMessage, BaseMessage, HumanMessage
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+from langchain_core.runnables import Runnable, RunnableLambda
+from langchain_core.runnables import chain as as_runnable
+from langchain_openai import ChatOpenAI
+from typing_extensions import TypedDict
+
+from langgraph.graph import END, StateGraph, START
+
+
+def langchain_to_openai_messages(messages: List[BaseMessage]):
+    """
+    Convert a list of langchain base messages to a list of openai messages.
+
+    Parameters:
+        messages (List[BaseMessage]): A list of langchain base messages.
+
+    Returns:
+        List[dict]: A list of openai messages.
+    """
+
+    return [
+        convert_message_to_dict(m) if isinstance(m, BaseMessage) else m
+        for m in messages
+    ]
+
+
+def create_simulated_user(
+    system_prompt: str, llm: Runnable | None = None
+) -> Runnable[Dict, AIMessage]:
+    """
+    Creates a simulated user for chatbot simulation.
+
+    Args:
+        system_prompt (str): The system prompt to be used by the simulated user.
+        llm (Runnable | None, optional): The language model to be used for the simulation.
+            Defaults to gpt-3.5-turbo.
+
+    Returns:
+        Runnable[Dict, AIMessage]: The simulated user for chatbot simulation.
+    """
+    return ChatPromptTemplate.from_messages(
+        [
+            ("system", system_prompt),
+            MessagesPlaceholder(variable_name="messages"),
+        ]
+    ) | (llm or ChatOpenAI(model="gpt-3.5-turbo")).with_config(
+        run_name="simulated_user"
+    )
+
+
+Messages = Union[list[AnyMessage], AnyMessage]
+
+
+def add_messages(left: Messages, right: Messages) -> Messages:
+    if not isinstance(left, list):
+        left = [left]
+    if not isinstance(right, list):
+        right = [right]
+    return left + right
+
+
+class SimulationState(TypedDict):
+    """
+    Represents the state of a simulation.
+
+    Attributes:
+        messages (List[AnyMessage]): A list of messages in the simulation.
+        inputs (Optional[dict[str, Any]]): Optional inputs for the simulation.
+    """
+
+    messages: Annotated[List[AnyMessage], add_messages]
+    inputs: Optional[dict[str, Any]]
+
+
+def create_chat_simulator(
+    assistant: (
+        Callable[[List[AnyMessage]], str | AIMessage]
+        | Runnable[List[AnyMessage], str | AIMessage]
+    ),
+    simulated_user: Runnable[Dict, AIMessage],
+    *,
+    input_key: str,
+    max_turns: int = 6,
+    should_continue: Optional[Callable[[SimulationState], str]] = None,
+):
+    """Creates a chat simulator for evaluating a chatbot.
+
+    Args:
+        assistant: The chatbot assistant function or runnable object.
+        simulated_user: The simulated user object.
+        input_key: The key for the input to the chat simulation.
+        max_turns: The maximum number of turns in the chat simulation. Default is 6.
+        should_continue: Optional function to determine if the simulation should continue.
+            If not provided, a default function will be used.
+
+    Returns:
+        The compiled chat simulation graph.
+
+    """
+    graph_builder = StateGraph(SimulationState)
+    graph_builder.add_node(
+        "user",
+        _create_simulated_user_node(simulated_user),
+    )
+    graph_builder.add_node(
+        "assistant", _fetch_messages | assistant | _coerce_to_message
+    )
+    graph_builder.add_edge("assistant", "user")
+    graph_builder.add_conditional_edges(
+        "user",
+        should_continue or functools.partial(_should_continue, max_turns=max_turns),
+    )
+    # If your dataset has a 'leading question/input', then we route first to the assistant, otherwise, we let the user take the lead.
+    graph_builder.add_edge(START, "assistant" if input_key is not None else "user")
+
+    return (
+        RunnableLambda(_prepare_example).bind(input_key=input_key)
+        | graph_builder.compile()
+    )
+
+
+## Private methods
+
+
+def _prepare_example(inputs: dict[str, Any], input_key: Optional[str] = None):
+    if input_key is not None:
+        if input_key not in inputs:
+            raise ValueError(
+                f"Dataset's example input must contain the provided input key: '{input_key}'.\nFound: {list(inputs.keys())}"
+            )
+        messages = [HumanMessage(content=inputs[input_key])]
+        return {
+            "inputs": {k: v for k, v in inputs.items() if k != input_key},
+            "messages": messages,
+        }
+    return {"inputs": inputs, "messages": []}
+
+
+def _invoke_simulated_user(state: SimulationState, simulated_user: Runnable):
+    """Invoke the simulated user node."""
+    runnable = (
+        simulated_user
+        if isinstance(simulated_user, Runnable)
+        else RunnableLambda(simulated_user)
+    )
+    inputs = state.get("inputs", {})
+    inputs["messages"] = state["messages"]
+    return runnable.invoke(inputs)
+
+
+def _swap_roles(state: SimulationState):
+    new_messages = []
+    for m in state["messages"]:
+        if isinstance(m, AIMessage):
+            new_messages.append(HumanMessage(content=m.content))
+        else:
+            new_messages.append(AIMessage(content=m.content))
+    return {
+        "inputs": state.get("inputs", {}),
+        "messages": new_messages,
+    }
+
+
+@as_runnable
+def _fetch_messages(state: SimulationState):
+    """Invoke the simulated user node."""
+    return state["messages"]
+
+
+def _convert_to_human_message(message: BaseMessage):
+    return {"messages": [HumanMessage(content=message.content)]}
+
+
+def _create_simulated_user_node(simulated_user: Runnable):
+    """Simulated user accepts a {"messages": [...]} argument and returns a single message."""
+    return (
+        _swap_roles
+        | RunnableLambda(_invoke_simulated_user).bind(simulated_user=simulated_user)
+        | _convert_to_human_message
+    )
+
+
+def _coerce_to_message(assistant_output: str | BaseMessage):
+    if isinstance(assistant_output, str):
+        return {"messages": [AIMessage(content=assistant_output)]}
+    else:
+        return {"messages": [assistant_output]}
+
+
+def _should_continue(state: SimulationState, max_turns: int = 6):
+    messages = state["messages"]
+    # TODO support other stop criteria
+    if len(messages) > max_turns:
+        return END
+    elif messages[-1].content.strip() == "FINISHED":
+        return END
+    else:
+        return "assistant"

docs/mkdocs.yml

@@ -56,29 +56,6 @@ 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:
@@ -203,7 +180,7 @@ nav:
               - how-tos/autogen-integration-functional.ipynb
           - Prebuilt ReAct Agent:
               - Prebuilt ReAct Agent: how-tos#prebuilt-react-agent
-              - how-tos/create-react-agent.md
+              - how-tos/create-react-agent.ipynb
               - how-tos/create-react-agent-memory.ipynb
               - how-tos/create-react-agent-system-prompt.ipynb
               - how-tos/create-react-agent-hitl.ipynb
@@ -253,6 +230,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
@@ -292,6 +270,7 @@ nav:
           - concepts/memory.md
           - concepts/streaming.md
           - concepts/functional_api.md
+          - concepts/durable_execution.md
         - LangGraph Platform:
           - LangGraph Platform: concepts#langgraph-platform
           - High Level:
@@ -377,6 +356,7 @@ nav:
             - tutorials/auth/resource_auth.md
             - tutorials/auth/add_auth_server.md
     - Resources:
+      # NOTE: prebuilt.md is auto-generated by `make build-prebuilt`
       - Prebuilt Agents: prebuilt.md
       - Adopters: adopters.md
       - FAQ: concepts/faq.md
@@ -467,6 +447,16 @@ markdown_extensions:
 hooks:
   - _scripts/notebook_hooks.py
 extra:
+  consent:
+    title: Cookie consent
+    actions:
+      - accept
+      - reject
+    description: >- 
+      We use cookies to recognize your repeated visits and preferences, as well
+      as to measure the effectiveness of our documentation and whether users
+      find what they're searching for. <strong>Clicking "Accept" makes our
+      documentation better. Thank you!</strong> ❤️
   social:
     - icon: fontawesome/brands/js
       link: https://langchain-ai.github.io/langgraphjs/
@@ -475,9 +465,9 @@ extra:
     - icon: fontawesome/brands/twitter
       link: https://twitter.com/LangChainAI
   analytics:
-    - provider: google
-    - property: G-G8X6ELZYE0
-    - feedback:
+    provider: google
+    property: G-G8X6ELZYE0
+    feedback:
       title: Was this page helpful?
       ratings:
         - icon: material/emoticon-happy-outline
@@ -508,3 +498,5 @@ validation:
   anchors: info
   # this is needed to handle headers with anchors for nav
   not_found: info
+copyright: >
+  Copyright &copy; 2025 LangChain, Inc | <a href="#__consent">Consent Preferences</a>

docs/pyproject.toml

@@ -9,7 +9,7 @@ readme = "README.md"
 [tool.poetry.dependencies]
 python = "^3.10"
 aiohappyeyeballs = "2.4.3"
-pygments-ansi-color = ">=0.3"
+hub = "^3.0.1"
 
 [tool.poetry.group.docs.dependencies]
 langgraph = { path = "../libs/langgraph/", develop = true }
@@ -17,6 +17,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"
@@ -28,10 +29,14 @@ mkdocs-material = {extras = ["imaging"], version = "^9.5.27"}
 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"
@@ -41,6 +46,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"

docs/tests/unit_tests/test_api_reference.py

@@ -0,0 +1,212 @@
+"""Test generation of links into the API reference."""
+
+import pytest
+
+from _scripts.generate_api_reference_links import (
+    update_markdown_with_imports,
+    get_imports,
+)
+
+MARKDOWN_IMPORTS = """\
+```python
+from langgraph.types import interrupt
+```
+"""
+
+EXPECTED_MARKDOWN = """\
+```python
+from langgraph.types import interrupt
+```
+
+API Reference: <a href="https://langchain-ai.github.io/langgraph/reference/types/#langgraph.types.interrupt">interrupt</a>
+"""
+
+
+def test_update_markdown_with_imports() -> None:
+    """Light weight end-to-end test."""
+    assert (
+        update_markdown_with_imports(MARKDOWN_IMPORTS, "some_path") == EXPECTED_MARKDOWN
+    )
+
+
+@pytest.mark.parametrize(
+    "code_block, expected_imports",
+    [
+        (
+            "from langgraph.types import interrupt",
+            [
+                {
+                    "docs": "https://langchain-ai.github.io/langgraph/reference/types/#langgraph.types.interrupt",
+                    "imported": "interrupt",
+                    "path": "some_path",
+                    "source": "langgraph.types",
+                }
+            ],
+        ),
+        (
+            "from langgraph.types import ( interrupt )",
+            [
+                {
+                    "docs": "https://langchain-ai.github.io/langgraph/reference/types/#langgraph.types.interrupt",
+                    "imported": "interrupt",
+                    "path": "some_path",
+                    "source": "langgraph.types",
+                }
+            ],
+        ),
+        (
+            "from langgraph.types import interrupt as foo",
+            [
+                {
+                    "docs": "https://langchain-ai.github.io/langgraph/reference/types/#langgraph.types.interrupt",
+                    "imported": "interrupt",
+                    "path": "some_path",
+                    "source": "langgraph.types",
+                }
+            ],
+        ),
+    ],
+)
+def test_get_imports(code_block: str, expected_imports: list) -> None:
+    """Get imports from a code block."""
+    assert (
+        get_imports(code_block, "some_path") == expected_imports
+    ), f"Failed for code_block=`{code_block}`"
+
+
+@pytest.mark.parametrize(
+    "code, expected_imports",
+    [
+        # Single import without parenthesis
+        (
+            "from langgraph.types import interrupt",
+            [
+                {
+                    "source": "langgraph.types",
+                    "imported": "interrupt",
+                }
+            ],
+        ),
+        # Multiple imports
+        (
+            (
+                "from langgraph.types import interrupt\n"
+                "from langgraph.func import task"
+            ),
+            [
+                {
+                    "source": "langgraph.types",
+                    "imported": "interrupt",
+                },
+                {
+                    "source": "langgraph.func",
+                    "imported": "task",
+                },
+            ],
+        ),
+        # Single import with parenthesis and extra whitespace
+        (
+            "from langgraph.types import ( interrupt )",
+            [
+                {
+                    "source": "langgraph.types",
+                    "imported": "interrupt",
+                }
+            ],
+        ),
+        # Single import with an alias
+        (
+            "from langgraph.types import interrupt as foo",
+            [
+                {
+                    "source": "langgraph.types",
+                    "imported": "interrupt",
+                }
+            ],
+        ),
+        # Multiple imports on one line with an alias
+        (
+            "from langgraph.types import interrupt, StreamWriter as bar",
+            [
+                {
+                    "source": "langgraph.types",
+                    "imported": "interrupt",
+                },
+                {
+                    "source": "langgraph.types",
+                    "imported": "StreamWriter",
+                },
+            ],
+        ),
+        # Multiple imports without aliases
+        (
+            "from langgraph.types import interrupt, StreamWriter",
+            [
+                {
+                    "source": "langgraph.types",
+                    "imported": "interrupt",
+                },
+                {
+                    "source": "langgraph.types",
+                    "imported": "StreamWriter",
+                },
+            ],
+        ),
+        # Multiline import with parenthesis and trailing comma
+        (
+            """from langgraph.types import (
+            interrupt,
+            StreamWriter as foo,
+            Command,
+        )""",
+            [
+                {
+                    "source": "langgraph.types",
+                    "imported": "interrupt",
+                },
+                {
+                    "source": "langgraph.types",
+                    "imported": "StreamWriter",
+                },
+                {
+                    "source": "langgraph.types",
+                    "imported": "Command",
+                },
+            ],
+        ),
+        # Multiline import with parenthesis and trailing comma
+        (
+            (
+                "from langgraph.types import (\n"
+                "        interrupt,\n"
+                "        StreamWriter as foo\n,"
+                "        Command,\n"
+                ")\n"
+                "def foo():\n"
+                "    pass\n"
+                ""
+            ),
+            [
+                {
+                    "source": "langgraph.types",
+                    "imported": "interrupt",
+                },
+                {
+                    "source": "langgraph.types",
+                    "imported": "StreamWriter",
+                },
+                {
+                    "source": "langgraph.types",
+                    "imported": "Command",
+                },
+            ],
+        ),
+    ],
+)
+def test_regexp_matching(code: str, expected_imports: list) -> None:
+    results = get_imports(code, "some_path")
+    for result in results:
+        del result["docs"]
+        del result["path"]
+
+    assert results == expected_imports

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" path="dummy.md"
+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,34 @@
+import pytest
+
+from _scripts.notebook_convert import (
+    _convert_links_in_markdown,
+    _has_output,
+)
+
+
+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

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

@@ -16,6 +16,7 @@ from langgraph.checkpoint.base import (
     CheckpointMetadata,
     CheckpointTuple,
     get_checkpoint_id,
+    get_checkpoint_metadata,
 )
 from langgraph.checkpoint.postgres import _internal
 from langgraph.checkpoint.postgres.base import BasePostgresSaver
@@ -317,17 +318,7 @@ class PostgresSaver(BasePostgresSaver):
                     checkpoint["id"],
                     checkpoint_id,
                     Jsonb(self._dump_checkpoint(copy)),
-                    self._dump_metadata(
-                        {
-                            **{
-                                k: v
-                                for k, v in config["configurable"].items()
-                                if not k.startswith("__")
-                            },
-                            **config.get("metadata", {}),
-                            **metadata,
-                        }
-                    ),
+                    self._dump_metadata(get_checkpoint_metadata(config, metadata)),
                 ),
             )
         return next_config

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

@@ -16,6 +16,7 @@ from langgraph.checkpoint.base import (
     CheckpointMetadata,
     CheckpointTuple,
     get_checkpoint_id,
+    get_checkpoint_metadata,
 )
 from langgraph.checkpoint.postgres import _ainternal
 from langgraph.checkpoint.postgres.base import BasePostgresSaver
@@ -275,17 +276,7 @@ class AsyncPostgresSaver(BasePostgresSaver):
                     checkpoint["id"],
                     checkpoint_id,
                     Jsonb(self._dump_checkpoint(copy)),
-                    self._dump_metadata(
-                        {
-                            **{
-                                k: v
-                                for k, v in config["configurable"].items()
-                                if not k.startswith("__")
-                            },
-                            **config.get("metadata", {}),
-                            **metadata,
-                        }
-                    ),
+                    self._dump_metadata(get_checkpoint_metadata(config, metadata)),
                 ),
             )
         return next_config

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

@@ -24,6 +24,7 @@ from langgraph.checkpoint.base import (
     Checkpoint,
     CheckpointMetadata,
     CheckpointTuple,
+    get_checkpoint_metadata,
 )
 from langgraph.checkpoint.postgres import _ainternal, _internal
 from langgraph.checkpoint.postgres.base import BasePostgresSaver
@@ -423,17 +424,7 @@ class ShallowPostgresSaver(BasePostgresSaver):
                     thread_id,
                     checkpoint_ns,
                     Jsonb(self._dump_checkpoint(copy)),
-                    self._dump_metadata(
-                        {
-                            **{
-                                k: v
-                                for k, v in config["configurable"].items()
-                                if not k.startswith("__")
-                            },
-                            **config.get("metadata", {}),
-                            **metadata,
-                        }
-                    ),
+                    self._dump_metadata(get_checkpoint_metadata(config, metadata)),
                 ),
             )
         return next_config
@@ -752,17 +743,7 @@ class AsyncShallowPostgresSaver(BasePostgresSaver):
                     thread_id,
                     checkpoint_ns,
                     Jsonb(self._dump_checkpoint(copy)),
-                    self._dump_metadata(
-                        {
-                            **{
-                                k: v
-                                for k, v in config["configurable"].items()
-                                if not k.startswith("__")
-                            },
-                            **config.get("metadata", {}),
-                            **metadata,
-                        }
-                    ),
+                    self._dump_metadata(get_checkpoint_metadata(config, metadata)),
                 ),
             )
         return next_config

libs/checkpoint-postgres/poetry.lock

@@ -187,22 +187,12 @@ description = "Cross-platform colored terminal text."
 optional = false
 python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7"
 groups = ["dev"]
+markers = "sys_platform == \"win32\""
 files = [
     {file = "colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6"},
     {file = "colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44"},
 ]
 
-[[package]]
-name = "docopt"
-version = "0.6.2"
-description = "Pythonic argument parser, that will make you smile"
-optional = false
-python-versions = "*"
-groups = ["dev"]
-files = [
-    {file = "docopt-0.6.2.tar.gz", hash = "sha256:49b3a825280bd66b3aa83585ef59c4a8c82f2c8a522dbe754a8bc8d08c85c491"},
-]
-
 [[package]]
 name = "exceptiongroup"
 version = "1.2.2"
@@ -358,7 +348,7 @@ typing-extensions = ">=4.7"
 
 [[package]]
 name = "langgraph-checkpoint"
-version = "2.0.10"
+version = "2.0.15"
 description = "Library with base interfaces for LangGraph checkpoint savers."
 optional = false
 python-versions = "^3.9.0,<4.0"
@@ -962,21 +952,20 @@ pytest = ">=6.2.5"
 dev = ["pre-commit", "pytest-asyncio", "tox"]
 
 [[package]]
-name = "pytest-watch"
-version = "4.2.0"
-description = "Local continuous test runner with pytest and watchdog."
+name = "pytest-watcher"
+version = "0.4.3"
+description = "Automatically rerun your tests on file modifications"
 optional = false
-python-versions = "*"
+python-versions = "<4.0.0,>=3.7.0"
 groups = ["dev"]
 files = [
-    {file = "pytest-watch-4.2.0.tar.gz", hash = "sha256:06136f03d5b361718b8d0d234042f7b2f203910d8568f63df2f866b547b3d4b9"},
+    {file = "pytest_watcher-0.4.3-py3-none-any.whl", hash = "sha256:d59b1e1396f33a65ea4949b713d6884637755d641646960056a90b267c3460f9"},
+    {file = "pytest_watcher-0.4.3.tar.gz", hash = "sha256:0cb0e4661648c8c0ff2b2d25efa5a8e421784b9e4c60fcecbf9b7c30b2d731b3"},
 ]
 
 [package.dependencies]
-colorama = ">=0.3.3"
-docopt = ">=0.4.0"
-pytest = ">=2.6.4"
-watchdog = ">=0.6.0"
+tomli = {version = ">=2.0.1,<3.0.0", markers = "python_version < \"3.11\""}
+watchdog = ">=2.0.0"
 
 [[package]]
 name = "pyyaml"
@@ -1266,4 +1255,4 @@ watchmedo = ["PyYAML (>=3.10)"]
 [metadata]
 lock-version = "2.1"
 python-versions = "^3.9.0,<4.0"
-content-hash = "61326e4e81a4e8854763a119f39d4f5d0a54cee868b4dbc91b95ce7d2cebba5b"
+content-hash = "369bfffecb9489835b43b8255932e043176a11d2f639aad2d055ffd89263ca1e"

libs/checkpoint-postgres/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "langgraph-checkpoint-postgres"
-version = "2.0.14"
+version = "2.0.15"
 description = "Library with a Postgres implementation of LangGraph checkpoint saver."
 authors = []
 license = "MIT"
@@ -10,7 +10,7 @@ packages = [{ include = "langgraph" }]
 
 [tool.poetry.dependencies]
 python = "^3.9.0,<4.0"
-langgraph-checkpoint = "^2.0.10"
+langgraph-checkpoint = "^2.0.15"
 orjson = ">=3.10.1"
 psycopg = "^3.2.0"
 psycopg-pool = "^3.2.0"
@@ -22,10 +22,10 @@ pytest = "^7.2.1"
 anyio = "^4.4.0"
 pytest-asyncio = "^0.21.1"
 pytest-mock = "^3.11.1"
-pytest-watch = "^4.2.0"
 mypy = "^1.10.0"
 psycopg = {extras = ["binary"], version = ">=3.0.0"}
 langgraph-checkpoint = {path = "../checkpoint", develop = true}
+pytest-watcher = "^0.4.3"
 
 [tool.pytest.ini_options]
 # --strict-markers will raise errors on unknown marks.
@@ -61,3 +61,9 @@ warn_unused_ignores = "True"
 warn_redundant_casts = "True"
 allow_redefinition = "True"
 disable_error_code = "typeddict-item, return-value"
+
+[tool.pytest-watcher]
+now = true
+delay = 0.1
+runner_args = ["--ff", "-x", "-v", "--tb", "short"]
+patterns = ["*.py"]

libs/checkpoint-postgres/tests/test_async.py

@@ -11,6 +11,7 @@ from psycopg.rows import dict_row
 from psycopg_pool import AsyncConnectionPool
 
 from langgraph.checkpoint.base import (
+    EXCLUDED_METADATA_KEYS,
     Checkpoint,
     CheckpointMetadata,
     create_checkpoint,
@@ -23,6 +24,10 @@ from langgraph.checkpoint.postgres.aio import (
 from tests.conftest import DEFAULT_POSTGRES_URI
 
 
+def _exclude_keys(config: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in config.items() if k not in EXCLUDED_METADATA_KEYS}
+
+
 @asynccontextmanager
 async def _pool_saver():
     """Fixture for pool mode testing."""
@@ -223,7 +228,6 @@ async def test_combined_metadata(saver_name: str, test_data) -> None:
         assert checkpoint.metadata == {
             **metadata,
             "thread_id": "thread-2",
-            "checkpoint_ns": "",
             "run_id": "my_run_id",
         }
 
@@ -251,14 +255,14 @@ async def test_asearch(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 == {
-            **configs[0]["configurable"],
+            **_exclude_keys(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 == {
-            **configs[1]["configurable"],
+            **_exclude_keys(configs[1]["configurable"]),
             **metadata[1],
         }
 

libs/checkpoint-postgres/tests/test_sync.py

@@ -12,6 +12,7 @@ from psycopg.rows import dict_row
 from psycopg_pool import ConnectionPool
 
 from langgraph.checkpoint.base import (
+    EXCLUDED_METADATA_KEYS,
     Checkpoint,
     CheckpointMetadata,
     create_checkpoint,
@@ -21,6 +22,10 @@ from langgraph.checkpoint.postgres import PostgresSaver, ShallowPostgresSaver
 from tests.conftest import DEFAULT_POSTGRES_URI
 
 
+def _exclude_keys(config: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in config.items() if k not in EXCLUDED_METADATA_KEYS}
+
+
 @contextmanager
 def _pool_saver():
     """Fixture for pool mode testing."""
@@ -205,7 +210,6 @@ def test_combined_metadata(saver_name: str, test_data) -> None:
         assert checkpoint.metadata == {
             **metadata,
             "thread_id": "thread-2",
-            "checkpoint_ns": "",
             "run_id": "my_run_id",
         }
 
@@ -233,14 +237,14 @@ 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 == {
-            **configs[0]["configurable"],
+            **_exclude_keys(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 == {
-            **configs[1]["configurable"],
+            **_exclude_keys(configs[1]["configurable"]),
             **metadata[1],
         }
 

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

@@ -15,6 +15,7 @@ from langgraph.checkpoint.base import (
     CheckpointTuple,
     SerializerProtocol,
     get_checkpoint_id,
+    get_checkpoint_metadata,
 )
 from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
 from langgraph.checkpoint.serde.types import ChannelProtocol
@@ -398,15 +399,7 @@ class SqliteSaver(BaseCheckpointSaver[str]):
         checkpoint_ns = config["configurable"]["checkpoint_ns"]
         type_, serialized_checkpoint = self.serde.dumps_typed(checkpoint)
         serialized_metadata = self.jsonplus_serde.dumps(
-            {
-                **{
-                    k: v
-                    for k, v in config["configurable"].items()
-                    if not k.startswith("__")
-                },
-                **config.get("metadata", {}),
-                **metadata,
-            }
+            get_checkpoint_metadata(config, metadata)
         )
         with self.cursor() as cur:
             cur.execute(

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

@@ -16,6 +16,7 @@ from langgraph.checkpoint.base import (
     CheckpointTuple,
     SerializerProtocol,
     get_checkpoint_id,
+    get_checkpoint_metadata,
 )
 from langgraph.checkpoint.serde.jsonplus import JsonPlusSerializer
 from langgraph.checkpoint.serde.types import ChannelProtocol
@@ -464,15 +465,7 @@ class AsyncSqliteSaver(BaseCheckpointSaver[str]):
         checkpoint_ns = config["configurable"]["checkpoint_ns"]
         type_, serialized_checkpoint = self.serde.dumps_typed(checkpoint)
         serialized_metadata = self.jsonplus_serde.dumps(
-            {
-                **{
-                    k: v
-                    for k, v in config["configurable"].items()
-                    if not k.startswith("__")
-                },
-                **config.get("metadata", {}),
-                **metadata,
-            }
+            get_checkpoint_metadata(config, metadata)
         )
         async with (
             self.lock,

libs/checkpoint-sqlite/poetry.lock

@@ -350,7 +350,7 @@ typing-extensions = ">=4.7"
 
 [[package]]
 name = "langgraph-checkpoint"
-version = "2.0.10"
+version = "2.0.15"
 description = "Library with base interfaces for LangGraph checkpoint savers."
 optional = false
 python-versions = "^3.9.0,<4.0"
@@ -1043,4 +1043,4 @@ watchmedo = ["PyYAML (>=3.10)"]
 [metadata]
 lock-version = "2.1"
 python-versions = "^3.9.0"
-content-hash = "03c697eae6f550f3c7e29f1d61f4c409dabe04ae8d43281728e549174d2fc670"
+content-hash = "e6d3ca9bce723c05f4c5ae9dc4bee872f7581b7763680b34112f1d280f5a9b0a"

libs/checkpoint-sqlite/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "langgraph-checkpoint-sqlite"
-version = "2.0.4"
+version = "2.0.5"
 description = "Library with a SQLite implementation of LangGraph checkpoint saver."
 authors = []
 license = "MIT"
@@ -10,7 +10,7 @@ packages = [{ include = "langgraph" }]
 
 [tool.poetry.dependencies]
 python = "^3.9.0"
-langgraph-checkpoint = "^2.0.10"
+langgraph-checkpoint = "^2.0.15"
 aiosqlite = "^0.20.0"
 
 [tool.poetry.group.dev.dependencies]

libs/checkpoint-sqlite/tests/test_aiosqlite.py

@@ -72,7 +72,6 @@ class TestAsyncSqliteSaver:
             assert checkpoint.metadata == {
                 **self.metadata_2,
                 "thread_id": "thread-2",
-                "checkpoint_ns": "",
                 "run_id": "my_run_id",
             }
 
@@ -94,14 +93,15 @@ 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.config_1["configurable"],
+                "thread_id": "thread-1",
+                "thread_ts": "1",
                 **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.config_2["configurable"],
+                "thread_id": "thread-2",
                 **self.metadata_2,
             }
 

libs/checkpoint-sqlite/tests/test_sqlite.py

@@ -73,7 +73,6 @@ class TestSqliteSaver:
             assert checkpoint.metadata == {
                 **self.metadata_2,
                 "thread_id": "thread-2",
-                "checkpoint_ns": "",
                 "run_id": "my_run_id",
             }
 
@@ -97,14 +96,15 @@ 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.config_1["configurable"],
+                "thread_id": "thread-1",
+                "thread_ts": "1",
                 **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.config_2["configurable"],
+                "thread_id": "thread-2",
                 **self.metadata_2,
             }
 

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

@@ -446,6 +446,23 @@ def get_checkpoint_id(config: RunnableConfig) -> Optional[str]:
     )
 
 
+def get_checkpoint_metadata(
+    config: RunnableConfig, metadata: CheckpointMetadata
+) -> CheckpointMetadata:
+    """Get checkpoint metadata in a backwards-compatible manner."""
+    metadata = metadata.copy()
+    for obj in (config.get("metadata"), config.get("configurable")):
+        if not obj:
+            continue
+        for key in obj:
+            if key in metadata or key in EXCLUDED_METADATA_KEYS or key.startswith("__"):
+                continue
+            v = obj[key]
+            if isinstance(v, (str, int, bool, float)):
+                metadata[key] = v  # type: ignore[literal-required]
+    return metadata
+
+
 """
 Mapping from error type to error index.
 Regular writes just map to their index in the list of writes being saved.
@@ -454,3 +471,9 @@ conflicting with regular writes.
 Each Checkpointer implementation should use this mapping in put_writes.
 """
 WRITES_IDX_MAP = {ERROR: -1, SCHEDULED: -2, INTERRUPT: -3, RESUME: -4}
+
+EXCLUDED_METADATA_KEYS = {
+    "checkpoint_id",
+    "checkpoint_ns",
+    "checkpoint_map",
+}

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

@@ -20,6 +20,7 @@ from langgraph.checkpoint.base import (
     CheckpointTuple,
     SerializerProtocol,
     get_checkpoint_id,
+    get_checkpoint_metadata,
 )
 from langgraph.checkpoint.serde.types import TASKS, ChannelProtocol
 
@@ -356,17 +357,7 @@ class InMemorySaver(
             {
                 checkpoint["id"]: (
                     self.serde.dumps_typed(c),
-                    self.serde.dumps_typed(
-                        {
-                            **{
-                                k: v
-                                for k, v in config["configurable"].items()
-                                if not k.startswith("__")
-                            },
-                            **config.get("metadata", {}),
-                            **metadata,
-                        }
-                    ),
+                    self.serde.dumps_typed(get_checkpoint_metadata(config, metadata)),
                     config["configurable"].get("checkpoint_id"),  # parent
                 )
             }

libs/checkpoint/langgraph/checkpoint/serde/jsonplus.py

@@ -5,6 +5,7 @@ import json
 import pathlib
 import re
 from collections import deque
+from collections.abc import Sequence
 from datetime import date, datetime, time, timedelta, timezone
 from enum import Enum
 from inspect import isclass
@@ -16,7 +17,7 @@ from ipaddress import (
     IPv6Interface,
     IPv6Network,
 )
-from typing import Any, Callable, Optional, Sequence, Union, cast
+from typing import Any, Callable, Optional, Union, cast
 from uuid import UUID
 
 import msgpack  # type: ignore[import-untyped]
@@ -502,15 +503,5 @@ def _msgpack_ext_hook(code: int, data: bytes) -> Any:
             return
 
 
-ENC_POOL: deque[msgpack.Packer] = deque(maxlen=32)
-
-
 def _msgpack_enc(data: Any) -> bytes:
-    try:
-        enc = ENC_POOL.popleft()
-    except IndexError:
-        enc = msgpack.Packer(default=_msgpack_default)
-    try:
-        return enc.pack(data)
-    finally:
-        ENC_POOL.append(enc)
+    return msgpack.packb(data, default=_msgpack_default)

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

@@ -1,7 +1,8 @@
 import asyncio
 import functools
 import weakref
-from typing import Any, Callable, Iterable, Literal, Optional, TypeVar, Union
+from collections.abc import Iterable
+from typing import Any, Callable, Literal, Optional, TypeVar, Union
 
 from langgraph.store.base import (
     BaseStore,
@@ -54,19 +55,23 @@ class AsyncBatchedBaseStore(BaseStore):
     def __init__(self) -> None:
         super().__init__()
         self._loop = asyncio.get_running_loop()
-        self._aqueue: dict[asyncio.Future, Op] = {}
+        self._aqueue: asyncio.Queue[tuple[asyncio.Future, Op]] = asyncio.Queue()
         self._task = self._loop.create_task(_run(self._aqueue, weakref.ref(self)))
 
     def __del__(self) -> None:
-        self._task.cancel()
+        try:
+            self._task.cancel()
+        except RuntimeError:
+            pass
 
     async def aget(
         self,
         namespace: tuple[str, ...],
         key: str,
     ) -> Optional[Item]:
+        assert not self._task.done()
         fut = self._loop.create_future()
-        self._aqueue[fut] = GetOp(namespace, key)
+        self._aqueue.put_nowait((fut, GetOp(namespace, key)))
         return await fut
 
     async def asearch(
@@ -79,8 +84,11 @@ class AsyncBatchedBaseStore(BaseStore):
         limit: int = 10,
         offset: int = 0,
     ) -> list[SearchItem]:
+        assert not self._task.done()
         fut = self._loop.create_future()
-        self._aqueue[fut] = SearchOp(namespace_prefix, filter, limit, offset, query)
+        self._aqueue.put_nowait(
+            (fut, SearchOp(namespace_prefix, filter, limit, offset, query))
+        )
         return await fut
 
     async def aput(
@@ -90,9 +98,10 @@ class AsyncBatchedBaseStore(BaseStore):
         value: dict[str, Any],
         index: Optional[Union[Literal[False], list[str]]] = None,
     ) -> None:
+        assert not self._task.done()
         _validate_namespace(namespace)
         fut = self._loop.create_future()
-        self._aqueue[fut] = PutOp(namespace, key, value, index)
+        self._aqueue.put_nowait((fut, PutOp(namespace, key, value, index)))
         return await fut
 
     async def adelete(
@@ -100,8 +109,9 @@ class AsyncBatchedBaseStore(BaseStore):
         namespace: tuple[str, ...],
         key: str,
     ) -> None:
+        assert not self._task.done()
         fut = self._loop.create_future()
-        self._aqueue[fut] = PutOp(namespace, key, None)
+        self._aqueue.put_nowait((fut, PutOp(namespace, key, None)))
         return await fut
 
     async def alist_namespaces(
@@ -113,6 +123,7 @@ class AsyncBatchedBaseStore(BaseStore):
         limit: int = 100,
         offset: int = 0,
     ) -> list[tuple[str, ...]]:
+        assert not self._task.done()
         fut = self._loop.create_future()
         match_conditions = []
         if prefix:
@@ -126,7 +137,7 @@ class AsyncBatchedBaseStore(BaseStore):
             limit=limit,
             offset=offset,
         )
-        self._aqueue[fut] = op
+        self._aqueue.put_nowait((fut, op))
         return await fut
 
     @_check_loop
@@ -250,34 +261,38 @@ def _dedupe_ops(values: list[Op]) -> tuple[Optional[list[int]], list[Op]]:
 
 
 async def _run(
-    aqueue: dict[asyncio.Future, Op],
+    aqueue: asyncio.Queue[tuple[asyncio.Future, Op]],
     store: weakref.ReferenceType[BaseStore],
 ) -> None:
-    while True:
-        await asyncio.sleep(0)
-        if not aqueue:
-            continue
+    while item := await aqueue.get():
+        # check if store is still alive
         if s := store():
-            # get the operations to run
-            taken = aqueue.copy()
-            # action each operation
             try:
-                values = list(taken.values())
-                listen, dedupped = _dedupe_ops(values)
-                results = await s.abatch(dedupped)
-                if listen is not None:
-                    results = [results[ix] for ix in listen]
+                # accumulate operations scheduled in same tick
+                items = [item]
+                try:
+                    while item := aqueue.get_nowait():
+                        items.append(item)
+                except asyncio.QueueEmpty:
+                    pass
+                # get the operations to run
+                futs = [item[0] for item in items]
+                values = [item[1] for item in items]
+                # action each operation
+                try:
+                    listen, dedupped = _dedupe_ops(values)
+                    results = await s.abatch(dedupped)
+                    if listen is not None:
+                        results = [results[ix] for ix in listen]
 
-                # set the results of each operation
-                for fut, result in zip(taken, results):
-                    fut.set_result(result)
-            except Exception as e:
-                for fut in taken:
-                    fut.set_exception(e)
-            # remove the operations from the queue
-            for fut in taken:
-                del aqueue[fut]
+                    # set the results of each operation
+                    for fut, result in zip(futs, results):
+                        fut.set_result(result)
+                except Exception as e:
+                    for fut in futs:
+                        fut.set_exception(e)
+            finally:
+                # remove strong ref to store
+                del s
         else:
             break
-        # remove strong ref to store
-        del s

libs/checkpoint/pyproject.toml

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

libs/checkpoint/tests/test_memory.py

@@ -60,7 +60,7 @@ class TestMemorySaver:
         self.metadata_3: CheckpointMetadata = {}
 
     def test_combined_metadata(self) -> None:
-        config = {
+        config: RunnableConfig = {
             "configurable": {
                 "thread_id": "thread-2",
                 "checkpoint_ns": "",
@@ -70,10 +70,10 @@ class TestMemorySaver:
         }
         self.memory_saver.put(config, self.chkpnt_2, self.metadata_2, {})
         checkpoint = self.memory_saver.get_tuple(config)
+        assert checkpoint is not None
         assert checkpoint.metadata == {
             **self.metadata_2,
             "thread_id": "thread-2",
-            "checkpoint_ns": "",
             "run_id": "my_run_id",
         }
 
@@ -96,14 +96,15 @@ 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.config_1["configurable"],
+            "thread_id": "thread-1",
+            "thread_ts": "1",
             **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.config_2["configurable"],
+            "thread_id": "thread-2",
             **self.metadata_2,
         }
 
@@ -146,7 +147,8 @@ class TestMemorySaver:
         ]
         assert len(search_results_1) == 1
         assert search_results_1[0].metadata == {
-            **self.config_1["configurable"],
+            "thread_id": "thread-1",
+            "thread_ts": "1",
             **self.metadata_1,
         }
 
@@ -155,7 +157,7 @@ class TestMemorySaver:
         ]
         assert len(search_results_2) == 1
         assert search_results_2[0].metadata == {
-            **self.config_2["configurable"],
+            "thread_id": "thread-2",
             **self.metadata_2,
         }
 

libs/cli/examples/my_app.py

@@ -0,0 +1,62 @@
+from contextlib import asynccontextmanager
+from contextvars import ContextVar
+from typing import Any
+
+from starlette.applications import Starlette
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import JSONResponse
+from starlette.routing import Route
+
+my_context_var: ContextVar[str] = ContextVar("my_context_var", default="")
+LIFESPAN_VAL = ""
+other_context_var = ContextVar("other_context_var", default="")
+
+
+@asynccontextmanager
+async def my_lifespan(app):
+    global LIFESPAN_VAL
+    LIFESPAN_VAL = "foobar-lifespan"
+    yield
+    assert LIFESPAN_VAL == "foobar-lifespan"
+    LIFESPAN_VAL = ""
+
+
+class MyContextMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Any, call_next: Any) -> Any:
+        token = my_context_var.set("Foobar")
+        try:
+            response = await call_next(request)
+            return response
+        finally:
+            my_context_var.reset(token)
+
+
+async def custom_my_route(request):
+    """A great route."""
+    assert my_context_var.get() == "Foobar"
+    assert LIFESPAN_VAL == "foobar-lifespan"
+    return JSONResponse({"foo": "bar"})
+
+
+async def runs_afakeroute(request):
+    """Another great route."""
+    assert my_context_var.get() == "Foobar"
+    assert LIFESPAN_VAL == "foobar-lifespan"
+    return JSONResponse({"foo": "afakeroute"})
+
+
+async def other_middleware(request: Any, call_next: Any) -> Any:
+    other_context_var.set("foobar")
+    response = await call_next(request)
+    other_context_var.reset()
+    return response
+
+
+app = Starlette(
+    middleware=[(MyContextMiddleware, {}, {})],
+    routes=[
+        Route("/custom/my-route", custom_my_route),
+        Route("/runs/afakeroute", runs_afakeroute),
+    ],
+    lifespan=my_lifespan,
+)

libs/cli/langgraph_cli/cli.py

@@ -303,7 +303,15 @@ def _build(
         tag,
     ]
     # apply config
-    stdin = langgraph_cli.config.config_to_docker(config, config_json, base_image)
+    stdin, additional_contexts = langgraph_cli.config.config_to_docker(
+        config, config_json, base_image
+    )
+    # add additional_contexts
+    if additional_contexts:
+        additional_contexts_str = ",".join(
+            f"{k}={v}" for k, v in additional_contexts.items()
+        )
+        args.extend(["--build-context", additional_contexts_str])
     # run docker build
     runner.run(
         subp_exec(
@@ -439,20 +447,28 @@ def dockerfile(save_path: str, config: pathlib.Path, add_docker_compose: bool) -
     secho("✅ Configuration validated!", fg="green")
 
     secho(f"📝 Generating Dockerfile at {save_path}", fg="yellow")
+    dockerfile, additional_contexts = langgraph_cli.config.config_to_docker(
+        config,
+        config_json,
+        (
+            "langchain/langgraphjs-api"
+            if config_json.get("node_version")
+            else "langchain/langgraph-api"
+        ),
+    )
     with open(str(save_path), "w", encoding="utf-8") as f:
-        f.write(
-            langgraph_cli.config.config_to_docker(
-                config,
-                config_json,
-                (
-                    "langchain/langgraphjs-api"
-                    if config_json.get("node_version")
-                    else "langchain/langgraph-api"
-                ),
-            )
-        )
+        f.write(dockerfile)
     secho("✅ Created: Dockerfile", fg="green")
 
+    if additional_contexts:
+        additional_contexts_str = ",".join(
+            f"{k}={v}" for k, v in additional_contexts.items()
+        )
+        secho(
+            f"""📝 Run docker build with these additional build contexts `--build-context {additional_contexts_str}`""",
+            fg="yellow",
+        )
+
     if add_docker_compose:
         # Add docker compose and related files
         # Add .dockerignore file in the same directory as the Dockerfile
@@ -575,7 +591,7 @@ def dev(
 ):
     """CLI entrypoint for running the LangGraph API server."""
     try:
-        from langgraph_api.cli import run_server
+        from langgraph_api.cli import run_server  # type: ignore
     except ImportError:
         py_version_msg = ""
         if sys.version_info < (3, 11):
@@ -634,6 +650,7 @@ def dev(
         store=config_json.get("store"),
         wait_for_client=wait_for_client,
         auth=config_json.get("auth"),
+        http=config_json.get("http"),
     )
 
 
@@ -662,6 +679,7 @@ def prepare_args_and_stdin(
     debugger_base_url: Optional[str] = None,
     postgres_uri: Optional[str] = None,
 ) -> Tuple[List[str], str]:
+    assert config_path.exists(), f"Config file not found: {config_path}"
     # prepare args
     stdin = langgraph_cli.docker.compose(
         capabilities,

libs/cli/langgraph_cli/config.py

@@ -2,6 +2,7 @@ import json
 import os
 import pathlib
 import textwrap
+from collections import Counter
 from typing import NamedTuple, Optional, TypedDict, Union
 
 import click
@@ -85,6 +86,33 @@ class AuthConfig(TypedDict, total=False):
     """
 
 
+class CorsConfig(TypedDict, total=False):
+    allow_origins: list[str]
+    allow_methods: list[str]
+    allow_headers: list[str]
+    allow_credentials: bool
+    allow_origin_regex: str
+    expose_headers: list[str]
+    max_age: int
+
+
+class HttpConfig(TypedDict, total=False):
+    app: str
+    """Import path for a custom Starlette/FastAPI app to mount"""
+    disable_assistants: bool
+    """Disable /assistants routes"""
+    disable_threads: bool
+    """Disable /threads routes"""
+    disable_runs: bool
+    """Disable /runs routes"""
+    disable_store: bool
+    """Disable /store routes"""
+    disable_meta: bool
+    """Disable /ok, /info, /metrics, and /docs routes"""
+    cors: Optional[CorsConfig]
+    """Cross-Origin Resource Sharing (CORS) configuration"""
+
+
 class Config(TypedDict, total=False):
     """Configuration for langgraph-cli."""
 
@@ -123,6 +151,9 @@ class Config(TypedDict, total=False):
     auth: Optional[AuthConfig]
     """Configuration for authentication."""
 
+    http: Optional[HttpConfig]
+    """Configuration for HTTP server."""
+
 
 def _parse_version(version_str: str) -> tuple[int, int]:
     """Parse a version string into a tuple of (major, minor)."""
@@ -157,6 +188,7 @@ def validate_config(config: Config) -> Config:
             "env": config.get("env", {}),
             "store": config.get("store"),
             "auth": config.get("auth"),
+            "http": config.get("http"),
         }
         if config.get("node_version")
         else {
@@ -168,6 +200,7 @@ def validate_config(config: Config) -> Config:
             "env": config.get("env", {}),
             "store": config.get("store"),
             "auth": config.get("auth"),
+            "http": config.get("http"),
         }
     )
 
@@ -220,7 +253,13 @@ def validate_config(config: Config) -> Config:
                     f"Invalid auth.path format: '{auth_conf['path']}'. "
                     "Must be in format './path/to/file.py:attribute_name'"
                 )
-
+    if http_conf := config.get("http"):
+        if "app" in http_conf:
+            if ":" not in http_conf["app"]:
+                raise ValueError(
+                    f"Invalid http.app format: '{http_conf['app']}'. "
+                    "Must be in format './path/to/file.py:attribute_name'"
+                )
     return config
 
 
@@ -294,10 +333,10 @@ class LocalDeps(NamedTuple):
             tuples. Each entry points to a local `requirements.txt` file and where
             it should be placed inside the Docker container before running `pip install`.
 
-        real_pkgs: A dictionary mapping a local directory path (host side) to the
-            same dependency string from the config. These directories contain the
-            necessary files (e.g., `pyproject.toml` or `setup.py`) to be installed
-            as a standard Python package with pip.
+        real_pkgs: A dictionary mapping a local directory path (host side) to a
+            tuple of (dependency_string, container_package_path). These directories
+            contain the necessary files (e.g., `pyproject.toml` or `setup.py`) to be
+            installed as a standard Python package with pip.
 
         faux_pkgs: A dictionary mapping a local directory path (host side) to a
             tuple of (dependency_string, container_package_path). For these
@@ -310,16 +349,23 @@ class LocalDeps(NamedTuple):
             directory. If the local dependency `"."` is present in the config, this
             field captures the path where that dependency will appear in the
             container (e.g., `/deps/<name>` or similar). Otherwise, it may be `None`.
+
+        additional_contexts: A list of paths to directories that contain local
+            dependencies in parent directories. These directories are added to the
+            Docker build context to ensure that the Dockerfile can access them.
     """
 
-    pip_reqs: list[tuple[str, str]]
-    real_pkgs: dict[pathlib.Path, str]
+    pip_reqs: list[tuple[pathlib.Path, str]]
+    real_pkgs: dict[pathlib.Path, tuple[str, str]]
     faux_pkgs: dict[pathlib.Path, tuple[str, str]]
     # if . is in dependencies, use it as working_dir
     working_dir: Optional[str] = None
+    # if there are local dependencies in parent directories, use additional_contexts
+    additional_contexts: list[pathlib.Path] = None
 
 
 def _assemble_local_deps(config_path: pathlib.Path, config: Config) -> LocalDeps:
+    config_path = config_path.resolve()
     # ensure reserved package names are not used
     reserved = {
         "src",
@@ -336,6 +382,7 @@ def _assemble_local_deps(config_path: pathlib.Path, config: Config) -> LocalDeps
         "httpx",
         "langsmith",
     }
+    counter = Counter()
 
     def check_reserved(name: str, ref: str):
         if name in reserved:
@@ -348,7 +395,8 @@ def _assemble_local_deps(config_path: pathlib.Path, config: Config) -> LocalDeps
     pip_reqs = []
     real_pkgs = {}
     faux_pkgs = {}
-    working_dir = None
+    working_dir: Optional[str] = None
+    additional_contexts: list[pathlib.Path] = []
 
     for local_dep in config["dependencies"]:
         if not local_dep.startswith("."):
@@ -357,7 +405,7 @@ def _assemble_local_deps(config_path: pathlib.Path, config: Config) -> LocalDeps
 
         # Verify that the local dependency can be resolved
         # (e.g., this would raise an informative error if a user mistyped a path).
-        resolved = config_path.parent / local_dep
+        resolved = (config_path.parent / local_dep).resolve()
 
         # validate local dependency
         if not resolved.exists():
@@ -366,25 +414,28 @@ def _assemble_local_deps(config_path: pathlib.Path, config: Config) -> LocalDeps
             raise NotADirectoryError(
                 f"Local dependency must be a directory: {resolved}"
             )
-        elif not resolved.is_relative_to(config_path.parent):
-            raise ValueError(
-                f"Local dependency '{resolved}' must be a subdirectory of '{config_path.parent}'"
-            )
+        elif resolved == config_path.parent:
+            pass
+        elif config_path.parent not in resolved.parents:
+            additional_contexts.append(resolved)
 
         # Check for pyproject.toml or setup.py
         # If found, treat as a real package, if not treat as a faux package.
         # For faux packages, we'll also check for presence of requirements.txt.
         files = os.listdir(resolved)
-        if "pyproject.toml" in files:
+        if "pyproject.toml" in files or "setup.py" in files:
             # real package
-            real_pkgs[resolved] = local_dep
+
+            # assign a unique folder name
+            container_name = resolved.name
+            if counter[container_name] > 0:
+                container_name += f"_{counter[container_name]}"
+            counter[container_name] += 1
+            # add to deps
+            real_pkgs[resolved] = (local_dep, container_name)
+            # set working_dir
             if local_dep == ".":
-                working_dir = f"/deps/{resolved.name}"
-        elif "setup.py" in files:
-            # real package
-            real_pkgs[resolved] = local_dep
-            if local_dep == ".":
-                working_dir = f"/deps/{resolved.name}"
+                working_dir = f"/deps/{container_name}"
         else:
             # We could not find a pyproject.toml or setup.py, so treat as a faux package
             if any(file == "__init__.py" for file in files):
@@ -423,12 +474,12 @@ def _assemble_local_deps(config_path: pathlib.Path, config: Config) -> LocalDeps
                 rfile = resolved / "requirements.txt"
                 pip_reqs.append(
                     (
-                        rfile.relative_to(config_path.parent).as_posix(),
+                        rfile,
                         f"{container_path}/requirements.txt",
                     )
                 )
 
-    return LocalDeps(pip_reqs, real_pkgs, faux_pkgs, working_dir)
+    return LocalDeps(pip_reqs, real_pkgs, faux_pkgs, working_dir, additional_contexts)
 
 
 def _update_graph_paths(
@@ -554,9 +605,62 @@ def _update_auth_path(
     )
 
 
+def _update_http_app_path(
+    config_path: pathlib.Path, config: Config, local_deps: LocalDeps
+) -> None:
+    """Update the HTTP app path to point to the correct location in the Docker container.
+
+    Similar to _update_graph_paths, this ensures that if a custom app is specified via
+    a local file path, that file is included in the Docker build context and its path
+    is updated to point to the correct location in the container.
+    """
+    if not (http_config := config.get("http")) or not (
+        app_str := http_config.get("app")
+    ):
+        return
+
+    module_str, _, attr_str = app_str.partition(":")
+    if not module_str or not attr_str:
+        message = (
+            'Import string "{import_str}" must be in format "<module>:<attribute>".'
+        )
+        raise ValueError(message.format(import_str=app_str))
+
+    # Check if it's a file path
+    if "/" in module_str or "\\" in module_str:
+        # Resolve the local path properly on the current OS
+        resolved = (config_path.parent / module_str).resolve()
+        if not resolved.exists():
+            raise FileNotFoundError(f"Could not find HTTP app module: {resolved}")
+        elif not resolved.is_file():
+            raise IsADirectoryError(f"HTTP app module must be a file: {resolved}")
+        else:
+            for path in local_deps.real_pkgs:
+                if resolved.is_relative_to(path):
+                    container_path = (
+                        pathlib.Path("/deps") / path.name / resolved.relative_to(path)
+                    )
+                    module_str = container_path.as_posix()
+                    break
+            else:
+                for faux_pkg, (_, destpath) in local_deps.faux_pkgs.items():
+                    if resolved.is_relative_to(faux_pkg):
+                        container_subpath = resolved.relative_to(faux_pkg)
+                        # Construct the final path, ensuring POSIX style
+                        module_str = f"{destpath}/{container_subpath.as_posix()}"
+                        break
+                else:
+                    raise ValueError(
+                        f"HTTP app module '{app_str}' not found in 'dependencies' list. "
+                        "Add its containing package to 'dependencies' list."
+                    )
+        # update the config
+        http_config["app"] = f"{module_str}:{attr_str}"
+
+
 def python_config_to_docker(
     config_path: pathlib.Path, config: Config, base_image: str
-) -> str:
+) -> tuple[str, dict[str, str]]:
     """Generate a Dockerfile from the configuration."""
     # configure pip
     pip_install = (
@@ -577,13 +681,21 @@ def python_config_to_docker(
     _update_graph_paths(config_path, config, local_deps)
     # Rewrite auth path, so it points to the correct location in the Docker container
     _update_auth_path(config_path, config, local_deps)
+    # Rewrite HTTP app path, so it points to the correct location in the Docker container
+    _update_http_app_path(config_path, config, local_deps)
 
     pip_pkgs_str = f"RUN {pip_install} {' '.join(pypi_deps)}" if pypi_deps else ""
     if local_deps.pip_reqs:
         pip_reqs_str = os.linesep.join(
-            f"ADD {reqpath} {destpath}" for reqpath, destpath in local_deps.pip_reqs
+            f"COPY --from=__outer_{reqpath.name} requirements.txt {destpath}"
+            if reqpath.parent in local_deps.additional_contexts
+            else f"ADD {reqpath.relative_to(config_path.parent)} {destpath}"
+            for reqpath, destpath in local_deps.pip_reqs
         )
         pip_reqs_str += f'{os.linesep}RUN {pip_install} {" ".join("-r " + r for _,r in local_deps.pip_reqs)}'
+        pip_reqs_str = f"""# -- Installing local requirements --
+{pip_reqs_str}
+# -- End of local requirements install --"""
 
     else:
         pip_reqs_str = ""
@@ -591,7 +703,14 @@ def python_config_to_docker(
     # https://setuptools.pypa.io/en/latest/userguide/datafiles.html#package-data
     # https://til.simonwillison.net/python/pyproject
     faux_pkgs_str = f"{os.linesep}{os.linesep}".join(
-        f"""ADD {relpath} {destpath}
+        (
+            f"""# -- Adding non-package dependency {fullpath.name} --
+COPY --from=__outer_{fullpath.name} . {destpath}"""
+            if fullpath in local_deps.additional_contexts
+            else f"""# -- Adding non-package dependency {fullpath.name} --
+ADD {relpath} {destpath}"""
+        )
+        + f"""
 RUN set -ex && \\
     for line in '[project]' \\
                 'name = "{fullpath.name}"' \\
@@ -599,12 +718,20 @@ RUN set -ex && \\
                 '[tool.setuptools.package-data]' \\
                 '"*" = ["**/*"]'; do \\
         echo "$line" >> /deps/__outer_{fullpath.name}/pyproject.toml; \\
-    done"""
+    done
+# -- End of non-package dependency {fullpath.name} --"""
         for fullpath, (relpath, destpath) in local_deps.faux_pkgs.items()
     )
+
     local_pkgs_str = os.linesep.join(
-        f"ADD {relpath} /deps/{fullpath.name}"
-        for fullpath, relpath in local_deps.real_pkgs.items()
+        f"""# -- Adding local package {relpath} --
+COPY --from={name} . /deps/{name}
+# -- End of local package {relpath} --"""
+        if fullpath in local_deps.additional_contexts
+        else f"""# -- Adding local package {relpath} --
+ADD {relpath} /deps/{name}
+# -- End of local package {relpath} --"""
+        for fullpath, (relpath, name) in local_deps.real_pkgs.items()
     )
 
     installs = f"{os.linesep}{os.linesep}".join(
@@ -628,6 +755,9 @@ RUN set -ex && \\
     if (auth_config := config.get("auth")) is not None:
         env_vars.append(f"ENV LANGGRAPH_AUTH='{json.dumps(auth_config)}'")
 
+    if (http_config := config.get("http")) is not None:
+        env_vars.append(f"ENV LANGGRAPH_HTTP='{json.dumps(http_config)}'")
+
     graphs = config["graphs"]
     env_vars.append(f"ENV LANGSERVE_GRAPHS='{json.dumps(graphs)}'")
 
@@ -638,15 +768,30 @@ RUN set -ex && \\
         "",
         installs,
         "",
+        "# -- Installing all local dependencies --",
         f"RUN {pip_install} -e /deps/*",
+        "# -- End of local dependencies install --",
         os.linesep.join(env_vars),
         "",
         f"WORKDIR {local_deps.working_dir}" if local_deps.working_dir else "",
     ]
-    return os.linesep.join(docker_file_contents)
+
+    additional_contexts: dict[str, str] = {}
+    for p in local_deps.additional_contexts:
+        if p in local_deps.real_pkgs:
+            name = local_deps.real_pkgs[p][1]
+        elif p in local_deps.faux_pkgs:
+            name = f"__outer_{p.name}"
+        else:
+            raise RuntimeError(f"Unknown additional context: {p}")
+        additional_contexts[name] = str(p)
+
+    return os.linesep.join(docker_file_contents), additional_contexts
 
 
-def node_config_to_docker(config_path: pathlib.Path, config: Config, base_image: str):
+def node_config_to_docker(
+    config_path: pathlib.Path, config: Config, base_image: str
+) -> tuple[str, dict[str, str]]:
     faux_path = f"/deps/{config_path.parent.name}"
 
     def test_file(file_name):
@@ -684,9 +829,14 @@ ENV LANGGRAPH_STORE='{json.dumps(store_config)}'
     if (auth_config := config.get("auth")) is not None:
         env_additional_config += f"""
 ENV LANGGRAPH_AUTH='{json.dumps(auth_config)}'
+"""
+    if (http_config := config.get("http")) is not None:
+        env_additional_config += f"""
+ENV LANGGRAPH_HTTP='{json.dumps(http_config)}'
 """
 
-    return f"""FROM {base_image}:{config['node_version']}
+    return (
+        f"""FROM {base_image}:{config['node_version']}
 
 {os.linesep.join(config["dockerfile_lines"])}
 
@@ -698,10 +848,14 @@ ENV LANGSERVE_GRAPHS='{json.dumps(config["graphs"])}'
 
 WORKDIR {faux_path}
 
-RUN (test ! -f /api/langgraph_api/js/build.mts && echo "Prebuild script not found, skipping") || tsx /api/langgraph_api/js/build.mts"""
+RUN (test ! -f /api/langgraph_api/js/build.mts && echo "Prebuild script not found, skipping") || tsx /api/langgraph_api/js/build.mts""",
+        {},
+    )
 
 
-def config_to_docker(config_path: pathlib.Path, config: Config, base_image: str):
+def config_to_docker(
+    config_path: pathlib.Path, config: Config, base_image: str
+) -> tuple[str, dict[str, str]]:
     if config.get("node_version"):
         return node_config_to_docker(config_path, config, base_image)
 
@@ -737,13 +891,24 @@ def config_to_compose(
     else:
         watch_str = ""
 
+    dockerfile, additional_contexts = config_to_docker(config_path, config, base_image)
+
+    additional_contexts_str = "\n".join(
+        f"                - {name}: {path}"
+        for name, path in additional_contexts.items()
+    )
+    if additional_contexts_str:
+        additional_contexts_str = f"""
+            additional_contexts:
+{additional_contexts_str}"""
+
     return f"""
 {textwrap.indent(env_vars_str, "            ")}
         {env_file_str}
         pull_policy: build
         build:
-            context: .
+            context: .{additional_contexts_str}
             dockerfile_inline: |
-{textwrap.indent(config_to_docker(config_path, config, base_image), "                ")}
+{textwrap.indent(dockerfile, "                ")}
         {watch_str}
 """

libs/cli/langgraph_cli/docker.py

@@ -49,7 +49,9 @@ def check_capabilities(runner) -> DockerCapabilities:
         raise click.UsageError("Docker not installed") from None
 
     try:
-        stdout, _ = runner.run(subp_exec("docker", "info", "-f", "json", collect=True))
+        stdout, _ = runner.run(
+            subp_exec("docker", "info", "-f", "{{json .}}", collect=True)
+        )
         info = json.loads(stdout)
     except (click.exceptions.Exit, json.JSONDecodeError):
         raise click.UsageError("Docker not installed or not running") from None

libs/cli/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "langgraph-cli"
-version = "0.1.71"
+version = "0.1.73"
 description = "CLI for interacting with LangGraph API"
 authors = []
 license = "MIT"
@@ -14,7 +14,7 @@ langgraph = "langgraph_cli.cli:cli"
 [tool.poetry.dependencies]
 python = "^3.9.0,<4.0"
 click = "^8.1.7"
-langgraph-api = { version = ">=0.0.12,<0.1.0", optional = true, python = ">=3.11,<4.0" }
+langgraph-api = { version = ">=0.0.26,<0.1.0", optional = true, python = ">=3.11,<4.0" }
 python-dotenv = { version = ">=0.8.0", optional = true }
 
 [tool.poetry.group.dev.dependencies]

libs/cli/tests/unit_tests/cli/test_cli.py

@@ -40,9 +40,9 @@ def temporary_config_folder(config_content: dict):
 
 def test_prepare_args_and_stdin() -> None:
     # this basically serves as an end-to-end test for using config and docker helpers
-    config_path = pathlib.Path("./langgraph.json")
+    config_path = pathlib.Path(__file__).parent / "langgraph.json"
     config = validate_config(
-        Config(dependencies=["."], graphs={"agent": "agent.py:graph"})
+        Config(dependencies=[".", "../../.."], graphs={"agent": "agent.py:graph"})
     )
     port = 8000
     debugger_port = 8001
@@ -61,7 +61,7 @@ def test_prepare_args_and_stdin() -> None:
 
     expected_args = [
         "--project-directory",
-        ".",
+        str(pathlib.Path(__file__).parent.absolute()),
         "-f",
         "custom-docker-compose.yml",
         "-f",
@@ -129,18 +129,29 @@ services:
         pull_policy: build
         build:
             context: .
+            additional_contexts:
+                - cli_1: {str(pathlib.Path(__file__).parent.parent.parent.parent.absolute())}
             dockerfile_inline: |
                 FROM langchain/langgraph-api:3.11
-                ADD . /deps/
+                # -- Adding local package . --
+                ADD . /deps/cli
+                # -- End of local package . --
+                # -- Adding local package ../../.. --
+                COPY --from=cli_1 . /deps/cli_1
+                # -- End of local package ../../.. --
+                # -- Installing all local dependencies --
                 RUN PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*
+                # -- End of local dependencies install --
                 ENV LANGSERVE_GRAPHS='{{"agent": "agent.py:graph"}}'
-                WORKDIR /deps/
+                WORKDIR /deps/cli
         
         develop:
             watch:
                 - path: langgraph.json
                   action: rebuild
                 - path: .
+                  action: rebuild
+                - path: ../../..
                   action: rebuild\
 """
     assert actual_args == expected_args

libs/cli/tests/unit_tests/graphs/agent.py

@@ -0,0 +1,6 @@
+from langgraph.func import entrypoint
+
+
+@entrypoint()
+def graph(state):
+    return None

libs/cli/tests/unit_tests/test_config.json

@@ -6,10 +6,14 @@
     ],
     "dependencies": [
         "langchain_openai",
+        "starlette",
         "."
     ],
     "graphs": {
         "agent": "graphs/agent.py:graph"
     },
-    "env": ".env"
+    "env": ".env",
+    "http": {
+        "app": "../../examples/my_app.py:app" 
+    }
 }

libs/cli/tests/unit_tests/test_config.py

@@ -32,6 +32,7 @@ def test_validate_config():
         "env": {},
         "store": None,
         "auth": None,
+        "http": None,
         **expected_config,
     }
     actual_config = validate_config(expected_config)
@@ -50,6 +51,7 @@ def test_validate_config():
         "env": env,
         "store": None,
         "auth": None,
+        "http": None,
     }
     actual_config = validate_config(expected_config)
     assert actual_config == expected_config
@@ -108,6 +110,18 @@ def test_validate_config():
         }
     )
     assert config["python_version"] == "3.12-slim"
+    with pytest.raises(
+        ValueError,
+        match="Invalid http.app format",
+    ):
+        validate_config(
+            {
+                "python_version": "3.12",
+                "dependencies": ["."],
+                "graphs": {"agent": "./agent.py:graph"},
+                "http": {"app": "../../examples/my_app.py"},
+            }
+        )
 
 
 def test_validate_config_file():
@@ -177,13 +191,27 @@ def test_validate_config_file():
 # config_to_docker
 def test_config_to_docker_simple():
     graphs = {"agent": "./agent.py:graph"}
-    actual_docker_stdin = config_to_docker(
+    actual_docker_stdin, additional_contexts = config_to_docker(
         PATH_TO_CONFIG,
-        validate_config({"dependencies": ["."], "graphs": graphs}),
+        validate_config(
+            {
+                "dependencies": [".", "../../examples/graphs_reqs_a", "../../examples"],
+                "graphs": graphs,
+                "http": {"app": "../../examples/my_app.py:app"},
+            }
+        ),
         "langchain/langgraph-api",
     )
     expected_docker_stdin = """\
 FROM langchain/langgraph-api:3.11
+# -- Installing local requirements --
+COPY --from=__outer_requirements.txt requirements.txt /deps/__outer_graphs_reqs_a/graphs_reqs_a/requirements.txt
+RUN PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -r /deps/__outer_graphs_reqs_a/graphs_reqs_a/requirements.txt
+# -- End of local requirements install --
+# -- Adding local package ../../examples --
+COPY --from=examples . /deps/examples
+# -- End of local package ../../examples --
+# -- Adding non-package dependency unit_tests --
 ADD . /deps/__outer_unit_tests/unit_tests
 RUN set -ex && \\
     for line in '[project]' \\
@@ -193,16 +221,81 @@ RUN set -ex && \\
                 '"*" = ["**/*"]'; do \\
         echo "$line" >> /deps/__outer_unit_tests/pyproject.toml; \\
     done
+# -- End of non-package dependency unit_tests --
+# -- Adding non-package dependency graphs_reqs_a --
+COPY --from=__outer_graphs_reqs_a . /deps/__outer_graphs_reqs_a/graphs_reqs_a
+RUN set -ex && \\
+    for line in '[project]' \\
+                'name = "graphs_reqs_a"' \\
+                'version = "0.1"' \\
+                '[tool.setuptools.package-data]' \\
+                '"*" = ["**/*"]'; do \\
+        echo "$line" >> /deps/__outer_graphs_reqs_a/pyproject.toml; \\
+    done
+# -- End of non-package dependency graphs_reqs_a --
+# -- Installing all local dependencies --
 RUN PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*
+# -- End of local dependencies install --
+ENV LANGGRAPH_HTTP='{"app": "/deps/examples/my_app.py:app"}'
 ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_unit_tests/unit_tests/agent.py:graph"}'
 WORKDIR /deps/__outer_unit_tests/unit_tests\
 """
     assert clean_empty_lines(actual_docker_stdin) == expected_docker_stdin
 
+    assert additional_contexts == {
+        "__outer_graphs_reqs_a": str(
+            (pathlib.Path(__file__).parent / "../../examples/graphs_reqs_a").resolve()
+        ),
+        "examples": str((pathlib.Path(__file__).parent / "../../examples").resolve()),
+    }
+
+
+def test_config_to_docker_outside_path():
+    graphs = {"agent": "./agent.py:graph"}
+    actual_docker_stdin, additional_contexts = config_to_docker(
+        PATH_TO_CONFIG,
+        validate_config({"dependencies": [".", ".."], "graphs": graphs}),
+        "langchain/langgraph-api",
+    )
+    expected_docker_stdin = """\
+FROM langchain/langgraph-api:3.11
+# -- Adding non-package dependency unit_tests --
+ADD . /deps/__outer_unit_tests/unit_tests
+RUN set -ex && \\
+    for line in '[project]' \\
+                'name = "unit_tests"' \\
+                'version = "0.1"' \\
+                '[tool.setuptools.package-data]' \\
+                '"*" = ["**/*"]'; do \\
+        echo "$line" >> /deps/__outer_unit_tests/pyproject.toml; \\
+    done
+# -- End of non-package dependency unit_tests --
+# -- Adding non-package dependency tests --
+COPY --from=__outer_tests . /deps/__outer_tests/tests
+RUN set -ex && \\
+    for line in '[project]' \\
+                'name = "tests"' \\
+                'version = "0.1"' \\
+                '[tool.setuptools.package-data]' \\
+                '"*" = ["**/*"]'; do \\
+        echo "$line" >> /deps/__outer_tests/pyproject.toml; \\
+    done
+# -- End of non-package dependency tests --
+# -- Installing all local dependencies --
+RUN PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*
+# -- End of local dependencies install --
+ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_unit_tests/unit_tests/agent.py:graph"}'
+WORKDIR /deps/__outer_unit_tests/unit_tests\
+"""
+    assert clean_empty_lines(actual_docker_stdin) == expected_docker_stdin
+    assert additional_contexts == {
+        "__outer_tests": str(pathlib.Path(__file__).parent.parent.absolute()),
+    }
+
 
 def test_config_to_docker_pipconfig():
     graphs = {"agent": "./agent.py:graph"}
-    actual_docker_stdin = config_to_docker(
+    actual_docker_stdin, additional_contexts = config_to_docker(
         PATH_TO_CONFIG,
         validate_config(
             {
@@ -216,6 +309,7 @@ def test_config_to_docker_pipconfig():
     expected_docker_stdin = """\
 FROM langchain/langgraph-api:3.11
 ADD pipconfig.txt /pipconfig.txt
+# -- Adding non-package dependency unit_tests --
 ADD . /deps/__outer_unit_tests/unit_tests
 RUN set -ex && \\
     for line in '[project]' \\
@@ -225,11 +319,15 @@ RUN set -ex && \\
                 '"*" = ["**/*"]'; do \\
         echo "$line" >> /deps/__outer_unit_tests/pyproject.toml; \\
     done
+# -- End of non-package dependency unit_tests --
+# -- Installing all local dependencies --
 RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*
+# -- End of local dependencies install --
 ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_unit_tests/unit_tests/agent.py:graph"}'
 WORKDIR /deps/__outer_unit_tests/unit_tests\
 """
     assert clean_empty_lines(actual_docker_stdin) == expected_docker_stdin
+    assert additional_contexts == {}
 
 
 def test_config_to_docker_invalid_inputs():
@@ -254,7 +352,7 @@ def test_config_to_docker_invalid_inputs():
 
 def test_config_to_docker_local_deps():
     graphs = {"agent": "./graphs/agent.py:graph"}
-    actual_docker_stdin = config_to_docker(
+    actual_docker_stdin, additional_contexts = config_to_docker(
         PATH_TO_CONFIG,
         validate_config(
             {
@@ -266,6 +364,7 @@ def test_config_to_docker_local_deps():
     )
     expected_docker_stdin = """\
 FROM langchain/langgraph-api-custom:3.11
+# -- Adding non-package dependency graphs --
 ADD ./graphs /deps/__outer_graphs/src
 RUN set -ex && \\
     for line in '[project]' \\
@@ -275,10 +374,14 @@ RUN set -ex && \\
                 '"*" = ["**/*"]'; do \\
         echo "$line" >> /deps/__outer_graphs/pyproject.toml; \\
     done
+# -- End of non-package dependency graphs --
+# -- Installing all local dependencies --
 RUN PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*
+# -- End of local dependencies install --
 ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_graphs/src/agent.py:graph"}'\
 """
     assert clean_empty_lines(actual_docker_stdin) == expected_docker_stdin
+    assert additional_contexts == {}
 
 
 def test_config_to_docker_pyproject():
@@ -291,7 +394,7 @@ dependencies = ["langchain"]"""
         f.write(pyproject_str)
 
     graphs = {"agent": "./graphs/agent.py:graph"}
-    actual_docker_stdin = config_to_docker(
+    actual_docker_stdin, additional_contexts = config_to_docker(
         PATH_TO_CONFIG,
         validate_config(
             {
@@ -303,16 +406,21 @@ dependencies = ["langchain"]"""
     )
     os.remove(pyproject_path)
     expected_docker_stdin = """FROM langchain/langgraph-api:3.11
+# -- Adding local package . --
 ADD . /deps/unit_tests
+# -- End of local package . --
+# -- Installing all local dependencies --
 RUN PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*
+# -- End of local dependencies install --
 ENV LANGSERVE_GRAPHS='{"agent": "/deps/unit_tests/graphs/agent.py:graph"}'
 WORKDIR /deps/unit_tests"""
     assert clean_empty_lines(actual_docker_stdin) == expected_docker_stdin
+    assert additional_contexts == {}
 
 
 def test_config_to_docker_end_to_end():
     graphs = {"agent": "./graphs/agent.py:graph"}
-    actual_docker_stdin = config_to_docker(
+    actual_docker_stdin, additional_contexts = config_to_docker(
         PATH_TO_CONFIG,
         validate_config(
             {
@@ -330,6 +438,7 @@ ARG meow
 ARG foo
 ADD pipconfig.txt /pipconfig.txt
 RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt langchain langchain_openai
+# -- Adding non-package dependency graphs --
 ADD ./graphs/ /deps/__outer_graphs/src
 RUN set -ex && \\
     for line in '[project]' \\
@@ -339,15 +448,19 @@ RUN set -ex && \\
                 '"*" = ["**/*"]'; do \\
         echo "$line" >> /deps/__outer_graphs/pyproject.toml; \\
     done
+# -- End of non-package dependency graphs --
+# -- Installing all local dependencies --
 RUN PIP_CONFIG_FILE=/pipconfig.txt PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*
+# -- End of local dependencies install --
 ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_graphs/src/agent.py:graph"}'"""
     assert clean_empty_lines(actual_docker_stdin) == expected_docker_stdin
+    assert additional_contexts == {}
 
 
 # node.js build used for LangGraph Cloud
 def test_config_to_docker_nodejs():
     graphs = {"agent": "./graphs/agent.js:graph"}
-    actual_docker_stdin = config_to_docker(
+    actual_docker_stdin, additional_contexts = config_to_docker(
         PATH_TO_CONFIG,
         validate_config(
             {
@@ -368,6 +481,7 @@ WORKDIR /deps/unit_tests
 RUN (test ! -f /api/langgraph_api/js/build.mts && echo "Prebuild script not found, skipping") || tsx /api/langgraph_api/js/build.mts"""
 
     assert clean_empty_lines(actual_docker_stdin) == expected_docker_stdin
+    assert additional_contexts == {}
 
 
 # config_to_compose
@@ -380,6 +494,7 @@ def test_config_to_compose_simple_config():
             context: .
             dockerfile_inline: |
                 FROM langchain/langgraph-api:3.11
+                # -- Adding non-package dependency unit_tests --
                 ADD . /deps/__outer_unit_tests/unit_tests
                 RUN set -ex && \\
                     for line in '[project]' \\
@@ -389,7 +504,10 @@ def test_config_to_compose_simple_config():
                                 '"*" = ["**/*"]'; do \\
                         echo "$line" >> /deps/__outer_unit_tests/pyproject.toml; \\
                     done
+                # -- End of non-package dependency unit_tests --
+                # -- Installing all local dependencies --
                 RUN PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*
+                # -- End of local dependencies install --
                 ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_unit_tests/unit_tests/agent.py:graph"}'
                 WORKDIR /deps/__outer_unit_tests/unit_tests
         """
@@ -410,6 +528,7 @@ def test_config_to_compose_env_vars():
             context: .
             dockerfile_inline: |
                 FROM langchain/langgraph-api-custom:3.11
+                # -- Adding non-package dependency unit_tests --
                 ADD . /deps/__outer_unit_tests/unit_tests
                 RUN set -ex && \\
                     for line in '[project]' \\
@@ -419,7 +538,10 @@ def test_config_to_compose_env_vars():
                                 '"*" = ["**/*"]'; do \\
                         echo "$line" >> /deps/__outer_unit_tests/pyproject.toml; \\
                     done
+                # -- End of non-package dependency unit_tests --
+                # -- Installing all local dependencies --
                 RUN PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*
+                # -- End of local dependencies install --
                 ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_unit_tests/unit_tests/agent.py:graph"}'
                 WORKDIR /deps/__outer_unit_tests/unit_tests
         """
@@ -447,6 +569,7 @@ def test_config_to_compose_env_file():
             context: .
             dockerfile_inline: |
                 FROM langchain/langgraph-api:3.11
+                # -- Adding non-package dependency unit_tests --
                 ADD . /deps/__outer_unit_tests/unit_tests
                 RUN set -ex && \\
                     for line in '[project]' \\
@@ -456,7 +579,10 @@ def test_config_to_compose_env_file():
                                 '"*" = ["**/*"]'; do \\
                         echo "$line" >> /deps/__outer_unit_tests/pyproject.toml; \\
                     done
+                # -- End of non-package dependency unit_tests --
+                # -- Installing all local dependencies --
                 RUN PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*
+                # -- End of local dependencies install --
                 ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_unit_tests/unit_tests/agent.py:graph"}'
                 WORKDIR /deps/__outer_unit_tests/unit_tests
         """
@@ -477,6 +603,7 @@ def test_config_to_compose_watch():
             context: .
             dockerfile_inline: |
                 FROM langchain/langgraph-api:3.11
+                # -- Adding non-package dependency unit_tests --
                 ADD . /deps/__outer_unit_tests/unit_tests
                 RUN set -ex && \\
                     for line in '[project]' \\
@@ -486,7 +613,10 @@ def test_config_to_compose_watch():
                                 '"*" = ["**/*"]'; do \\
                         echo "$line" >> /deps/__outer_unit_tests/pyproject.toml; \\
                     done
+                # -- End of non-package dependency unit_tests --
+                # -- Installing all local dependencies --
                 RUN PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*
+                # -- End of local dependencies install --
                 ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_unit_tests/unit_tests/agent.py:graph"}'
                 WORKDIR /deps/__outer_unit_tests/unit_tests
         
@@ -516,6 +646,7 @@ def test_config_to_compose_end_to_end():
             context: .
             dockerfile_inline: |
                 FROM langchain/langgraph-api:3.11
+                # -- Adding non-package dependency unit_tests --
                 ADD . /deps/__outer_unit_tests/unit_tests
                 RUN set -ex && \\
                     for line in '[project]' \\
@@ -525,7 +656,10 @@ def test_config_to_compose_end_to_end():
                                 '"*" = ["**/*"]'; do \\
                         echo "$line" >> /deps/__outer_unit_tests/pyproject.toml; \\
                     done
+                # -- End of non-package dependency unit_tests --
+                # -- Installing all local dependencies --
                 RUN PYTHONDONTWRITEBYTECODE=1 pip install --no-cache-dir -c /api/constraints.txt -e /deps/*
+                # -- End of local dependencies install --
                 ENV LANGSERVE_GRAPHS='{"agent": "/deps/__outer_unit_tests/unit_tests/agent.py:graph"}'
                 WORKDIR /deps/__outer_unit_tests/unit_tests
         

libs/langgraph/langgraph/config.py

@@ -1,5 +1,6 @@
 import asyncio
 import sys
+from typing import Any
 
 from langchain_core.runnables import RunnableConfig
 from langchain_core.runnables.config import var_child_runnable_config
@@ -9,6 +10,10 @@ from langgraph.store.base import BaseStore
 from langgraph.types import StreamWriter
 
 
+def _no_op_stream_writer(c: Any) -> None:
+    pass
+
+
 def get_config() -> RunnableConfig:
     if sys.version_info < (3, 11):
         try:
@@ -177,4 +182,4 @@ def get_stream_writer() -> StreamWriter:
         ```
     """
     config = get_config()
-    return config[CONF][CONFIG_KEY_STREAM_WRITER]
+    return config[CONF].get(CONFIG_KEY_STREAM_WRITER, _no_op_stream_writer)

libs/langgraph/langgraph/constants.py

@@ -81,6 +81,8 @@ CONFIG_KEY_SCRATCHPAD = sys.intern("__pregel_scratchpad")
 # holds a mutable dict for temporary storage scoped to the current task
 CONFIG_KEY_PREVIOUS = sys.intern("__pregel_previous")
 # holds the previous return value from a stateful Pregel graph.
+CONFIG_KEY_RUNNER_SUBMIT = sys.intern("__pregel_runner_submit")
+# holds a function that receives tasks from runner, executes them and returns results
 
 # --- Other constants ---
 PUSH = sys.intern("__pregel_push")

libs/langgraph/langgraph/func/__init__.py

@@ -57,9 +57,6 @@ def task(
 ]:
     """Define a LangGraph task using the `task` decorator.
 
-    !!! warning "Beta"
-        The Functional API is currently in beta and is subject to change.
-
     !!! important "Requires python 3.11 or higher for async functions"
         The `task` decorator supports both sync and async functions. To use async
         functions, ensure that you are using Python 3.11 or higher.
@@ -153,10 +150,6 @@ S = TypeVar("S")
 class entrypoint:
     """Define a LangGraph workflow using the `entrypoint` decorator.
 
-    !!! warning "Beta"
-        The Functional API is currently in beta and is subject to change.
-
-
     ### Function signature
 
     The decorated function must accept a **single parameter**, which serves as the input

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,
@@ -286,7 +286,7 @@ class StateGraph(Graph):
         Will take the name of the function/runnable as the node name.
 
         Args:
-            node (Union[str, RunnableLike)]: The function or runnable this node will run.
+            node (Union[str, RunnableLike]): The function or runnable this node will run.
             action (Optional[RunnableLike]): The action associated with the node. (default: None)
             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)
@@ -691,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/prebuilt/chat_agent_executor.py

@@ -12,7 +12,11 @@ from typing import (
     cast,
 )
 
-from langchain_core.language_models import BaseChatModel, LanguageModelLike
+from langchain_core.language_models import (
+    BaseChatModel,
+    LanguageModelInput,
+    LanguageModelLike,
+)
 from langchain_core.messages import AIMessage, BaseMessage, SystemMessage, ToolMessage
 from langchain_core.runnables import (
     Runnable,
@@ -52,6 +56,10 @@ class AgentState(TypedDict):
 
     remaining_steps: RemainingSteps
 
+
+class AgentStateWithStructuredResponse(AgentState):
+    """The state of the agent with a structured response."""
+
     structured_response: StructuredResponse
 
 
@@ -63,15 +71,15 @@ PROMPT_RUNNABLE_NAME = "Prompt"
 MessagesModifier = Union[
     SystemMessage,
     str,
-    Callable[[Sequence[BaseMessage]], Sequence[BaseMessage]],
-    Runnable[Sequence[BaseMessage], Sequence[BaseMessage]],
+    Callable[[Sequence[BaseMessage]], LanguageModelInput],
+    Runnable[Sequence[BaseMessage], LanguageModelInput],
 ]
 
 Prompt = Union[
     SystemMessage,
     str,
-    Callable[[StateSchema], Sequence[BaseMessage]],
-    Runnable[StateSchema, Sequence[BaseMessage]],
+    Callable[[StateSchema], LanguageModelInput],
+    Runnable[StateSchema, LanguageModelInput],
 ]
 
 
@@ -599,6 +607,13 @@ def create_react_agent(
         if missing_keys := required_keys - set(state_schema.__annotations__):
             raise ValueError(f"Missing required key(s) {missing_keys} in state_schema")
 
+    if state_schema is None:
+        state_schema = (
+            AgentStateWithStructuredResponse
+            if response_format is not None
+            else AgentState
+        )
+
     if isinstance(tools, ToolExecutor):
         tool_classes: Sequence[BaseTool] = tools.tools
         tool_node = ToolNode(tool_classes)
@@ -748,7 +763,7 @@ def create_react_agent(
 
     if not tool_calling_enabled:
         # Define a new graph
-        workflow = StateGraph(state_schema or AgentState)
+        workflow = StateGraph(state_schema)
         workflow.add_node("agent", RunnableCallable(call_model, acall_model))
         workflow.set_entry_point("agent")
         if response_format is not None:

libs/langgraph/langgraph/pregel/__init__.py

@@ -59,6 +59,7 @@ from langgraph.constants import (
     CONFIG_KEY_NODE_FINISHED,
     CONFIG_KEY_READ,
     CONFIG_KEY_RESUMING,
+    CONFIG_KEY_RUNNER_SUBMIT,
     CONFIG_KEY_SEND,
     CONFIG_KEY_STORE,
     CONFIG_KEY_STREAM,
@@ -197,6 +198,60 @@ 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.
+    """
+
     nodes: dict[str, PregelNode]
 
     channels: dict[str, Union[BaseChannel, ManagedValueSpec]]
@@ -1682,7 +1737,7 @@ class Pregel(PregelProtocol):
             ) as loop:
                 # create runner
                 runner = PregelRunner(
-                    submit=loop.submit,
+                    submit=config[CONF].get(CONFIG_KEY_RUNNER_SUBMIT, loop.submit),
                     put_writes=loop.put_writes,
                     schedule_task=loop.accept_push,
                     node_finished=config[CONF].get(CONFIG_KEY_NODE_FINISHED),
@@ -1974,7 +2029,7 @@ class Pregel(PregelProtocol):
             ) as loop:
                 # create runner
                 runner = PregelRunner(
-                    submit=loop.submit,
+                    submit=config[CONF].get(CONFIG_KEY_RUNNER_SUBMIT, loop.submit),
                     put_writes=loop.put_writes,
                     schedule_task=loop.accept_push,
                     use_astream=do_stream is not None,

libs/langgraph/langgraph/pregel/remote.py

@@ -323,11 +323,15 @@ class RemoteGraph(PregelProtocol):
             if k not in reserved_configurable_keys and not k.startswith("__pregel_")
         }
 
-        return {
+        sanitized: RunnableConfig = {
             "tags": config.get("tags") or [],
             "metadata": config.get("metadata") or {},
             "configurable": new_configurable,
         }
+        if "recursion_limit" in config:
+            sanitized["recursion_limit"] = config["recursion_limit"]
+
+        return sanitized
 
     def get_state(
         self, config: RunnableConfig, *, subgraphs: bool = False

libs/langgraph/langgraph/utils/runnable.py

@@ -13,6 +13,7 @@ from typing import (
     Coroutine,
     Iterator,
     Optional,
+    Protocol,
     Sequence,
     Tuple,
     Union,
@@ -35,7 +36,7 @@ from langchain_core.runnables.config import (
 )
 from langchain_core.runnables.utils import Input, Output
 from langchain_core.tracers._streaming import _StreamingCallbackHandler
-from typing_extensions import Concatenate, ParamSpec, TypeGuard
+from typing_extensions import TypeGuard
 
 from langgraph.constants import (
     CONF,
@@ -132,12 +133,51 @@ Each tuple contains:
 VALID_KINDS = (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)
 
 
-P = ParamSpec("P")  # to handle injected kwargs like `writer` / `store`
+class _RunnableWithWriter(Protocol[Input, Output]):
+    def __call__(self, state: Input, *, writer: StreamWriter) -> Output: ...
+
+
+class _RunnableWithStore(Protocol[Input, Output]):
+    def __call__(self, state: Input, *, store: BaseStore) -> Output: ...
+
+
+class _RunnableWithWriterStore(Protocol[Input, Output]):
+    def __call__(
+        self, state: Input, *, writer: StreamWriter, store: BaseStore
+    ) -> Output: ...
+
+
+class _RunnableWithConfigWriter(Protocol[Input, Output]):
+    def __call__(
+        self, state: Input, *, config: RunnableConfig, writer: StreamWriter
+    ) -> Output: ...
+
+
+class _RunnableWithConfigStore(Protocol[Input, Output]):
+    def __call__(
+        self, state: Input, *, config: RunnableConfig, store: BaseStore
+    ) -> Output: ...
+
+
+class _RunnableWithConfigWriterStore(Protocol[Input, Output]):
+    def __call__(
+        self,
+        state: Input,
+        *,
+        config: RunnableConfig,
+        writer: StreamWriter,
+        store: BaseStore,
+    ) -> Output: ...
+
 
 RunnableLike = Union[
     LCRunnableLike,
-    Callable[Concatenate[Input, P], Output],
-    Callable[Concatenate[Input, P], Awaitable[Output]],
+    _RunnableWithWriter[Input, Output],
+    _RunnableWithStore[Input, Output],
+    _RunnableWithWriterStore[Input, Output],
+    _RunnableWithConfigWriter[Input, Output],
+    _RunnableWithConfigStore[Input, Output],
+    _RunnableWithConfigWriterStore[Input, Output],
 ]
 
 

libs/langgraph/pyproject.toml

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

libs/langgraph/tests/__snapshots__/test_large_cases.ambr

@@ -2832,10 +2832,10 @@
   '''
 # ---
 # name: test_prebuilt_tool_chat
-  '{"$defs": {"BaseMessage": {"additionalProperties": true, "description": "Base abstract message class.\\n\\nMessages are the inputs and outputs of ChatModels.", "properties": {"content": {"anyOf": [{"type": "string"}, {"items": {"anyOf": [{"type": "string"}, {"type": "object"}]}, "type": "array"}], "title": "Content"}, "additional_kwargs": {"title": "Additional Kwargs", "type": "object"}, "response_metadata": {"title": "Response Metadata", "type": "object"}, "type": {"title": "Type", "type": "string"}, "name": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "title": "Name"}, "id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "title": "Id"}}, "required": ["content", "type"], "title": "BaseMessage", "type": "object"}, "BaseModel": {"properties": {}, "title": "BaseModel", "type": "object"}}, "properties": {"messages": {"items": {"$ref": "#/$defs/BaseMessage"}, "title": "Messages", "type": "array"}, "structured_response": {"anyOf": [{"type": "object"}, {"$ref": "#/$defs/BaseModel"}], "title": "Structured Response"}}, "required": ["messages", "structured_response"], "title": "LangGraphInput", "type": "object"}'
+  '{"$defs": {"BaseMessage": {"additionalProperties": true, "description": "Base abstract message class.\\n\\nMessages are the inputs and outputs of ChatModels.", "properties": {"content": {"anyOf": [{"type": "string"}, {"items": {"anyOf": [{"type": "string"}, {"type": "object"}]}, "type": "array"}], "title": "Content"}, "additional_kwargs": {"title": "Additional Kwargs", "type": "object"}, "response_metadata": {"title": "Response Metadata", "type": "object"}, "type": {"title": "Type", "type": "string"}, "name": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "title": "Name"}, "id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "title": "Id"}}, "required": ["content", "type"], "title": "BaseMessage", "type": "object"}}, "properties": {"messages": {"items": {"$ref": "#/$defs/BaseMessage"}, "title": "Messages", "type": "array"}}, "required": ["messages"], "title": "LangGraphInput", "type": "object"}'
 # ---
 # name: test_prebuilt_tool_chat.1
-  '{"$defs": {"BaseMessage": {"additionalProperties": true, "description": "Base abstract message class.\\n\\nMessages are the inputs and outputs of ChatModels.", "properties": {"content": {"anyOf": [{"type": "string"}, {"items": {"anyOf": [{"type": "string"}, {"type": "object"}]}, "type": "array"}], "title": "Content"}, "additional_kwargs": {"title": "Additional Kwargs", "type": "object"}, "response_metadata": {"title": "Response Metadata", "type": "object"}, "type": {"title": "Type", "type": "string"}, "name": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "title": "Name"}, "id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "title": "Id"}}, "required": ["content", "type"], "title": "BaseMessage", "type": "object"}, "BaseModel": {"properties": {}, "title": "BaseModel", "type": "object"}}, "properties": {"messages": {"items": {"$ref": "#/$defs/BaseMessage"}, "title": "Messages", "type": "array"}, "structured_response": {"anyOf": [{"type": "object"}, {"$ref": "#/$defs/BaseModel"}], "title": "Structured Response"}}, "required": ["messages", "structured_response"], "title": "LangGraphOutput", "type": "object"}'
+  '{"$defs": {"BaseMessage": {"additionalProperties": true, "description": "Base abstract message class.\\n\\nMessages are the inputs and outputs of ChatModels.", "properties": {"content": {"anyOf": [{"type": "string"}, {"items": {"anyOf": [{"type": "string"}, {"type": "object"}]}, "type": "array"}], "title": "Content"}, "additional_kwargs": {"title": "Additional Kwargs", "type": "object"}, "response_metadata": {"title": "Response Metadata", "type": "object"}, "type": {"title": "Type", "type": "string"}, "name": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "title": "Name"}, "id": {"anyOf": [{"type": "string"}, {"type": "null"}], "default": null, "title": "Id"}}, "required": ["content", "type"], "title": "BaseMessage", "type": "object"}}, "properties": {"messages": {"items": {"$ref": "#/$defs/BaseMessage"}, "title": "Messages", "type": "array"}}, "required": ["messages"], "title": "LangGraphOutput", "type": "object"}'
 # ---
 # name: test_prebuilt_tool_chat.2
   '''

libs/langgraph/tests/test_large_cases_async.py

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

libs/langgraph/tests/test_prebuilt.py

@@ -63,7 +63,6 @@ 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,
@@ -183,8 +182,6 @@ 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")]}},
@@ -217,8 +214,6 @@ 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

@@ -54,6 +54,7 @@ from langgraph.checkpoint.base import (
     CheckpointTuple,
 )
 from langgraph.checkpoint.memory import InMemorySaver, MemorySaver
+from langgraph.config import get_stream_writer
 from langgraph.constants import CONFIG_KEY_NODE_FINISHED, ERROR, PULL, START
 from langgraph.errors import InvalidUpdateError
 from langgraph.func import entrypoint, task
@@ -1112,8 +1113,6 @@ 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,
@@ -1212,8 +1211,6 @@ def test_pending_writes_resume(
             "channel_values": {"one": "one", "two": "two", "value": 6},
         },
         metadata={
-            "checkpoint_id": AnyStr(),
-            "checkpoint_ns": "",
             "parents": {},
             "step": 1,
             "source": "loop",
@@ -1264,8 +1261,6 @@ def test_pending_writes_resume(
             },
         },
         metadata={
-            "checkpoint_id": AnyStr(),
-            "checkpoint_ns": "",
             "parents": {},
             "step": 0,
             "source": "loop",
@@ -1307,7 +1302,6 @@ def test_pending_writes_resume(
             "channel_values": {"__start__": {"value": 1}},
         },
         metadata={
-            "checkpoint_ns": "",
             "parents": {},
             "step": -1,
             "source": "input",
@@ -2398,8 +2392,6 @@ def test_in_one_fan_out_state_graph_waiting_edge(
         },
         created_at=AnyStr(),
         metadata={
-            "checkpoint_id": AnyStr(),
-            "checkpoint_ns": "",
             "parents": {},
             "source": "update",
             "step": 4,
@@ -4835,8 +4827,6 @@ def test_parent_command(request: pytest.FixtureRequest, checkpointer_name: str)
             }
         },
         metadata={
-            "checkpoint_id": AnyStr(),
-            "checkpoint_ns": "",
             "source": "loop",
             "writes": {
                 "alice": {
@@ -6493,3 +6483,47 @@ def test_node_destinations() -> None:
             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}
+
+
+def test_get_stream_writer() -> None:
+    class State(TypedDict):
+        foo: str
+
+    def my_node(state):
+        writer = get_stream_writer()
+        writer("custom!")
+        return state
+
+    graph = StateGraph(State).add_node(my_node).add_edge(START, "my_node").compile()
+    assert list(graph.stream({"foo": "bar"}, stream_mode="custom")) == ["custom!"]
+    assert list(graph.stream({"foo": "bar"}, stream_mode="values")) == [
+        {"foo": "bar"},
+        {"foo": "bar"},
+    ]
+    assert list(graph.stream({"foo": "bar"}, stream_mode=["custom", "updates"])) == [
+        (
+            "custom",
+            "custom!",
+        ),
+        (
+            "updates",
+            {
+                "my_node": {
+                    "foo": "bar",
+                },
+            },
+        ),
+    ]

libs/langgraph/tests/test_pregel_async.py

@@ -606,8 +606,6 @@ 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,
@@ -615,7 +613,6 @@ async def test_dynamic_interrupt(checkpointer_name: str) -> None:
                     "thread_id": "1",
                 },
                 {
-                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "input",
                     "step": -1,
@@ -644,8 +641,6 @@ 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,
@@ -672,8 +667,6 @@ 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,
@@ -798,8 +791,6 @@ 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,
@@ -807,7 +798,6 @@ async def test_dynamic_interrupt_subgraph(checkpointer_name: str) -> None:
                     "thread_id": "1",
                 },
                 {
-                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "input",
                     "step": -1,
@@ -842,8 +832,6 @@ 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,
@@ -870,8 +858,6 @@ 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,
@@ -990,8 +976,6 @@ 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,
@@ -999,7 +983,6 @@ async def test_copy_checkpoint(checkpointer_name: str) -> None:
                     "thread_id": "1",
                 },
                 {
-                    "checkpoint_ns": "",
                     "parents": {},
                     "source": "input",
                     "step": -1,
@@ -1038,8 +1021,6 @@ 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,
@@ -1083,8 +1064,6 @@ 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,
@@ -1251,8 +1230,6 @@ 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,
@@ -1330,8 +1307,6 @@ 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,
@@ -2032,8 +2007,6 @@ async def test_pending_writes_resume(
             ),
         )
         assert state.metadata == {
-            "checkpoint_id": AnyStr(),
-            "checkpoint_ns": "",
             "parents": {},
             "source": "loop",
             "step": 0,
@@ -2132,8 +2105,6 @@ 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",
@@ -2186,8 +2157,6 @@ async def test_pending_writes_resume(
                 },
             },
             metadata={
-                "checkpoint_id": AnyStr(),
-                "checkpoint_ns": "",
                 "parents": {},
                 "step": 0,
                 "source": "loop",
@@ -2231,7 +2200,6 @@ async def test_pending_writes_resume(
                 "channel_values": {"__start__": {"value": 1}},
             },
             metadata={
-                "checkpoint_ns": "",
                 "parents": {},
                 "step": -1,
                 "source": "input",
@@ -2810,8 +2778,6 @@ 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",
@@ -2848,8 +2814,6 @@ 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",
@@ -2893,8 +2857,6 @@ async def test_send_dedupe_on_resume(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
-                    "checkpoint_id": AnyStr(),
-                    "checkpoint_ns": "",
                     "source": "loop",
                     "writes": {
                         "2": [
@@ -2960,8 +2922,6 @@ 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",
@@ -3017,8 +2977,6 @@ async def test_send_dedupe_on_resume(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
-                    "checkpoint_id": AnyStr(),
-                    "checkpoint_ns": "",
                     "source": "loop",
                     "writes": None,
                     "thread_id": "1",
@@ -3056,7 +3014,6 @@ async def test_send_dedupe_on_resume(checkpointer_name: str) -> None:
                     }
                 },
                 metadata={
-                    "checkpoint_ns": "",
                     "source": "input",
                     "writes": {"__start__": ["0"]},
                     "thread_id": "1",
@@ -3229,8 +3186,6 @@ async def test_send_react_interrupt(checkpointer_name: str) -> None:
                 }
             },
             metadata={
-                "checkpoint_id": AnyStr(),
-                "checkpoint_ns": "",
                 "step": 1,
                 "source": "loop",
                 "writes": {
@@ -3302,8 +3257,6 @@ async def test_send_react_interrupt(checkpointer_name: str) -> None:
                 }
             },
             metadata={
-                "checkpoint_id": AnyStr(),
-                "checkpoint_ns": "",
                 "step": 2,
                 "source": "update",
                 "writes": {
@@ -3391,8 +3344,6 @@ async def test_send_react_interrupt(checkpointer_name: str) -> None:
                 }
             },
             metadata={
-                "checkpoint_id": AnyStr(),
-                "checkpoint_ns": "",
                 "step": 1,
                 "source": "loop",
                 "writes": {
@@ -3485,8 +3436,6 @@ async def test_send_react_interrupt(checkpointer_name: str) -> None:
                 }
             },
             metadata={
-                "checkpoint_id": AnyStr(),
-                "checkpoint_ns": "",
                 "step": 2,
                 "source": "update",
                 "writes": {
@@ -3702,8 +3651,6 @@ async def test_send_react_interrupt_control(
                 }
             },
             metadata={
-                "checkpoint_id": AnyStr(),
-                "checkpoint_ns": "",
                 "step": 1,
                 "source": "loop",
                 "writes": {
@@ -3775,8 +3722,6 @@ async def test_send_react_interrupt_control(
                 }
             },
             metadata={
-                "checkpoint_id": AnyStr(),
-                "checkpoint_ns": "",
                 "step": 2,
                 "source": "update",
                 "writes": {
@@ -4726,8 +4671,6 @@ 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"}},
@@ -6202,8 +6145,6 @@ async def test_parent_command(checkpointer_name: str) -> None:
                 }
             },
             metadata={
-                "checkpoint_id": AnyStr(),
-                "checkpoint_ns": "",
                 "source": "loop",
                 "writes": {
                     "alice": {

libs/sdk-js/.gitignore

@@ -13,3 +13,4 @@ react.d.cts
 node_modules
 dist
 .yarn
+docs

libs/sdk-js/langchain.config.js

@@ -15,5 +15,6 @@ export const config = {
   tsConfigPath: resolve("./tsconfig.json"),
   cjsSource: "./dist-cjs",
   cjsDestination: "./dist",
+  additionalGitignorePaths: ["docs"],
   abs,
 };

libs/sdk-js/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-sdk",
-  "version": "0.0.40",
+  "version": "0.0.43",
   "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",
@@ -33,8 +34,8 @@
     "jest": "^29.7.0",
     "prettier": "^3.2.5",
     "ts-jest": "^29.1.2",
-    "typedoc": "^0.26.1",
-    "typedoc-plugin-markdown": "^4.1.0",
+    "typedoc": "^0.27.7",
+    "typedoc-plugin-markdown": "^4.4.2",
     "typescript": "^5.4.5",
     "react": "^18.3.1"
   },
@@ -42,6 +43,14 @@
     "react": "^18 || ^19",
     "@langchain/core": ">=0.2.31 <0.4.0"
   },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@langchain/core": {
+      "optional": true
+    }
+  },
   "exports": {
     ".": {
       "types": {

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

@@ -128,13 +128,145 @@ interface ValidSequence<StateType = any> {
 }
 
 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,
@@ -179,29 +311,198 @@ function useThreadHistory<StateType extends Record<string, unknown>>(
   };
 }
 
-export function useStream<
+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,
->(options: {
+> {
+  /**
+   * 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"];
 
-  withMessages?: string;
+  /**
+   * 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;
 
-  // TODO: can we make threadId uncontrollable / controllable?
+  /**
+   * 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>,
+  ConfigurableType extends Record<string, unknown> = Record<string, unknown>,
+> {
+  /**
+   * 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, ConfigurableType>,
+  ) => 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;
+}
+
+type ConfigWithConfigurable<ConfigurableType extends Record<string, unknown>> =
+  Config & { configurable?: ConfigurableType };
+
+interface SubmitOptions<
+  StateType extends Record<string, unknown> = Record<string, unknown>,
+  ConfigurableType extends Record<string, unknown> = Record<string, unknown>,
+> {
+  config?: ConfigWithConfigurable<ConfigurableType>;
+  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>,
+  ConfigurableType extends Record<string, unknown> = Record<string, unknown>,
+  CustomType = unknown,
+>(
+  options: UseStreamOptions<StateType, UpdateType, CustomType>,
+): UseStream<StateType, UpdateType, ConfigurableType> {
   type EventStreamEvent =
     | ValuesStreamEvent<StateType>
     | UpdatesStreamEvent<UpdateType>
@@ -214,15 +515,17 @@ export function useStream<
     | ErrorStreamEvent
     | FeedbackStreamEvent;
 
-  const { assistantId, threadId, withMessages, onError, onFinish } = options;
+  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 [branchPath, setBranchPath] = useState<string[]>([]);
+  const [branch, setBranch] = useState<string>("");
   const [isLoading, setIsLoading] = useState(false);
-  const [_, setEvents] = useState<EventStreamEvent[]>([]);
 
   const [streamError, setStreamError] = useState<unknown>(undefined);
   const [streamValues, setStreamValues] = useState<StateType | null>(null);
@@ -269,118 +572,20 @@ export function useStream<
   );
 
   const getMessages = useMemo(() => {
-    if (withMessages == null) return undefined;
     return (value: StateType) =>
-      Array.isArray(value[withMessages])
-        ? (value[withMessages] as Message[])
+      Array.isArray(value[messagesKey])
+        ? (value[messagesKey] as Message[])
         : [];
-  }, [withMessages]);
+  }, [messagesKey]);
 
-  const [sequence, pathMap] = (() => {
-    const childrenMap: Record<string, ThreadState<StateType>[]> = {};
+  const { rootSequence, paths } = getBranchSequence(history.data);
+  const { history: flatHistory, branchByCheckpoint } = getBranchView(
+    rootSequence,
+    paths,
+    branch,
+  );
 
-    // First pass - collect nodes for each checkpoint
-    history.data.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 });
-      }
-    }
-
-    // Third pass, create a map for available forks
-    const pathMap: Record<string, string[][]> = {};
-    for (const path of paths) {
-      const parent = path.at(-2) ?? "$";
-      pathMap[parent] ??= [];
-      pathMap[parent].unshift(path);
-    }
-
-    return [rootSequence as ValidSequence, pathMap];
-  })();
-
-  const [flatValues, flatPaths] = (() => {
-    const result: ThreadState<StateType>[] = [];
-    const flatPaths: Record<
-      string,
-      { current: string[] | undefined; branches: string[][] | undefined }
-    > = {};
-
-    const forkStack = branchPath.slice();
-    const queue: (Node<StateType> | Fork<StateType>)[] = [...sequence.items];
-
-    while (queue.length > 0) {
-      const item = queue.shift()!;
-
-      if (item.type === "node") {
-        result.push(item.value);
-        flatPaths[item.value.checkpoint.checkpoint_id!] = {
-          current: item.path,
-          branches:
-            item.path.length > 0 ? pathMap[item.path.at(-2) ?? "$"] ?? [] : [],
-        };
-      }
-      if (item.type === "fork") {
-        const forkId = forkStack.shift();
-        const index =
-          forkId != null
-            ? item.items.findIndex((value) => {
-                const firstItem = value.items.at(0);
-                if (!firstItem || firstItem.type !== "node") return false;
-                return firstItem.value.checkpoint.checkpoint_id === forkId;
-              })
-            : -1;
-
-        const nextItems = item.items.at(index)?.items ?? [];
-        queue.push(...nextItems);
-      }
-    }
-
-    return [result, flatPaths];
-  })();
-
-  const threadHead: ThreadState<StateType> | undefined = flatValues.at(-1);
+  const threadHead: ThreadState<StateType> | undefined = flatHistory.at(-1);
   const historyValues = threadHead?.values ?? ({} as StateType);
   const historyError = (() => {
     const error = threadHead?.tasks?.at(-1)?.error;
@@ -399,8 +604,6 @@ export function useStream<
   })();
 
   const messageMetadata = (() => {
-    if (getMessages == null) return undefined;
-
     const alreadyShown = new Set<string>();
     return getMessages(historyValues).map(
       (message, idx): MessageMetadata<StateType> => {
@@ -416,13 +619,13 @@ export function useStream<
           | undefined;
 
         let branch = firstSeen
-          ? flatPaths[firstSeen.checkpoint.checkpoint_id!]
+          ? branchByCheckpoint[firstSeen.checkpoint.checkpoint_id!]
           : undefined;
 
-        if (!branch?.current?.length) branch = undefined;
+        if (!branch?.branch?.length) branch = undefined;
 
         // serialize branches
-        const optionsShown = branch?.branches?.flat(2).join(",");
+        const optionsShown = branch?.branchOptions?.flat(2).join(",");
         if (optionsShown) {
           if (alreadyShown.has(optionsShown)) branch = undefined;
           alreadyShown.add(optionsShown);
@@ -431,8 +634,9 @@ export function useStream<
         return {
           messageId: messageId.toString(),
           firstSeenState: firstSeen,
-          branch: branch?.current?.join(">"),
-          branchOptions: branch?.branches?.map((b) => b.join(">")),
+
+          branch: branch?.branch,
+          branchOptions: branch?.branchOptions,
         };
       },
     );
@@ -445,22 +649,7 @@ export function useStream<
 
   const submit = async (
     values: UpdateType | undefined,
-    submitOptions?: {
-      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>);
-    },
+    submitOptions?: SubmitOptions<StateType, ConfigurableType>,
   ) => {
     try {
       setIsLoading(true);
@@ -472,7 +661,7 @@ export function useStream<
       let usableThreadId = threadId;
       if (!usableThreadId) {
         const thread = await client.threads.create();
-        options?.onThreadId?.(thread.thread_id);
+        onThreadId(thread.thread_id);
         usableThreadId = thread.thread_id;
       }
 
@@ -507,9 +696,10 @@ export function useStream<
 
       // Unbranch things
       const newPath = submitOptions?.checkpoint?.checkpoint_id
-        ? flatPaths[submitOptions?.checkpoint?.checkpoint_id]?.current
+        ? branchByCheckpoint[submitOptions?.checkpoint?.checkpoint_id]?.branch
         : undefined;
-      if (newPath != null) setBranchPath(newPath ?? []);
+
+      if (newPath != null) setBranch(newPath ?? "");
 
       // Assumption: we're setting the initial value
       // Used for instant feedback
@@ -530,32 +720,17 @@ export function useStream<
 
       let streamError: StreamError | undefined;
       for await (const { event, data } of run) {
-        setEvents((events) => [...events, { event, data } as EventStreamEvent]);
-
         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 === "updates") options.onUpdateEvent?.(data);
+        if (event === "custom") options.onCustomEvent?.(data);
+        if (event === "metadata") options.onMetadataEvent?.(data);
 
+        if (event === "values") setStreamValues(data);
         if (event === "messages") {
-          if (!getMessages) continue;
-
           const [serialized] = data;
 
           const messageId = messageManagerRef.current.add(serialized);
@@ -577,15 +752,13 @@ export function useStream<
             if (!chunk || index == null) return values;
             messages[index] = toMessageDict(chunk);
 
-            return { ...values, [withMessages!]: messages };
+            return { ...values, [messagesKey!]: messages };
           });
         }
       }
 
       // TODO: stream created checkpoints to avoid an unnecessary network request
       const result = await history.mutate(usableThreadId);
-
-      // TODO: write tests verifying that stream values are properly handled lifecycle-wise
       setStreamValues(null);
 
       if (streamError != null) throw streamError;
@@ -615,11 +788,6 @@ export function useStream<
   const error = isLoading ? streamError : historyError;
   const values = streamValues ?? historyValues;
 
-  const setBranch = useCallback(
-    (path: string) => setBranchPath(path.split(">")),
-    [setBranchPath],
-  );
-
   return {
     get values() {
       trackStreamMode("values");
@@ -631,17 +799,15 @@ export function useStream<
 
     stop,
     submit,
+
+    branch,
     setBranch,
 
+    history: flatHistory,
+    experimental_branchTree: rootSequence,
+
     get messages() {
       trackStreamMode("messages-tuple");
-
-      if (getMessages == null) {
-        throw new Error(
-          "No messages key provided. Make sure that `useStream` contains the `messagesKey` property.",
-        );
-      }
-
       return getMessages(values);
     },
 
@@ -650,13 +816,6 @@ export function useStream<
       index?: number,
     ): MessageMetadata<StateType> | undefined {
       trackStreamMode("messages-tuple");
-
-      if (getMessages == null) {
-        throw new Error(
-          "No messages key provided. Make sure that `useStream` contains the `messagesKey` property.",
-        );
-      }
-
       return messageMetadata?.find(
         (m) => m.messageId === (message.id ?? index),
       );