generated from kgod/ai-review-template
提交
This commit is contained in:
kgod
@@ -0,0 +1,45 @@
|
||||
"""Streaming infrastructure for LangGraph.
|
||||
|
||||
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.
|
||||
"""
|
||||
|
||||
from langgraph.stream._types import ProtocolEvent, StreamTransformer
|
||||
from langgraph.stream.run_stream import (
|
||||
AsyncGraphRunStream,
|
||||
AsyncSubgraphRunStream,
|
||||
GraphRunStream,
|
||||
SubgraphRunStream,
|
||||
)
|
||||
from langgraph.stream.stream_channel import StreamChannel
|
||||
from langgraph.stream.transformers import (
|
||||
CheckpointsTransformer,
|
||||
CustomTransformer,
|
||||
DebugTransformer,
|
||||
LifecyclePayload,
|
||||
LifecycleTransformer,
|
||||
SubgraphStatus,
|
||||
SubgraphTransformer,
|
||||
TasksTransformer,
|
||||
UpdatesTransformer,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
"AsyncGraphRunStream",
|
||||
"AsyncSubgraphRunStream",
|
||||
"CheckpointsTransformer",
|
||||
"CustomTransformer",
|
||||
"DebugTransformer",
|
||||
"GraphRunStream",
|
||||
"LifecyclePayload",
|
||||
"LifecycleTransformer",
|
||||
"ProtocolEvent",
|
||||
"StreamChannel",
|
||||
"StreamTransformer",
|
||||
"SubgraphRunStream",
|
||||
"SubgraphStatus",
|
||||
"SubgraphTransformer",
|
||||
"TasksTransformer",
|
||||
"UpdatesTransformer",
|
||||
]
|
||||
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
@@ -0,0 +1,32 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import time
|
||||
from typing import Any, cast
|
||||
|
||||
from langgraph.stream._types import ProtocolEvent, _ProtocolEventParams
|
||||
from langgraph.types import StreamPart
|
||||
|
||||
|
||||
def convert_to_protocol_event(part: StreamPart) -> ProtocolEvent:
|
||||
"""Convert a v2 StreamPart to a ProtocolEvent.
|
||||
|
||||
Args:
|
||||
part: A stream part with keys `type`, `ns`, `data`, and
|
||||
optionally `interrupts` (present on values events).
|
||||
|
||||
Returns:
|
||||
The equivalent ProtocolEvent.
|
||||
"""
|
||||
part_dict = cast(dict[str, Any], part)
|
||||
params: _ProtocolEventParams = {
|
||||
"namespace": list(part_dict["ns"]),
|
||||
"timestamp": int(time.time() * 1000),
|
||||
"data": part_dict["data"],
|
||||
}
|
||||
if "interrupts" in part_dict:
|
||||
params["interrupts"] = part_dict["interrupts"]
|
||||
return {
|
||||
"type": "event",
|
||||
"method": part_dict["type"],
|
||||
"params": params,
|
||||
}
|
||||
@@ -0,0 +1,498 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import time
|
||||
from collections.abc import Awaitable, Callable
|
||||
from typing import Any
|
||||
|
||||
from langgraph.stream._types import (
|
||||
ProtocolEvent,
|
||||
StreamTransformer,
|
||||
transformer_requires_async,
|
||||
)
|
||||
from langgraph.stream.stream_channel import StreamChannel
|
||||
|
||||
TransformerFactory = Callable[["tuple[str, ...]"], StreamTransformer]
|
||||
"""Factory that builds a scoped transformer for a mux.
|
||||
|
||||
Called once per `StreamMux` with the mux's scope (typically `()` for
|
||||
the root). Standard transformer classes accept a single positional
|
||||
scope argument, so the class itself is a valid factory. User
|
||||
transformers can close over their config:
|
||||
`lambda scope: MyTransformer(scope, foo=...)`.
|
||||
"""
|
||||
|
||||
|
||||
class StreamMux:
|
||||
"""Central event dispatcher for the streaming infrastructure.
|
||||
|
||||
Owns the main event log and routes events through a transformer
|
||||
pipeline. StreamChannels with a name discovered in transformer
|
||||
projections are auto-wired so that every `push()` also injects a
|
||||
`ProtocolEvent` into the main log. StreamChannels without a name
|
||||
are local-only.
|
||||
|
||||
Pass `is_async=True` when the mux will be consumed via async
|
||||
iteration (`handler.astream()`). All StreamChannel instances
|
||||
discovered during registration are automatically bound to the
|
||||
matching mode.
|
||||
|
||||
Attributes:
|
||||
extensions: Merged projection dict across all registered
|
||||
transformers. Treat as read-only — mutations won't be
|
||||
reflected back in individual transformers' state.
|
||||
native_keys: Projection keys contributed by transformers with
|
||||
`_native = True`.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
transformers: list[StreamTransformer] | None = None,
|
||||
*,
|
||||
is_async: bool = False,
|
||||
factories: list[TransformerFactory] | None = None,
|
||||
scope: tuple[str, ...] = (),
|
||||
_assign_seq: bool = True,
|
||||
) -> None:
|
||||
"""Initialize the mux and register transformers in order.
|
||||
|
||||
Callers pass either `transformers` (pre-built instances) or
|
||||
`factories` (callables producing fresh instances per mux). Each
|
||||
transformer's `init()` is called, projections are merged into
|
||||
`extensions`, `_native` keys are recorded in `native_keys`, and
|
||||
any StreamChannel instances are bound and (if named) wired.
|
||||
|
||||
Args:
|
||||
transformers: Already-built transformer instances. Registered
|
||||
only on this mux — they are NOT cloned into child
|
||||
mini-muxes built by `_make_child`. Use `factories` for
|
||||
transformers that should propagate to nested scopes.
|
||||
is_async: True for async dispatch (`apush` / `aclose` /
|
||||
`afail`), False for the sync path.
|
||||
factories: One-argument callables `(scope) -> StreamTransformer`.
|
||||
Called once with this mux's `scope` here, and cloned
|
||||
again per child scope by `_make_child` so each
|
||||
sub-mux gets fresh instances.
|
||||
scope: The namespace the mux operates within. The root mux
|
||||
is `()`.
|
||||
_assign_seq: Internal flag for child muxes. Root muxes assign
|
||||
monotonic `seq` numbers when appending to their main event
|
||||
log; child muxes share forwarded event objects and must not
|
||||
mutate their envelopes.
|
||||
|
||||
Raises:
|
||||
RuntimeError: If any transformer requires an async run but
|
||||
the mux is in sync mode.
|
||||
TypeError: If a transformer's `init()` doesn't return a dict.
|
||||
ValueError: If transformers' projection keys collide.
|
||||
"""
|
||||
self.is_async = is_async
|
||||
self.scope: tuple[str, ...] = scope
|
||||
self._assign_seq = _assign_seq
|
||||
self._events: StreamChannel[ProtocolEvent] = StreamChannel()
|
||||
self._events._bind(is_async=is_async)
|
||||
self._events._bind_mux(self)
|
||||
self._transformers: list[StreamTransformer] = []
|
||||
self._channels: list[StreamChannel[Any]] = []
|
||||
self._seq = 0
|
||||
self._push_seq = 0
|
||||
|
||||
self.extensions: dict[str, Any] = {}
|
||||
self.native_keys: set[str] = set()
|
||||
self._projection_owners: dict[str, str] = {}
|
||||
self._transformer_by_key: dict[str, StreamTransformer] = {}
|
||||
|
||||
# Stored only when constructed from factories — used by
|
||||
# `_make_child` to clone the transformer pipeline at a deeper
|
||||
# scope. Pre-built transformers can't be cloned, so a mux
|
||||
# built with `transformers=` rejects child construction.
|
||||
self._factories: list[TransformerFactory] | None = (
|
||||
list(factories) if factories is not None else None
|
||||
)
|
||||
self._pump_fn: Callable[[], bool] | None = None
|
||||
self._apump_fn: Callable[[], Awaitable[bool]] | None = None
|
||||
|
||||
# Factories run first (they propagate to child mini-muxes
|
||||
# via `_make_child`), then any pre-built `transformers=`
|
||||
# instances are registered as root-only — they aren't cloned
|
||||
# for child scopes.
|
||||
if factories is not None:
|
||||
for factory in factories:
|
||||
self._register(factory(scope))
|
||||
for transformer in transformers or ():
|
||||
self._register(transformer)
|
||||
|
||||
def transformer_by_key(self, key: str) -> StreamTransformer | None:
|
||||
"""Return the transformer that contributed `key` to the projection."""
|
||||
return self._transformer_by_key.get(key)
|
||||
|
||||
def _next_push_seq(self) -> int:
|
||||
self._push_seq += 1
|
||||
return self._push_seq
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Pump wiring + mini-mux nesting
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def bind_pump(self, fn: Callable[[], bool]) -> None:
|
||||
"""Wire the sync pull callback onto every projection in this mux.
|
||||
|
||||
Records the pump on the mux so child mini-muxes built by
|
||||
`_make_child` can inherit it. Propagates to:
|
||||
- the main event log (`self._events`)
|
||||
- every projection StreamChannel in `extensions`
|
||||
- any registered transformer that exposes `_bind_pump` (e.g.
|
||||
`MessagesTransformer` so `ChatModelStream` instances drive the
|
||||
shared pump from their cursors)
|
||||
"""
|
||||
self._pump_fn = fn
|
||||
self._events._request_more = fn
|
||||
for ch in self._channels:
|
||||
ch._request_more = fn
|
||||
for transformer in self._transformers:
|
||||
bind = getattr(transformer, "_bind_pump", None)
|
||||
if bind is not None:
|
||||
bind(fn)
|
||||
|
||||
def bind_apump(self, fn: Callable[[], Awaitable[bool]]) -> None:
|
||||
"""Async counterpart to `bind_pump`."""
|
||||
self._apump_fn = fn
|
||||
self._events._arequest_more = fn
|
||||
for ch in self._channels:
|
||||
ch._arequest_more = fn
|
||||
for transformer in self._transformers:
|
||||
abind = getattr(transformer, "_bind_apump", None)
|
||||
if abind is not None:
|
||||
abind(fn)
|
||||
|
||||
def _make_child(self, scope: tuple[str, ...]) -> StreamMux:
|
||||
"""Build a mini-mux with the same factories scoped to `scope`.
|
||||
|
||||
Used by `SubgraphTransformer` to attach a fresh transformer
|
||||
pipeline to each discovered subgraph handle. The child mux
|
||||
inherits the current pump bindings (so cursors on its
|
||||
projection logs drive the root pump), carries the same factory
|
||||
list forward to any grandchild subgraphs, and does not assign
|
||||
`seq` numbers so forwarded events can be shared without
|
||||
mutating their envelope.
|
||||
|
||||
Raises:
|
||||
RuntimeError: If the mux was not constructed with
|
||||
`factories=`. Mini-muxes require factories so each scope
|
||||
gets its own fresh transformer instances.
|
||||
"""
|
||||
if self._factories is None:
|
||||
raise RuntimeError(
|
||||
"StreamMux._make_child requires the mux to be constructed "
|
||||
"with `factories=`; pre-built transformers can't be "
|
||||
"cloned to a new scope."
|
||||
)
|
||||
child = StreamMux(
|
||||
factories=self._factories,
|
||||
is_async=self.is_async,
|
||||
scope=scope,
|
||||
_assign_seq=False,
|
||||
)
|
||||
if self._pump_fn is not None:
|
||||
child.bind_pump(self._pump_fn)
|
||||
if self._apump_fn is not None:
|
||||
child.bind_apump(self._apump_fn)
|
||||
return child
|
||||
|
||||
def _register(self, transformer: StreamTransformer) -> None:
|
||||
"""Register a single transformer.
|
||||
|
||||
Calls `transformer.init()`, stores the transformer for event
|
||||
processing, binds any StreamChannel instances in the projection,
|
||||
and merges the projection into `extensions`.
|
||||
"""
|
||||
if transformer_requires_async(transformer) and not self.is_async:
|
||||
raise RuntimeError(
|
||||
f"{type(transformer).__name__} requires an async run — "
|
||||
"it overrides aprocess/afinalize/afail or sets "
|
||||
"requires_async=True. Use astream(), not stream()."
|
||||
)
|
||||
projection = transformer.init()
|
||||
if not isinstance(projection, dict):
|
||||
raise TypeError(
|
||||
f"StreamTransformer.init() must return a dict, "
|
||||
f"got {type(projection).__name__}"
|
||||
)
|
||||
conflicts = set(projection) & set(self.extensions)
|
||||
if conflicts:
|
||||
attributions = ", ".join(
|
||||
f"{key!r} (owned by {self._projection_owners[key]})"
|
||||
for key in sorted(conflicts)
|
||||
)
|
||||
raise ValueError(
|
||||
f"Transformer {type(transformer).__name__} returned "
|
||||
f"projection keys that conflict with already-registered "
|
||||
f"keys: {attributions}"
|
||||
)
|
||||
is_native = bool(getattr(transformer, "_native", False))
|
||||
self._transformers.append(transformer)
|
||||
self._bind_and_wire(projection, native=is_native)
|
||||
self.extensions.update(projection)
|
||||
owner_name = type(transformer).__name__
|
||||
for key in projection:
|
||||
self._projection_owners[key] = owner_name
|
||||
self._transformer_by_key[key] = transformer
|
||||
if is_native:
|
||||
self.native_keys.update(projection.keys())
|
||||
transformer._on_register(self)
|
||||
|
||||
def push(self, event: ProtocolEvent) -> None:
|
||||
"""Route an event through all transformers, then append to the main log.
|
||||
|
||||
Each transformer's `process()` is called in registration order.
|
||||
If any transformer returns False, the event is suppressed from
|
||||
the main log, but transformers that already saw it keep their
|
||||
side effects.
|
||||
|
||||
On the root mux, `seq` is assigned right before an event enters
|
||||
the main log, not before the transformer pipeline runs. This
|
||||
ensures that events auto-forwarded from StreamChannels during
|
||||
`process()` get earlier seq numbers than the original event,
|
||||
preserving monotonic ordering in the root log. Child muxes do
|
||||
not assign `seq`, so subgraph forwarding can share event objects
|
||||
without mutating their envelopes.
|
||||
|
||||
Args:
|
||||
event: The protocol event to dispatch.
|
||||
"""
|
||||
keep = True
|
||||
for transformer in self._transformers:
|
||||
if not transformer.process(event):
|
||||
keep = False
|
||||
if keep:
|
||||
if self._assign_seq:
|
||||
self._seq += 1
|
||||
event["seq"] = self._seq
|
||||
self._events.push(event)
|
||||
|
||||
def close(self) -> None:
|
||||
"""Finalize all transformers, close all projections and the main log.
|
||||
|
||||
StreamChannels discovered in transformer projections are
|
||||
auto-closed after `finalize()` runs — transformers don't need
|
||||
to close them manually. If any transformer's `finalize()` raises,
|
||||
the remaining transformers, projections, and the main log are
|
||||
still closed; the first error is re-raised after cleanup
|
||||
completes.
|
||||
|
||||
Raises:
|
||||
BaseException: The first error raised by a transformer's
|
||||
`finalize()`, re-raised after cleanup finishes.
|
||||
"""
|
||||
first_error: BaseException | None = None
|
||||
for transformer in self._transformers:
|
||||
try:
|
||||
transformer.finalize()
|
||||
except BaseException as e:
|
||||
if first_error is None:
|
||||
first_error = e
|
||||
for ch in self._channels:
|
||||
if not ch._closed:
|
||||
ch.close()
|
||||
self._events.close()
|
||||
if first_error is not None:
|
||||
raise first_error
|
||||
|
||||
def fail(self, err: BaseException) -> None:
|
||||
"""Fail all transformers, projections, and the main log.
|
||||
|
||||
StreamChannels discovered in transformer projections are
|
||||
auto-failed — transformers don't need to fail them manually.
|
||||
If any transformer's `fail()` raises, the remaining
|
||||
transformers, projections, and the main log are still failed.
|
||||
|
||||
Args:
|
||||
err: The exception that ended the run.
|
||||
"""
|
||||
for transformer in self._transformers:
|
||||
try:
|
||||
transformer.fail(err)
|
||||
except BaseException:
|
||||
pass
|
||||
for ch in self._channels:
|
||||
if not ch._closed:
|
||||
ch.fail(err)
|
||||
self._events.fail(err)
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Async dispatch
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
async def apush(self, event: ProtocolEvent) -> None:
|
||||
"""Dispatch an event on the async lane.
|
||||
|
||||
Awaits each transformer's `aprocess` in registration order
|
||||
before appending to the main log. A slow `aprocess` serializes
|
||||
the pipeline by design — that's the guarantee that lets a later
|
||||
transformer (or a synchronous consumer) see the result of the
|
||||
async work. For decoupled work, use `schedule()` from inside
|
||||
`process` / `aprocess` instead.
|
||||
|
||||
The main log append is a non-blocking `push` — matching v1's
|
||||
`put_nowait` shape. The root mux assigns `seq`; child muxes do
|
||||
not, so forwarded subgraph events can be shared without copying.
|
||||
Memory is bounded by caller pace via the caller-driven pump; see
|
||||
`StreamChannel` for the full tradeoff story.
|
||||
|
||||
Args:
|
||||
event: The protocol event to dispatch.
|
||||
"""
|
||||
keep = True
|
||||
for transformer in self._transformers:
|
||||
if not await transformer.aprocess(event):
|
||||
keep = False
|
||||
if keep:
|
||||
if self._assign_seq:
|
||||
self._seq += 1
|
||||
event["seq"] = self._seq
|
||||
self._events.push(event)
|
||||
|
||||
async def aclose(self) -> None:
|
||||
"""Finalize on the async lane.
|
||||
|
||||
Awaits every task started via `StreamTransformer.schedule()`
|
||||
across all transformers, then calls `afinalize()` on each,
|
||||
then auto-closes channels and the main event log.
|
||||
|
||||
If any scheduled task raised under `on_error="raise"`, or any
|
||||
transformer's `afinalize` raises, the exception propagates.
|
||||
The caller (the pump) handles it by routing into `afail`.
|
||||
|
||||
Raises:
|
||||
BaseException: The first scheduled-task or `afinalize`
|
||||
error, re-raised after cleanup.
|
||||
"""
|
||||
pending = self._collect_scheduled_tasks()
|
||||
if pending:
|
||||
results = await asyncio.gather(*pending, return_exceptions=True)
|
||||
first_err = next(
|
||||
(
|
||||
r
|
||||
for r in results
|
||||
if isinstance(r, BaseException)
|
||||
and not isinstance(r, asyncio.CancelledError)
|
||||
),
|
||||
None,
|
||||
)
|
||||
if first_err is not None:
|
||||
raise first_err
|
||||
|
||||
first_error: BaseException | None = None
|
||||
for transformer in self._transformers:
|
||||
try:
|
||||
await transformer.afinalize()
|
||||
except BaseException as e:
|
||||
if first_error is None:
|
||||
first_error = e
|
||||
for ch in self._channels:
|
||||
if not ch._closed:
|
||||
ch.close()
|
||||
self._events.close()
|
||||
if first_error is not None:
|
||||
raise first_error
|
||||
|
||||
async def afail(self, err: BaseException) -> None:
|
||||
"""Fail on the async lane.
|
||||
|
||||
Cancels every scheduled task across all transformers, awaits
|
||||
them to completion, then runs each transformer's `afail` hook
|
||||
and auto-fails channels and the main event log.
|
||||
|
||||
Args:
|
||||
err: The exception that ended the run.
|
||||
"""
|
||||
pending = self._collect_scheduled_tasks()
|
||||
for task in pending:
|
||||
task.cancel()
|
||||
if pending:
|
||||
await asyncio.gather(*pending, return_exceptions=True)
|
||||
|
||||
for transformer in self._transformers:
|
||||
try:
|
||||
await transformer.afail(err)
|
||||
except BaseException:
|
||||
pass
|
||||
for ch in self._channels:
|
||||
if not ch._closed:
|
||||
ch.fail(err)
|
||||
if not self._events._closed:
|
||||
self._events.fail(err)
|
||||
|
||||
def _collect_scheduled_tasks(self) -> list[asyncio.Task[Any]]:
|
||||
"""Return a snapshot of in-flight tasks scheduled via transformers."""
|
||||
return [
|
||||
task
|
||||
for transformer in self._transformers
|
||||
for task in getattr(transformer, "_stream_scheduled_tasks", ())
|
||||
if not task.done()
|
||||
]
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Binding and StreamChannel auto-wiring
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _bind_and_wire(
|
||||
self, projection: dict[str, Any], *, native: bool = False
|
||||
) -> None:
|
||||
"""Bind and optionally wire StreamChannel instances in a projection.
|
||||
|
||||
All StreamChannels are bound and tracked. Channels with a name
|
||||
are additionally wired for protocol auto-forwarding.
|
||||
|
||||
Args:
|
||||
projection: The projection dict returned by a transformer's
|
||||
`init()`.
|
||||
native: True when the owning transformer is `_native`.
|
||||
Named channels owned by a native transformer use the
|
||||
channel name directly as the protocol method;
|
||||
user-defined channels are prefixed with `custom:`.
|
||||
"""
|
||||
for value in projection.values():
|
||||
if isinstance(value, StreamChannel):
|
||||
value._bind(is_async=self.is_async)
|
||||
value._bind_mux(self)
|
||||
self._channels.append(value)
|
||||
if value.name is not None:
|
||||
method = value.name if native else f"custom:{value.name}"
|
||||
|
||||
def _make_forward(method_name: str) -> Callable[[Any], None]:
|
||||
def _forward(item: Any) -> None:
|
||||
self._forward(method_name, item)
|
||||
|
||||
return _forward
|
||||
|
||||
value._wire(_make_forward(method))
|
||||
|
||||
def _forward(self, method: str, item: Any) -> None:
|
||||
"""Inject a ProtocolEvent for a StreamChannel push.
|
||||
|
||||
Forwarded events bypass the transformer pipeline to avoid
|
||||
infinite recursion (a transformer that pushes to a channel
|
||||
during `process()` would re-trigger itself). These events are
|
||||
visible in this mux's main event log but are not passed through
|
||||
transformers' `process()` methods. Only the root mux assigns
|
||||
`seq` to forwarded channel events.
|
||||
|
||||
Args:
|
||||
method: The full protocol method (already with or without
|
||||
the `custom:` prefix; resolved by `_bind_and_wire`).
|
||||
item: The payload pushed onto the channel.
|
||||
"""
|
||||
event: ProtocolEvent = {
|
||||
"type": "event",
|
||||
"method": method,
|
||||
"params": {
|
||||
"namespace": [],
|
||||
"timestamp": int(time.time() * 1000),
|
||||
"data": item,
|
||||
},
|
||||
}
|
||||
if self._assign_seq:
|
||||
self._seq += 1
|
||||
event["seq"] = self._seq
|
||||
self._events.push(event)
|
||||
@@ -0,0 +1,313 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import logging
|
||||
from abc import ABC, abstractmethod
|
||||
from collections.abc import Coroutine
|
||||
from typing import Any, ClassVar, Literal
|
||||
|
||||
from typing_extensions import NotRequired, TypedDict
|
||||
|
||||
_logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class _ProtocolEventParams(TypedDict):
|
||||
"""Parameters for a protocol event.
|
||||
|
||||
`timestamp` is wall-clock milliseconds since the epoch and can go
|
||||
backwards across NTP adjustments — use `ProtocolEvent.seq` for
|
||||
ordering.
|
||||
"""
|
||||
|
||||
namespace: list[str]
|
||||
timestamp: int
|
||||
data: Any
|
||||
interrupts: NotRequired[tuple[Any, ...]]
|
||||
|
||||
|
||||
class ProtocolEvent(TypedDict):
|
||||
"""A protocol event emitted by the streaming infrastructure.
|
||||
|
||||
Wraps a raw stream part (values, messages, custom, etc.) in a uniform
|
||||
envelope with a monotonic sequence number assigned by the root StreamMux.
|
||||
Consumers that need a total order across root events should use `seq`, not
|
||||
`params.timestamp` (which is wall-clock and not monotonic).
|
||||
"""
|
||||
|
||||
type: Literal["event"]
|
||||
eventId: NotRequired[str]
|
||||
seq: NotRequired[int]
|
||||
method: str # StreamMode value: "values", "messages", "custom", etc.
|
||||
params: _ProtocolEventParams
|
||||
|
||||
|
||||
class StreamTransformer(ABC):
|
||||
"""Extension point for custom stream projections.
|
||||
|
||||
Transformers observe protocol events flowing through the StreamMux and
|
||||
build typed derived projections (StreamChannels, promises, etc.).
|
||||
|
||||
Set `_native = True` on a transformer to have its projection keys
|
||||
exposed as direct attributes on the run stream (in addition to
|
||||
appearing in `run.extensions`).
|
||||
|
||||
Subclasses must implement `init` and override at least one of
|
||||
`process` / `aprocess`. The `finalize` / `afinalize` and `fail` /
|
||||
`afail` hooks are optional — the default implementations are no-ops.
|
||||
StreamChannel instances in the projection dict are auto-closed /
|
||||
auto-failed by the mux, so most transformers don't need `finalize`
|
||||
or `fail` at all.
|
||||
|
||||
Transformers that need async work pick the async lane by:
|
||||
|
||||
1. Overriding `aprocess` (and optionally `afinalize` / `afail`), or
|
||||
2. Calling `self.schedule(coro)` from inside a sync `process`, or
|
||||
3. Setting `requires_async = True` explicitly.
|
||||
|
||||
The mux detects these cases at registration and raises if they're
|
||||
used under sync `stream()` — they only work under `astream()`.
|
||||
|
||||
Use `aprocess` when the pump must wait for async work before the
|
||||
next transformer sees the event (e.g. PII redaction that mutates
|
||||
`event` in place). Use `schedule()` for decoupled async work whose
|
||||
result lands on an independent projection (e.g. async moderation
|
||||
scoring, cost lookup, external tracing).
|
||||
|
||||
Attributes:
|
||||
scope: Namespace the transformer operates within — `()` for the
|
||||
root mux. Set at construction from the mux's scope (each
|
||||
factory is called as `factory(scope)`).
|
||||
requires_async: Explicit opt-in for transformers that need a
|
||||
running event loop but don't override any async method (for
|
||||
example, transformers that call `schedule()` from a sync
|
||||
`process`). The mux also auto-detects the async lane when
|
||||
`aprocess`, `afinalize`, or `afail` is overridden.
|
||||
supports_sync: Set True only for transformers that override
|
||||
async-lane hooks while still fully supporting the sync lane.
|
||||
Such transformers may be registered under `stream()`.
|
||||
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_events(version="v3")` run requests from the graph.
|
||||
Empty tuple means the transformer consumes only synthetic
|
||||
events (or is purely passive).
|
||||
"""
|
||||
|
||||
requires_async: ClassVar[bool] = False
|
||||
supports_sync: ClassVar[bool] = False
|
||||
required_stream_modes: ClassVar[tuple[str, ...]] = ()
|
||||
|
||||
def __init__(self, scope: tuple[str, ...] = ()) -> None:
|
||||
"""Initialize the transformer with its mux's scope.
|
||||
|
||||
Args:
|
||||
scope: The namespace tuple the owning mux is scoped to.
|
||||
`()` for the root. Factories receive this at
|
||||
construction time (`factory(scope)` in `StreamMux`).
|
||||
"""
|
||||
self.scope: tuple[str, ...] = scope
|
||||
|
||||
@abstractmethod
|
||||
def init(self) -> dict[str, Any]:
|
||||
"""Return the projection dict.
|
||||
|
||||
Keys become entries in `run.extensions`. If the transformer has
|
||||
`_native = True`, keys are also set as direct attributes on the
|
||||
run stream.
|
||||
|
||||
StreamChannel instances in the return value are automatically
|
||||
wired by the StreamMux for protocol event auto-forwarding.
|
||||
"""
|
||||
...
|
||||
|
||||
def _on_register(self, mux: Any) -> None:
|
||||
"""Called by `StreamMux._register` after this transformer is wired in.
|
||||
|
||||
Default is a no-op. Override to capture a reference to the
|
||||
owning mux — needed for transformers that build mini-muxes
|
||||
via `mux._make_child(...)` (e.g. `SubgraphTransformer`).
|
||||
"""
|
||||
|
||||
def process(self, event: ProtocolEvent) -> bool:
|
||||
"""Handle an event on the sync lane.
|
||||
|
||||
Called for every event before it is appended to the main event
|
||||
log. Subclasses must override either `process` or `aprocess`.
|
||||
The default raises so a missing override fails loudly rather
|
||||
than silently passing every event through.
|
||||
|
||||
Args:
|
||||
event: The protocol event to observe.
|
||||
|
||||
Returns:
|
||||
True to keep the event in the main log, False to suppress it.
|
||||
"""
|
||||
raise NotImplementedError(
|
||||
f"{type(self).__name__} must override process() or aprocess()"
|
||||
)
|
||||
|
||||
async def aprocess(self, event: ProtocolEvent) -> bool:
|
||||
"""Handle an event on the async lane.
|
||||
|
||||
The mux awaits this before dispatching to the next transformer,
|
||||
so a slow `aprocess` serializes the pipeline. Use it only when
|
||||
a later transformer — or a consumer reading the event
|
||||
synchronously — must see the result of the async work (e.g.
|
||||
PII redaction that mutates `event` in place).
|
||||
|
||||
The default delegates to `process`, so purely-sync transformers
|
||||
run unchanged under `astream()`.
|
||||
|
||||
Args:
|
||||
event: The protocol event to observe.
|
||||
|
||||
Returns:
|
||||
True to keep the event in the main log, False to suppress it.
|
||||
"""
|
||||
return self.process(event)
|
||||
|
||||
def finalize(self) -> None:
|
||||
"""Called when the run ends normally (sync lane).
|
||||
|
||||
Override to close StreamChannels, resolve promises, or perform
|
||||
other teardown. StreamChannel instances in the projection dict
|
||||
are auto-closed by the mux.
|
||||
"""
|
||||
|
||||
async def afinalize(self) -> None:
|
||||
"""Called when the run ends normally (async lane).
|
||||
|
||||
By the time this runs, the mux has already awaited every task
|
||||
started via `schedule()`, so StreamChannels can be closed here
|
||||
without a last-task-wins race.
|
||||
|
||||
The default delegates to `finalize`.
|
||||
"""
|
||||
self.finalize()
|
||||
|
||||
def fail(self, err: BaseException) -> None:
|
||||
"""Called when the run ends with an error (sync lane).
|
||||
|
||||
Override to fail StreamChannels, reject promises, or perform
|
||||
other teardown. StreamChannel instances in the projection dict
|
||||
are auto-failed by the mux.
|
||||
|
||||
Args:
|
||||
err: The exception that ended the run.
|
||||
"""
|
||||
|
||||
async def afail(self, err: BaseException) -> None:
|
||||
"""Called when the run ends with an error (async lane).
|
||||
|
||||
The mux cancels and awaits every task started via `schedule()`
|
||||
before calling this, so cleanup doesn't race with in-flight work.
|
||||
|
||||
The default delegates to `fail`.
|
||||
|
||||
Args:
|
||||
err: The exception that ended the run.
|
||||
"""
|
||||
self.fail(err)
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Scheduled async work
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def schedule(
|
||||
self,
|
||||
coro: Coroutine[Any, Any, Any],
|
||||
*,
|
||||
on_error: Literal["log", "raise"] = "log",
|
||||
) -> asyncio.Task[Any]:
|
||||
"""Schedule a coroutine tied to this transformer's lifecycle.
|
||||
|
||||
The mux holds the task reference, awaits all scheduled tasks
|
||||
during `aclose()` before calling `afinalize()`, and cancels
|
||||
them on `afail()`. Authors don't need to track tasks or
|
||||
implement the last-task-closes-the-log dance.
|
||||
|
||||
Requires a running event loop — call only under `astream()`.
|
||||
Set `requires_async = True` on the class so registration under
|
||||
sync `stream()` fails fast with a clear message.
|
||||
|
||||
Args:
|
||||
coro: The coroutine to run. Its lifecycle is owned by the
|
||||
mux from this point on.
|
||||
on_error: `"log"` (default) catches and logs any exception
|
||||
the coroutine raises, so a single failure doesn't tear
|
||||
down the run. `"raise"` lets the exception propagate
|
||||
when the mux joins pendings, converting the close path
|
||||
into the fail path.
|
||||
|
||||
Returns:
|
||||
The asyncio Task. Authors rarely need to await it directly
|
||||
— consumers read results from whatever projection the
|
||||
coroutine pushes into.
|
||||
|
||||
Raises:
|
||||
RuntimeError: If called without a running event loop (i.e.
|
||||
under sync `stream()` rather than `astream()`).
|
||||
"""
|
||||
try:
|
||||
asyncio.get_running_loop()
|
||||
except RuntimeError:
|
||||
raise RuntimeError(
|
||||
f"{type(self).__name__}.schedule() requires a running "
|
||||
"event loop; this transformer must run under astream(), "
|
||||
"not stream(). Set requires_async=True on the class so "
|
||||
"this fails at registration rather than at first event."
|
||||
) from None
|
||||
|
||||
wrapped = self._wrap_scheduled(coro) if on_error == "log" else coro
|
||||
task = asyncio.create_task(wrapped)
|
||||
tasks = self._scheduled_task_set()
|
||||
tasks.add(task)
|
||||
task.add_done_callback(tasks.discard)
|
||||
return task
|
||||
|
||||
@staticmethod
|
||||
async def _wrap_scheduled(coro: Coroutine[Any, Any, Any]) -> Any:
|
||||
try:
|
||||
return await coro
|
||||
except asyncio.CancelledError:
|
||||
raise
|
||||
except BaseException:
|
||||
_logger.exception("Scheduled StreamTransformer task failed")
|
||||
|
||||
def _scheduled_task_set(self) -> set[asyncio.Task[Any]]:
|
||||
"""Return the lazily-allocated task set.
|
||||
|
||||
Avoids requiring subclasses to call `super().__init__()`.
|
||||
"""
|
||||
tasks: set[asyncio.Task[Any]] | None = getattr(
|
||||
self, "_stream_scheduled_tasks", None
|
||||
)
|
||||
if tasks is None:
|
||||
tasks = set()
|
||||
self._stream_scheduled_tasks = tasks
|
||||
return tasks
|
||||
|
||||
|
||||
def transformer_requires_async(transformer: StreamTransformer) -> bool:
|
||||
"""Return True if the transformer needs a running event loop.
|
||||
|
||||
A transformer requires async if it explicitly opts in
|
||||
(`requires_async = True`) or overrides any of the async-lane methods
|
||||
(`aprocess`, `afinalize`, `afail`) without also declaring that it
|
||||
supports the sync lane.
|
||||
|
||||
Args:
|
||||
transformer: The transformer to inspect.
|
||||
|
||||
Returns:
|
||||
True if the transformer cannot run under sync `stream()`.
|
||||
"""
|
||||
if transformer.requires_async:
|
||||
return True
|
||||
if transformer.supports_sync:
|
||||
return False
|
||||
cls = type(transformer)
|
||||
for name in ("aprocess", "afinalize", "afail"):
|
||||
if getattr(cls, name) is not getattr(StreamTransformer, name):
|
||||
return True
|
||||
return False
|
||||
@@ -0,0 +1,608 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
from collections.abc import AsyncIterator, Awaitable, Callable, Iterator, Mapping
|
||||
from types import MappingProxyType, TracebackType
|
||||
from typing import TYPE_CHECKING, Any
|
||||
|
||||
from langchain_core._api import beta
|
||||
|
||||
from langgraph.stream._convert import convert_to_protocol_event
|
||||
from langgraph.stream._mux import StreamMux
|
||||
from langgraph.stream._types import ProtocolEvent
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from langgraph.stream.transformers import SubgraphStatus
|
||||
|
||||
|
||||
def _drive_until_done(pump: Callable[[], bool]) -> None:
|
||||
"""Call the sync pump until it returns False."""
|
||||
while pump():
|
||||
pass
|
||||
|
||||
|
||||
async def _adrive_until_done(pump: Callable[[], Awaitable[bool]]) -> None:
|
||||
"""Call the async pump until it returns False."""
|
||||
while await pump():
|
||||
pass
|
||||
|
||||
|
||||
@beta(message="The v3 streaming protocol on Pregel is experimental.")
|
||||
class GraphRunStream:
|
||||
"""Sync run stream with caller-driven pumping.
|
||||
|
||||
The caller's iteration on any projection (`values`, `messages`,
|
||||
raw events, or `output`) drives the graph forward. No background
|
||||
thread is used — the caller's `for` loop is the pump.
|
||||
|
||||
Projections are single-consumer — iterating `run.values` twice
|
||||
raises. Use `projection.tee(n)` if you genuinely need fan-out.
|
||||
|
||||
All transformer projections live in `extensions`. Native transformer
|
||||
projections (those with `_native = True`) are also set as direct
|
||||
attributes on this instance (e.g. `run.values`, `run.messages`).
|
||||
|
||||
!!! warning
|
||||
|
||||
Returned by `Pregel.stream_events(version="v3")`, which is
|
||||
experimental and may change.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
graph_iter: Iterator[Any] | None,
|
||||
mux: StreamMux,
|
||||
*,
|
||||
wire_pump: bool = True,
|
||||
) -> None:
|
||||
"""Initialize the run stream.
|
||||
|
||||
Args:
|
||||
graph_iter: Pull-based iterator over the graph's stream,
|
||||
or `None` for nested run streams whose pump is driven
|
||||
by an outer run (e.g. `SubgraphRunStream`).
|
||||
mux: The StreamMux owning projections and the main log.
|
||||
wire_pump: When True (default), bind `_pump_next` as the
|
||||
mux's pump callable. Subclasses that inherit a parent
|
||||
pump via `StreamMux._make_child` should pass False to
|
||||
preserve the parent binding.
|
||||
"""
|
||||
self._graph_iter = graph_iter
|
||||
self._mux = mux
|
||||
self.extensions: Mapping[str, Any] = MappingProxyType(mux.extensions)
|
||||
self._exhausted = False
|
||||
self._latest: dict[str, Any] | None = None
|
||||
self._interrupted = False
|
||||
self._interrupts: list[Any] = []
|
||||
self._scope_list: list[str] = list(mux.scope)
|
||||
for key in mux.native_keys:
|
||||
setattr(self, key, mux.extensions[key])
|
||||
if wire_pump:
|
||||
self._wire_request_more(mux)
|
||||
|
||||
def _wire_request_more(self, mux: StreamMux) -> None:
|
||||
"""Wire the sync pull callback through the mux.
|
||||
|
||||
Routing through `mux.bind_pump` (rather than walking
|
||||
projections directly here) lets child mini-muxes built by
|
||||
`mux._make_child(...)` inherit the same pump callable, so
|
||||
cursors on a subgraph handle's projections drive the root
|
||||
pump just like cursors on `run.values` do.
|
||||
"""
|
||||
mux.bind_pump(self._pump_next)
|
||||
|
||||
def _observe_event(self, event: ProtocolEvent) -> None:
|
||||
"""Track values-event state for output/interrupted/interrupts."""
|
||||
if event["method"] != "values":
|
||||
return
|
||||
params = event["params"]
|
||||
if params["namespace"] != self._scope_list:
|
||||
return
|
||||
self._latest = params["data"]
|
||||
interrupts = params.get("interrupts", ())
|
||||
if interrupts:
|
||||
self._interrupted = True
|
||||
self._interrupts.extend(interrupts)
|
||||
|
||||
def _pump_next(self) -> bool:
|
||||
"""Pull one event from the graph and push it through the mux.
|
||||
|
||||
Returns:
|
||||
True if an event was pulled, False if the graph is exhausted
|
||||
or has raised. Always False when constructed with
|
||||
`graph_iter=None` (the run is driven by an outer pump).
|
||||
"""
|
||||
if self._exhausted or self._graph_iter is None:
|
||||
return False
|
||||
try:
|
||||
part = next(self._graph_iter)
|
||||
event = convert_to_protocol_event(part)
|
||||
self._observe_event(event)
|
||||
self._mux.push(event)
|
||||
return True
|
||||
except StopIteration:
|
||||
self._mux.close()
|
||||
self._exhausted = True
|
||||
return False
|
||||
except Exception as e:
|
||||
self._mux.fail(e)
|
||||
self._exhausted = True
|
||||
return False
|
||||
|
||||
def abort(self) -> None:
|
||||
"""Stop the run early.
|
||||
|
||||
Closes the mux and marks the stream exhausted. The graph
|
||||
iterator is dropped; any in-flight nodes see the closure on
|
||||
their next yield point. Idempotent.
|
||||
"""
|
||||
if self._exhausted:
|
||||
return
|
||||
self._exhausted = True
|
||||
try:
|
||||
self._mux.close()
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
def __enter__(self) -> GraphRunStream:
|
||||
return self
|
||||
|
||||
def __exit__(
|
||||
self,
|
||||
exc_type: type[BaseException] | None,
|
||||
exc: BaseException | None,
|
||||
tb: TracebackType | None,
|
||||
) -> None:
|
||||
self.abort()
|
||||
|
||||
@property
|
||||
def output(self) -> dict[str, Any] | None:
|
||||
"""Drive the run to completion and return the final state."""
|
||||
_drive_until_done(self._pump_next)
|
||||
if (err := self._mux._events._error) is not None:
|
||||
raise err
|
||||
return self._latest
|
||||
|
||||
@property
|
||||
def interrupted(self) -> bool:
|
||||
"""Drive the run to completion, then return whether it was
|
||||
interrupted.
|
||||
|
||||
Raises:
|
||||
BaseException: If the run ended with an error.
|
||||
"""
|
||||
_drive_until_done(self._pump_next)
|
||||
if (err := self._mux._events._error) is not None:
|
||||
raise err
|
||||
return self._interrupted
|
||||
|
||||
@property
|
||||
def interrupts(self) -> list[Any]:
|
||||
"""Drive the run to completion, then return interrupt payloads.
|
||||
|
||||
Raises:
|
||||
BaseException: If the run ended with an error.
|
||||
"""
|
||||
_drive_until_done(self._pump_next)
|
||||
if (err := self._mux._events._error) is not None:
|
||||
raise err
|
||||
return self._interrupts
|
||||
|
||||
def __iter__(self) -> Iterator[ProtocolEvent]:
|
||||
"""Subscribe to the main event log and iterate protocol events."""
|
||||
return iter(self._mux._events)
|
||||
|
||||
def interleave(self, *names: str) -> Iterator[tuple[str, Any]]:
|
||||
"""Iterate multiple projections in arrival order, yielding ``(name, item)``.
|
||||
|
||||
Items are ordered by a monotonic push stamp assigned when each
|
||||
transformer pushes into its `StreamChannel`. This gives strict
|
||||
arrival ordering across projections, unlike round-robin.
|
||||
|
||||
Args:
|
||||
*names: Projection keys to interleave. Must match keys in
|
||||
``extensions``.
|
||||
|
||||
Yields:
|
||||
``(name, item)`` tuples in arrival order across the named
|
||||
projections.
|
||||
|
||||
Each named channel is locked for the duration of iteration and
|
||||
released when the generator completes, is closed, or raises.
|
||||
Channels cannot be subscribed concurrently — use `.tee(n)` if
|
||||
you need fan-out.
|
||||
|
||||
Raises:
|
||||
KeyError: If a name doesn't match a registered projection.
|
||||
|
||||
Example:
|
||||
```python
|
||||
for name, item in run.interleave("messages", "values"):
|
||||
if name == "messages":
|
||||
print("msg:", item)
|
||||
else:
|
||||
print("val:", item)
|
||||
```
|
||||
"""
|
||||
from langgraph.stream.stream_channel import StreamChannel
|
||||
|
||||
channels: dict[str, StreamChannel[Any]] = {}
|
||||
try:
|
||||
for name in names:
|
||||
ch = self.extensions[name]
|
||||
if not isinstance(ch, StreamChannel):
|
||||
raise TypeError(
|
||||
f"interleave() requires StreamChannel projections, "
|
||||
f"got {type(ch).__name__} for {name!r}"
|
||||
)
|
||||
if ch._is_async is None:
|
||||
raise TypeError(
|
||||
f"StreamChannel {name!r} has not been bound yet. "
|
||||
"Register the transformer with a StreamMux first."
|
||||
)
|
||||
if ch._is_async:
|
||||
raise TypeError(
|
||||
f"StreamChannel {name!r} is bound to async mode — "
|
||||
"sync interleave() cannot consume async channels."
|
||||
)
|
||||
if ch._subscribed:
|
||||
raise RuntimeError(
|
||||
f"StreamChannel {name!r} already has a subscriber; "
|
||||
"use .tee(n) for fan-out."
|
||||
)
|
||||
ch._subscribed = True
|
||||
channels[name] = ch
|
||||
|
||||
done: set[str] = set()
|
||||
|
||||
while len(done) < len(channels):
|
||||
best: tuple[int, str] | None = None
|
||||
for name, ch in channels.items():
|
||||
if name in done:
|
||||
continue
|
||||
if ch._closed and not ch._items:
|
||||
if ch._error is not None:
|
||||
raise ch._error
|
||||
done.add(name)
|
||||
continue
|
||||
if ch._items:
|
||||
stamp = ch._items[0][0]
|
||||
if best is None or stamp < best[0]:
|
||||
best = (stamp, name)
|
||||
|
||||
if best is not None:
|
||||
_stamp, item = channels[best[1]]._items.popleft()
|
||||
yield (best[1], item)
|
||||
else:
|
||||
pump = self._mux._pump_fn
|
||||
if pump is None or not pump():
|
||||
before = len(done)
|
||||
for name, ch in channels.items():
|
||||
if name not in done and not ch._items:
|
||||
if ch._closed:
|
||||
if ch._error is not None:
|
||||
raise ch._error
|
||||
done.add(name)
|
||||
if len(done) == before:
|
||||
break
|
||||
finally:
|
||||
for ch in channels.values():
|
||||
ch._subscribed = False
|
||||
|
||||
|
||||
@beta(message="The v3 streaming protocol on Pregel is experimental.")
|
||||
class AsyncGraphRunStream:
|
||||
"""Async run stream with caller-driven pumping.
|
||||
|
||||
Async iteration on any projection drives the graph forward — there
|
||||
is no background task. Concurrent consumers share a single-flight
|
||||
pump via an `asyncio.Lock`, so each awaiting cursor contributes one
|
||||
event per acquisition. Backpressure comes from the logs: when a
|
||||
subscribed log's buffer reaches `maxlen`, `apush` awaits the
|
||||
subscriber to drain, which holds back the pump and paces the graph.
|
||||
|
||||
Projections are single-consumer — a second `aiter(run.values)`
|
||||
raises. Use `projection.tee(n)` for fan-out.
|
||||
|
||||
Use as an async context manager to guarantee clean shutdown on
|
||||
early exit:
|
||||
|
||||
```python
|
||||
async with await handler.astream(input) as run:
|
||||
async for msg in run.messages:
|
||||
...
|
||||
```
|
||||
|
||||
!!! warning
|
||||
|
||||
Awaited from `Pregel.astream_events(version="v3")`, which is
|
||||
experimental and may change.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
graph_aiter: AsyncIterator[Any] | None,
|
||||
mux: StreamMux,
|
||||
*,
|
||||
wire_pump: bool = True,
|
||||
) -> None:
|
||||
"""Initialize the async run stream.
|
||||
|
||||
Args:
|
||||
graph_aiter: Async iterator over the graph's stream, or
|
||||
`None` for nested run streams whose pump is driven by
|
||||
an outer run (e.g. `AsyncSubgraphRunStream`).
|
||||
mux: The StreamMux owning projections and the main log.
|
||||
wire_pump: When True (default), bind `_apump_next` as the
|
||||
mux's async pump callable. Subclasses that inherit a
|
||||
parent pump via `StreamMux._make_child` should pass
|
||||
False to preserve the parent binding.
|
||||
"""
|
||||
self._graph_aiter = graph_aiter
|
||||
self._mux = mux
|
||||
self.extensions: Mapping[str, Any] = MappingProxyType(mux.extensions)
|
||||
self._exhausted = False
|
||||
self._latest: dict[str, Any] | None = None
|
||||
self._interrupted = False
|
||||
self._interrupts: list[Any] = []
|
||||
self._scope_list: list[str] = list(mux.scope)
|
||||
self._pump_cond = asyncio.Condition()
|
||||
self._pumping = False
|
||||
for key in mux.native_keys:
|
||||
setattr(self, key, mux.extensions[key])
|
||||
if wire_pump:
|
||||
self._wire_arequest_more(mux)
|
||||
|
||||
def _observe_event(self, event: ProtocolEvent) -> None:
|
||||
"""Track values-event state for output/interrupted/interrupts."""
|
||||
if event["method"] != "values":
|
||||
return
|
||||
params = event["params"]
|
||||
if params["namespace"] != self._scope_list:
|
||||
return
|
||||
self._latest = params["data"]
|
||||
interrupts = params.get("interrupts", ())
|
||||
if interrupts:
|
||||
self._interrupted = True
|
||||
self._interrupts.extend(interrupts)
|
||||
|
||||
def _wire_arequest_more(self, mux: StreamMux) -> None:
|
||||
"""Wire the async pull callback through the mux.
|
||||
|
||||
Mirrors `_wire_request_more`: routing through
|
||||
`mux.bind_apump` lets child mini-muxes inherit the pump
|
||||
callable so cursors on subgraph handles drive the root
|
||||
pump.
|
||||
"""
|
||||
mux.bind_apump(self._apump_next)
|
||||
|
||||
async def _apump_next(self) -> bool:
|
||||
"""Drive one pump step, or wait for the active pumper to drive one.
|
||||
|
||||
"Take-a-number" semantics: at most one task at a time calls
|
||||
`graph_aiter.__anext__()` (asyncio iterators can't be advanced
|
||||
concurrently). Other callers wait on a Condition that the
|
||||
active pumper notifies after each step. This lets a "passive"
|
||||
consumer — one whose projection's buffer is being filled by the
|
||||
active pumper's push — wake up as soon as its data lands,
|
||||
instead of queueing on the pump and only observing its data one
|
||||
graph event late.
|
||||
|
||||
`except Exception` is intentional — `CancelledError` and other
|
||||
`BaseException` subclasses propagate, matching asyncio's
|
||||
cancellation contract.
|
||||
|
||||
Returns:
|
||||
True if a pump step completed (by this task or another),
|
||||
False if the graph is exhausted.
|
||||
"""
|
||||
async with self._pump_cond:
|
||||
if self._exhausted or self._graph_aiter is None:
|
||||
return False
|
||||
if self._pumping:
|
||||
# Another task is pumping; wait for its progress signal.
|
||||
await self._pump_cond.wait()
|
||||
return not self._exhausted
|
||||
self._pumping = True
|
||||
|
||||
try:
|
||||
try:
|
||||
part = await self._graph_aiter.__anext__()
|
||||
event = convert_to_protocol_event(part)
|
||||
self._observe_event(event)
|
||||
await self._mux.apush(event)
|
||||
return True
|
||||
except StopAsyncIteration:
|
||||
self._exhausted = True
|
||||
await self._mux.aclose()
|
||||
return False
|
||||
except Exception as e:
|
||||
self._exhausted = True
|
||||
await self._mux.afail(e)
|
||||
return False
|
||||
finally:
|
||||
async with self._pump_cond:
|
||||
self._pumping = False
|
||||
self._pump_cond.notify_all()
|
||||
|
||||
async def abort(self) -> None:
|
||||
"""Stop the run early.
|
||||
|
||||
Marks the stream exhausted, wakes any pump-waiters, and closes
|
||||
the mux. Any `apush` blocked on backpressure wakes and returns
|
||||
without appending. Idempotent.
|
||||
"""
|
||||
async with self._pump_cond:
|
||||
if self._exhausted:
|
||||
return
|
||||
self._exhausted = True
|
||||
self._pump_cond.notify_all()
|
||||
try:
|
||||
await self._mux.aclose()
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
async def __aenter__(self) -> AsyncGraphRunStream:
|
||||
return self
|
||||
|
||||
async def __aexit__(
|
||||
self,
|
||||
exc_type: type[BaseException] | None,
|
||||
exc: BaseException | None,
|
||||
tb: TracebackType | None,
|
||||
) -> None:
|
||||
await self.abort()
|
||||
|
||||
async def output(self) -> dict[str, Any] | None:
|
||||
"""Drive the run to completion and return the final state.
|
||||
|
||||
Methods (not properties) on the async lane so `run.output`
|
||||
without `await` raises at type-check time instead of silently
|
||||
yielding a coroutine object.
|
||||
|
||||
Example:
|
||||
```python
|
||||
output = await run.output()
|
||||
```
|
||||
|
||||
Raises:
|
||||
BaseException: If the run ended with an error.
|
||||
"""
|
||||
await _adrive_until_done(self._apump_next)
|
||||
if (err := self._mux._events._error) is not None:
|
||||
raise err
|
||||
return self._latest
|
||||
|
||||
async def interrupted(self) -> bool:
|
||||
"""Drive the run to completion and return whether it was
|
||||
interrupted.
|
||||
|
||||
Raises:
|
||||
BaseException: If the run ended with an error.
|
||||
"""
|
||||
await _adrive_until_done(self._apump_next)
|
||||
if (err := self._mux._events._error) is not None:
|
||||
raise err
|
||||
return self._interrupted
|
||||
|
||||
async def interrupts(self) -> list[Any]:
|
||||
"""Drive the run to completion and return interrupt payloads.
|
||||
|
||||
Raises:
|
||||
BaseException: If the run ended with an error.
|
||||
"""
|
||||
await _adrive_until_done(self._apump_next)
|
||||
if (err := self._mux._events._error) is not None:
|
||||
raise err
|
||||
return self._interrupts
|
||||
|
||||
def __aiter__(self) -> AsyncIterator[ProtocolEvent]:
|
||||
"""Subscribe to the main event log and iterate protocol events."""
|
||||
return self._mux._events.__aiter__()
|
||||
|
||||
|
||||
class _SubgraphRunStreamMixin:
|
||||
"""Subgraph metadata + parent-pump delegation shared by both lanes.
|
||||
|
||||
Inherits from `GraphRunStream` (or `AsyncGraphRunStream`) with
|
||||
`graph_iter=None` + `wire_pump=False` — the mini-mux is driven
|
||||
by the parent's pump (inherited via `StreamMux._make_child`), and
|
||||
the handle never pulls upstream itself. Pump-driving methods
|
||||
delegate to the parent pump so `handle.output` and friends drive
|
||||
the root run.
|
||||
|
||||
Subclasses set the parent pump function captured at construction
|
||||
(`_parent_pump_fn` / `_parent_apump_fn`) and override
|
||||
`_pump_next` / `_apump_next` to delegate to it.
|
||||
|
||||
Status is updated in place by `SubgraphTransformer`. Iterate
|
||||
`run.subgraphs` to receive handles as subgraphs spawn, then
|
||||
drill into projections inside the loop body **before** the next
|
||||
pump cycle — same lazy-subscribe constraint as root projections.
|
||||
"""
|
||||
|
||||
path: tuple[str, ...]
|
||||
graph_name: str | None
|
||||
trigger_call_id: str | None
|
||||
status: SubgraphStatus
|
||||
error: str | None
|
||||
_seen_terminal: bool
|
||||
|
||||
|
||||
class SubgraphRunStream(GraphRunStream, _SubgraphRunStreamMixin):
|
||||
"""Sync handle for a discovered subgraph (extends `GraphRunStream`)."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
mux: StreamMux,
|
||||
*,
|
||||
path: tuple[str, ...],
|
||||
graph_name: str | None = None,
|
||||
trigger_call_id: str | None = None,
|
||||
) -> None:
|
||||
# Capture the parent-inherited pump before super().__init__
|
||||
# touches anything; we delegate to it from `_pump_next`.
|
||||
self._parent_pump_fn: Callable[[], bool] | None = mux._pump_fn
|
||||
super().__init__(
|
||||
graph_iter=None,
|
||||
mux=mux,
|
||||
wire_pump=False,
|
||||
)
|
||||
self.path = path
|
||||
self.graph_name = graph_name
|
||||
self.trigger_call_id = trigger_call_id
|
||||
self.status = "started"
|
||||
self.error = None
|
||||
self._seen_terminal = False
|
||||
|
||||
def _pump_next(self) -> bool:
|
||||
"""Delegate to the parent's pump.
|
||||
|
||||
Cursors on this handle's projections call here when their
|
||||
buffers empty. Driving the parent fans events into our
|
||||
mini-mux, transparently advancing the whole run.
|
||||
"""
|
||||
if (
|
||||
self._exhausted
|
||||
or self._seen_terminal
|
||||
or self._mux._events._closed
|
||||
or self._parent_pump_fn is None
|
||||
):
|
||||
return False
|
||||
return self._parent_pump_fn()
|
||||
|
||||
|
||||
class AsyncSubgraphRunStream(AsyncGraphRunStream, _SubgraphRunStreamMixin):
|
||||
"""Async handle for a discovered subgraph (extends `AsyncGraphRunStream`)."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
mux: StreamMux,
|
||||
*,
|
||||
path: tuple[str, ...],
|
||||
graph_name: str | None = None,
|
||||
trigger_call_id: str | None = None,
|
||||
) -> None:
|
||||
self._parent_apump_fn: Callable[[], Awaitable[bool]] | None = mux._apump_fn
|
||||
super().__init__(
|
||||
graph_aiter=None,
|
||||
mux=mux,
|
||||
wire_pump=False,
|
||||
)
|
||||
self.path = path
|
||||
self.graph_name = graph_name
|
||||
self.trigger_call_id = trigger_call_id
|
||||
self.status = "started"
|
||||
self.error = None
|
||||
self._seen_terminal = False
|
||||
|
||||
async def _apump_next(self) -> bool:
|
||||
"""Delegate to the parent's async pump."""
|
||||
if (
|
||||
self._exhausted
|
||||
or self._seen_terminal
|
||||
or self._mux._events._closed
|
||||
or self._parent_apump_fn is None
|
||||
):
|
||||
return False
|
||||
return await self._parent_apump_fn()
|
||||
@@ -0,0 +1,341 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
from collections import deque
|
||||
from collections.abc import AsyncIterator, Awaitable, Callable, Iterator
|
||||
from typing import TYPE_CHECKING, Generic, TypeVar
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from langgraph.stream._mux import StreamMux
|
||||
|
||||
T = TypeVar("T")
|
||||
|
||||
|
||||
class StreamChannel(Generic[T]):
|
||||
"""Single-consumer drainable queue for streaming events, with optional
|
||||
protocol auto-forwarding.
|
||||
|
||||
When constructed with a `name`, the StreamMux auto-wires every
|
||||
`push()` to also inject a `ProtocolEvent` into the main event stream
|
||||
using the channel's name as the method. When constructed without a
|
||||
name, the channel is local-only — items are only visible to
|
||||
in-process consumers that iterate the channel directly.
|
||||
|
||||
Items are popped off the front as the consumer advances — there is
|
||||
no retention beyond what's currently queued. A channel accepts
|
||||
exactly one subscriber; a second `__iter__` / `__aiter__` call
|
||||
raises. Use `tee(n)` / `atee(n)` for fan-out.
|
||||
|
||||
Starts unbound — neither `__iter__` nor `__aiter__` is available
|
||||
until the StreamMux calls `_bind(is_async)`. After binding, only
|
||||
the matching iteration protocol works; the other raises `TypeError`.
|
||||
|
||||
Pump wiring (set by the run stream, not by `_bind`):
|
||||
- `_request_more`: sync pump callable, returns True if a new
|
||||
event was produced.
|
||||
- `_arequest_more`: async pump coroutine factory, same contract.
|
||||
|
||||
Memory is bounded by caller pace: both sync and async use caller-
|
||||
driven pumps, so each cursor advance produces at most one event.
|
||||
|
||||
Lazy-subscribe: `push` appends to the local buffer only when a
|
||||
subscriber has registered. Auto-forward via `_wire_fn` always fires
|
||||
regardless of subscription state.
|
||||
|
||||
Lifecycle (`close` / `fail`) is managed by the mux — transformers
|
||||
don't need to close their channels manually.
|
||||
"""
|
||||
|
||||
def __init__(self, name: str | None = None, *, maxlen: int | None = None) -> None:
|
||||
"""Initialize the channel.
|
||||
|
||||
Args:
|
||||
name: Optional protocol channel name. When set, the
|
||||
StreamMux wires every `push()` to also inject a
|
||||
`ProtocolEvent` into the main event stream. Surfaced
|
||||
on the wire as `custom:<name>` for user-defined
|
||||
transformers, or as `<name>` for channels owned by a
|
||||
native transformer (`_native = True`). When `None`,
|
||||
the channel is local-only.
|
||||
maxlen: Accepted for forward compatibility; currently
|
||||
unused. The caller-driven pump bounds memory naturally
|
||||
for single-consumer use.
|
||||
|
||||
Raises:
|
||||
ValueError: If `maxlen` is not a positive integer or `None`.
|
||||
"""
|
||||
if maxlen is not None and maxlen <= 0:
|
||||
raise ValueError("StreamChannel maxlen must be a positive int or None")
|
||||
self.name = name
|
||||
self._items: deque[tuple[int, T]] = deque()
|
||||
self._maxlen: int | None = maxlen
|
||||
self._closed = False
|
||||
self._error: BaseException | None = None
|
||||
|
||||
self._is_async: bool | None = None
|
||||
|
||||
self._subscribed = False
|
||||
|
||||
self._request_more: Callable[[], bool] | None = None
|
||||
self._arequest_more: Callable[[], Awaitable[bool]] | None = None
|
||||
|
||||
self._wire_fn: Callable[[T], None] | None = None
|
||||
self._mux: StreamMux | None = None
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Binding
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _bind_mux(self, mux: StreamMux) -> None:
|
||||
self._mux = mux
|
||||
|
||||
def _bind(self, *, is_async: bool) -> None:
|
||||
"""Bind this channel to sync or async mode.
|
||||
|
||||
Called by the StreamMux after transformer registration. Must be
|
||||
called exactly once before any iteration.
|
||||
|
||||
Args:
|
||||
is_async: True to enable async iteration, False for sync.
|
||||
|
||||
Raises:
|
||||
RuntimeError: If the channel has already been bound.
|
||||
"""
|
||||
if self._is_async is not None:
|
||||
raise RuntimeError("StreamChannel is already bound")
|
||||
self._is_async = is_async
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Mux wiring (not called by transformers directly)
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def _wire(self, fn: Callable[[T], None]) -> None:
|
||||
"""Install the auto-forward callback (called by StreamMux)."""
|
||||
self._wire_fn = fn
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Producer API
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def push(self, item: T) -> None:
|
||||
"""Append an item. Auto-forwards if wired.
|
||||
|
||||
The local buffer append is a no-op when no subscriber is
|
||||
registered, but auto-forwarding always fires so wired events
|
||||
reach the main event log regardless of subscription state.
|
||||
|
||||
Items are stored as `(stamp, item)` tuples where stamp is a
|
||||
monotonic counter from the owning mux. Stamps are stripped by
|
||||
the default cursors; raw stamped tuples are visible on `_items`.
|
||||
|
||||
Raises:
|
||||
RuntimeError: If the channel is closed (and subscribed).
|
||||
"""
|
||||
if self._subscribed:
|
||||
if self._closed:
|
||||
raise RuntimeError("Cannot push to a closed StreamChannel")
|
||||
stamp = self._mux._next_push_seq() if self._mux is not None else 0
|
||||
self._items.append((stamp, item))
|
||||
if self._wire_fn is not None:
|
||||
self._wire_fn(item)
|
||||
|
||||
def close(self) -> None:
|
||||
"""Mark the channel as complete."""
|
||||
self._closed = True
|
||||
|
||||
def fail(self, err: BaseException) -> None:
|
||||
"""Mark the channel as errored.
|
||||
|
||||
Args:
|
||||
err: The exception to surface to the subscriber.
|
||||
"""
|
||||
self._error = err
|
||||
self._closed = True
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Sync iteration (caller-driven pump)
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def __iter__(self) -> Iterator[T]:
|
||||
"""Subscribe and return a sync cursor. Can be called only once.
|
||||
|
||||
Raises:
|
||||
TypeError: If the channel is unbound or bound to async mode.
|
||||
RuntimeError: If the channel already has a subscriber.
|
||||
"""
|
||||
if self._is_async is None:
|
||||
raise TypeError(
|
||||
"StreamChannel has not been bound yet. "
|
||||
"Register the transformer with a StreamMux first."
|
||||
)
|
||||
if self._is_async:
|
||||
raise TypeError(
|
||||
"This StreamChannel is bound to async mode — use 'async for' instead."
|
||||
)
|
||||
if self._subscribed:
|
||||
raise RuntimeError(
|
||||
"StreamChannel already has a subscriber; use .tee(n) for fan-out."
|
||||
)
|
||||
self._subscribed = True
|
||||
return self._sync_cursor()
|
||||
|
||||
def _sync_cursor(self) -> Iterator[T]:
|
||||
while True:
|
||||
if self._items:
|
||||
_stamp, item = self._items.popleft()
|
||||
yield item
|
||||
elif self._closed:
|
||||
if self._error is not None:
|
||||
raise self._error
|
||||
return
|
||||
elif self._request_more is not None:
|
||||
if not self._request_more():
|
||||
if not self._items and not self._closed:
|
||||
return
|
||||
else:
|
||||
return
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Async iteration (caller-driven pump)
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def __aiter__(self) -> AsyncIterator[T]:
|
||||
"""Subscribe and return an async cursor. Can be called only once.
|
||||
|
||||
Raises:
|
||||
TypeError: If the channel is unbound or bound to sync mode.
|
||||
RuntimeError: If the channel already has a subscriber.
|
||||
"""
|
||||
if self._is_async is None:
|
||||
raise TypeError(
|
||||
"StreamChannel has not been bound yet. "
|
||||
"Register the transformer with a StreamMux first."
|
||||
)
|
||||
if not self._is_async:
|
||||
raise TypeError(
|
||||
"This StreamChannel is bound to sync mode — use 'for' instead."
|
||||
)
|
||||
if self._subscribed:
|
||||
raise RuntimeError(
|
||||
"StreamChannel already has a subscriber; use .atee(n) for fan-out."
|
||||
)
|
||||
self._subscribed = True
|
||||
return self._async_cursor()
|
||||
|
||||
async def _async_cursor(self) -> AsyncIterator[T]:
|
||||
while True:
|
||||
if self._items:
|
||||
_stamp, item = self._items.popleft()
|
||||
yield item
|
||||
elif self._closed:
|
||||
if self._error is not None:
|
||||
raise self._error
|
||||
return
|
||||
elif self._arequest_more is not None:
|
||||
if not await self._arequest_more():
|
||||
if not self._items and not self._closed:
|
||||
return
|
||||
else:
|
||||
return
|
||||
|
||||
# ------------------------------------------------------------------
|
||||
# Fan-out via tee
|
||||
# ------------------------------------------------------------------
|
||||
|
||||
def tee(self, n: int = 2) -> tuple[Iterator[T], ...]:
|
||||
"""Subscribe and return `n` independent sync iterators.
|
||||
|
||||
Each branch has its own buffer; items pulled from the
|
||||
underlying cursor are copied into every branch. Branches are
|
||||
naturally bounded by caller pace since the sync pump is
|
||||
caller-driven.
|
||||
|
||||
Args:
|
||||
n: Number of branches to create. Must be >= 1.
|
||||
|
||||
Returns:
|
||||
A tuple of `n` iterators over the same underlying stream.
|
||||
|
||||
Raises:
|
||||
TypeError: If the channel is unbound or bound to async mode.
|
||||
RuntimeError: If the channel already has a subscriber.
|
||||
ValueError: If `n` < 1.
|
||||
"""
|
||||
if n < 1:
|
||||
raise ValueError("tee() requires n >= 1")
|
||||
source = self.__iter__()
|
||||
buffers: list[deque[T]] = [deque() for _ in range(n)]
|
||||
exhausted = [False]
|
||||
|
||||
def branch(i: int) -> Iterator[T]:
|
||||
buf = buffers[i]
|
||||
while True:
|
||||
if buf:
|
||||
yield buf.popleft()
|
||||
elif exhausted[0]:
|
||||
return
|
||||
else:
|
||||
try:
|
||||
item = next(source)
|
||||
except StopIteration:
|
||||
exhausted[0] = True
|
||||
return
|
||||
for b in buffers:
|
||||
b.append(item)
|
||||
|
||||
return tuple(branch(i) for i in range(n))
|
||||
|
||||
def atee(self, n: int = 2) -> tuple[AsyncIterator[T], ...]:
|
||||
"""Subscribe and return `n` independent async iterators.
|
||||
|
||||
Caller-driven fan-out: each branch's `__anext__` either pops
|
||||
from its own buffer or, under a shared `asyncio.Lock`, pulls
|
||||
one item from the underlying cursor and distributes it to
|
||||
every branch's buffer.
|
||||
|
||||
Args:
|
||||
n: Number of branches to create. Must be >= 1.
|
||||
|
||||
Returns:
|
||||
A tuple of `n` async iterators over the same underlying
|
||||
stream.
|
||||
|
||||
Raises:
|
||||
TypeError: If the channel is unbound or bound to sync mode.
|
||||
RuntimeError: If the channel already has a subscriber.
|
||||
ValueError: If `n` < 1.
|
||||
"""
|
||||
if n < 1:
|
||||
raise ValueError("atee() requires n >= 1")
|
||||
source = self.__aiter__()
|
||||
buffers: list[deque[T]] = [deque() for _ in range(n)]
|
||||
exhausted = [False]
|
||||
error: list[BaseException | None] = [None]
|
||||
lock = asyncio.Lock()
|
||||
|
||||
async def branch(i: int) -> AsyncIterator[T]:
|
||||
buf = buffers[i]
|
||||
while True:
|
||||
if buf:
|
||||
yield buf.popleft()
|
||||
continue
|
||||
if exhausted[0]:
|
||||
if error[0] is not None:
|
||||
raise error[0]
|
||||
return
|
||||
async with lock:
|
||||
if buf or exhausted[0]:
|
||||
continue
|
||||
try:
|
||||
item = await source.__anext__()
|
||||
except StopAsyncIteration:
|
||||
exhausted[0] = True
|
||||
continue
|
||||
except Exception as e:
|
||||
error[0] = e
|
||||
exhausted[0] = True
|
||||
continue
|
||||
for b in buffers:
|
||||
b.append(item)
|
||||
|
||||
return tuple(branch(i) for i in range(n))
|
||||
@@ -0,0 +1,928 @@
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from typing import TYPE_CHECKING, Any, Literal, cast
|
||||
|
||||
from langchain_core.language_models._compat_bridge import message_to_events
|
||||
from langchain_core.language_models.chat_model_stream import (
|
||||
AsyncChatModelStream,
|
||||
ChatModelStream,
|
||||
)
|
||||
from langchain_core.messages import AIMessageChunk, BaseMessage
|
||||
from langchain_protocol.protocol import MessagesData
|
||||
from typing_extensions import NotRequired, TypedDict
|
||||
|
||||
from langgraph.errors import GraphDrained, GraphInterrupt
|
||||
from langgraph.stream._types import ProtocolEvent, StreamTransformer
|
||||
from langgraph.stream.run_stream import AsyncSubgraphRunStream, SubgraphRunStream
|
||||
from langgraph.stream.stream_channel import StreamChannel
|
||||
|
||||
if TYPE_CHECKING:
|
||||
from collections.abc import Awaitable, Callable
|
||||
|
||||
from langgraph.stream._mux import StreamMux
|
||||
|
||||
_logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class ValuesTransformer(StreamTransformer):
|
||||
"""Capture values events as a drainable stream of state snapshots.
|
||||
|
||||
Provides the `run.values` projection. `run.output`,
|
||||
`run.interrupted` and `run.interrupts` are tracked directly
|
||||
by the run stream and do not depend on this transformer.
|
||||
|
||||
Native transformer — projection keys are exposed as direct
|
||||
attributes on the run stream (e.g. `run.values`).
|
||||
|
||||
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_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.
|
||||
"""
|
||||
|
||||
_native = True
|
||||
required_stream_modes = ("values",)
|
||||
|
||||
def __init__(self, scope: tuple[str, ...] = ()) -> None:
|
||||
super().__init__(scope)
|
||||
self._log: StreamChannel[dict[str, Any]] = StreamChannel()
|
||||
self._latest: dict[str, Any] | None = None
|
||||
self._interrupted = False
|
||||
self._interrupts: list[Any] = []
|
||||
# Cached as a list once for cheap equality with the protocol
|
||||
# event's `namespace` field, which is `list[str]`.
|
||||
self._scope_list: list[str] = list(scope)
|
||||
|
||||
def init(self) -> dict[str, Any]:
|
||||
return {"values": self._log}
|
||||
|
||||
@property
|
||||
def error(self) -> BaseException | None:
|
||||
"""The error that ended the run, or `None` if it succeeded.
|
||||
|
||||
Set by the mux when it auto-fails the projection log.
|
||||
"""
|
||||
return self._log._error
|
||||
|
||||
def process(self, event: ProtocolEvent) -> bool:
|
||||
if event["method"] != "values":
|
||||
return True
|
||||
params = event["params"]
|
||||
if params["namespace"] != self._scope_list:
|
||||
return True
|
||||
self._latest = params["data"]
|
||||
interrupts = params.get("interrupts", ())
|
||||
if interrupts:
|
||||
self._interrupted = True
|
||||
self._interrupts.extend(interrupts)
|
||||
self._log.push(params["data"])
|
||||
return True
|
||||
|
||||
|
||||
class CustomTransformer(StreamTransformer):
|
||||
"""Capture custom events as a drainable stream of arbitrary payloads.
|
||||
|
||||
Nodes emit custom data via `get_stream_writer()`. This transformer
|
||||
surfaces those events on `run.custom` as a `StreamChannel[Any]`,
|
||||
preserving payloads in arrival order.
|
||||
|
||||
Only events at the run's own scope are captured; custom data from
|
||||
deeper subgraphs is available on the respective subgraph handle's
|
||||
`.custom` projection.
|
||||
|
||||
Native transformer — `run.custom` is a direct attribute.
|
||||
"""
|
||||
|
||||
_native = True
|
||||
required_stream_modes = ("custom",)
|
||||
|
||||
def __init__(self, scope: tuple[str, ...] = ()) -> None:
|
||||
super().__init__(scope)
|
||||
self._log: StreamChannel[Any] = StreamChannel()
|
||||
self._scope_list: list[str] = list(scope)
|
||||
|
||||
def init(self) -> dict[str, Any]:
|
||||
return {"custom": self._log}
|
||||
|
||||
def process(self, event: ProtocolEvent) -> bool:
|
||||
if event["method"] != "custom":
|
||||
return True
|
||||
params = event["params"]
|
||||
if params["namespace"] != self._scope_list:
|
||||
return True
|
||||
self._log.push(params["data"])
|
||||
return True
|
||||
|
||||
|
||||
class UpdatesTransformer(StreamTransformer):
|
||||
"""Capture updates events as a drainable stream of node outputs.
|
||||
|
||||
Surfaces `stream_mode="updates"` data on `run.updates` as a
|
||||
`StreamChannel[dict[str, Any]]`. Each item is a dict mapping a node
|
||||
(or task) name to the update it returned after a step.
|
||||
|
||||
Only events at the run's own scope are captured; updates from deeper
|
||||
subgraphs are available on the respective subgraph handle's
|
||||
`.updates` projection.
|
||||
|
||||
Native transformer — `run.updates` is a direct attribute.
|
||||
"""
|
||||
|
||||
_native = True
|
||||
required_stream_modes = ("updates",)
|
||||
|
||||
def __init__(self, scope: tuple[str, ...] = ()) -> None:
|
||||
super().__init__(scope)
|
||||
self._log: StreamChannel[dict[str, Any]] = StreamChannel()
|
||||
self._scope_list: list[str] = list(scope)
|
||||
|
||||
def init(self) -> dict[str, Any]:
|
||||
return {"updates": self._log}
|
||||
|
||||
def process(self, event: ProtocolEvent) -> bool:
|
||||
if event["method"] != "updates":
|
||||
return True
|
||||
params = event["params"]
|
||||
if params["namespace"] != self._scope_list:
|
||||
return True
|
||||
self._log.push(params["data"])
|
||||
return True
|
||||
|
||||
|
||||
class MessagesTransformer(StreamTransformer):
|
||||
"""Capture messages events as ChatModelStream objects.
|
||||
|
||||
The messages projection yields one `ChatModelStream` (or
|
||||
`AsyncChatModelStream`) per LLM call. Consumers iterate
|
||||
`run.messages` to get stream handles, then use each handle's typed
|
||||
projections (`.text`, `.reasoning`, `.tool_calls`, `.usage`,
|
||||
`.output`) for per-message content.
|
||||
|
||||
Two input shapes are handled (via `params["data"] = (payload,
|
||||
metadata)` from `StreamMessagesHandler`):
|
||||
|
||||
1. Protocol event (dict with `"event"` key) — emitted by
|
||||
`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.
|
||||
2. Whole `AIMessage` — emitted from `on_chain_end` when a node
|
||||
returns a finalized message. Replayed as a synthetic protocol
|
||||
event lifecycle via `message_to_events`, then the
|
||||
already-complete stream is pushed to the log.
|
||||
|
||||
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_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_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.
|
||||
|
||||
Native transformer — the `messages` projection is exposed as a
|
||||
direct attribute on the run stream.
|
||||
"""
|
||||
|
||||
_native = True
|
||||
required_stream_modes = ("messages",)
|
||||
|
||||
def __init__(self, scope: tuple[str, ...] = ()) -> None:
|
||||
super().__init__(scope)
|
||||
self._log: StreamChannel[ChatModelStream] = StreamChannel()
|
||||
# Correlate protocol events back to a ChatModelStream by run_id
|
||||
# (attached to the event's metadata by StreamMessagesHandler).
|
||||
self._by_run: dict[str, ChatModelStream] = {}
|
||||
self._pump_fn: Callable[[], bool] | None = None
|
||||
self._apump_fn: Callable[[], Awaitable[bool]] | None = None
|
||||
# Cached as a list once for cheap equality with the protocol
|
||||
# event's `namespace` field, which is `list[str]`.
|
||||
self._scope_list: list[str] = list(scope)
|
||||
|
||||
def init(self) -> dict[str, Any]:
|
||||
return {"messages": self._log}
|
||||
|
||||
def _bind_pump(self, fn: Callable[[], bool]) -> None:
|
||||
"""Wire the sync pull callback. Called by GraphRunStream._wire_request_more."""
|
||||
self._pump_fn = fn
|
||||
|
||||
def _bind_apump(self, fn: Callable[[], Awaitable[bool]]) -> None:
|
||||
"""Wire the async pull callback.
|
||||
|
||||
Called by `AsyncGraphRunStream._wire_arequest_more` so each
|
||||
`AsyncChatModelStream` this transformer creates can drive the
|
||||
shared graph pump from its projection cursors.
|
||||
"""
|
||||
self._apump_fn = fn
|
||||
|
||||
def _make_stream(
|
||||
self,
|
||||
*,
|
||||
namespace: list[str],
|
||||
node: str | None,
|
||||
message_id: str | None,
|
||||
) -> ChatModelStream:
|
||||
"""Create a ChatModelStream (sync) or AsyncChatModelStream (async).
|
||||
|
||||
Wires whichever pump is bound. Prefers the async pump so nested
|
||||
iteration under `AsyncGraphRunStream` drives the graph forward
|
||||
without a background task. The unwired fallback (no pump bound)
|
||||
is used by unit tests that dispatch events manually.
|
||||
"""
|
||||
if self._apump_fn is not None:
|
||||
astream = AsyncChatModelStream(
|
||||
namespace=namespace,
|
||||
node=node,
|
||||
message_id=message_id,
|
||||
)
|
||||
astream.set_arequest_more(self._apump_fn)
|
||||
return astream
|
||||
if self._pump_fn is not None:
|
||||
stream: ChatModelStream = ChatModelStream(
|
||||
namespace=namespace,
|
||||
node=node,
|
||||
message_id=message_id,
|
||||
)
|
||||
stream.set_request_more(self._pump_fn)
|
||||
return stream
|
||||
return AsyncChatModelStream(
|
||||
namespace=namespace,
|
||||
node=node,
|
||||
message_id=message_id,
|
||||
)
|
||||
|
||||
def process(self, event: ProtocolEvent) -> bool:
|
||||
if event["method"] != "messages":
|
||||
return True
|
||||
params = event["params"]
|
||||
if params["namespace"] != self._scope_list:
|
||||
return True
|
||||
|
||||
payload, metadata = params["data"]
|
||||
node: str | None = metadata.get("langgraph_node")
|
||||
run_id = str(metadata.get("run_id", "")) if metadata else ""
|
||||
|
||||
if isinstance(payload, dict) and "event" in payload:
|
||||
self._route_protocol_event(
|
||||
cast("MessagesData", payload), run_id=run_id, node=node
|
||||
)
|
||||
elif isinstance(payload, BaseMessage) and not isinstance(
|
||||
payload, AIMessageChunk
|
||||
):
|
||||
self._route_whole_message(payload, node=node)
|
||||
# Legacy AIMessageChunk tuples (from on_llm_new_token) are ignored;
|
||||
# v1 streaming callers must switch to stream_events(version="v3") to populate this
|
||||
# projection.
|
||||
|
||||
return True
|
||||
|
||||
def _route_protocol_event(
|
||||
self,
|
||||
event: MessagesData,
|
||||
*,
|
||||
run_id: str,
|
||||
node: str | None,
|
||||
) -> None:
|
||||
event_type = event.get("event")
|
||||
if event_type == "message-start":
|
||||
message_id = event.get("message_id")
|
||||
stream = self._make_stream(
|
||||
namespace=[],
|
||||
node=node,
|
||||
message_id=str(message_id) if message_id is not None else None,
|
||||
)
|
||||
self._by_run[run_id] = stream
|
||||
self._log.push(stream)
|
||||
stream.dispatch(event)
|
||||
elif run_id in self._by_run:
|
||||
stream = self._by_run[run_id]
|
||||
stream.dispatch(event)
|
||||
if event_type == "message-finish":
|
||||
del self._by_run[run_id]
|
||||
|
||||
def _route_whole_message(self, message: BaseMessage, *, node: str | None) -> None:
|
||||
stream = self._make_stream(namespace=[], node=node, message_id=message.id)
|
||||
for evt in message_to_events(message, message_id=message.id):
|
||||
stream.dispatch(evt)
|
||||
self._log.push(stream)
|
||||
|
||||
def finalize(self) -> None:
|
||||
"""Clear any routing state — streams close themselves via `message-finish`."""
|
||||
self._by_run.clear()
|
||||
|
||||
def fail(self, err: BaseException) -> None:
|
||||
"""Propagate run error to any streams still open when the graph fails."""
|
||||
for stream in list(self._by_run.values()):
|
||||
stream.fail(err)
|
||||
self._by_run.clear()
|
||||
|
||||
|
||||
SubgraphStatus = Literal["started", "completed", "failed", "interrupted", "drained"]
|
||||
|
||||
|
||||
def _parse_ns_segment(segment: str) -> tuple[str, str | None]:
|
||||
"""Split a namespace segment into `(graph_name, trigger_call_id)`.
|
||||
|
||||
Segments are formatted `node_name:task_id` by `prepare_next_tasks`.
|
||||
Returns `(segment, None)` if no `:` is present.
|
||||
"""
|
||||
name, sep, task_id = segment.partition(":")
|
||||
return name, task_id if sep else None
|
||||
|
||||
|
||||
class LifecyclePayload(TypedDict, total=False):
|
||||
"""Payload of a lifecycle event surfaced on the `lifecycle` channel.
|
||||
|
||||
Auto-forwarded as `lifecycle` protocol events (no `custom:` prefix
|
||||
because `LifecycleTransformer` is a native transformer) so remote
|
||||
SDK clients receive the same data in-process consumers see via
|
||||
`run.lifecycle`.
|
||||
"""
|
||||
|
||||
event: SubgraphStatus
|
||||
namespace: list[str]
|
||||
graph_name: NotRequired[str]
|
||||
trigger_call_id: NotRequired[str]
|
||||
error: NotRequired[str]
|
||||
|
||||
|
||||
class _TasksLifecycleBase(StreamTransformer):
|
||||
"""Shared bookkeeping for `tasks`-event-driven lifecycle inference.
|
||||
|
||||
Both `LifecycleTransformer` (wire-serializable channel) and
|
||||
`SubgraphTransformer` (in-process navigation handles) discover
|
||||
subgraphs by watching the same `tasks` stream — `started` on the
|
||||
first event at a tracked namespace, terminal status when the
|
||||
parent's `TaskResultPayload` arrives. Centralizing the dispatch
|
||||
+ open-set bookkeeping here keeps the inference rules from
|
||||
drifting between the two surfaces.
|
||||
|
||||
Subclasses provide three template-method hooks:
|
||||
|
||||
- `_should_track(ns)` — scope filter (e.g. multi-depth vs
|
||||
direct-children-only).
|
||||
- `_on_started(ns, graph_name, trigger_call_id)` — first sighting
|
||||
action (push payload / build handle / etc.). Called once per
|
||||
discovered namespace.
|
||||
- `_on_terminal(ns, status, error)` — terminal action (push
|
||||
terminal payload / mark handle status). Called once per
|
||||
tracked namespace at result time, or via `finalize` / `fail`
|
||||
sweeps if no parent result arrived.
|
||||
|
||||
Tasks events are suppressed from the main event log (`process`
|
||||
returns False) — they're folded into whichever projection the
|
||||
subclass populates; consumers iterating the raw protocol stream
|
||||
see the higher-level view.
|
||||
"""
|
||||
|
||||
required_stream_modes = ("tasks",)
|
||||
|
||||
def __init__(self, scope: tuple[str, ...] = ()) -> None:
|
||||
super().__init__(scope)
|
||||
self._seen: set[tuple[str, ...]] = set()
|
||||
# Maps tracked namespace -> task_id of the parent task whose
|
||||
# `TaskResultPayload` will close it.
|
||||
self._open: dict[tuple[str, ...], str] = {}
|
||||
|
||||
# --- Template-method hooks (subclass overrides) ---
|
||||
|
||||
def _should_track(self, ns: tuple[str, ...]) -> bool:
|
||||
"""Scope filter — return True iff `ns` is in this transformer's region."""
|
||||
raise NotImplementedError
|
||||
|
||||
def _on_started(
|
||||
self,
|
||||
ns: tuple[str, ...],
|
||||
graph_name: str | None,
|
||||
trigger_call_id: str | None,
|
||||
) -> None:
|
||||
"""Fired once per discovered namespace (first observed task event)."""
|
||||
raise NotImplementedError
|
||||
|
||||
def _on_terminal(
|
||||
self,
|
||||
ns: tuple[str, ...],
|
||||
status: SubgraphStatus,
|
||||
error: str | None,
|
||||
) -> None:
|
||||
"""Fired once per tracked namespace when its parent's result arrives,
|
||||
or via finalize/fail safety-net sweeps.
|
||||
"""
|
||||
raise NotImplementedError
|
||||
|
||||
# --- Dispatch + bookkeeping (shared) ---
|
||||
|
||||
def process(self, event: ProtocolEvent) -> bool:
|
||||
if event["method"] != "tasks":
|
||||
return True
|
||||
ns = tuple(event["params"]["namespace"])
|
||||
data = event["params"]["data"]
|
||||
if "result" in data:
|
||||
self._handle_task_result(ns, data)
|
||||
else:
|
||||
self._handle_task_start(ns)
|
||||
# Tasks events are folded into the synthesized projections;
|
||||
# suppress from the main event log so iterators don't double-see
|
||||
# the same information in two shapes.
|
||||
return False
|
||||
|
||||
def _handle_task_start(self, ns: tuple[str, ...]) -> None:
|
||||
if not self._should_track(ns) or ns in self._seen:
|
||||
return
|
||||
self._seen.add(ns)
|
||||
graph_name, trigger_call_id = _parse_ns_segment(ns[-1])
|
||||
self._on_started(ns, graph_name or None, trigger_call_id)
|
||||
if trigger_call_id is not None:
|
||||
self._open[ns] = trigger_call_id
|
||||
|
||||
def _pop_terminal_transitions(
|
||||
self, ns: tuple[str, ...], data: dict[str, Any]
|
||||
) -> list[tuple[tuple[str, ...], SubgraphStatus, str | None]]:
|
||||
"""Return and remove tracked children closed by this task result."""
|
||||
result_id = data.get("id")
|
||||
if not result_id:
|
||||
return []
|
||||
transitions: list[tuple[tuple[str, ...], SubgraphStatus, str | None]] = []
|
||||
for child_ns, parent_task_id in list(self._open.items()):
|
||||
if child_ns[:-1] != ns or parent_task_id != result_id:
|
||||
continue
|
||||
status, error = _terminal_from_result(data)
|
||||
transitions.append((child_ns, status, error))
|
||||
del self._open[child_ns]
|
||||
return transitions
|
||||
|
||||
def _handle_task_result(self, ns: tuple[str, ...], data: dict[str, Any]) -> None:
|
||||
for child_ns, status, error in self._pop_terminal_transitions(ns, data):
|
||||
self._on_terminal(child_ns, status, error)
|
||||
|
||||
def finalize(self) -> None:
|
||||
"""Emit `completed` for any tracked namespace still open at run end."""
|
||||
for ns in list(self._open):
|
||||
self._on_terminal(ns, "completed", None)
|
||||
self._open.clear()
|
||||
|
||||
def fail(self, err: BaseException) -> None:
|
||||
"""Emit terminal status for any tracked namespace still open."""
|
||||
status, error_str = _status_from_exception(err)
|
||||
for ns in list(self._open):
|
||||
self._on_terminal(ns, status, error_str)
|
||||
self._open.clear()
|
||||
|
||||
|
||||
def _status_from_exception(err: BaseException) -> tuple[SubgraphStatus, str | None]:
|
||||
"""Map a run exception to a subgraph terminal status and error string."""
|
||||
if isinstance(err, GraphDrained):
|
||||
return "drained", None
|
||||
if isinstance(err, GraphInterrupt):
|
||||
return "interrupted", None
|
||||
return "failed", str(err)
|
||||
|
||||
|
||||
def _terminal_from_result(
|
||||
payload: dict[str, Any],
|
||||
) -> tuple[SubgraphStatus, str | None]:
|
||||
"""Map a `TaskResultPayload` to a `(status, error)` pair.
|
||||
|
||||
Order matters: a result with both `error` and `interrupts` prefers
|
||||
the interrupt classification, since `GraphInterrupt` manifests as
|
||||
a populated `interrupts` list, not as `error`.
|
||||
"""
|
||||
if payload.get("interrupts"):
|
||||
return "interrupted", None
|
||||
error = payload.get("error")
|
||||
if error:
|
||||
return "failed", str(error)
|
||||
return "completed", None
|
||||
|
||||
|
||||
class LifecycleTransformer(_TasksLifecycleBase):
|
||||
"""Surface subgraph lifecycle as `lifecycle` protocol events.
|
||||
|
||||
Pushes `LifecyclePayload` to a `StreamChannel` named `lifecycle`.
|
||||
The channel is auto-forwarded by the mux so payloads land in the
|
||||
main event log under `method = "lifecycle"` (native transformer —
|
||||
no `custom:` prefix) — visible to remote SDK clients over the
|
||||
wire and to in-process consumers via `run.lifecycle`.
|
||||
|
||||
Tracks subgraphs at every depth strictly below the transformer's
|
||||
scope, so a graph → subgraph → subgraph chain produces lifecycle
|
||||
events for both nested levels in a flat stream.
|
||||
|
||||
Native transformer — projection key `lifecycle` is exposed as
|
||||
`run.lifecycle`.
|
||||
"""
|
||||
|
||||
_native = True
|
||||
|
||||
def __init__(self, scope: tuple[str, ...] = ()) -> None:
|
||||
super().__init__(scope)
|
||||
self._channel: StreamChannel[LifecyclePayload] = StreamChannel("lifecycle")
|
||||
|
||||
def init(self) -> dict[str, Any]:
|
||||
return {"lifecycle": self._channel}
|
||||
|
||||
def _should_track(self, ns: tuple[str, ...]) -> bool:
|
||||
depth = len(self.scope)
|
||||
return len(ns) > depth and ns[:depth] == self.scope
|
||||
|
||||
def _on_started(
|
||||
self,
|
||||
ns: tuple[str, ...],
|
||||
graph_name: str | None,
|
||||
trigger_call_id: str | None,
|
||||
) -> None:
|
||||
if trigger_call_id is None:
|
||||
# Without a task id we can't correlate a parent-result
|
||||
# event back to this namespace — skip the started payload
|
||||
# and rely on finalize/fail to close.
|
||||
return
|
||||
payload: LifecyclePayload = {"event": "started", "namespace": list(ns)}
|
||||
if graph_name:
|
||||
payload["graph_name"] = graph_name
|
||||
payload["trigger_call_id"] = trigger_call_id
|
||||
self._channel.push(payload)
|
||||
|
||||
def _on_terminal(
|
||||
self,
|
||||
ns: tuple[str, ...],
|
||||
status: SubgraphStatus,
|
||||
error: str | None,
|
||||
) -> None:
|
||||
payload: LifecyclePayload = {"event": status, "namespace": list(ns)}
|
||||
if error is not None:
|
||||
payload["error"] = error
|
||||
self._channel.push(payload)
|
||||
|
||||
|
||||
class SubgraphTransformer(_TasksLifecycleBase):
|
||||
"""Discover subgraph invocations as in-process navigation handles.
|
||||
|
||||
Per discovered direct-child subgraph, builds a `SubgraphRunStream`
|
||||
(or `AsyncSubgraphRunStream`) wrapping a child mini-mux scoped to
|
||||
the subgraph's namespace. Consumers iterate `run.subgraphs` to
|
||||
receive handles, then drill into `handle.values` / `handle.messages`
|
||||
/ `handle.subgraphs` (recursive grandchildren) / `handle.lifecycle`.
|
||||
|
||||
Each mini-mux owns its own scope and uses its own
|
||||
`SubgraphTransformer` to discover its direct children, so
|
||||
grandchildren live on the child handle — never on the root's
|
||||
`subgraphs` log. Forwarding events into the matching child mini-mux
|
||||
is what keeps the child's projections populated.
|
||||
|
||||
Native transformer — `subgraphs` is exposed as `run.subgraphs`.
|
||||
"""
|
||||
|
||||
_native = True
|
||||
supports_sync = True
|
||||
|
||||
def __init__(self, scope: tuple[str, ...] = ()) -> None:
|
||||
super().__init__(scope)
|
||||
self._log: StreamChannel[SubgraphRunStream | AsyncSubgraphRunStream] = (
|
||||
StreamChannel()
|
||||
)
|
||||
self._handles: dict[
|
||||
tuple[str, ...], SubgraphRunStream | AsyncSubgraphRunStream
|
||||
] = {}
|
||||
self._mux: StreamMux | None = None
|
||||
|
||||
def init(self) -> dict[str, Any]:
|
||||
return {"subgraphs": self._log}
|
||||
|
||||
def _on_register(self, mux: Any) -> None:
|
||||
self._mux = mux
|
||||
|
||||
def _should_track(self, ns: tuple[str, ...]) -> bool:
|
||||
# Direct children only — grandchildren are picked up by the
|
||||
# child mini-mux's own SubgraphTransformer.
|
||||
depth = len(self.scope)
|
||||
return len(ns) == depth + 1 and ns[:depth] == self.scope
|
||||
|
||||
def _on_started(
|
||||
self,
|
||||
ns: tuple[str, ...],
|
||||
graph_name: str | None,
|
||||
trigger_call_id: str | None,
|
||||
) -> None:
|
||||
if self._mux is None:
|
||||
return
|
||||
try:
|
||||
child_mux = self._mux._make_child(ns)
|
||||
except RuntimeError:
|
||||
return
|
||||
handle_cls = AsyncSubgraphRunStream if child_mux.is_async else SubgraphRunStream
|
||||
handle = handle_cls(
|
||||
mux=child_mux,
|
||||
path=ns,
|
||||
graph_name=graph_name,
|
||||
trigger_call_id=trigger_call_id,
|
||||
)
|
||||
self._handles[ns] = handle
|
||||
self._log.push(handle)
|
||||
|
||||
def _on_terminal(
|
||||
self,
|
||||
ns: tuple[str, ...],
|
||||
status: SubgraphStatus,
|
||||
error: str | None,
|
||||
) -> None:
|
||||
handle = self._handles.get(ns)
|
||||
if handle is None or not self._mark_terminal(handle, status, error):
|
||||
return
|
||||
self._close_or_fail_handle(handle, status, error)
|
||||
|
||||
async def _aon_terminal(
|
||||
self,
|
||||
ns: tuple[str, ...],
|
||||
status: SubgraphStatus,
|
||||
error: str | None,
|
||||
) -> None:
|
||||
handle = self._handles.get(ns)
|
||||
if handle is None or not self._mark_terminal(handle, status, error):
|
||||
return
|
||||
await self._aclose_or_fail_handle(handle, status, error)
|
||||
|
||||
def _mark_terminal(
|
||||
self,
|
||||
handle: SubgraphRunStream | AsyncSubgraphRunStream,
|
||||
status: SubgraphStatus,
|
||||
error: str | None,
|
||||
) -> bool:
|
||||
"""Mark a handle terminal once. Returns True on first transition."""
|
||||
if handle._seen_terminal:
|
||||
return False
|
||||
handle.status = status
|
||||
if error is not None and handle.error is None:
|
||||
handle.error = error
|
||||
handle._seen_terminal = True
|
||||
return True
|
||||
|
||||
def _close_or_fail_handle(
|
||||
self,
|
||||
handle: SubgraphRunStream | AsyncSubgraphRunStream,
|
||||
status: SubgraphStatus,
|
||||
error: str | None,
|
||||
) -> None:
|
||||
if handle._mux is None or handle._mux._events._closed:
|
||||
return
|
||||
if status == "failed":
|
||||
handle._mux.fail(RuntimeError(error or "Subgraph failed"))
|
||||
else:
|
||||
handle._mux.close()
|
||||
|
||||
async def _aclose_or_fail_handle(
|
||||
self,
|
||||
handle: SubgraphRunStream | AsyncSubgraphRunStream,
|
||||
status: SubgraphStatus,
|
||||
error: str | None,
|
||||
) -> None:
|
||||
if handle._mux is None or handle._mux._events._closed:
|
||||
return
|
||||
if status == "failed":
|
||||
await handle._mux.afail(RuntimeError(error or "Subgraph failed"))
|
||||
else:
|
||||
await handle._mux.aclose()
|
||||
|
||||
def _handle_for_event(
|
||||
self, event: ProtocolEvent
|
||||
) -> SubgraphRunStream | AsyncSubgraphRunStream | None:
|
||||
ns = tuple(event["params"]["namespace"])
|
||||
depth = len(self.scope)
|
||||
if len(ns) < depth + 1:
|
||||
return None
|
||||
handle = self._handles.get(ns[: depth + 1])
|
||||
if handle is None or handle._mux is None or handle._mux._events._closed:
|
||||
return None
|
||||
return handle
|
||||
|
||||
def process(self, event: ProtocolEvent) -> bool:
|
||||
# Run tasks bookkeeping first so a `started` handle exists
|
||||
# by the time we forward the event to the child mini-mux.
|
||||
keep = super().process(event)
|
||||
handle = self._handle_for_event(event)
|
||||
if handle is not None:
|
||||
handle._observe_event(event)
|
||||
handle._mux.push(event)
|
||||
return keep
|
||||
|
||||
async def aprocess(self, event: ProtocolEvent) -> bool:
|
||||
# Async counterpart: repeats the tasks bookkeeping here so
|
||||
# child mini-muxes receive events through their async lane.
|
||||
if event["method"] == "tasks":
|
||||
ns = tuple(event["params"]["namespace"])
|
||||
data = event["params"]["data"]
|
||||
if "result" in data:
|
||||
for child_ns, status, error in self._pop_terminal_transitions(ns, data):
|
||||
await self._aon_terminal(child_ns, status, error)
|
||||
else:
|
||||
self._handle_task_start(ns)
|
||||
keep = False
|
||||
else:
|
||||
keep = True
|
||||
handle = self._handle_for_event(event)
|
||||
if handle is not None:
|
||||
handle._observe_event(event)
|
||||
await handle._mux.apush(event)
|
||||
return keep
|
||||
|
||||
def _complete_open_handles(self) -> BaseException | None:
|
||||
first_error: BaseException | None = None
|
||||
for ns in list(self._open):
|
||||
try:
|
||||
self._on_terminal(ns, "completed", None)
|
||||
except BaseException as e:
|
||||
if first_error is None:
|
||||
first_error = e
|
||||
self._open.clear()
|
||||
for handle in self._handles.values():
|
||||
if self._mark_terminal(handle, "completed", None):
|
||||
try:
|
||||
self._close_or_fail_handle(handle, "completed", None)
|
||||
except BaseException as e:
|
||||
if first_error is None:
|
||||
first_error = e
|
||||
return first_error
|
||||
|
||||
async def _acomplete_open_handles(self) -> BaseException | None:
|
||||
first_error: BaseException | None = None
|
||||
for ns in list(self._open):
|
||||
try:
|
||||
await self._aon_terminal(ns, "completed", None)
|
||||
except BaseException as e:
|
||||
if first_error is None:
|
||||
first_error = e
|
||||
self._open.clear()
|
||||
for handle in self._handles.values():
|
||||
if self._mark_terminal(handle, "completed", None):
|
||||
try:
|
||||
await self._aclose_or_fail_handle(handle, "completed", None)
|
||||
except BaseException as e:
|
||||
if first_error is None:
|
||||
first_error = e
|
||||
return first_error
|
||||
|
||||
def finalize(self) -> None:
|
||||
first_error = self._complete_open_handles()
|
||||
if first_error is not None:
|
||||
raise first_error
|
||||
|
||||
async def afinalize(self) -> None:
|
||||
first_error = await self._acomplete_open_handles()
|
||||
if first_error is not None:
|
||||
raise first_error
|
||||
|
||||
def fail(self, err: BaseException) -> None:
|
||||
status, error_str = _status_from_exception(err)
|
||||
self._open.clear()
|
||||
for handle in self._handles.values():
|
||||
self._mark_terminal(handle, status, error_str)
|
||||
if handle._mux is not None and not handle._mux._events._closed:
|
||||
try:
|
||||
handle._mux.fail(err)
|
||||
except Exception:
|
||||
_logger.warning(
|
||||
"Error failing subgraph mini-mux at %s; "
|
||||
"subscribers may not see the terminal error.",
|
||||
handle.path,
|
||||
exc_info=True,
|
||||
)
|
||||
|
||||
async def afail(self, err: BaseException) -> None:
|
||||
status, error_str = _status_from_exception(err)
|
||||
self._open.clear()
|
||||
for handle in self._handles.values():
|
||||
self._mark_terminal(handle, status, error_str)
|
||||
if handle._mux is not None and not handle._mux._events._closed:
|
||||
try:
|
||||
await handle._mux.afail(err)
|
||||
except Exception:
|
||||
_logger.warning(
|
||||
"Error failing subgraph mini-mux at %s; "
|
||||
"subscribers may not see the terminal error.",
|
||||
handle.path,
|
||||
exc_info=True,
|
||||
)
|
||||
|
||||
|
||||
class CheckpointsTransformer(StreamTransformer):
|
||||
"""Capture checkpoint events as a drainable stream.
|
||||
|
||||
Surfaces `stream_mode="checkpoints"` data on `run.checkpoints` as
|
||||
a `StreamChannel[dict[str, Any]]`. Each item is in the same format
|
||||
as returned by `get_state()`.
|
||||
|
||||
Checkpoint events are only emitted when a checkpointer is configured
|
||||
on the graph. When no checkpointer is present, the projection exists
|
||||
but receives no events.
|
||||
|
||||
Only events at the run's own scope are captured; checkpoint data from
|
||||
deeper subgraphs is available on the respective subgraph handle's
|
||||
`.checkpoints` projection.
|
||||
|
||||
Native transformer — `run.checkpoints` is a direct attribute.
|
||||
"""
|
||||
|
||||
_native = True
|
||||
required_stream_modes = ("checkpoints",)
|
||||
|
||||
def __init__(self, scope: tuple[str, ...] = ()) -> None:
|
||||
super().__init__(scope)
|
||||
self._log: StreamChannel[dict[str, Any]] = StreamChannel()
|
||||
self._scope_list: list[str] = list(scope)
|
||||
|
||||
def init(self) -> dict[str, Any]:
|
||||
return {"checkpoints": self._log}
|
||||
|
||||
def process(self, event: ProtocolEvent) -> bool:
|
||||
if event["method"] != "checkpoints":
|
||||
return True
|
||||
params = event["params"]
|
||||
if params["namespace"] != self._scope_list:
|
||||
return True
|
||||
self._log.push(params["data"])
|
||||
return True
|
||||
|
||||
|
||||
class DebugTransformer(StreamTransformer):
|
||||
"""Capture debug events as a drainable stream.
|
||||
|
||||
Surfaces `stream_mode="debug"` data on `run.debug` as a
|
||||
`StreamChannel[dict[str, Any]]`. Each item is a debug event with
|
||||
step-level detail (checkpoint snapshots, task payloads, and
|
||||
task results wrapped with step number and timestamp).
|
||||
|
||||
Only events at the run's own scope are captured; debug data from
|
||||
deeper subgraphs is available on the respective subgraph handle's
|
||||
`.debug` projection.
|
||||
|
||||
Native transformer — `run.debug` is a direct attribute.
|
||||
"""
|
||||
|
||||
_native = True
|
||||
required_stream_modes = ("debug",)
|
||||
|
||||
def __init__(self, scope: tuple[str, ...] = ()) -> None:
|
||||
super().__init__(scope)
|
||||
self._log: StreamChannel[dict[str, Any]] = StreamChannel()
|
||||
self._scope_list: list[str] = list(scope)
|
||||
|
||||
def init(self) -> dict[str, Any]:
|
||||
return {"debug": self._log}
|
||||
|
||||
def process(self, event: ProtocolEvent) -> bool:
|
||||
if event["method"] != "debug":
|
||||
return True
|
||||
params = event["params"]
|
||||
if params["namespace"] != self._scope_list:
|
||||
return True
|
||||
self._log.push(params["data"])
|
||||
return True
|
||||
|
||||
|
||||
class TasksTransformer(StreamTransformer):
|
||||
"""Capture raw task events as a drainable stream.
|
||||
|
||||
Surfaces `stream_mode="tasks"` data on `run.tasks` as a
|
||||
`StreamChannel[dict[str, Any]]`. Each item is a task payload
|
||||
(start or result).
|
||||
|
||||
`LifecycleTransformer` and `SubgraphTransformer` also consume
|
||||
`tasks` events for subgraph discovery and lifecycle tracking.
|
||||
This transformer captures the raw payloads independently for
|
||||
consumers who need task-level detail.
|
||||
|
||||
Only events at the run's own scope are captured; task data from
|
||||
deeper subgraphs is available on the respective subgraph handle's
|
||||
`.tasks` projection.
|
||||
|
||||
Native transformer — `run.tasks` is a direct attribute.
|
||||
"""
|
||||
|
||||
_native = True
|
||||
required_stream_modes = ("tasks",)
|
||||
|
||||
def __init__(self, scope: tuple[str, ...] = ()) -> None:
|
||||
super().__init__(scope)
|
||||
self._log: StreamChannel[dict[str, Any]] = StreamChannel()
|
||||
self._scope_list: list[str] = list(scope)
|
||||
|
||||
def init(self) -> dict[str, Any]:
|
||||
return {"tasks": self._log}
|
||||
|
||||
def process(self, event: ProtocolEvent) -> bool:
|
||||
if event["method"] != "tasks":
|
||||
return True
|
||||
params = event["params"]
|
||||
if params["namespace"] != self._scope_list:
|
||||
return True
|
||||
self._log.push(params["data"])
|
||||
return True
|
||||
Reference in New Issue
Block a user