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

ksadk/a2a/card_builder.py

@@ -1,64 +0,0 @@
-"""Helpers for building A2A agent cards."""
-
-from __future__ import annotations
-
-from collections.abc import Sequence
-
-from a2a.types import AgentCapabilities, AgentCard, AgentSkill
-
-_DEFAULT_IO_MODES = ["text/plain"]
-
-
-class AgentCardBuilder:
-    """Build an A2A AgentCard for a KsADK runner."""
-
-    def __init__(
-        self,
-        name: str,
-        url: str,
-        description: str = "",
-        skills: Sequence[str] | None = None,
-        version: str = "1.0.0",
-    ) -> None:
-        self.name = name
-        self.url = url.rstrip("/") or url
-        self.description = description or f"{name} agent powered by ksadk"
-        self.skills = list(skills or [])
-        self.version = version
-
-    def build(self) -> AgentCard:
-        """Create the final A2A agent card."""
-        return AgentCard(
-            name=self.name,
-            description=self.description,
-            url=self.url,
-            version=self.version,
-            capabilities=AgentCapabilities(
-                streaming=True,
-                push_notifications=False,
-            ),
-            default_input_modes=list(_DEFAULT_IO_MODES),
-            default_output_modes=list(_DEFAULT_IO_MODES),
-            skills=self._build_skills(),
-        )
-
-    def _build_skills(self) -> list[AgentSkill]:
-        if not self.skills:
-            return [
-                AgentSkill(
-                    id="general",
-                    name="General",
-                    description="General purpose agent powered by ksadk",
-                    tags=["general"],
-                )
-            ]
-
-        return [
-            AgentSkill(
-                id=skill,
-                name=skill.replace("_", " ").title(),
-                description=f"Skill: {skill}",
-                tags=[skill],
-            )
-            for skill in self.skills
-        ]

ksadk/a2a/client.py

@@ -1,309 +0,0 @@
-"""Client helpers for invoking remote A2A agents from KsADK code."""
-
-from __future__ import annotations
-
-from collections.abc import AsyncIterator
-from typing import Any
-from uuid import uuid4
-
-import httpx
-from a2a.client import Client, ClientConfig, ClientFactory
-from a2a.types import (
-    Message,
-    MessageSendConfiguration,
-    Part,
-    Role,
-    Task,
-    TaskArtifactUpdateEvent,
-    TaskState,
-    TaskStatusUpdateEvent,
-    TextPart,
-)
-from a2a.utils import get_artifact_text, get_message_text
-
-_FAILED_TASK_STATES = {
-    TaskState.canceled,
-    TaskState.failed,
-    TaskState.rejected,
-}
-
-
-def _build_text_message(
-    text: str,
-    *,
-    context_id: str | None = None,
-    task_id: str | None = None,
-) -> Message:
-    return Message(
-        role=Role.user,
-        parts=[Part(root=TextPart(text=text))],
-        message_id=str(uuid4()),
-        context_id=context_id,
-        task_id=task_id,
-    )
-
-
-def _task_output(task: Task) -> str:
-    outputs = []
-    for artifact in task.artifacts or []:
-        artifact_text = get_artifact_text(artifact, delimiter="")
-        if artifact_text:
-            outputs.append(artifact_text)
-    if outputs:
-        return "".join(outputs)
-
-    if task.status.message is not None:
-        return get_message_text(task.status.message)
-
-    if task.history:
-        for message in reversed(task.history):
-            if message.role == Role.agent:
-                message_text = get_message_text(message)
-                if message_text:
-                    return message_text
-
-    return ""
-
-
-def _task_error(task: Task) -> str:
-    text = _task_output(task)
-    if text:
-        return text
-    return f"Remote A2A task ended in state: {task.status.state.value}"
-
-
-class RemoteA2AClient:
-    """Thin client wrapper for interacting with a remote A2A endpoint."""
-
-    def __init__(
-        self,
-        endpoint: str,
-        *,
-        http_client: httpx.AsyncClient | None = None,
-        timeout: float = 120.0,
-    ) -> None:
-        self.endpoint = endpoint.rstrip("/") or endpoint
-        self.timeout = timeout
-        self._http_client = http_client
-        self._owns_http_client = http_client is None
-        self._streaming_client: Client | None = None
-        self._blocking_client: Client | None = None
-
-    async def get_card(self) -> Any:
-        client = await self._ensure_client(streaming=True)
-        return await client.get_card()
-
-    async def invoke(
-        self,
-        text: str,
-        *,
-        context_id: str | None = None,
-        task_id: str | None = None,
-        metadata: dict[str, Any] | None = None,
-    ) -> dict[str, Any]:
-        client = await self._ensure_client(streaming=False)
-        message = _build_text_message(
-            text,
-            context_id=context_id,
-            task_id=task_id,
-        )
-        final_task: Task | None = None
-
-        async for event in client.send_message(
-            message,
-            configuration=MessageSendConfiguration(blocking=True),
-            request_metadata=metadata,
-        ):
-            if isinstance(event, Message):
-                return {
-                    "output": get_message_text(event),
-                    "task_id": event.task_id,
-                    "context_id": event.context_id,
-                    "message": event,
-                }
-            final_task, _ = event
-
-        if final_task is None:
-            raise RuntimeError("A2A response did not include a task result")
-
-        self._raise_for_failed_task(final_task)
-        return {
-            "output": _task_output(final_task),
-            "task_id": final_task.id,
-            "context_id": final_task.context_id,
-            "task": final_task,
-        }
-
-    async def stream(
-        self,
-        text: str,
-        *,
-        context_id: str | None = None,
-        task_id: str | None = None,
-        metadata: dict[str, Any] | None = None,
-    ) -> AsyncIterator[dict[str, Any]]:
-        client = await self._ensure_client(streaming=True)
-        message = _build_text_message(
-            text,
-            context_id=context_id,
-            task_id=task_id,
-        )
-        emitted_output = False
-        latest_task: Task | None = None
-
-        async for event in client.send_message(
-            message,
-            configuration=MessageSendConfiguration(blocking=True),
-            request_metadata=metadata,
-        ):
-            if isinstance(event, Message):
-                text_output = get_message_text(event)
-                if text_output:
-                    emitted_output = True
-                    yield {
-                        "delta": text_output,
-                        "type": "text",
-                        "task_id": event.task_id,
-                        "context_id": event.context_id,
-                    }
-                return
-
-            latest_task, update = event
-            if isinstance(update, TaskArtifactUpdateEvent):
-                artifact_text = get_artifact_text(update.artifact)
-                if artifact_text:
-                    emitted_output = True
-                    yield {
-                        "delta": artifact_text,
-                        "type": "text",
-                        "task_id": update.task_id,
-                        "context_id": update.context_id,
-                    }
-                continue
-
-            if isinstance(update, TaskStatusUpdateEvent) and update.final:
-                self._raise_for_failed_task(latest_task)
-
-        if latest_task is None:
-            return
-
-        self._raise_for_failed_task(latest_task)
-        if emitted_output:
-            return
-
-        task_text = _task_output(latest_task)
-        if task_text:
-            yield {
-                "delta": task_text,
-                "type": "text",
-                "task_id": latest_task.id,
-                "context_id": latest_task.context_id,
-            }
-
-    async def close(self) -> None:
-        if self._owns_http_client and self._http_client is not None:
-            await self._http_client.aclose()
-        self._http_client = None
-        self._streaming_client = None
-        self._blocking_client = None
-
-    async def __aenter__(self) -> "RemoteA2AClient":
-        await self._ensure_client(streaming=True)
-        return self
-
-    async def __aexit__(self, *_: Any) -> None:
-        await self.close()
-
-    async def _ensure_client(self, *, streaming: bool) -> Client:
-        cached_client = (
-            self._streaming_client if streaming else self._blocking_client
-        )
-        if cached_client is not None:
-            return cached_client
-
-        if self._http_client is None:
-            self._http_client = httpx.AsyncClient(timeout=self.timeout)
-
-        client = await ClientFactory.connect(
-            self.endpoint,
-            client_config=ClientConfig(
-                httpx_client=self._http_client,
-                streaming=streaming,
-                polling=False,
-                accepted_output_modes=["text/plain"],
-            ),
-        )
-        if streaming:
-            self._streaming_client = client
-        else:
-            self._blocking_client = client
-        return client
-
-    @staticmethod
-    def _raise_for_failed_task(task: Task) -> None:
-        if task.status.state in _FAILED_TASK_STATES:
-            raise RuntimeError(_task_error(task))
-
-
-class RemoteA2AAgent:
-    """Runner-like adapter for using a remote A2A endpoint inside KsADK flows."""
-
-    def __init__(
-        self,
-        endpoint: str,
-        *,
-        name: str = "remote_a2a_agent",
-        http_client: httpx.AsyncClient | None = None,
-        timeout: float = 120.0,
-    ) -> None:
-        self.name = name
-        self._client = RemoteA2AClient(
-            endpoint=endpoint,
-            http_client=http_client,
-            timeout=timeout,
-        )
-
-    async def get_card(self) -> Any:
-        return await self._client.get_card()
-
-    async def invoke(self, input_data: dict[str, Any]) -> dict[str, Any]:
-        response = await self._client.invoke(
-            str(input_data.get("input", "")),
-            context_id=input_data.get("context_id") or input_data.get("session_id"),
-            task_id=input_data.get("task_id"),
-            metadata=self._build_metadata(input_data),
-        )
-        return {
-            "output": response["output"],
-            "task_id": response.get("task_id"),
-            "context_id": response.get("context_id"),
-        }
-
-    async def stream(
-        self,
-        input_data: dict[str, Any],
-    ) -> AsyncIterator[dict[str, Any]]:
-        async for event in self._client.stream(
-            str(input_data.get("input", "")),
-            context_id=input_data.get("context_id") or input_data.get("session_id"),
-            task_id=input_data.get("task_id"),
-            metadata=self._build_metadata(input_data),
-        ):
-            yield event
-
-    async def close(self) -> None:
-        await self._client.close()
-
-    @staticmethod
-    def _build_metadata(input_data: dict[str, Any]) -> dict[str, Any] | None:
-        metadata = dict(input_data.get("metadata") or {})
-
-        state = input_data.get("state")
-        if isinstance(state, dict) and state:
-            metadata["state"] = dict(state)
-
-        branch = input_data.get("branch")
-        if isinstance(branch, str) and branch:
-            metadata["branch"] = branch
-
-        return metadata or None

ksadk/events/parser.py

@@ -1,191 +0,0 @@
-"""共享 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"]