langgraph 1.2.7__tar.gz → 1.2.9__tar.gz

{langgraph-1.2.7 → langgraph-1.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph
-Version: 1.2.7
+Version: 1.2.9
 Summary: Building stateful, multi-actor applications with LLMs
 Project-URL: Homepage, https://docs.langchain.com/oss/python/langgraph/overview
 Project-URL: Documentation, https://reference.langchain.com/python/langgraph/

{langgraph-1.2.7 → langgraph-1.2.9}/langgraph/pregel/_checkpoint.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import uuid
-from collections.abc import Callable, Mapping
+from collections.abc import Callable, Iterable, Mapping
 from datetime import datetime, timezone
 from typing import Any, cast
 
@@ -14,6 +14,7 @@ from langgraph.checkpoint.base.id import uuid6
 from langgraph.checkpoint.serde.types import _DeltaSnapshot
 
 from langgraph._internal._config import DELTA_MAX_SUPERSTEPS_SINCE_SNAPSHOT
+from langgraph._internal._constants import PUSH
 from langgraph._internal._typing import MISSING
 from langgraph.channels.base import BaseChannel
 from langgraph.channels.delta import DeltaChannel
@@ -70,6 +71,81 @@ def delta_channels_to_snapshot(
     return result
 
 
+def get_updated_channels_from_tasks(
+    run_tasks: Iterable[Any],
+) -> set[str]:
+    """Channel names written by an update_state superstep (excluding PUSH)."""
+    return {c for task in run_tasks for c, _ in task.writes if c != PUSH}
+
+
+def get_delta_channels_from_all_channels(
+    channels: Mapping[str, BaseChannel],
+) -> set[str]:
+    """DeltaChannels to snapshot on the first update_state of a fresh thread."""
+    return {
+        k
+        for k, ch in channels.items()
+        if isinstance(ch, DeltaChannel) and ch.is_available()
+    }
+
+
+def create_metadata_for_update_state_api(
+    channels: Mapping[str, BaseChannel],
+    updated_channels: set[str],
+    *,
+    prev_metadata: Mapping[str, Any] | None,
+) -> dict[str, tuple[int, int]]:
+    """Advance ``counters_since_delta_snapshot`` for update_state on a non-fresh thread.
+
+    Mirrors the per-superstep counter bump in ``_loop._put_checkpoint``.
+    """
+    prev_counters = dict(
+        (prev_metadata or {}).get("counters_since_delta_snapshot") or {}
+    )
+    new_counters: dict[str, tuple[int, int]] = {}
+    for ch_name, ch in channels.items():
+        if not isinstance(ch, DeltaChannel):
+            continue
+        u, s = prev_counters.get(ch_name, (0, 0))
+        s += 1
+        if ch_name in updated_channels:
+            u += 1
+        new_counters[ch_name] = (u, s)
+    return new_counters
+
+
+def create_checkpoint_plan_for_update_state_api(
+    channels: Mapping[str, BaseChannel],
+    updated_channels: set[str],
+    *,
+    step: int,
+    parents: dict[str, Any],
+    saved_metadata: Mapping[str, Any] | None,
+    is_fresh_thread: bool,
+) -> tuple[set[str], dict[str, Any]]:
+    """Return ``(channels_to_snapshot, metadata)`` for an update_state head."""
+    metadata: dict[str, Any] = {
+        "source": "update",
+        "step": step,
+        "parents": parents,
+    }
+    if is_fresh_thread:
+        return get_delta_channels_from_all_channels(channels), metadata
+
+    new_counters = create_metadata_for_update_state_api(
+        channels,
+        updated_channels,
+        prev_metadata=saved_metadata,
+    )
+    channels_to_snapshot = delta_channels_to_snapshot(channels, new_counters)
+    for k in channels_to_snapshot:
+        new_counters[k] = (0, 0)
+    non_zero = {k: v for k, v in new_counters.items() if v != (0, 0)}
+    if non_zero:
+        metadata["counters_since_delta_snapshot"] = non_zero
+    return channels_to_snapshot, metadata
+
+
 def create_checkpoint(
     checkpoint: Checkpoint,
     channels: Mapping[str, BaseChannel] | None,
@@ -102,6 +178,11 @@ def create_checkpoint(
                 continue
             ch = channels[k]
             if k in channels_to_snapshot:
+                # Callers force a full snapshot blob here: exit mode when a
+                # delta channel reaches its snapshot cadence, and update_state
+                # on a fresh thread (no ancestor to replay writes from). The
+                # manual version-bump below only applies to the exit-mode case.
+                #
                 # In exit mode, the snapshot decision is deferred to exit
                 # time (intermediate steps have do_checkpoint=False). The
                 # channel's count may have reached snapshot_frequency over

{langgraph-1.2.7 → langgraph-1.2.9}/langgraph/pregel/main.py

@@ -108,7 +108,6 @@ from langgraph.callbacks import (
     get_sync_graph_callback_manager_for_config,
 )
 from langgraph.channels.base import BaseChannel
-from langgraph.channels.delta import DeltaChannel
 from langgraph.channels.topic import Topic
 from langgraph.config import get_config
 from langgraph.constants import END
@@ -133,7 +132,9 @@ from langgraph.pregel._checkpoint import (
     channels_from_checkpoint,
     copy_checkpoint,
     create_checkpoint,
+    create_checkpoint_plan_for_update_state_api,
     empty_checkpoint,
+    get_updated_channels_from_tasks,
 )
 from langgraph.pregel._draw import draw_graph
 from langgraph.pregel._io import map_input, read_channels
@@ -1996,35 +1997,14 @@ class Pregel(
                         },
                     ),
                 )
-            # save task writes
-            has_delta_writes = any(
-                isinstance(channels.get(c), DeltaChannel)
-                for task in run_tasks
-                for c, _ in task.writes
-            )
-            should_put_writes = saved is not None or has_delta_writes
-
-            if saved is None and has_delta_writes:
-                # If there is no previous checkpoint, we need to create a stub checkpoint
-                # so the first delta writes has a parent to anchor under.
-                # This is the model of DeltaChannel.
-                stub = empty_checkpoint()
-                checkpoint_config = checkpointer.put(
-                    patch_configurable(
-                        checkpoint_config, {CONFIG_KEY_CHECKPOINT_ID: None}
-                    ),
-                    stub,
-                    {"source": "update", "step": -1, "parents": {}},
-                    {},
-                )
-
-            for task_id, task in zip(run_task_ids, run_tasks):
-                # channel writes are saved to current checkpoint
-                channel_writes = [w for w in task.writes if w[0] != PUSH]
-                if should_put_writes and channel_writes:
-                    checkpointer.put_writes(checkpoint_config, channel_writes, task_id)
-
-            # apply to checkpoint and save
+            updated_channels = get_updated_channels_from_tasks(run_tasks)
+            if saved is not None:
+                for task_id, task in zip(run_task_ids, run_tasks):
+                    channel_writes = [w for w in task.writes if w[0] != PUSH]
+                    if channel_writes:
+                        checkpointer.put_writes(
+                            checkpoint_config, channel_writes, task_id
+                        )
             apply_writes(
                 checkpoint,
                 channels,
@@ -2032,21 +2012,35 @@ class Pregel(
                 checkpointer.get_next_version,
                 self.trigger_to_nodes,
             )
-            checkpoint = create_checkpoint(checkpoint, channels, step + 1)
+            channels_to_snapshot, checkpoint_metadata = (
+                create_checkpoint_plan_for_update_state_api(
+                    channels,
+                    updated_channels,
+                    step=step + 1,
+                    parents=saved.metadata.get("parents", {}) if saved else {},
+                    saved_metadata=saved.metadata if saved else None,
+                    is_fresh_thread=saved is None,
+                )
+            )
+            checkpoint = create_checkpoint(
+                checkpoint,
+                channels,
+                step + 1,
+                updated_channels=updated_channels if channels_to_snapshot else None,
+                get_next_version=checkpointer.get_next_version
+                if channels_to_snapshot
+                else None,
+                channels_to_snapshot=channels_to_snapshot,
+            )
             next_config = checkpointer.put(
                 checkpoint_config,
                 checkpoint,
-                {
-                    "source": "update",
-                    "step": step + 1,
-                    "parents": saved.metadata.get("parents", {}) if saved else {},
-                },
+                checkpoint_metadata,
                 get_new_channel_versions(
                     checkpoint_previous_versions, checkpoint["channel_versions"]
                 ),
             )
             for task_id, task in zip(run_task_ids, run_tasks):
-                # save push writes
                 if push_writes := [w for w in task.writes if w[0] == PUSH]:
                     checkpointer.put_writes(next_config, push_writes, task_id)
 
@@ -2463,36 +2457,14 @@ class Pregel(
                         },
                     ),
                 )
-            # save task writes
-            has_delta_writes = any(
-                isinstance(channels.get(c), DeltaChannel)
-                for task in run_tasks
-                for c, _ in task.writes
-            )
-            should_put_writes = saved is not None or has_delta_writes
-
-            if saved is None and has_delta_writes:
-                # If there is no previous checkpoint, we need to create a stub checkpoint
-                # so the first delta writes has a parent to anchor under.
-                # This is the model of DeltaChannel.
-                stub = empty_checkpoint()
-                checkpoint_config = await checkpointer.aput(
-                    patch_configurable(
-                        checkpoint_config, {CONFIG_KEY_CHECKPOINT_ID: None}
-                    ),
-                    stub,
-                    {"source": "update", "step": -1, "parents": {}},
-                    {},
-                )
-
-            for task_id, task in zip(run_task_ids, run_tasks):
-                # channel writes are saved to current checkpoint
-                channel_writes = [w for w in task.writes if w[0] != PUSH]
-                if should_put_writes and channel_writes:
-                    await checkpointer.aput_writes(
-                        checkpoint_config, channel_writes, task_id
-                    )
-            # apply to checkpoint and save
+            updated_channels = get_updated_channels_from_tasks(run_tasks)
+            if saved is not None:
+                for task_id, task in zip(run_task_ids, run_tasks):
+                    channel_writes = [w for w in task.writes if w[0] != PUSH]
+                    if channel_writes:
+                        await checkpointer.aput_writes(
+                            checkpoint_config, channel_writes, task_id
+                        )
             apply_writes(
                 checkpoint,
                 channels,
@@ -2500,22 +2472,35 @@ class Pregel(
                 checkpointer.get_next_version,
                 self.trigger_to_nodes,
             )
-            checkpoint = create_checkpoint(checkpoint, channels, step + 1)
-            # save checkpoint, after applying writes
+            channels_to_snapshot, checkpoint_metadata = (
+                create_checkpoint_plan_for_update_state_api(
+                    channels,
+                    updated_channels,
+                    step=step + 1,
+                    parents=saved.metadata.get("parents", {}) if saved else {},
+                    saved_metadata=saved.metadata if saved else None,
+                    is_fresh_thread=saved is None,
+                )
+            )
+            checkpoint = create_checkpoint(
+                checkpoint,
+                channels,
+                step + 1,
+                updated_channels=updated_channels if channels_to_snapshot else None,
+                get_next_version=checkpointer.get_next_version
+                if channels_to_snapshot
+                else None,
+                channels_to_snapshot=channels_to_snapshot,
+            )
             next_config = await checkpointer.aput(
                 checkpoint_config,
                 checkpoint,
-                {
-                    "source": "update",
-                    "step": step + 1,
-                    "parents": saved.metadata.get("parents", {}) if saved else {},
-                },
+                checkpoint_metadata,
                 get_new_channel_versions(
                     checkpoint_previous_versions, checkpoint["channel_versions"]
                 ),
             )
             for task_id, task in zip(run_task_ids, run_tasks):
-                # save push writes
                 if push_writes := [w for w in task.writes if w[0] == PUSH]:
                     await checkpointer.aput_writes(next_config, push_writes, task_id)
             return patch_checkpoint_map(next_config, saved.metadata if saved else None)

{langgraph-1.2.7 → langgraph-1.2.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "langgraph"
-version = "1.2.7"
+version = "1.2.9"
 description = "Building stateful, multi-actor applications with LLMs"
 authors = []
 requires-python = ">=3.10"

{langgraph-1.2.7 → langgraph-1.2.9}/tests/test_delta_channel_update_state.py

@@ -1,20 +1,19 @@
 """Tests for `update_state` / `aupdate_state` against `DeltaChannel`.
 
-Originally a regression suite for deepagents#3774 — `update_state` on a *fresh*
-thread silently dropped the first write to a `DeltaChannel`-backed channel
-because channel writes were only persisted when a previous checkpoint existed.
-Fixed by lazily persisting an empty stub checkpoint on a fresh thread so the
-first write has a parent to anchor under (mirrors the exit-mode lazy-stub
-pattern in `_loop._put_exit_delta_writes`).
+Regression suite for deepagents#3774 and Postgres read-path compatibility.
+
+Fresh-thread ``update_state`` force-snapshots DeltaChannels (1.2.8). Non-fresh
+``update_state`` persists ``checkpoint_writes`` on the parent, advances
+``counters_since_delta_snapshot`` on the new head, and snapshots when a
+channel reaches ``snapshot_frequency`` (mirroring normal run cadence).
 
 Coverage:
 
-* fresh-thread regression: single `update_state` writes a message and reads back
-* non-fresh thread: `update_state` after `invoke`, after another `update_state`,
-  and `bulk_update_state` with multiple per-superstep updates
-* update-by-id end-to-end via `update_state` (DeltaChannel reducer semantics)
-* state-history chain shape on a fresh thread (lazy stub + update checkpoint
-  with correct parent linking)
+* fresh-thread regression: single ``update_state`` writes a message and reads back
+* non-fresh thread: ``update_state`` after ``invoke``, after another ``update_state``,
+  and ``bulk_update_state`` with multiple per-superstep updates
+* update-by-id end-to-end via ``update_state`` (DeltaChannel reducer semantics)
+* fresh-thread head is snapshotted; non-fresh heads carry delta replay counters
 """
 
 from typing import Annotated, Any
@@ -22,6 +21,7 @@ from typing import Annotated, Any
 import pytest
 from langchain_core.messages import HumanMessage
 from langgraph.checkpoint.memory import InMemorySaver
+from langgraph.checkpoint.serde.types import _DeltaSnapshot
 from typing_extensions import TypedDict
 
 from langgraph.channels.delta import DeltaChannel
@@ -31,13 +31,20 @@ from langgraph.graph.message import _messages_delta_reducer
 pytestmark = pytest.mark.anyio
 
 
-def _build_graph(checkpointer: InMemorySaver, *, two_nodes: bool = False) -> Any:
+def _build_graph(
+    checkpointer: InMemorySaver,
+    *,
+    two_nodes: bool = False,
+    snapshot_frequency: int = 1000,
+) -> Any:
     """Compile a minimal DeltaChannel-backed `messages` graph.
 
     `two_nodes=True` adds a second writer node so `bulk_update_state` can route
     distinct updates to different `as_node` values within a single superstep.
     """
-    channel = DeltaChannel(_messages_delta_reducer)
+    channel = DeltaChannel(
+        _messages_delta_reducer, snapshot_frequency=snapshot_frequency
+    )
     State = TypedDict("State", {"messages": Annotated[list, channel]})  # type: ignore[call-overload]  # noqa: UP013
 
     def model(state: dict) -> dict:
@@ -87,14 +94,30 @@ async def test_aupdate_state_fresh_thread_delta_channel() -> None:
     assert [m.content for m in state.values["messages"]] == ["hello"]
 
 
+def test_fresh_update_state_head_snapshots_delta_channel() -> None:
+    saver = InMemorySaver()
+    graph = _build_graph(saver)
+    config = {"configurable": {"thread_id": "fresh-head-snapshot"}}
+
+    graph.update_state(
+        config,
+        {"messages": [HumanMessage(content="hello", id="m1")]},
+        as_node="model",
+    )
+
+    head = saver.get_tuple(config)
+    assert head is not None
+    assert isinstance(head.checkpoint["channel_values"].get("messages"), _DeltaSnapshot)
+    assert head.metadata is not None
+    assert "counters_since_delta_snapshot" not in head.metadata
+
+
 # ---------------------------------------------------------------------------
 # Non-fresh thread: update_state after invoke
 # ---------------------------------------------------------------------------
 
 
 def test_update_state_after_invoke_delta_channel() -> None:
-    """The non-fresh-thread path was already working before the fix; pin it
-    down so the lazy-stub change for fresh threads doesn't regress it."""
     saver = InMemorySaver()
     graph = _build_graph(saver)
     config = {"configurable": {"thread_id": "after-invoke-sync"}}
@@ -110,6 +133,12 @@ def test_update_state_after_invoke_delta_channel() -> None:
     assert [m.content for m in state.values["messages"]] == ["seed", "appended"]
     assert [m.id for m in state.values["messages"]] == ["m1", "m2"]
 
+    head = saver.get_tuple(config)
+    assert head is not None
+    assert "messages" not in head.checkpoint["channel_values"]
+    assert head.metadata is not None
+    assert head.metadata["counters_since_delta_snapshot"]["messages"] == [2, 4]
+
 
 async def test_aupdate_state_after_invoke_delta_channel() -> None:
     saver = InMemorySaver()
@@ -133,9 +162,6 @@ async def test_aupdate_state_after_invoke_delta_channel() -> None:
 
 
 def test_consecutive_update_states_delta_channel() -> None:
-    """First update_state lazily persists a stub; the second sees a real
-    parent (`saved is not None`) and takes the original write path. Both
-    messages must round-trip in chronological order."""
     saver = InMemorySaver()
     graph = _build_graph(saver)
     config = {"configurable": {"thread_id": "consecutive-sync"}}
@@ -155,6 +181,39 @@ def test_consecutive_update_states_delta_channel() -> None:
     assert [m.content for m in state.values["messages"]] == ["first", "second"]
     assert [m.id for m in state.values["messages"]] == ["m1", "m2"]
 
+    head = saver.get_tuple(config)
+    assert head is not None
+    assert "messages" not in head.checkpoint["channel_values"]
+    assert head.metadata is not None
+    assert head.metadata["counters_since_delta_snapshot"]["messages"] == [1, 1]
+
+
+def test_update_state_snapshots_at_frequency() -> None:
+    """Non-fresh update_state snapshots when counters reach snapshot_frequency."""
+    saver = InMemorySaver()
+    graph = _build_graph(saver, snapshot_frequency=1)
+    config = {"configurable": {"thread_id": "snapshot-at-freq"}}
+
+    graph.update_state(
+        config,
+        {"messages": [HumanMessage(content="first", id="m1")]},
+        as_node="model",
+    )
+    graph.update_state(
+        config,
+        {"messages": [HumanMessage(content="second", id="m2")]},
+        as_node="model",
+    )
+
+    state = graph.get_state(config)
+    assert [m.content for m in state.values["messages"]] == ["first", "second"]
+
+    head = saver.get_tuple(config)
+    assert head is not None
+    assert isinstance(head.checkpoint["channel_values"].get("messages"), _DeltaSnapshot)
+    assert head.metadata is not None
+    assert "counters_since_delta_snapshot" not in head.metadata
+
 
 async def test_aconsecutive_update_states_delta_channel() -> None:
     saver = InMemorySaver()
@@ -252,14 +311,14 @@ def test_bulk_update_state_multi_task_per_superstep_delta_channel() -> None:
 
 
 # ---------------------------------------------------------------------------
-# Public-API observation of the lazy-stub mechanism
+# Public-API observation of fresh-thread checkpoint shape
 # ---------------------------------------------------------------------------
 
 
 def test_state_history_chain_after_fresh_update_state_delta_channel() -> None:
-    """A fresh-thread `update_state` should produce two checkpoints visible
-    via `get_state_history`: a stub (step=-1, no parent) and the update
-    (step=0, parent=stub). Both attributed `source='update'`."""
+    """A fresh-thread `update_state` should produce a single self-contained
+    checkpoint visible via `get_state_history`: step=0, `source='update'`,
+    no parent, with the DeltaChannel value snapshotted inline."""
     saver = InMemorySaver()
     graph = _build_graph(saver)
     config = {"configurable": {"thread_id": "history-chain"}}
@@ -270,25 +329,12 @@ def test_state_history_chain_after_fresh_update_state_delta_channel() -> None:
         as_node="model",
     )
 
-    # Newest first per `get_state_history` ordering.
     history = list(graph.get_state_history(config))
-    assert len(history) == 2
-
-    update_snapshot, stub_snapshot = history
+    assert len(history) == 1
 
+    (update_snapshot,) = history
     assert update_snapshot.metadata is not None
     assert update_snapshot.metadata["source"] == "update"
     assert update_snapshot.metadata["step"] == 0
+    assert update_snapshot.parent_config is None
     assert [m.content for m in update_snapshot.values["messages"]] == ["hello"]
-
-    assert stub_snapshot.metadata is not None
-    assert stub_snapshot.metadata["source"] == "update"
-    assert stub_snapshot.metadata["step"] == -1
-    assert stub_snapshot.parent_config is None
-
-    # The update checkpoint's parent is the stub.
-    assert update_snapshot.parent_config is not None
-    assert (
-        update_snapshot.parent_config["configurable"]["checkpoint_id"]
-        == stub_snapshot.config["configurable"]["checkpoint_id"]
-    )