agentengine-sdk-python 0.7.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

ksadk/events/parser.py

@@ -0,0 +1,191 @@
+"""共享 RuntimeEvent → transcript parser (goal-12,H2 §3.2 P1-N)。
+
+**单实现**:live 增量渲染与 replay 历史回放**共用同一个 parser**,从根上杜绝"两个仓/
+两条路各实现一遍导致的行为漂移"(H2 高风险:历史 replay 行为漂移)。
+
+parser 把一串 :class:`RuntimeEvent` 折叠成**确定性** transcript(按事件顺序的 item 列表
++ run 状态),``to_json`` 输出逐字节稳定(json sort_keys + 有序 item),供 conformance
+fixture 断言 live 渲染与 replay 渲染**逐字节一致**。
+
+设计要点:
+
+- text/reasoning:按 ``(invocation_id, phase)`` 分组累积 delta,``completed`` 收尾。
+- tool.call:``begin`` 开工、``end`` 收尾(同名 call_id 配对)。
+- artifact:``created``/``updated`` 按 name 登记/更新版本。
+- run.*:按 invocation 记录最新 run 状态。
+- checkpoint/usage/a2ui/a2a:记为带类型的附加项(保序,不丢事件)。
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ksadk.events.runtime_event import EventType, RuntimeEvent
+
+#: parser 消费的渲染族(其余事件类型记为 generic 附加项,不丢)。
+_TEXT_TYPES = frozenset({EventType.TEXT_DELTA, EventType.TEXT_COMPLETED})
+_REASONING_TYPES = frozenset({EventType.REASONING_DELTA, EventType.REASONING_COMPLETED})
+_RUN_TYPES = frozenset(
+    {
+        EventType.RUN_STARTED,
+        EventType.RUN_PROGRESS,
+        EventType.RUN_INTERRUPTED,
+        EventType.RUN_COMPLETED,
+        EventType.RUN_FAILED,
+        EventType.RUN_CANCELED,
+    }
+)
+
+
+class RuntimeEventParser:
+    """RuntimeEvent → 确定性 transcript 的共享 parser(live/replay 单实现)。"""
+
+    def __init__(self) -> None:
+        # (invocation_id, phase) -> {"text": str, "final": bool}
+        self._text: dict[tuple[str, str], dict[str, Any]] = {}
+        self._reasoning: dict[tuple[str, str], dict[str, Any]] = {}
+        # call_id -> {"name","detail","done"}
+        self._tool_calls: dict[str, dict[str, Any]] = {}
+        # name -> {"version","text"}
+        self._artifacts: dict[str, dict[str, Any]] = {}
+        # invocation_id -> 最新 run 状态字符串
+        self._run_status: dict[str, str] = {}
+        # 渲染顺序:text/reasoning/tool/artifact 首次出现的键
+        self._order: list[tuple[str, Any]] = []
+        # 其他事件(checkpoint/usage/a2ui/a2a)保序附加
+        self._extras: list[dict[str, Any]] = []
+
+    # ---- 增量喂事件(live 与 replay 同一条路径) ----
+
+    def feed(self, event: RuntimeEvent) -> None:
+        et = event.event_type
+        if et in _TEXT_TYPES:
+            self._feed_text(self._text, "text", event, final=(et == EventType.TEXT_COMPLETED))
+        elif et in _REASONING_TYPES:
+            self._feed_text(
+                self._reasoning, "reasoning", event, final=(et == EventType.REASONING_COMPLETED)
+            )
+        elif et == EventType.TOOL_CALL_BEGIN:
+            call_id = str(event.payload.get("call_id") or "")
+            if call_id:
+                self._tool_calls[call_id] = {
+                    "name": event.payload.get("name", ""),
+                    "detail": event.payload.get("detail") or {},
+                    "done": False,
+                    "invocation_id": event.invocation_id,
+                }
+                self._order.append(("tool_call", call_id))
+        elif et == EventType.TOOL_CALL_END:
+            call_id = str(event.payload.get("call_id") or "")
+            if call_id and call_id in self._tool_calls:
+                self._tool_calls[call_id]["done"] = True
+                self._tool_calls[call_id]["result"] = event.payload.get("result")
+        elif et in (EventType.ARTIFACT_CREATED, EventType.ARTIFACT_UPDATED):
+            name = str(event.payload.get("name") or "artifact")
+            prev = self._artifacts.get(name, {"version": 0})
+            if name not in self._artifacts:
+                self._order.append(("artifact", name))
+            self._artifacts[name] = {
+                "version": int(event.payload.get("version") or prev["version"] + 1),
+                "text": str(event.payload.get("text") or ""),
+                "invocation_id": event.invocation_id,
+            }
+        elif et in _RUN_TYPES:
+            status = str(event.payload.get("status") or et)
+            self._run_status[event.invocation_id] = status
+        else:
+            # checkpoint/usage/a2ui/a2a 等:保序附加,不丢事件。
+            self._extras.append(
+                {
+                    "event_type": et,
+                    "invocation_id": event.invocation_id,
+                    "payload": event.payload,
+                }
+            )
+
+    def _feed_text(
+        self,
+        bucket: dict[tuple[str, str], dict[str, Any]],
+        kind: str,
+        event: RuntimeEvent,
+        *,
+        final: bool,
+    ) -> None:
+        key = (event.invocation_id, str(event.phase or "commentary"))
+        entry = bucket.setdefault(key, {"text": "", "final": False})
+        if (
+            len(bucket) == 1
+            and entry["text"] == ""
+            and not any(k == (kind, key) for k in self._order)
+        ):
+            self._order.append((kind, key))
+        entry["text"] += str(event.payload.get("text") or "")
+        if final:
+            entry["final"] = True
+
+    # ---- 投影 ----
+
+    def transcript(self) -> dict[str, Any]:
+        """折叠为确定性 transcript(dict;``to_json`` 逐字节稳定)。"""
+        items: list[dict[str, Any]] = []
+        for kind, key in self._order:
+            if kind == "text":
+                entry = self._text.get(key, {"text": "", "final": False})
+                items.append(
+                    {
+                        "kind": "text",
+                        "invocation_id": key[0],
+                        "phase": key[1],
+                        "text": entry["text"],
+                        "final": entry["final"],
+                    }
+                )
+            elif kind == "reasoning":
+                entry = self._reasoning.get(key, {"text": "", "final": False})
+                items.append(
+                    {
+                        "kind": "reasoning",
+                        "invocation_id": key[0],
+                        "phase": key[1],
+                        "text": entry["text"],
+                        "final": entry["final"],
+                    }
+                )
+            elif kind == "tool_call":
+                call = self._tool_calls.get(key, {})
+                items.append(
+                    {
+                        "kind": "tool_call",
+                        "call_id": key,
+                        "name": call.get("name", ""),
+                        "done": call.get("done", False),
+                        "result": call.get("result"),
+                        "invocation_id": call.get("invocation_id"),
+                    }
+                )
+            elif kind == "artifact":
+                art = self._artifacts.get(key, {})
+                items.append(
+                    {
+                        "kind": "artifact",
+                        "name": key,
+                        "version": art.get("version", 1),
+                        "text": art.get("text", ""),
+                        "invocation_id": art.get("invocation_id"),
+                    }
+                )
+        return {
+            "items": items,
+            "run_status": {k: self._run_status[k] for k in sorted(self._run_status)},
+            "extras": self._extras,
+        }
+
+    def to_json(self) -> str:
+        """确定性 JSON 序列化(sort_keys + 紧凑分隔符),供 conformance 逐字节比对。"""
+        return json.dumps(
+            self.transcript(), ensure_ascii=False, sort_keys=True, separators=(",", ":")
+        )
+
+
+__all__ = ["RuntimeEventParser"]

ksadk/events/replay.py

@@ -0,0 +1,37 @@
+"""历史 replay — 基于 session 级 cursor 的跨 invocation 回放 (goal-12)。
+
+replay 与 live 渲染**共用** :class:`~ksadk.events.parser.RuntimeEventParser`(单实现),
+回放只是"从 store 按 cursor 读事件、喂同一个 parser"。因此 live 与 replay 不可能漂移
+(H2 高风险项),由 conformance fixture 逐字节断言兜底。
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ksadk.events.parser import RuntimeEventParser
+from ksadk.events.store import RuntimeEventStore
+
+
+async def replay_transcript(
+    store: RuntimeEventStore,
+    session_id: str,
+    *,
+    after_seq_id: int = 0,
+    before_seq_id: Optional[int] = None,
+    parser: Optional[RuntimeEventParser] = None,
+) -> RuntimeEventParser:
+    """跨 invocation 历史回放:按 session cursor 读事件,经共享 parser 折叠成 transcript。
+
+    与 live 渲染同一条 parser 路径——live 是"事件边来边 feed",replay 是"从 store 读完
+    再 feed 同一个 parser",产物逐字节一致(conformance fixture 证明)。
+    """
+    parser = parser or RuntimeEventParser()
+    events = await store.list(session_id, after_seq_id=after_seq_id, before_seq_id=before_seq_id)
+    for event in events:
+        event.validate_conformance()
+        parser.feed(event)
+    return parser
+
+
+__all__ = ["replay_transcript"]

ksadk/events/runtime_event.py

@@ -0,0 +1,264 @@
+"""RuntimeEvent v1 schema (goal-02 / G0.2 冻结稿)。
+
+事件只定义一次:Runtime 产生 → server 持久化 → gateway 透传 → UI/协议 adapter 消费。
+本模块只负责**定义层**(类型 + 序列化/反序列化 + 事件族清单);不改 runtime.py 发事件
+(那是后续阶段)。
+
+设计约束(友商证伪,G0.2 冻结):
+
+- **additive + ``SCHEMA_VERSION``**:只增字段/事件类型,不改既有字段语义。
+- **相位字段** ``phase``:区分 ``commentary``(过程解说)vs ``final_answer``(最终答案),
+  仅 text/reasoning 类事件使用。
+- **工具审批一等事件**(``approval.*``),不是普通 text;审批回包走独立命令/恢复通道,
+  事件流上的 ``approval.resolved`` 仅作回放/审计(非 duplex stream)。
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from enum import Enum
+from typing import Any, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+#: additive 演进锚点。冻结为 1;只增不改。
+SCHEMA_VERSION: Literal[1] = 1
+
+
+class EventPhase(str, Enum):
+    """相位:text/reasoning 类事件区分过程解说与最终答案。"""
+
+    COMMENTARY = "commentary"
+    FINAL_ANSWER = "final_answer"
+
+
+# ---------------------------------------------------------------------------
+# 事件族(event_type 常量,v1 冻结)。新增事件类型只能 additive 追加。
+# ---------------------------------------------------------------------------
+
+
+class EventType:
+    """v1 事件族清单(冻结)。按族分组;每族注释标明 payload 关键字段。"""
+
+    # text(相位:commentary/final_answer)。payload: text, message_id
+    TEXT_DELTA = "text.delta"
+    TEXT_COMPLETED = "text.completed"
+    # reasoning(相位恒 commentary)。payload: text, summary
+    REASONING_DELTA = "reasoning.delta"
+    REASONING_COMPLETED = "reasoning.completed"
+    # tool。begin: call_id, name, args;end: call_id, name, result, error, duration_ms
+    TOOL_CALL_BEGIN = "tool.call.begin"
+    TOOL_CALL_END = "tool.call.end"
+    # artifact。payload: name, version, uri, mime
+    ARTIFACT_CREATED = "artifact.created"
+    ARTIFACT_UPDATED = "artifact.updated"
+    # approval(一等)。requested: approval_id, call_id, kind, detail;
+    # resolved: approval_id, call_id, decision(回放/审计)
+    APPROVAL_REQUESTED = "approval.requested"
+    APPROVAL_RESOLVED = "approval.resolved"
+    # run 生命周期。payload: status;progress?: progress;failed: error;canceled: cancel_result
+    RUN_STARTED = "run.started"
+    RUN_PROGRESS = "run.progress"
+    RUN_INTERRUPTED = "run.interrupted"
+    RUN_COMPLETED = "run.completed"
+    RUN_FAILED = "run.failed"
+    RUN_CANCELED = "run.canceled"
+    # checkpoint。payload: checkpoint_id, granularity(delta|snapshot), resume_target?
+    CHECKPOINT_CREATED = "checkpoint.created"
+    CHECKPOINT_RESUMED = "checkpoint.resumed"
+    # usage。payload: input_tokens, output_tokens, total_tokens, cached_tokens, reasoning_tokens
+    USAGE_REPORTED = "usage.reported"
+    # A2UI。payload: surface_id, block_id?, catalog?, data?
+    A2UI_SURFACE_BEGIN = "a2ui.surface.begin"
+    A2UI_SURFACE_UPDATE = "a2ui.surface.update"
+    A2UI_SURFACE_END = "a2ui.surface.end"
+    A2UI_INTERACTION = "a2ui.interaction"
+    A2UI_ACTION = "a2ui.action"
+    # remote A2A。payload: task_id, origin(remote agent url/space), status?, artifact?
+    A2A_TASK_CREATED = "a2a.task.created"
+    A2A_TASK_STATUS = "a2a.task.status"
+    A2A_TASK_ARTIFACT = "a2a.task.artifact"
+
+
+#: 全部 v1 事件类型(供校验/枚举)。
+ALL_EVENT_TYPES: frozenset[str] = frozenset(
+    {
+        EventType.TEXT_DELTA,
+        EventType.TEXT_COMPLETED,
+        EventType.REASONING_DELTA,
+        EventType.REASONING_COMPLETED,
+        EventType.TOOL_CALL_BEGIN,
+        EventType.TOOL_CALL_END,
+        EventType.ARTIFACT_CREATED,
+        EventType.ARTIFACT_UPDATED,
+        EventType.APPROVAL_REQUESTED,
+        EventType.APPROVAL_RESOLVED,
+        EventType.RUN_STARTED,
+        EventType.RUN_PROGRESS,
+        EventType.RUN_INTERRUPTED,
+        EventType.RUN_COMPLETED,
+        EventType.RUN_FAILED,
+        EventType.RUN_CANCELED,
+        EventType.CHECKPOINT_CREATED,
+        EventType.CHECKPOINT_RESUMED,
+        EventType.USAGE_REPORTED,
+        EventType.A2UI_SURFACE_BEGIN,
+        EventType.A2UI_SURFACE_UPDATE,
+        EventType.A2UI_SURFACE_END,
+        EventType.A2UI_INTERACTION,
+        EventType.A2UI_ACTION,
+        EventType.A2A_TASK_CREATED,
+        EventType.A2A_TASK_STATUS,
+        EventType.A2A_TASK_ARTIFACT,
+    }
+)
+
+#: 各 event_type 的 payload 必填键(conformance 用;additive —— 只允许增键)。
+#: 信封字段是硬冻结;payload 必填键是 v1 最低契约,后续版本只能加可选键。
+EVENT_PAYLOAD_REQUIRED_KEYS: dict[str, frozenset[str]] = {
+    EventType.TEXT_DELTA: frozenset({"text"}),
+    EventType.TEXT_COMPLETED: frozenset({"text"}),
+    EventType.REASONING_DELTA: frozenset({"text"}),
+    EventType.REASONING_COMPLETED: frozenset({"text"}),
+    EventType.TOOL_CALL_BEGIN: frozenset({"call_id", "name"}),
+    EventType.TOOL_CALL_END: frozenset({"call_id", "name"}),
+    EventType.ARTIFACT_CREATED: frozenset({"name", "version"}),
+    EventType.ARTIFACT_UPDATED: frozenset({"name", "version"}),
+    EventType.APPROVAL_REQUESTED: frozenset({"approval_id", "call_id", "kind"}),
+    EventType.APPROVAL_RESOLVED: frozenset({"approval_id", "call_id", "decision"}),
+    EventType.RUN_STARTED: frozenset({"status"}),
+    EventType.RUN_PROGRESS: frozenset({"status"}),
+    EventType.RUN_INTERRUPTED: frozenset({"status"}),
+    EventType.RUN_COMPLETED: frozenset({"status"}),
+    EventType.RUN_FAILED: frozenset({"status", "error"}),
+    EventType.RUN_CANCELED: frozenset({"status"}),
+    EventType.CHECKPOINT_CREATED: frozenset({"checkpoint_id", "granularity"}),
+    EventType.CHECKPOINT_RESUMED: frozenset({"checkpoint_id"}),
+    EventType.USAGE_REPORTED: frozenset({"input_tokens", "output_tokens", "total_tokens"}),
+    EventType.A2UI_SURFACE_BEGIN: frozenset({"surface_id"}),
+    EventType.A2UI_SURFACE_UPDATE: frozenset({"surface_id"}),
+    EventType.A2UI_SURFACE_END: frozenset({"surface_id"}),
+    EventType.A2UI_INTERACTION: frozenset({"surface_id"}),
+    EventType.A2UI_ACTION: frozenset({"surface_id"}),
+    EventType.A2A_TASK_CREATED: frozenset({"task_id", "origin"}),
+    EventType.A2A_TASK_STATUS: frozenset({"task_id", "origin", "status"}),
+    EventType.A2A_TASK_ARTIFACT: frozenset({"task_id", "origin"}),
+}
+
+#: 仅 text/reasoning 类事件使用相位字段。
+_PHASE_AWARE_TYPES: frozenset[str] = frozenset(
+    {
+        EventType.TEXT_DELTA,
+        EventType.TEXT_COMPLETED,
+        EventType.REASONING_DELTA,
+        EventType.REASONING_COMPLETED,
+    }
+)
+
+
+class RuntimeEvent(BaseModel):
+    """RuntimeEvent v1 信封。
+
+    字段全部硬冻结(additive 演进只允许新增可选字段)。``payload`` 按 event_type
+    承载,最低必填键见 :data:`EVENT_PAYLOAD_REQUIRED_KEYS`。
+    """
+
+    schema_version: Literal[1] = SCHEMA_VERSION
+    event_id: str
+    event_type: str
+    timestamp: float
+    agent_id: str
+    user_id: str
+    session_id: str
+    invocation_id: str
+    seq_id: int
+    phase: Optional[Literal["commentary", "final_answer"]] = None
+    payload: dict[str, Any] = Field(default_factory=dict)
+
+    # ---- 构造 ----
+
+    @classmethod
+    def create(
+        cls,
+        event_type: str,
+        *,
+        agent_id: str,
+        user_id: str,
+        session_id: str,
+        invocation_id: str,
+        seq_id: int,
+        payload: Optional[dict[str, Any]] = None,
+        phase: Optional[str] = None,
+        event_id: Optional[str] = None,
+        timestamp: Optional[float] = None,
+    ) -> "RuntimeEvent":
+        """便捷构造:自动补 event_id / timestamp,并按 event_type 校验相位与 payload。"""
+        event = cls(
+            event_id=event_id or f"evt_{uuid.uuid4().hex}",
+            event_type=event_type,
+            timestamp=time.time() if timestamp is None else timestamp,
+            agent_id=agent_id,
+            user_id=user_id,
+            session_id=session_id,
+            invocation_id=invocation_id,
+            seq_id=seq_id,
+            phase=phase,  # type: ignore[arg-type]
+            payload=payload or {},
+        )
+        event.validate_conformance()
+        return event
+
+    # ---- 序列化 ----
+
+    def to_dict(self) -> dict[str, Any]:
+        """序列化为 dict(含全部信封字段 + payload)。"""
+        return self.model_dump(mode="json", exclude_none=True)
+
+    def to_json(self) -> str:
+        """序列化为 JSON 字符串。"""
+        return self.model_dump_json(exclude_none=True)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "RuntimeEvent":
+        """从 dict 反序列化。与 :meth:`create` 一致过 conformance:
+        未知 event_type / 相位滥用 / 缺必填键抛 ``ValueError``,不得混入系统。"""
+        event = cls.model_validate(data)
+        event.validate_conformance()
+        return event
+
+    @classmethod
+    def from_json(cls, raw: str) -> "RuntimeEvent":
+        """从 JSON 字符串反序列化(同 :meth:`from_dict` 过 conformance)。"""
+        event = cls.model_validate_json(raw)
+        event.validate_conformance()
+        return event
+
+    # ---- conformance ----
+
+    def validate_conformance(self) -> None:
+        """按 v1 契约校验:事件类型已知、相位仅用于 text/reasoning、payload 必填键齐全。
+
+        additive 演进:允许 payload 含额外键(不作 strict 拒绝),只校验最低必填键。
+        未知 event_type / 缺必填键 / 相位滥用抛 :class:`ValueError`。
+        """
+        if self.event_type not in ALL_EVENT_TYPES:
+            raise ValueError(f"unknown event_type: {self.event_type!r}(v1 事件族之外)")
+        if self.phase is not None and self.event_type not in _PHASE_AWARE_TYPES:
+            raise ValueError(
+                f"phase 仅用于 text/reasoning 事件,{self.event_type!r} 不应带 phase={self.phase!r}"
+            )
+        required = EVENT_PAYLOAD_REQUIRED_KEYS.get(self.event_type, frozenset())
+        missing = required - set(self.payload.keys())
+        if missing:
+            raise ValueError(f"event_type {self.event_type!r} payload 缺必填键: {sorted(missing)}")
+
+
+__all__ = [
+    "ALL_EVENT_TYPES",
+    "EVENT_PAYLOAD_REQUIRED_KEYS",
+    "EventPhase",
+    "EventType",
+    "RuntimeEvent",
+    "SCHEMA_VERSION",
+]