langgraph 1.2.6__tar.gz → 1.2.7__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langgraph
-Version: 1.2.6
+Version: 1.2.7
 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.6 → langgraph-1.2.7}/langgraph/channels/binop.py

@@ -29,11 +29,25 @@ def _strip_extras(t):  # type: ignore[no-untyped-def]
 
 
 def _get_overwrite(value: Any) -> tuple[bool, Any]:
-    """Inspects the given value and returns (is_overwrite, overwrite_value)."""
+    """Inspects the given value and returns (is_overwrite, overwrite_value).
+
+    Recognises three forms:
+
+    * The typed `Overwrite` dataclass instance.
+    * The sentinel-keyed `{"__overwrite__": value}` dict form.
+    * The dataclass-erased `{"value": ..., "type": "__overwrite__"}` form that
+      results from JSON-serialising an `Overwrite` (e.g. an `orjson`-encoded
+      state update routed through the LangGraph API server). This keeps the
+      `Overwrite` semantics intact across JSON boundaries that strip dataclass
+      types.
+    """
     if isinstance(value, Overwrite):
         return True, value.value
-    if isinstance(value, dict) and len(value) == 1 and OVERWRITE in value:
-        return True, value[OVERWRITE]
+    if isinstance(value, dict):
+        if len(value) == 1 and OVERWRITE in value:
+            return True, value[OVERWRITE]
+        if value.get("type") == OVERWRITE and "value" in value:
+            return True, value["value"]
     return False, None
 
 

{langgraph-1.2.6 → langgraph-1.2.7}/langgraph/channels/delta.py

@@ -172,13 +172,11 @@ class DeltaChannel(Generic[Value], BaseChannel[Any, Any, Any]):
                 overwrite_idx = i
         if overwrite_idx is not None:
             _, overwrite_value = _get_overwrite(values[overwrite_idx])
-            base = (
+            self.value = (
                 _copy.copy(overwrite_value)
                 if overwrite_value is not None
                 else self.typ()
             )
-            remaining = [v for i, v in enumerate(values) if i != overwrite_idx]
-            self.value = self.reducer(base, remaining) if remaining else base
             return True
         base = self.typ() if self.value is MISSING else self.value
         self.value = self.reducer(base, list(values))

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

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import uuid
 from collections.abc import Callable, Mapping
 from datetime import datetime, timezone
 from typing import Any, cast
@@ -34,6 +35,17 @@ def empty_checkpoint() -> Checkpoint:
     )
 
 
+def exit_delta_task_id(step: int, task_id: str) -> str:
+    """Synthetic task id for exit-mode DeltaChannel writes.
+
+    Embeds the superstep in the first UUID group so `ORDER BY task_id, idx`
+    preserves chronological order while remaining a valid RFC UUID (required by
+    Postgres `checkpoint_writes.task_id uuid` columns).
+    """
+    parts = str(uuid.UUID(task_id)).split("-")
+    return f"{step:08d}-{parts[1]}-{parts[2]}-{parts[3]}-{parts[4]}"
+
+
 def delta_channels_to_snapshot(
     channels: Mapping[str, BaseChannel],
     counters_since_delta_snapshot: Mapping[str, tuple[int, int]],

{langgraph-1.2.6 → langgraph-1.2.7}/langgraph/pregel/_loop.py

@@ -70,6 +70,7 @@ from langgraph.callbacks import (
     GraphResumeEvent,
 )
 from langgraph.channels.base import BaseChannel
+from langgraph.channels.binop import _get_overwrite
 from langgraph.channels.delta import DeltaChannel
 from langgraph.channels.untracked_value import UntrackedValue
 from langgraph.constants import TAG_HIDDEN
@@ -102,6 +103,7 @@ from langgraph.pregel._checkpoint import (
     create_checkpoint,
     delta_channels_to_snapshot,
     empty_checkpoint,
+    exit_delta_task_id,
 )
 from langgraph.pregel._executor import (
     AsyncBackgroundExecutor,
@@ -220,6 +222,11 @@ class PregelLoop:
     # under the saver's `ORDER BY task_id, idx` sorting.
     _exit_delta_writes: list[tuple[int, str, str, Any]] | None = None
 
+    # Delta channels that saw an Overwrite since the last checkpoint. These
+    # channels must snapshot after live update applies overwrite semantics so
+    # sparse replay starts from the same post-overwrite value.
+    _delta_channels_with_overwrite: set[str]
+
     # The checkpoint_config that points at the parent loaded at `__enter__`
     # (or the synthetic-empty checkpoint, on first run). We capture it
     # eagerly because every `_put_checkpoint` advances `self.checkpoint_config`
@@ -676,6 +683,11 @@ class PregelLoop:
     def after_tick(self) -> None:
         # finish superstep
         writes = [w for t in self.tasks.values() for w in t.writes]
+        self._delta_channels_with_overwrite.update(
+            ch
+            for ch, v in writes
+            if isinstance(self.specs.get(ch), DeltaChannel) and _get_overwrite(v)[0]
+        )
         # all tasks have finished
         self.updated_channels = apply_writes(
             self.checkpoint,
@@ -979,6 +991,11 @@ class PregelLoop:
                 manager=None,
                 updated_channels=updated_channels,
             )
+            self._delta_channels_with_overwrite.update(
+                c
+                for c, v in input_writes
+                if isinstance(self.specs.get(c), DeltaChannel) and _get_overwrite(v)[0]
+            )
             # apply input writes
             updated_channels = apply_writes(
                 self.checkpoint,
@@ -1119,6 +1136,7 @@ class PregelLoop:
         # create new checkpoint
         channels_to_snapshot = (
             delta_channels_to_snapshot(self.channels, new_counters)
+            | self._delta_channels_with_overwrite
             if do_checkpoint
             else set()
         )
@@ -1135,6 +1153,8 @@ class PregelLoop:
         )
         for k in channels_to_snapshot:
             new_counters[k] = (0, 0)
+        if do_checkpoint:
+            self._delta_channels_with_overwrite.difference_update(channels_to_snapshot)
         non_zero = {k: v for k, v in new_counters.items() if v != (0, 0)}
         if non_zero:
             self.checkpoint_metadata["counters_since_delta_snapshot"] = non_zero
@@ -1217,7 +1237,10 @@ class PregelLoop:
         counters = dict(
             self.checkpoint_metadata.get("counters_since_delta_snapshot") or {}
         )
-        channels_to_snapshot = delta_channels_to_snapshot(self.channels, counters)
+        channels_to_snapshot = (
+            delta_channels_to_snapshot(self.channels, counters)
+            | self._delta_channels_with_overwrite
+        )
 
         pending = [
             (step, tid, ch, v)
@@ -1272,7 +1295,7 @@ class PregelLoop:
             },
         )
         for (step, tid), entries in grouped.items():
-            synth_tid = f"{step:08d}-{tid}"
+            synth_tid = exit_delta_task_id(step, tid)
             if self.checkpointer_put_writes_accepts_task_path:
                 fut = self.submit(
                     self.checkpointer_put_writes,
@@ -1661,6 +1684,7 @@ class SyncPregelLoop(PregelLoop, AbstractContextManager):
         )
         self._delta_write_futs = []
         self._error_handler_write_futs = []
+        self._delta_channels_with_overwrite = set()
         self._exit_delta_writes = (
             [] if self.durability == "exit" and self.checkpointer is not None else None
         )
@@ -1918,6 +1942,7 @@ class AsyncPregelLoop(PregelLoop, AbstractAsyncContextManager):
         )
         self._delta_write_futs = []
         self._error_handler_write_futs = []
+        self._delta_channels_with_overwrite = set()
         self._exit_delta_writes = (
             [] if self.durability == "exit" and self.checkpointer is not None else None
         )

{langgraph-1.2.6 → langgraph-1.2.7}/langgraph/types.py

@@ -976,3 +976,9 @@ class Overwrite:
 
     value: Any
     """The value to write directly to the channel, bypassing any reducer."""
+
+    type: Literal["__overwrite__"] = "__overwrite__"
+    """Discriminator field. Lets the channel reducer recognise an `Overwrite`
+    even after its dataclass form is JSON-serialised and the typed instance
+    is lost (e.g. an `orjson`-encoded state update routed through the
+    LangGraph API server)."""

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

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

{langgraph-1.2.6 → langgraph-1.2.7}/tests/test_channels.py

@@ -186,6 +186,50 @@ def test_delta_channel_overwrite() -> None:
     assert ch.get()[0].content == "new"
 
 
+def test_overwrite_dataclass_form_survives_json_roundtrip() -> None:
+    """`Overwrite` serialised with `orjson` collapses to a plain dict but
+    must still be recognised as an overwrite by the channel reducer.
+
+    Without the `type` discriminator the dataclass-erased shape (`{"value":
+    ...}`) is indistinguishable from a literal channel value, and downstream
+    reducers raise `MESSAGE_COERCION_FAILURE` (or similar) on read.
+    """
+    import orjson
+
+    from langgraph._internal._constants import OVERWRITE
+    from langgraph.channels.binop import _get_overwrite
+
+    ow = Overwrite(value=[HumanMessage(content="new", id="h2")])
+    erased = orjson.loads(orjson.dumps(ow, default=lambda o: o.model_dump()))
+
+    assert erased["type"] == OVERWRITE
+    is_overwrite, value = _get_overwrite(erased)
+    assert is_overwrite
+    assert isinstance(value, list)
+    assert value[0]["content"] == "new"
+
+
+def test_overwrite_sentinel_dict_still_recognised() -> None:
+    """The pre-existing `{"__overwrite__": value}` dict form continues to be
+    recognised. This is the canonical sentinel emitted by producers that do
+    not have an `Overwrite` dataclass available."""
+    from langgraph._internal._constants import OVERWRITE
+    from langgraph.channels.binop import _get_overwrite
+
+    is_overwrite, value = _get_overwrite({OVERWRITE: ["b"]})
+    assert is_overwrite
+    assert value == ["b"]
+
+
+def test_overwrite_non_matching_dict_not_recognised() -> None:
+    """Dicts that resemble the erased shape but do not carry the
+    `__overwrite__` discriminator must not be misclassified as overwrites."""
+    from langgraph.channels.binop import _get_overwrite
+
+    assert _get_overwrite({"value": ["b"]}) == (False, None)
+    assert _get_overwrite({"type": "human", "value": "hi"}) == (False, None)
+
+
 def test_delta_channel_remove_message_and_replay() -> None:
     """RemoveMessage must round-trip correctly when writes are replayed."""
     spec = DeltaChannel(_messages_delta_reducer, list)
@@ -397,6 +441,93 @@ def test_delta_channel_inmemory_saver_assembles_writes() -> None:
     assert len(state.values["messages"]) == 4  # 2 human + 2 AI
 
 
+def test_delta_channel_overwrite_superstep_snapshots() -> None:
+    def reducer(state: list[str], writes: Sequence[list[str]]) -> list[str]:
+        result = list(state)
+        for write in writes:
+            result.extend(write)
+        return result
+
+    class State(TypedDict):
+        items: Annotated[
+            list[str], DeltaChannel(reducer, list, snapshot_frequency=1000)
+        ]
+
+    def node_a(state: State) -> dict:
+        return {"items": ["a"]}
+
+    def node_b(state: State) -> dict:
+        return {"items": Overwrite(["b"])}
+
+    def node_c(state: State) -> dict:
+        return {"items": ["c"]}
+
+    builder = StateGraph(State)
+    builder.add_node("node_a", node_a)
+    builder.add_node("node_b", node_b)
+    builder.add_node("node_c", node_c)
+    builder.add_edge(START, "node_a")
+    builder.add_edge("node_a", "node_b")
+    builder.add_edge("node_a", "node_c")
+
+    saver = InMemorySaver()
+    graph = builder.compile(checkpointer=saver)
+    config = {"configurable": {"thread_id": "overwrite-snapshot"}}
+
+    result = graph.invoke({"items": ["START"]}, config)
+    assert result == {"items": ["b"]}
+
+    saved = saver.get_tuple(config)
+    assert saved is not None
+    snapshot = saved.checkpoint["channel_values"].get("items")
+    assert isinstance(snapshot, _DeltaSnapshot)
+    assert snapshot.value == ["b"]
+    assert saved.metadata.get("counters_since_delta_snapshot", {}).get("items") is None
+
+
+def test_delta_channel_replay_after_overwrite_snapshot() -> None:
+    def reducer(state: list[str], writes: Sequence[list[str]]) -> list[str]:
+        result = list(state)
+        for write in writes:
+            result.extend(write)
+        return result
+
+    class State(TypedDict):
+        items: Annotated[
+            list[str], DeltaChannel(reducer, list, snapshot_frequency=1000)
+        ]
+
+    calls = 0
+
+    def node(state: State) -> dict:
+        nonlocal calls
+        calls += 1
+        if calls == 1:
+            return {"items": Overwrite(["reset"])}
+        return {"items": ["after"]}
+
+    builder = StateGraph(State)
+    builder.add_node("node", node)
+    builder.add_edge(START, "node")
+
+    saver = InMemorySaver()
+    graph = builder.compile(checkpointer=saver)
+    config = {"configurable": {"thread_id": "overwrite-replay"}}
+
+    assert graph.invoke({"items": ["before"]}, config) == {"items": ["reset"]}
+    first_saved = saver.get_tuple(config)
+    assert first_saved is not None
+    assert isinstance(
+        first_saved.checkpoint["channel_values"].get("items"), _DeltaSnapshot
+    )
+
+    assert graph.invoke({"items": []}, config) == {"items": ["reset", "after"]}
+    second_saved = saver.get_tuple(config)
+    assert second_saved is not None
+    assert "items" not in second_saved.checkpoint["channel_values"]
+    assert graph.get_state(config).values == {"items": ["reset", "after"]}
+
+
 # ---------------------------------------------------------------------------
 # DeltaChannel — dict reducer
 # ---------------------------------------------------------------------------

{langgraph-1.2.6 → langgraph-1.2.7}/tests/test_delta_channel_exit_mode.py

@@ -6,6 +6,7 @@ channel), lazy stub creation when no parent exists, and proper read-path
 reconstruction via ancestor walks.
 """
 
+import uuid
 from typing import Annotated, Any
 
 import pytest
@@ -17,10 +18,28 @@ from typing_extensions import TypedDict
 from langgraph.channels.delta import DeltaChannel
 from langgraph.graph import START, StateGraph
 from langgraph.graph.message import _messages_delta_reducer
+from langgraph.pregel._checkpoint import exit_delta_task_id
 
 pytestmark = pytest.mark.anyio
 
 
+def test_exit_delta_task_id_is_valid_uuid_and_ordered() -> None:
+    """Exit-mode synthetic task ids must parse as UUID and sort by superstep."""
+    tid = "4f7226e4-0270-bf16-1ef8-fb321bef9f3d"
+    id1 = exit_delta_task_id(1, tid)
+    id7 = exit_delta_task_id(7, tid)
+
+    uuid.UUID(id1)
+    uuid.UUID(id7)
+    assert id1 < id7
+    assert id1.split("-")[0] == "00000001"
+    assert id7.split("-")[0] == "00000007"
+    assert id1.endswith("-0270-bf16-1ef8-fb321bef9f3d")
+
+    with pytest.raises(ValueError):
+        uuid.UUID(f"00000001-{tid}")
+
+
 def _build_graph(
     checkpointer: InMemorySaver,
     *,

{langgraph-1.2.6 → langgraph-1.2.7}/tests/test_pregel.py

@@ -2755,23 +2755,26 @@ def test_in_one_fan_out_state_graph_waiting_edge_plus_regular(
         "answer": "doc1,doc2,doc3,doc4",
     }
 
-    assert [*app.stream({"query": "what is weather in sf"})] in (
-        [
-            {"rewrite_query": {"query": "query: what is weather in sf"}},
-            {"qa": {"answer": ""}},
-            {"analyzer_one": {"query": "analyzed: query: what is weather in sf"}},
-            {"retriever_two": {"docs": ["doc3", "doc4"]}},
-            {"retriever_one": {"docs": ["doc1", "doc2"]}},
-            {"qa": {"answer": "doc1,doc2,doc3,doc4"}},
-        ],
-        [
-            {"rewrite_query": {"query": "query: what is weather in sf"}},
-            {"analyzer_one": {"query": "analyzed: query: what is weather in sf"}},
-            {"qa": {"answer": ""}},
-            {"retriever_two": {"docs": ["doc3", "doc4"]}},
-            {"retriever_one": {"docs": ["doc1", "doc2"]}},
-            {"qa": {"answer": "doc1,doc2,doc3,doc4"}},
-        ],
+    rewrite = {"rewrite_query": {"query": "query: what is weather in sf"}}
+    analyzer = {"analyzer_one": {"query": "analyzed: query: what is weather in sf"}}
+    empty_qa = {"qa": {"answer": ""}}
+    retriever_one_result = {"retriever_one": {"docs": ["doc1", "doc2"]}}
+    retriever_two_result = {"retriever_two": {"docs": ["doc3", "doc4"]}}
+
+    def assert_valid_stream_order(
+        chunks: list[dict[str, Any]], terminal: dict[str, Any]
+    ) -> None:
+        assert chunks[0] == rewrite
+        assert chunks[-1] == terminal
+        middle = chunks[1:-1]
+        assert sorted(middle, key=repr) == sorted(
+            [empty_qa, analyzer, retriever_one_result, retriever_two_result], key=repr
+        )
+        assert middle.index(analyzer) < middle.index(retriever_one_result)
+
+    assert_valid_stream_order(
+        [*app.stream({"query": "what is weather in sf"})],
+        {"qa": {"answer": "doc1,doc2,doc3,doc4"}},
     )
 
     app_w_interrupt = workflow.compile(
@@ -2780,25 +2783,9 @@ def test_in_one_fan_out_state_graph_waiting_edge_plus_regular(
     )
     config = {"configurable": {"thread_id": "1"}}
 
-    assert [
-        c for c in app_w_interrupt.stream({"query": "what is weather in sf"}, config)
-    ] in (
-        [
-            {"rewrite_query": {"query": "query: what is weather in sf"}},
-            {"qa": {"answer": ""}},
-            {"analyzer_one": {"query": "analyzed: query: what is weather in sf"}},
-            {"retriever_two": {"docs": ["doc3", "doc4"]}},
-            {"retriever_one": {"docs": ["doc1", "doc2"]}},
-            {"__interrupt__": ()},
-        ],
-        [
-            {"rewrite_query": {"query": "query: what is weather in sf"}},
-            {"analyzer_one": {"query": "analyzed: query: what is weather in sf"}},
-            {"qa": {"answer": ""}},
-            {"retriever_two": {"docs": ["doc3", "doc4"]}},
-            {"retriever_one": {"docs": ["doc1", "doc2"]}},
-            {"__interrupt__": ()},
-        ],
+    assert_valid_stream_order(
+        [c for c in app_w_interrupt.stream({"query": "what is weather in sf"}, config)],
+        {"__interrupt__": ()},
     )
 
     assert [c for c in app_w_interrupt.stream(None, config)] == [
@@ -6291,14 +6278,15 @@ def test_sync_streaming_with_functional_api() -> None:
     rather than have all the results arrive at once after the graph has completed.
 
     The time of arrival between the two updates corresponding to the two `slow` tasks
-    should be greater than the time delay between the two tasks.
+    should be roughly the task delay. If results are buffered until graph completion,
+    the two updates arrive back-to-back instead.
     """
 
     time_delay = 0.05
 
     @task()
     def slow() -> dict:
-        time.sleep(time_delay)  # Simulate a delay of 10 ms
+        time.sleep(time_delay)
         return {"tic": time.monotonic()}
 
     @entrypoint()
@@ -6316,8 +6304,9 @@ def test_sync_streaming_with_functional_api() -> None:
 
     assert len(arrival_times) == 2
     delta = arrival_times[1] - arrival_times[0]
-    # Delta cannot be less than 10 ms if it is streaming as results are generated.
-    assert delta > time_delay
+    # Allow a small amount of scheduler jitter while still verifying the chunks
+    # arrived separately rather than back-to-back after graph completion.
+    assert delta > time_delay * 0.8
 
 
 def test_entrypoint_without_checkpointer() -> None: