codekingpro/portable-devtools

1"""Module contains typedefs that are used with `Runnable` objects."""2 3from __future__ import annotations4 5from typing import TYPE_CHECKING, Any, Literal6 7from typing_extensions import NotRequired, TypedDict8 9if TYPE_CHECKING:10    from collections.abc import Sequence11 12 13class EventData(TypedDict, total=False):14    """Data associated with a streaming event."""15 16    input: Any17    """The input passed to the `Runnable` that generated the event.18 19    Inputs will sometimes be available at the *START* of the `Runnable`, and20    sometimes at the *END* of the `Runnable`.21 22    If a `Runnable` is able to stream its inputs, then its input by definition23    won't be known until the *END* of the `Runnable` when it has finished streaming24    its inputs.25    """26    error: NotRequired[BaseException]27    """The error that occurred during the execution of the `Runnable`.28 29    This field is only available if the `Runnable` raised an exception.30 31    !!! version-added "Added in `langchain-core` 1.0.0"32    """33    output: Any34    """The output of the `Runnable` that generated the event.35 36    Outputs will only be available at the *END* of the `Runnable`.37 38    For most `Runnable` objects, this field can be inferred from the `chunk` field,39    though there might be some exceptions for special a cased `Runnable` (e.g., like40    chat models), which may return more information.41    """42    chunk: Any43    """A streaming chunk from the output that generated the event.44 45    chunks support addition in general, and adding them up should result46    in the output of the `Runnable` that generated the event.47    """48    tool_call_id: NotRequired[str | None]49    """The tool call ID associated with the tool execution.50 51    This field is available for the `on_tool_error` event and can be used to52    link errors to specific tool calls in stateless agent implementations.53    """54 55 56class BaseStreamEvent(TypedDict):57    """Streaming event.58 59    Schema of a streaming event which is produced from the `astream_events` method.60 61    Example:62        ```python63        from langchain_core.runnables import RunnableLambda64 65 66        async def reverse(s: str) -> str:67            return s[::-1]68 69 70        chain = RunnableLambda(func=reverse)71 72        events = [event async for event in chain.astream_events("hello")]73 74        # Will produce the following events75        # (where some fields have been omitted for brevity):76        [77            {78                "data": {"input": "hello"},79                "event": "on_chain_start",80                "metadata": {},81                "name": "reverse",82                "tags": [],83            },84            {85                "data": {"chunk": "olleh"},86                "event": "on_chain_stream",87                "metadata": {},88                "name": "reverse",89                "tags": [],90            },91            {92                "data": {"output": "olleh"},93                "event": "on_chain_end",94                "metadata": {},95                "name": "reverse",96                "tags": [],97            },98        ]99        ```100    """101 102    event: str103    """Event names are of the format: `on_[runnable_type]_(start|stream|end)`.104 105    Runnable types are one of:106 107    - **llm** - used by non chat models108    - **chat_model** - used by chat models109    - **prompt** --  e.g., `ChatPromptTemplate`110    - **tool** -- from tools defined via `@tool` decorator or inheriting111        from `Tool`/`BaseTool`112    - **chain** - most `Runnable` objects are of this type113 114    Further, the events are categorized as one of:115 116    - **start** - when the `Runnable` starts117    - **stream** - when the `Runnable` is streaming118    - **end* - when the `Runnable` ends119 120    start, stream and end are associated with slightly different `data` payload.121 122    Please see the documentation for `EventData` for more details.123    """124    run_id: str125    """An randomly generated ID to keep track of the execution of the given `Runnable`.126 127    Each child `Runnable` that gets invoked as part of the execution of a parent128    `Runnable` is assigned its own unique ID.129    """130    tags: NotRequired[list[str]]131    """Tags associated with the `Runnable` that generated this event.132 133    Tags are always inherited from parent `Runnable` objects.134 135    Tags can either be bound to a `Runnable` using `.with_config({"tags":  ["hello"]})`136    or passed at run time using `.astream_events(..., {"tags": ["hello"]})`.137    """138    metadata: NotRequired[dict[str, Any]]139    """Metadata associated with the `Runnable` that generated this event.140 141    Metadata can either be bound to a `Runnable` using142 143        `.with_config({"metadata": { "foo": "bar" }})`144 145    or passed at run time using146 147        `.astream_events(..., {"metadata": {"foo": "bar"}})`.148    """149 150    parent_ids: Sequence[str]151    """A list of the parent IDs associated with this event.152 153    Root Events will have an empty list.154 155    For example, if a `Runnable` A calls `Runnable` B, then the event generated by156    `Runnable` B will have `Runnable` A's ID in the `parent_ids` field.157 158    The order of the parent IDs is from the root parent to the immediate parent.159 160    Only supported as of v2 of the astream events API. v1 will return an empty list.161    """162 163 164class StandardStreamEvent(BaseStreamEvent):165    """A standard stream event that follows LangChain convention for event data."""166 167    data: EventData168    """Event data.169 170    The contents of the event data depend on the event type.171    """172    name: str173    """The name of the `Runnable` that generated the event."""174 175 176class CustomStreamEvent(BaseStreamEvent):177    """Custom stream event created by the user."""178 179    # Overwrite the event field to be more specific.180    event: Literal["on_custom_event"]  # type: ignore[misc]181    """The event type."""182    name: str183    """User defined name for the event."""184    data: Any185    """The data associated with the event. Free form and can be anything."""186 187 188StreamEvent = StandardStreamEvent | CustomStreamEvent189