From 536b471efd8e8c7348b574069e2162d2c9ecad40 Mon Sep 17 00:00:00 2001 From: Nick Hollon Date: Thu, 30 Apr 2026 15:01:40 -0400 Subject: [PATCH] docs(core): rewrite stream_v2 references to stream_events v3 Update all docstrings and comments in production code to refer to the public stream_events(version="v3") / astream_events(version="v3") API rather than the removed stream_v2 / astream_v2 methods. --- libs/core/langchain_core/callbacks/base.py | 4 +-- libs/core/langchain_core/callbacks/manager.py | 4 +-- .../language_models/chat_model_stream.py | 34 +++++++++---------- .../language_models/chat_models.py | 6 ++-- .../core/langchain_core/tracers/_streaming.py | 2 +- 5 files changed, 25 insertions(+), 25 deletions(-) diff --git a/libs/core/langchain_core/callbacks/base.py b/libs/core/langchain_core/callbacks/base.py index 383b256cb26..7c7a721f72b 100644 --- a/libs/core/langchain_core/callbacks/base.py +++ b/libs/core/langchain_core/callbacks/base.py @@ -134,7 +134,7 @@ class LLMManagerMixin: tags: list[str] | None = None, **kwargs: Any, ) -> Any: - """Run on each protocol event produced by `stream_v2` / `astream_v2`. + """Run on each protocol event produced by `stream_events(version="v3")` / `astream_events(version="v3")`. Fires once per `MessagesData` event — `message-start`, per-block `content-block-start` / `content-block-delta` / @@ -699,7 +699,7 @@ class AsyncCallbackHandler(BaseCallbackHandler): tags: list[str] | None = None, **kwargs: Any, ) -> None: - """Run on each protocol event produced by `astream_v2`. + """Run on each protocol event produced by `astream_events(version="v3")`. See :meth:`LLMManagerMixin.on_stream_event` for the full contract. Fires once per `MessagesData` event at event granularity, uniformly diff --git a/libs/core/langchain_core/callbacks/manager.py b/libs/core/langchain_core/callbacks/manager.py index 0efab4ad04c..c1ba9b76c0a 100644 --- a/libs/core/langchain_core/callbacks/manager.py +++ b/libs/core/langchain_core/callbacks/manager.py @@ -749,7 +749,7 @@ class CallbackManagerForLLMRun(RunManager, LLMManagerMixin): ) def on_stream_event(self, event: MessagesData, **kwargs: Any) -> None: - """Run on each protocol event from `stream_v2`. + """Run on each protocol event from `stream_events(version="v3")`. Args: event: The protocol event. @@ -871,7 +871,7 @@ class AsyncCallbackManagerForLLMRun(AsyncRunManager, LLMManagerMixin): ) async def on_stream_event(self, event: MessagesData, **kwargs: Any) -> None: - """Run on each protocol event from `astream_v2`. + """Run on each protocol event from `astream_events(version="v3")`. Args: event: The protocol event. diff --git a/libs/core/langchain_core/language_models/chat_model_stream.py b/libs/core/langchain_core/language_models/chat_model_stream.py index 678727625eb..2c05f0faea7 100644 --- a/libs/core/langchain_core/language_models/chat_model_stream.py +++ b/libs/core/langchain_core/language_models/chat_model_stream.py @@ -1,8 +1,8 @@ """Per-message streaming objects for content-block protocol events. `ChatModelStream` is the synchronous variant returned by -`BaseChatModel.stream_v2()`. `AsyncChatModelStream` is the -asynchronous variant returned by `BaseChatModel.astream_v2()`. +`BaseChatModel.stream_events(version="v3")`. `AsyncChatModelStream` is the +asynchronous variant returned by `BaseChatModel.astream_events(version="v3")`. Both expose typed projection properties (`.text`, `.reasoning`, `.tool_calls`, `.usage`, `.output`) that accumulate protocol @@ -546,9 +546,9 @@ class _ChatModelStreamBase: def set_message_id(self, message_id: str) -> None: """Assign the stable message identifier once the run starts. - Called by the stream driver (`stream_v2` / `astream_v2`) after - `on_chat_model_start` produces a run id. Not intended for - end-user code. + Called by the stream driver (`stream_events(version="v3")` / + `astream_events(version="v3")`) after `on_chat_model_start` produces a run + id. Not intended for end-user code. """ self._message_id = message_id @@ -568,8 +568,8 @@ class _ChatModelStreamBase: Unlike `ChatModelStream.output` (which blocks until the stream finishes), this never pumps, blocks, or raises. Intended for the - stream driver (`stream_v2` / `astream_v2`) to check whether the - stream produced a message before firing `on_llm_end` callbacks. + stream driver (`stream_events(version="v3")` / `astream_events(version="v3")`) + to check whether the stream produced a message before firing `on_llm_end` callbacks. """ return self._output_message @@ -579,8 +579,8 @@ class _ChatModelStreamBase: """Route a protocol event to the appropriate internal handler. Public entry point for feeding events into the stream. Called by - the stream driver (`stream_v2` / `astream_v2`'s pump) and by - any observer or test that needs to inject protocol events. + the stream driver (`stream_events(version="v3")` / `astream_events(version="v3")`'s + pump) and by any observer or test that needs to inject protocol events. """ self._record_event(event) event_type = event.get("event") @@ -937,8 +937,8 @@ class _ChatModelStreamBase: def fail(self, error: BaseException) -> None: """Mark the stream as errored and propagate to all projections. - Public API — called by the stream driver (`stream_v2` / - `astream_v2`) when the underlying producer raises, by + Public API — called by the stream driver (`stream_events(version="v3")` / + `astream_events(version="v3")`) when the underlying producer raises, by `dispatch` when an `error` protocol event arrives, and by cancellation paths. """ @@ -979,7 +979,7 @@ class _ChatModelStreamBase: response_metadata["model_name"] = self._start_metadata["model"] if self._finish_metadata: response_metadata.update(self._finish_metadata) - # Pin `output_version` last: `stream_v2` always assembles content as v1 + # Pin `output_version` last: `stream_events(version="v3")` always assembles content as v1 # protocol blocks, regardless of the provider's configured output format. # A provider-supplied `output_version` in finish metadata (e.g. # `"responses/v1"` from `ChatOpenAI(use_responses_api=True, ...)`) would @@ -1026,7 +1026,7 @@ class _ChatModelStreamBase: class ChatModelStream(_ChatModelStreamBase): """Synchronous per-message streaming object for a single LLM response. - Returned by `BaseChatModel.stream_v2()`. Content-block protocol + Returned by `BaseChatModel.stream_events(version="v3")`. Content-block protocol events are fed into this object and accumulated into typed projections. Projections (always return the same cached object): @@ -1081,7 +1081,7 @@ class ChatModelStream(_ChatModelStreamBase): """Bind a pump for standalone streaming. Delegates to `set_request_more`. Used by - `BaseChatModel.stream_v2()`. + `BaseChatModel.stream_events(version="v3")`. """ self.set_request_more(pump_one) @@ -1182,7 +1182,7 @@ class ChatModelStream(_ChatModelStreamBase): class AsyncChatModelStream(_ChatModelStreamBase): """Asynchronous per-message streaming object for a single LLM response. - Returned by `BaseChatModel.astream_v2()`. Content-block events + Returned by `BaseChatModel.astream_events(version="v3")`. Content-block events are fed into this object by a background producer task. Projections: @@ -1228,7 +1228,7 @@ class AsyncChatModelStream(_ChatModelStreamBase): # Teardown callback invoked by `aclose()` only when the producer # task was cancelled before its body ran (so the normal # `_produce` CancelledError handler — which fires - # `on_llm_error` — never executed). Set by `astream_v2`. + # `on_llm_error` — never executed). Set by `astream_events(version="v3")`. self._on_aclose_fail: Callable[[BaseException], Awaitable[None]] | None = None # -- Pump/pull wiring (async) ------------------------------------------ @@ -1369,7 +1369,7 @@ class AsyncChatModelStream(_ChatModelStreamBase): task.remove_done_callback(_link) # If the task was cancelled before `_produce` ran (e.g. - # `astream_v2()` immediately followed by `aclose()`), the stream + # `astream_events(version="v3")` immediately followed by `aclose()`), the stream # never reached `_produce`'s CancelledError handler — its # projections are still pending and no end-of-lifecycle callback # has fired. Resolve both here so callers of `await stream.output` diff --git a/libs/core/langchain_core/language_models/chat_models.py b/libs/core/langchain_core/language_models/chat_models.py index 5490580ef1e..8a6ef517de9 100644 --- a/libs/core/langchain_core/language_models/chat_models.py +++ b/libs/core/langchain_core/language_models/chat_models.py @@ -638,7 +638,7 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC): ) -> Iterator[MessagesData]: """Drive the v2 event generator with per-event dispatch. - Shared between `stream_v2`'s pump and the invoke-time v2 branch + Shared between `stream_events(version="v3")`'s pump and the invoke-time v2 branch in `_generate_with_cache`. Picks the native `_stream_chat_model_events` hook when the subclass provides one, else bridges `_stream` chunks via `chunks_to_events`. Each event @@ -988,7 +988,7 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC): # Strip tracing-only kwargs before forwarding to `_stream` — matches # `stream()` / `astream()`. Provider clients reject unknown kwargs, so - # `.with_structured_output().stream_v2(...)` and any other binding that + # `.with_structured_output().stream_events(version="v3", ...)` and any other binding that # carries `ls_structured_output_format` / `structured_output_format` # would raise without this pop. ls_structured_output_format = kwargs.pop( @@ -1120,7 +1120,7 @@ class BaseChatModel(BaseLanguageModel[AIMessage], ABC): messages = self._convert_input(input).to_messages() input_messages = _normalize_messages(messages) - # Strip tracing-only kwargs before forwarding — see `stream_v2` for the + # Strip tracing-only kwargs before forwarding — see `stream_events(version="v3")` for the # full rationale. ls_structured_output_format = kwargs.pop( "ls_structured_output_format", None diff --git a/libs/core/langchain_core/tracers/_streaming.py b/libs/core/langchain_core/tracers/_streaming.py index 2c2b54c0e49..ba1ec0281f0 100644 --- a/libs/core/langchain_core/tracers/_streaming.py +++ b/libs/core/langchain_core/tracers/_streaming.py @@ -33,7 +33,7 @@ class _V2StreamingCallbackHandler: """Marker base class for handlers that consume `on_stream_event` (v2). A handler inheriting from this class signals that it wants content- - block lifecycle events from `stream_v2` / `astream_v2` rather than + block lifecycle events from `stream_events(version="v3")` / `astream_events(version="v3")` rather than the v1 `on_llm_new_token` chunks. `BaseChatModel.invoke` uses `isinstance(handler, _V2StreamingCallbackHandler)` to decide whether to route an invoke through the v2 event generator.