core/agent: add AgentEvent types and ChatClient protocol

src/plyngent/agent/client.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal, Protocol, overload
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+    from plyngent.lmproto.openai_compatible.model import (
+        ChatCompletionChunk,
+        ChatCompletionResponse,
+        ChatCompletionsParam,
+    )
+
+
+class ChatClient(Protocol):
+    """Structural protocol for OpenAI-compatible chat completion clients."""
+
+    @overload
+    async def chat_completions(
+        self, param: ChatCompletionsParam, *, stream: Literal[False] = False
+    ) -> ChatCompletionResponse: ...
+
+    @overload
+    async def chat_completions(
+        self, param: ChatCompletionsParam, *, stream: Literal[True]
+    ) -> AsyncIterator[ChatCompletionChunk]: ...
+
+    async def chat_completions(
+        self, param: ChatCompletionsParam, *, stream: bool = False
+    ) -> ChatCompletionResponse | AsyncIterator[ChatCompletionChunk]: ...

src/plyngent/agent/events.py

@@ -0,0 +1,30 @@
+from msgspec import Struct
+
+from plyngent.lmproto.openai_compatible.model import (  # noqa: TC001
+    AnyAssistantToolCall,
+    AssistantChatMessage,
+    ToolChatMessage,
+)
+
+
+class TextDeltaEvent(Struct, tag_field="type", tag="text_delta"):
+    content: str
+
+
+class AssistantMessageEvent(Struct, tag_field="type", tag="assistant_message"):
+    message: AssistantChatMessage
+
+
+class ToolCallEvent(Struct, tag_field="type", tag="tool_call"):
+    tool_call: AnyAssistantToolCall
+
+
+class ToolResultEvent(Struct, tag_field="type", tag="tool_result"):
+    message: ToolChatMessage
+
+
+class MaxRoundsEvent(Struct, tag_field="type", tag="max_rounds"):
+    rounds: int
+
+
+type AgentEvent = TextDeltaEvent | AssistantMessageEvent | ToolCallEvent | ToolResultEvent | MaxRoundsEvent