Source code for langchain_core.runnables.schema

"""模块包含与可运行项一起使用的typedef。"""
from __future__ import annotations

from typing import Any, Dict, List

from typing_extensions import NotRequired, TypedDict


class EventData(TypedDict, total=False):
    """与流事件相关的数据。"""

    input: Any
    """传递给生成事件的可运行对象的输入。

有时输入将在可运行对象的*开始*处可用，有时在可运行对象的*结束*处可用。

如果可运行对象能够流式传输其输入，那么根据定义，在可运行对象完成流式传输其输入时，其输入直到可运行对象的*结束*时才会被知晓。"""
    output: Any
    """生成事件的可运行对象的输出。

输出只会在可运行对象的*结束*时可用。

对于大多数可运行对象，可以从`chunk`字段中推断出这个字段，尽管对于一些特殊情况的可运行对象（例如聊天模型）可能会返回更多信息。"""
    chunk: Any
    """生成事件的输出流块。

流块通常支持加法操作，将它们相加应该得到生成事件的可运行对象的输出。"""


class StreamEvent(TypedDict):
    """流式事件。

从astream_events方法产生的流式事件的模式。

示例：

    .. code-block:: python

        from langchain_core.runnables import RunnableLambda

        async def reverse(s: str) -> str:
            return s[::-1]

        chain = RunnableLambda(func=reverse)

        events = [event async for event in chain.astream_events("hello")]

        # 将产生以下事件（为简洁起见，省略了run_id）：
        [
            {
                "data": {"input": "hello"},
                "event": "on_chain_start",
                "metadata": {},
                "name": "reverse",
                "tags": [],
            },
            {
                "data": {"chunk": "olleh"},
                "event": "on_chain_stream",
                "metadata": {},
                "name": "reverse",
                "tags": [],
            },
            {
                "data": {"output": "olleh"},
                "event": "on_chain_end",
                "metadata": {},
                "name": "reverse",
                "tags": [],
            },
        ]
"""

    event: str
    """事件名称的格式为：on_[runnable_type]_(start|stream|end)。

可运行类型包括：
* llm - 非聊天模型使用
* chat_model - 聊天模型使用
* prompt -- 例如，ChatPromptTemplate
* tool -- 通过@tool装饰器定义或从Tool/BaseTool继承的工具
* chain - 大多数可运行类型都是这种类型

此外，事件被归类为以下之一：
* start - 可运行开始时
* stream - 可运行正在流式传输时
* end - 可运行结束时

start、stream和end与略有不同的`data`负载相关联。

请参阅`EventData`的文档以获取更多详细信息。"""
    name: str
    """生成事件的可运行对象的名称。"""
    run_id: str
    """一个随机生成的ID，用于跟踪给定可运行对象的执行情况。

每个作为父可运行对象执行的一部分而被调用的子可运行对象都被分配了自己独特的ID。"""
    tags: NotRequired[List[str]]
    """与生成此事件的可运行程序相关联的标签。

标签始终从父可运行程序继承。

标签可以通过使用`.with_config({"tags": ["hello"]})`将其绑定到可运行程序，也可以在运行时使用`.astream_events(..., {"tags": ["hello"]})`传递。"""
    metadata: NotRequired[Dict[str, Any]]
    """与生成此事件的可运行程序相关的元数据。

元数据可以通过使用`.with_config({"metadata": { "foo": "bar" }})`将其绑定到可运行程序，
也可以在运行时使用`.astream_events(..., {"metadata": {"foo": "bar"}})`传递。"""
    data: EventData
    """事件数据。

    事件数据的内容取决于事件类型。"""