From 8ac829616aecd8595f9f908bd5055090d9f514cd Mon Sep 17 00:00:00 2001 From: Nick Hollon Date: Thu, 30 Apr 2026 15:46:40 -0400 Subject: [PATCH] docs(langgraph): rewrite stream_v2 references to stream_events v3 Update all docstrings and comments in production code that referred to stream_v2/astream_v2 to use stream_events(version="v3") / astream_events(version="v3") instead. --- libs/langgraph/langgraph/graph/state.py | 2 +- libs/langgraph/langgraph/pregel/_messages.py | 2 +- libs/langgraph/langgraph/pregel/main.py | 8 ++++---- libs/langgraph/langgraph/stream/__init__.py | 4 ++-- libs/langgraph/langgraph/stream/_types.py | 2 +- libs/langgraph/langgraph/stream/transformers.py | 14 +++++++------- 6 files changed, 16 insertions(+), 16 deletions(-) diff --git a/libs/langgraph/langgraph/graph/state.py b/libs/langgraph/langgraph/graph/state.py index 2bc1a7239..6f31431c9 100644 --- a/libs/langgraph/langgraph/graph/state.py +++ b/libs/langgraph/langgraph/graph/state.py @@ -1128,7 +1128,7 @@ class StateGraph(Generic[StateT, ContextT, InputT, OutputT]): name: The name to use for the compiled graph. transformers: Optional sequence of `StreamTransformer` classes or configured factories. Classes and factories are instantiated - per run whenever `stream_v2` / `astream_v2` is called and are + per run whenever `stream_events(version="v3")` / `astream_events(version="v3")` is called and are propagated to subgraph scopes. Custom factories should follow the standard `StreamTransformer` constructor shape by accepting `scope` as their first argument. Appended after the diff --git a/libs/langgraph/langgraph/pregel/_messages.py b/libs/langgraph/langgraph/pregel/_messages.py index aa1db1ac9..5f7d3af16 100644 --- a/libs/langgraph/langgraph/pregel/_messages.py +++ b/libs/langgraph/langgraph/pregel/_messages.py @@ -349,7 +349,7 @@ class StreamMessagesHandlerV2(StreamMessagesHandler, _V2StreamingCallbackHandler tags: list[str] | None = None, **kwargs: Any, ) -> Any: - """Forward a protocol event from `stream_v2` as a messages stream part. + """Forward a protocol event from `stream_events(version="v3")` as a messages stream part. Fires once per `MessagesData` event (`message-start`, per-block `content-block-*`, `message-finish`). The transformer layer diff --git a/libs/langgraph/langgraph/pregel/main.py b/libs/langgraph/langgraph/pregel/main.py index 43f5f6708..468fb74b2 100644 --- a/libs/langgraph/langgraph/pregel/main.py +++ b/libs/langgraph/langgraph/pregel/main.py @@ -378,7 +378,7 @@ def _collect_stream_modes(mux: Any) -> list[StreamMode]: """Return the union of `required_stream_modes` across registered transformers. Transformers declare the stream modes they need to function, and - `stream_v2` asks the graph for exactly that union — no hardcoded + `stream_events(version="v3")` asks the graph for exactly that union — no hardcoded default set. If zero transformers declare a given mode, the graph does not stream events for it. """ @@ -408,14 +408,14 @@ def _normalize_stream_transformer_factories( for spec in specs or (): if isinstance(spec, StreamTransformer): raise TypeError( - "stream_v2 transformers must be scope-aware callables, " + "stream_events(version='v3') transformers must be scope-aware callables, " f"got pre-built instance {type(spec).__name__}. Pass the " "transformer class or a factory like " "`lambda scope: MyTransformer(scope, ...)`." ) if not callable(spec): raise TypeError( - "stream_v2 transformers must be scope-aware callables, " + "stream_events(version='v3') transformers must be scope-aware callables, " f"got {type(spec).__name__}." ) @@ -4145,7 +4145,7 @@ def _resolve_parent_ns( ) -> tuple[str, ...]: """Return the checkpoint namespace the caller is running under. - `stream_v2` uses this to scope its native projections + `stream_events(version="v3")` uses this to scope its native projections (`ValuesTransformer`, `MessagesTransformer`) to events emitted at the run's own level. A root call resolves to `()`; a call made from inside a node carries the outer graph's task namespace so the diff --git a/libs/langgraph/langgraph/stream/__init__.py b/libs/langgraph/langgraph/stream/__init__.py index 294b760b2..e67b5131a 100644 --- a/libs/langgraph/langgraph/stream/__init__.py +++ b/libs/langgraph/langgraph/stream/__init__.py @@ -1,7 +1,7 @@ """Streaming infrastructure for LangGraph. -Compile a graph with `transformers=[...]` and call `graph.stream_v2()` / -`graph.astream_v2()` to drive a transformer pipeline that projects the +Compile a graph with `transformers=[...]` and call `graph.stream_events(version="v3")` / +`graph.astream_events(version="v3")` to drive a transformer pipeline that projects the graph's raw events into ergonomic per-channel streams. """ diff --git a/libs/langgraph/langgraph/stream/_types.py b/libs/langgraph/langgraph/stream/_types.py index 4001c8860..38a4e78ad 100644 --- a/libs/langgraph/langgraph/stream/_types.py +++ b/libs/langgraph/langgraph/stream/_types.py @@ -88,7 +88,7 @@ class StreamTransformer(ABC): required_stream_modes: Stream modes the graph must emit for this transformer to have anything to process. Computed as the union across all registered transformers to determine - which modes a `stream_v2` run requests from the graph. + which modes a `stream_events(version="v3")` run requests from the graph. Empty tuple means the transformer consumes only synthetic events (or is purely passive). """ diff --git a/libs/langgraph/langgraph/stream/transformers.py b/libs/langgraph/langgraph/stream/transformers.py index ef0ef4bf9..0ce420af7 100644 --- a/libs/langgraph/langgraph/stream/transformers.py +++ b/libs/langgraph/langgraph/stream/transformers.py @@ -38,8 +38,8 @@ class ValuesTransformer(StreamTransformer): Only values events at the run's own level are captured; snapshots from deeper subgraphs are left in the main event log but excluded from the projection. "Own level" is defined by `scope`, which - `stream_v2` / `astream_v2` populate from the caller's - checkpoint namespace so that a nested `stream_v2` call still + `stream_events(version="v3")` / `astream_events(version="v3")` populate from the caller's + checkpoint namespace so that a nested `stream_events(version="v3")` call still sees its own root snapshots. """ @@ -165,7 +165,7 @@ class MessagesTransformer(StreamTransformer): metadata)` from `StreamMessagesHandler`): 1. Protocol event (dict with `"event"` key) — emitted by - `stream_v2()` / `astream_v2()` via the `on_stream_event` + `stream_events(version="v3")` / `astream_events(version="v3")` via the `on_stream_event` callback. Routed to an existing `ChatModelStream` by `metadata["run_id"]`. A `message-start` event creates a new stream; `message-finish` closes it. @@ -177,15 +177,15 @@ class MessagesTransformer(StreamTransformer): V1 `AIMessageChunk` tuples (from `on_llm_new_token`) are not streamed into this projection: chat models that want to populate `run.messages` with content-block streaming must use - `stream_v2()` / `astream_v2()`. Models called via the legacy + `stream_events(version="v3")` / `astream_events(version="v3")`. Models called via the legacy `stream()` method still surface their final `AIMessage` via `on_chain_end` when a node returns it as state. Only events at the run's own level are projected; tokens from deeper subgraphs are left in the main event log but excluded from `.messages`. "Own level" is defined by `scope`, which - `stream_v2` / `astream_v2` populate from the caller's checkpoint - namespace so that a `stream_v2` call inside a node still sees its + `stream_events(version="v3")` / `astream_events(version="v3")` populate from the caller's checkpoint + namespace so that a `stream_events(version="v3")` call inside a node still sees its own root chat model streams on `.messages`. Consumers that need subgraph tokens should iterate the raw event stream or register a custom transformer. @@ -281,7 +281,7 @@ class MessagesTransformer(StreamTransformer): ): self._route_whole_message(payload, node=node) # Legacy AIMessageChunk tuples (from on_llm_new_token) are ignored; - # v1 streaming callers must switch to stream_v2() to populate this + # v1 streaming callers must switch to stream_events(version="v3") to populate this # projection. return True