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

ksadk/evaluation/studio_build_adapter.py

@@ -0,0 +1,253 @@
+"""Evaluation adapter for immutable Studio Build artifacts."""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from ksadk.events.canonical import RuntimeEvent, parse_runtime_event
+
+from .adapters import TargetAdapterError
+from .contracts import (
+    EvalCase,
+    EvalRunSpec,
+    TargetKind,
+    TargetRef,
+    TargetRun,
+    TargetRunStatus,
+    TargetSnapshot,
+    ToolCallEvidence,
+    TraceRef,
+    UsageSnapshot,
+)
+from .evidence import EvidenceStore, project_tool_calls
+
+
+class _StudioRunService(Protocol):
+    event_store: Any
+
+    async def run(
+        self,
+        spec: Any,
+        user_input: str,
+        *,
+        session_id: str,
+        on_event: Any = None,
+    ) -> Any: ...
+
+    async def events(self, run_id: str, *, after: int = 0) -> list[Any]: ...
+
+
+@dataclass(frozen=True)
+class StudioBuildResolution:
+    """Frozen Studio-owned build identity and executable run specification."""
+
+    build_id: str
+    agent_id: str
+    revision_digest: str
+    runtime: str
+    model: str | None
+    run_spec: Any
+    metadata: dict[str, Any]
+
+
+class StudioBuildTargetError(TargetAdapterError):
+    """Classified failure resolving or executing a Studio Build."""
+
+
+class StudioBuildTargetAdapter:
+    """Execute EvalCases through Studio's immutable Build runtime path."""
+
+    kind = TargetKind.STUDIO_BUILD
+
+    def __init__(
+        self,
+        *,
+        timeout_seconds: int,
+        resolve_build: Callable[[str], StudioBuildResolution],
+        run_service: _StudioRunService,
+        evidence_store: EvidenceStore | None = None,
+    ) -> None:
+        self._timeout_seconds = timeout_seconds
+        self._resolve_build = resolve_build
+        self._run_service = run_service
+        self._evidence_store = evidence_store
+        self._resolved: StudioBuildResolution | None = None
+        self._snapshot: TargetSnapshot | None = None
+
+    def _resolve(self, build_id: str) -> StudioBuildResolution:
+        try:
+            resolved = self._resolve_build(build_id)
+        except StudioBuildTargetError:
+            raise
+        except Exception as exc:
+            raise StudioBuildTargetError(
+                "STUDIO_BUILD_RESOLUTION_FAILED",
+                "Studio Build could not be resolved",
+            ) from exc
+        if resolved.build_id != build_id:
+            raise StudioBuildTargetError(
+                "STUDIO_BUILD_MISMATCH",
+                "Studio Build resolver returned a different immutable Build",
+            )
+        if not resolved.revision_digest or not resolved.runtime:
+            raise StudioBuildTargetError(
+                "STUDIO_BUILD_INVALID",
+                "Studio Build is missing immutable runtime identity",
+            )
+        return resolved
+
+    async def snapshot(self, target: TargetRef) -> TargetSnapshot:
+        if target.kind is not self.kind:
+            raise StudioBuildTargetError(
+                "STUDIO_BUILD_KIND_INVALID",
+                "Studio Build adapter received a non-Build target",
+            )
+        resolved = self._resolve(target.locator)
+        metadata = {
+            "buildId": resolved.build_id,
+            "agentId": resolved.agent_id,
+            **dict(resolved.metadata),
+        }
+        if resolved.model:
+            metadata["model"] = resolved.model
+        snapshot = TargetSnapshot(
+            kind=self.kind,
+            entrypoint=f"build:{resolved.build_id}",
+            revision_digest=resolved.revision_digest,
+            runtime=resolved.runtime,
+            metadata=metadata,
+        )
+        self._resolved = resolved
+        self._snapshot = snapshot
+        return snapshot
+
+    async def run_case(
+        self,
+        spec: EvalRunSpec,
+        case: EvalCase,
+        *,
+        attempt: int,
+    ) -> TargetRun:
+        resolved = self._resolved
+        snapshot = self._snapshot
+        if resolved is None or snapshot is None:
+            raise RuntimeError("Studio Build target must be snapshotted before execution")
+        if spec.target != snapshot:
+            raise RuntimeError("EvalRunSpec target does not match the Studio Build snapshot")
+
+        session_id = _scoped_id("eval-build-session", spec.id, case.id, str(attempt))
+        output = ""
+        duration_ms = 0
+        usage = UsageSnapshot()
+        trace_ref: TraceRef | None = None
+        trace_refs: list[TraceRef] = []
+        tool_calls: list[ToolCallEvidence] = []
+        for turn in case.turns:
+            record = await self._run_service.run(
+                resolved.run_spec,
+                turn.input,
+                session_id=session_id,
+            )
+            events = _runtime_events(await self._run_service.events(record.id))
+            if events:
+                tool_calls.extend(project_tool_calls(events))
+            trace_ref = _trace_ref(spec.id, record, events)
+            if self._evidence_store is not None and events:
+                persisted_ref = self._evidence_store.write_trace(
+                    spec.id,
+                    events,
+                    session_id=session_id,
+                    policy=spec.config.data_policy,
+                )
+                trace_ref = persisted_ref.model_copy(
+                    update={"trace_id": str(getattr(record, "trace_id", "") or "") or None}
+                )
+            trace_refs.append(trace_ref)
+            duration_ms += max(0, int(getattr(record, "duration_ms", 0) or 0))
+            usage = _add_usage(usage, getattr(record, "usage", None))
+            status = _status_value(getattr(record, "status", ""))
+            if status != "COMPLETED":
+                error = getattr(record, "error", None) or {}
+                return TargetRun(
+                    status=(
+                        TargetRunStatus.CANCELLED
+                        if status in {"CANCELLED", "INTERRUPTED"}
+                        else TargetRunStatus.ERROR
+                    ),
+                    duration_ms=duration_ms,
+                    usage=usage,
+                    error_code=str(error.get("code") or "STUDIO_BUILD_RUN_FAILED"),
+                    error_message="Studio Build runtime failed",
+                    trace_ref=trace_ref,
+                    trace_refs=trace_refs,
+                    tool_calls=tool_calls,
+                    metadata={"runtime": resolved.runtime, "turnCount": len(tool_calls)},
+                )
+            output = str(getattr(record, "output", "") or "")
+
+        return TargetRun(
+            status=TargetRunStatus.PASSED if output else TargetRunStatus.UNAVAILABLE,
+            output=output,
+            duration_ms=duration_ms,
+            usage=usage,
+            error_code=None if output else "STUDIO_BUILD_OUTPUT_UNAVAILABLE",
+            error_message=None if output else "Studio Build did not provide evaluable text output",
+            trace_ref=trace_ref,
+            trace_refs=trace_refs,
+            tool_calls=tool_calls,
+            metadata={"runtime": resolved.runtime, "turnCount": len(case.turns)},
+        )
+
+
+def _runtime_events(stored_events: list[Any]) -> list[RuntimeEvent]:
+    events: list[RuntimeEvent] = []
+    for stored in stored_events:
+        data = getattr(stored, "data", None)
+        payload = data.get("runtimeEvent") if isinstance(data, dict) else None
+        if not isinstance(payload, dict):
+            continue
+        try:
+            events.append(parse_runtime_event(payload))
+        except ValueError:
+            continue
+    return sorted(events, key=lambda event: event.seq)
+
+
+def _trace_ref(run_id: str, record: Any, events: list[RuntimeEvent]) -> TraceRef:
+    return TraceRef(
+        run_id=run_id,
+        trace_id=str(getattr(record, "trace_id", "") or "") or None,
+        session_id=str(getattr(record, "session_id", "") or "") or None,
+        invocation_id=str(getattr(record, "id", "") or "") or None,
+        seq_start=events[0].seq if events else None,
+        seq_end=events[-1].seq if events else None,
+    )
+
+
+def _add_usage(total: UsageSnapshot, raw: Any) -> UsageSnapshot:
+    return UsageSnapshot(
+        input_tokens=total.input_tokens + max(0, int(getattr(raw, "input_tokens", 0) or 0)),
+        output_tokens=total.output_tokens + max(0, int(getattr(raw, "output_tokens", 0) or 0)),
+        total_tokens=total.total_tokens + max(0, int(getattr(raw, "total_tokens", 0) or 0)),
+        reported=total.reported or bool(getattr(raw, "reported", False)),
+    )
+
+
+def _status_value(raw: Any) -> str:
+    value = getattr(raw, "value", raw)
+    return str(value or "").upper()
+
+
+def _scoped_id(prefix: str, *parts: str) -> str:
+    payload = "\0".join(parts).encode("utf-8")
+    return f"{prefix}-{hashlib.sha256(payload).hexdigest()[:24]}"
+
+
+__all__ = [
+    "StudioBuildResolution",
+    "StudioBuildTargetAdapter",
+    "StudioBuildTargetError",
+]

ksadk/evaluation/target.py

@@ -0,0 +1,82 @@
+"""Common target lifecycle shared by all evaluation adapters."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from .adapters import (
+    EvaluationNotImplementedError,
+    TargetAdapter,
+    TargetAdapterError,
+    create_target_adapter,
+)
+from .contracts import (
+    EvalCase,
+    EvalRunSpec,
+    EvaluationConfig,
+    TargetRef,
+    TargetRun,
+    TargetRunStatus,
+    TargetSnapshot,
+)
+
+if TYPE_CHECKING:
+    from .evidence import EvidenceStore
+
+
+class EvaluationExecutionError(RuntimeError):
+    """A classified failure from the common target execution boundary."""
+
+
+class EvaluationTarget:
+    """Own target lifecycle; protocol details stay in the selected adapter."""
+
+    def __init__(
+        self,
+        target: TargetRef,
+        config: EvaluationConfig,
+        *,
+        evidence_store: EvidenceStore | None = None,
+        adapter: TargetAdapter | None = None,
+    ) -> None:
+        self.reference = target
+        self._timeout_seconds = config.timeout_seconds
+        self._adapter: TargetAdapter = adapter or create_target_adapter(
+            target, timeout_seconds=config.timeout_seconds, evidence_store=evidence_store
+        )
+
+    async def snapshot(self) -> TargetSnapshot:
+        try:
+            return await asyncio.wait_for(
+                self._adapter.snapshot(self.reference),
+                timeout=self._timeout_seconds,
+            )
+        except TimeoutError as exc:
+            raise EvaluationExecutionError(f"{self.reference.kind.value} Target 快照超时") from exc
+        except TargetAdapterError as exc:
+            raise EvaluationExecutionError(f"{exc.code}: {exc}") from exc
+
+    async def run_case(
+        self,
+        spec: EvalRunSpec,
+        case: EvalCase,
+    ) -> TargetRun:
+        try:
+            return await asyncio.wait_for(
+                self._adapter.run_case(spec, case, attempt=spec.attempt),
+                timeout=self._timeout_seconds,
+            )
+        except TimeoutError:
+            return TargetRun(
+                status=TargetRunStatus.ERROR,
+                error_code="EVALUATION_CASE_TIMEOUT",
+                error_message=f"Case {case.id} 执行超时",
+            )
+
+
+__all__ = [
+    "EvaluationExecutionError",
+    "EvaluationNotImplementedError",
+    "EvaluationTarget",
+]

ksadk/events/__init__.py

@@ -1,25 +1,25 @@
-"""RuntimeEvent schema (goal-02)。见 :mod:`ksadk.events.runtime_event`。"""
+"""Canonical RuntimeEvent public API."""
 
-from ksadk.events.parser import RuntimeEventParser
-from ksadk.events.replay import replay_transcript
-from ksadk.events.runtime_event import (
+from ksadk.events.canonical import (
     ALL_EVENT_TYPES,
-    EVENT_PAYLOAD_REQUIRED_KEYS,
-    SCHEMA_VERSION,
     EventPhase,
-    EventType,
     RuntimeEvent,
+    dump_runtime_event,
+    parse_runtime_event,
 )
-from ksadk.events.store import RuntimeEventStore
+from ksadk.events.canonical_replay import replay_projection
+from ksadk.events.canonical_store import RuntimeEventStore
+from ksadk.events.reducer import ProjectionPatch, RunProjection, StreamReducer
 
 __all__ = [
     "ALL_EVENT_TYPES",
-    "EVENT_PAYLOAD_REQUIRED_KEYS",
     "EventPhase",
-    "EventType",
+    "ProjectionPatch",
+    "RunProjection",
     "RuntimeEvent",
-    "RuntimeEventParser",
     "RuntimeEventStore",
-    "replay_transcript",
-    "SCHEMA_VERSION",
+    "StreamReducer",
+    "dump_runtime_event",
+    "parse_runtime_event",
+    "replay_projection",
 ]

ksadk/events/_v1_compat/__init__.py

@@ -0,0 +1 @@
+"""Internal v1_compat implementation subpackage; stable API lives in ksadk.events.v1_compat."""

ksadk/events/_v1_compat/models.py

@@ -0,0 +1,299 @@
+"""v1 wire models: envelope, event-type registry, and projection context."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Literal, Mapping, TypeAlias
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ksadk.events.content import ToolCallContent
+from ksadk.events.reducer import ItemProjection, RunProjection
+
+RuntimeEventV1ProjectionMode: TypeAlias = Literal["snapshot_only", "identity_replace"]
+
+
+class V1ProjectionContextRequiredError(ValueError):
+    """Raised when a lossless v1 projection needs compat-local context."""
+
+
+@dataclass(frozen=True)
+class A2UISurfaceProjectionRef:
+    surface_id: str
+    catalog: str | None = None
+
+
+@dataclass(frozen=True)
+class A2UIInteractionProjectionRef:
+    surface_id: str
+    block_id: str | None = None
+
+
+@dataclass(frozen=True)
+class A2ATaskProjectionRef:
+    task_id: str
+    origin: str
+
+
+@dataclass(frozen=True)
+class RuntimeEventV1ProjectionContext:
+    """Ephemeral values absent from the canonical event envelope.
+
+    These values are supplied by the v1 read boundary.  Framework adapters and
+    the canonical store must not manufacture or persist them for this module.
+    """
+
+    agent_id: str
+    user_id: str
+    session_id: str
+    projection: RunProjection | None
+    a2ui_surfaces: Mapping[tuple[str, str], A2UISurfaceProjectionRef] = field(default_factory=dict)
+    a2ui_interactions: Mapping[tuple[str, str], A2UIInteractionProjectionRef] = field(
+        default_factory=dict
+    )
+    a2a_tasks: Mapping[tuple[str, str], A2ATaskProjectionRef] = field(default_factory=dict)
+    artifact_versions: Mapping[tuple[str, str, str], int] = field(default_factory=dict)
+    compaction_phase: str = "runtime"
+
+    @classmethod
+    def from_projection(
+        cls,
+        projection: RunProjection | None,
+        *,
+        agent_id: str,
+        user_id: str,
+        session_id: str,
+        a2ui_surfaces: Mapping[tuple[str, str], A2UISurfaceProjectionRef] | None = None,
+        a2ui_interactions: Mapping[tuple[str, str], A2UIInteractionProjectionRef] | None = None,
+        a2a_tasks: Mapping[tuple[str, str], A2ATaskProjectionRef] | None = None,
+        artifact_versions: Mapping[tuple[str, str, str], int] | None = None,
+        compaction_phase: str = "runtime",
+    ) -> RuntimeEventV1ProjectionContext:
+        return cls(
+            agent_id=agent_id,
+            user_id=user_id,
+            session_id=session_id,
+            projection=projection,
+            a2ui_surfaces=a2ui_surfaces or {},
+            a2ui_interactions=a2ui_interactions or {},
+            a2a_tasks=a2a_tasks or {},
+            artifact_versions=artifact_versions or {},
+            compaction_phase=compaction_phase,
+        )
+
+    def item(self, scope_id: str, item_id: str) -> ItemProjection | None:
+        if self.projection is None:
+            return None
+        return next(
+            (
+                item
+                for item in self.projection.items
+                if item.scope_id == scope_id and item.item_id == item_id
+            ),
+            None,
+        )
+
+    def tool_name(self, scope_id: str, call_id: str) -> str:
+        if self.projection is None:
+            return ""
+        for item in self.projection.items:
+            if item.scope_id != scope_id:
+                continue
+            for part in item.parts:
+                if isinstance(part, ToolCallContent) and part.call_id == call_id:
+                    return part.name
+        return ""
+
+    def interaction_call_id(self, scope_id: str, interaction_id: str) -> str:
+        if self.projection is None:
+            return ""
+        for interaction in self.projection.interactions:
+            if (
+                interaction.scope_id == scope_id
+                and interaction.interaction_id == interaction_id
+                and interaction.request.request_type == "approval"
+            ):
+                return interaction.request.call_id or ""
+        return ""
+
+    def artifact_version(self, scope_id: str, item_id: str, artifact_id: str) -> int:
+        version = self.artifact_versions.get((scope_id, item_id, artifact_id))
+        if isinstance(version, bool) or not isinstance(version, int) or version <= 0:
+            raise V1ProjectionContextRequiredError(
+                "artifact version must be an explicit positive integer"
+            )
+        return version
+
+
+class EventTypeV1:
+    TEXT_DELTA = "text.delta"
+    TEXT_COMPLETED = "text.completed"
+    REASONING_DELTA = "reasoning.delta"
+    REASONING_COMPLETED = "reasoning.completed"
+    TOOL_CALL_BEGIN = "tool.call.begin"
+    TOOL_CALL_END = "tool.call.end"
+    ARTIFACT_CREATED = "artifact.created"
+    ARTIFACT_UPDATED = "artifact.updated"
+    APPROVAL_REQUESTED = "approval.requested"
+    APPROVAL_RESOLVED = "approval.resolved"
+    RUN_STARTED = "run.started"
+    RUN_PROGRESS = "run.progress"
+    RUN_INTERRUPTED = "run.interrupted"
+    RUN_COMPLETED = "run.completed"
+    RUN_FAILED = "run.failed"
+    RUN_CANCELED = "run.canceled"
+    CONTEXT_COMPACTION_STARTED = "context.compaction.started"
+    CONTEXT_COMPACTION_COMPLETED = "context.compaction.completed"
+    CHECKPOINT_CREATED = "checkpoint.created"
+    CHECKPOINT_RESUMED = "checkpoint.resumed"
+    USAGE_REPORTED = "usage.reported"
+    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"
+    A2A_TASK_CREATED = "a2a.task.created"
+    A2A_TASK_STATUS = "a2a.task.status"
+    A2A_TASK_ARTIFACT = "a2a.task.artifact"
+
+
+ALL_V1_EVENT_TYPES = frozenset(
+    value for name, value in vars(EventTypeV1).items() if name.isupper() and isinstance(value, str)
+)
+
+V1_EVENT_PAYLOAD_REQUIRED_KEYS: dict[str, frozenset[str]] = {
+    EventTypeV1.TEXT_DELTA: frozenset({"text"}),
+    EventTypeV1.TEXT_COMPLETED: frozenset({"text"}),
+    EventTypeV1.REASONING_DELTA: frozenset({"text"}),
+    EventTypeV1.REASONING_COMPLETED: frozenset({"text"}),
+    EventTypeV1.TOOL_CALL_BEGIN: frozenset({"call_id", "name"}),
+    EventTypeV1.TOOL_CALL_END: frozenset({"call_id", "name"}),
+    EventTypeV1.ARTIFACT_CREATED: frozenset({"name", "version"}),
+    EventTypeV1.ARTIFACT_UPDATED: frozenset({"name", "version"}),
+    EventTypeV1.APPROVAL_REQUESTED: frozenset({"approval_id", "call_id", "kind"}),
+    EventTypeV1.APPROVAL_RESOLVED: frozenset({"approval_id", "call_id", "decision"}),
+    EventTypeV1.RUN_STARTED: frozenset({"status"}),
+    EventTypeV1.RUN_PROGRESS: frozenset({"status"}),
+    EventTypeV1.RUN_INTERRUPTED: frozenset({"status"}),
+    EventTypeV1.RUN_COMPLETED: frozenset({"status"}),
+    EventTypeV1.RUN_FAILED: frozenset({"status", "error"}),
+    EventTypeV1.RUN_CANCELED: frozenset({"status"}),
+    EventTypeV1.CONTEXT_COMPACTION_STARTED: frozenset({"phase", "trigger"}),
+    EventTypeV1.CONTEXT_COMPACTION_COMPLETED: frozenset(
+        {"phase", "trigger", "compacted_until_seq_id"}
+    ),
+    EventTypeV1.CHECKPOINT_CREATED: frozenset({"checkpoint_id", "granularity"}),
+    EventTypeV1.CHECKPOINT_RESUMED: frozenset({"checkpoint_id"}),
+    EventTypeV1.USAGE_REPORTED: frozenset({"input_tokens", "output_tokens", "total_tokens"}),
+    EventTypeV1.A2UI_SURFACE_BEGIN: frozenset({"surface_id"}),
+    EventTypeV1.A2UI_SURFACE_UPDATE: frozenset({"surface_id"}),
+    EventTypeV1.A2UI_SURFACE_END: frozenset({"surface_id"}),
+    EventTypeV1.A2UI_INTERACTION: frozenset({"surface_id"}),
+    EventTypeV1.A2UI_ACTION: frozenset({"surface_id"}),
+    EventTypeV1.A2A_TASK_CREATED: frozenset({"task_id", "origin"}),
+    EventTypeV1.A2A_TASK_STATUS: frozenset({"task_id", "origin", "status"}),
+    EventTypeV1.A2A_TASK_ARTIFACT: frozenset({"task_id", "origin"}),
+}
+
+_V1_PHASE_AWARE_TYPES = frozenset(
+    {
+        EventTypeV1.TEXT_DELTA,
+        EventTypeV1.TEXT_COMPLETED,
+        EventTypeV1.REASONING_DELTA,
+        EventTypeV1.REASONING_COMPLETED,
+    }
+)
+
+
+class RuntimeEventV1(BaseModel):
+    """Frozen RuntimeEvent v1 JSON envelope."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    schema_version: Literal[1] = 1
+    event_id: str
+    event_type: str
+    timestamp: float
+    agent_id: str
+    user_id: str
+    session_id: str
+    invocation_id: str
+    seq_id: int
+    phase: Literal["commentary", "final_answer"] | None = 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: dict[str, Any] | None = None,
+        phase: str | None = None,
+        event_id: str | None = None,
+        timestamp: float | None = None,
+    ) -> RuntimeEventV1:
+        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 validate_conformance(self) -> None:
+        if self.event_type not in ALL_V1_EVENT_TYPES:
+            raise ValueError(f"unknown event_type: {self.event_type!r} (v1 event family)")
+        if self.phase is not None and self.event_type not in _V1_PHASE_AWARE_TYPES:
+            raise ValueError(f"phase is only valid for v1 text/reasoning events: {self.event_type}")
+        required = V1_EVENT_PAYLOAD_REQUIRED_KEYS.get(self.event_type, frozenset())
+        missing = required - self.payload.keys()
+        if missing:
+            raise ValueError(
+                f"event_type {self.event_type!r} payload missing required keys: {sorted(missing)}"
+            )
+
+    def to_dict(self) -> dict[str, Any]:
+        return self.model_dump(mode="json", exclude_none=True)
+
+    def to_json(self) -> str:
+        return self.model_dump_json(exclude_none=True)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> RuntimeEventV1:
+        event = cls.model_validate(data)
+        event.validate_conformance()
+        return event
+
+    @classmethod
+    def from_json(cls, raw: str) -> RuntimeEventV1:
+        event = cls.model_validate_json(raw)
+        event.validate_conformance()
+        return event
+
+
+__all__ = [
+    "ALL_V1_EVENT_TYPES",
+    "A2ATaskProjectionRef",
+    "A2UIInteractionProjectionRef",
+    "A2UISurfaceProjectionRef",
+    "EventTypeV1",
+    "RuntimeEventV1",
+    "RuntimeEventV1ProjectionContext",
+    "RuntimeEventV1ProjectionMode",
+    "V1ProjectionContextRequiredError",
+    "V1_EVENT_PAYLOAD_REQUIRED_KEYS",
+]