autobyteus 1.2.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

autobyteus/agent/streaming/api_tool_call/file_content_streamer.py

@@ -0,0 +1,56 @@
+"""Content streamers for file tools in API tool call mode."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .json_string_field_extractor import JsonStringFieldExtractor
+
+
+@dataclass
+class FileContentStreamUpdate:
+    """Incremental update from a file content streamer."""
+
+    content_delta: str = ""
+    path: Optional[str] = None
+    content_complete: Optional[str] = None
+
+
+class _BaseFileContentStreamer:
+    def __init__(self, content_key: str):
+        self._content_key = content_key
+        self._extractor = JsonStringFieldExtractor(
+            stream_fields={content_key},
+            final_fields={"path", content_key},
+        )
+        self.path: Optional[str] = None
+        self.content: Optional[str] = None
+
+    def feed(self, json_delta: str) -> FileContentStreamUpdate:
+        result = self._extractor.feed(json_delta)
+
+        if "path" in result.completed and self.path is None:
+            self.path = result.completed["path"]
+
+        if self._content_key in result.completed:
+            self.content = result.completed[self._content_key]
+
+        return FileContentStreamUpdate(
+            content_delta=result.deltas.get(self._content_key, ""),
+            path=result.completed.get("path"),
+            content_complete=result.completed.get(self._content_key),
+        )
+
+
+class WriteFileContentStreamer(_BaseFileContentStreamer):
+    """Streams decoded write_file content from JSON argument deltas."""
+
+    def __init__(self):
+        super().__init__(content_key="content")
+
+
+class PatchFileContentStreamer(_BaseFileContentStreamer):
+    """Streams decoded patch_file content from JSON argument deltas."""
+
+    def __init__(self):
+        super().__init__(content_key="patch")

autobyteus/agent/streaming/api_tool_call/json_string_field_extractor.py

@@ -0,0 +1,175 @@
+"""
+Incremental JSON string field extractor for API tool call argument deltas.
+
+This parser is intentionally small and focused: it streams specific string
+fields (e.g., path/content/patch) from a JSON object as deltas arrive.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, Optional
+
+
+@dataclass
+class FieldExtractionResult:
+    """Holds incremental deltas and completed values for extracted fields."""
+
+    deltas: Dict[str, str] = field(default_factory=dict)
+    completed: Dict[str, str] = field(default_factory=dict)
+
+
+class JsonStringFieldExtractor:
+    """
+    Incrementally extracts specified string fields from a JSON object.
+
+    The extractor consumes raw JSON fragments and yields decoded string deltas
+    for configured fields. It is resilient to chunk boundaries and handles
+    common JSON escapes.
+    """
+
+    def __init__(
+        self,
+        stream_fields: Iterable[str],
+        final_fields: Optional[Iterable[str]] = None,
+    ):
+        self._stream_fields = set(stream_fields)
+        self._final_fields = set(final_fields) if final_fields is not None else set(stream_fields)
+        self._targets = self._stream_fields | self._final_fields
+        self._mode = "scan"
+        self._escape = False
+        self._unicode_escape: Optional[str] = None
+        self._current_key: Optional[str] = None
+        self._current_value_key: Optional[str] = None
+        self._string_buffer: str = ""
+        self._values: Dict[str, str] = {}
+        self._pending_delta: Dict[str, str] = {}
+
+    def feed(self, chunk: str) -> FieldExtractionResult:
+        """Process a chunk and return any new deltas or completed values."""
+        if not chunk:
+            return FieldExtractionResult()
+
+        self._pending_delta = {}
+        completed: Dict[str, str] = {}
+
+        for char in chunk:
+            self._step(char, completed)
+
+        return FieldExtractionResult(deltas=self._pending_delta.copy(), completed=completed)
+
+    def _step(self, char: str, completed: Dict[str, str]) -> None:
+        if self._mode == "scan":
+            if char == '"':
+                self._string_buffer = ""
+                self._mode = "key"
+            return
+
+        if self._mode == "key":
+            if self._escape:
+                self._string_buffer += self._decode_escape(char)
+                return
+            if char == "\\":
+                self._escape = True
+                return
+            if char == '"':
+                self._current_key = self._string_buffer
+                self._string_buffer = ""
+                self._mode = "post_key"
+                return
+            self._string_buffer += char
+            return
+
+        if self._mode == "post_key":
+            if char.isspace():
+                return
+            if char == ":":
+                self._mode = "post_colon"
+                return
+            # Unexpected token; reset
+            self._reset_string_state()
+            self._mode = "scan"
+            return
+
+        if self._mode == "post_colon":
+            if char.isspace():
+                return
+            if char == '"':
+                self._mode = "value"
+                self._current_value_key = self._current_key
+                self._string_buffer = ""
+                return
+            # Non-string value; ignore and reset
+            self._current_key = None
+            self._mode = "scan"
+            return
+
+        if self._mode == "value":
+            if self._escape:
+                decoded = self._decode_escape(char)
+                self._append_value(decoded, completed)
+                return
+            if char == "\\":
+                self._escape = True
+                return
+            if char == '"':
+                self._finalize_value(completed)
+                self._mode = "scan"
+                return
+            self._append_value(char, completed)
+
+    def _append_value(self, decoded_char: str, completed: Dict[str, str]) -> None:
+        key = self._current_value_key
+        if not key:
+            return
+        if key in self._targets:
+            if key in self._stream_fields:
+                self._pending_delta[key] = self._pending_delta.get(key, "") + decoded_char
+            self._values[key] = self._values.get(key, "") + decoded_char
+
+    def _finalize_value(self, completed: Dict[str, str]) -> None:
+        key = self._current_value_key
+        if key in self._final_fields and key in self._values:
+            completed[key] = self._values[key]
+        self._current_key = None
+        self._current_value_key = None
+        self._string_buffer = ""
+        self._escape = False
+        self._unicode_escape = None
+
+    def _reset_string_state(self) -> None:
+        self._current_key = None
+        self._current_value_key = None
+        self._string_buffer = ""
+        self._escape = False
+        self._unicode_escape = None
+
+    def _decode_escape(self, char: str) -> str:
+        """Decode common JSON escapes, tracking state for unicode if needed."""
+        if self._unicode_escape is not None:
+            self._unicode_escape += char
+            if len(self._unicode_escape) == 4:
+                try:
+                    decoded = chr(int(self._unicode_escape, 16))
+                except ValueError:
+                    decoded = ""
+                self._unicode_escape = None
+                self._escape = False
+                return decoded
+            return ""
+
+        self._escape = False
+
+        if char == "n":
+            return "\n"
+        if char == "t":
+            return "\t"
+        if char == "r":
+            return "\r"
+        if char == "\\":
+            return "\\"
+        if char == '"':
+            return '"'
+        if char == "u":
+            self._unicode_escape = ""
+            return ""
+        return char

autobyteus/agent/streaming/api_tool_call_streaming_response_handler.py

@@ -0,0 +1,4 @@
+"""Compatibility shim for ApiToolCallStreamingResponseHandler."""
+from .handlers.api_tool_call_streaming_response_handler import ApiToolCallStreamingResponseHandler
+
+__all__ = ["ApiToolCallStreamingResponseHandler"]

autobyteus/agent/streaming/events/__init__.py

@@ -0,0 +1,6 @@
+"""Stream event models for agent/team streaming."""
+
+from .stream_events import StreamEvent, StreamEventType
+from .stream_event_payloads import *  # re-export payload models
+
+__all__ = ["StreamEvent", "StreamEventType"]

autobyteus/agent/streaming/events/stream_event_payloads.py

@@ -0,0 +1,284 @@
+import logging
+from typing import Dict, Any, Optional, List, Union
+from pydantic import BaseModel, Field
+
+from autobyteus.llm.utils.token_usage import TokenUsage 
+from autobyteus.agent.status.status_enum import AgentStatus
+
+
+logger = logging.getLogger(__name__)
+
+# --- Base Payload Model (Optional, for common fields if any) ---
+class BaseStreamPayload(BaseModel):
+    class Config:
+        extra = "allow"
+
+# --- Specific Payload Models for each StreamEventType ---
+
+class AssistantChunkData(BaseStreamPayload):
+    content: str
+    reasoning: Optional[str] = None
+    is_complete: bool
+    usage: Optional[TokenUsage] = None 
+    image_urls: Optional[List[str]] = None
+    audio_urls: Optional[List[str]] = None
+    video_urls: Optional[List[str]] = None
+
+
+class AssistantCompleteResponseData(BaseStreamPayload):
+    content: str
+    reasoning: Optional[str] = None
+    usage: Optional[TokenUsage] = None 
+    image_urls: Optional[List[str]] = None
+    audio_urls: Optional[List[str]] = None
+    video_urls: Optional[List[str]] = None
+
+class ToolInteractionLogEntryData(BaseStreamPayload):
+    log_entry: str
+    tool_invocation_id: str
+    tool_name: str
+
+class AgentStatusUpdateData(BaseStreamPayload):
+    new_status: AgentStatus 
+    old_status: Optional[AgentStatus] = None
+    trigger: Optional[str] = None
+    tool_name: Optional[str] = None
+    error_message: Optional[str] = None
+    error_details: Optional[str] = None
+
+class ErrorEventData(BaseStreamPayload):
+    source: str
+    message: str
+    details: Optional[str] = None
+
+class ToolInvocationApprovalRequestedData(BaseStreamPayload):
+    invocation_id: str
+    tool_name: str
+    arguments: Dict[str, Any]
+
+class ToolInvocationAutoExecutingData(BaseStreamPayload):
+    invocation_id: str
+    tool_name: str
+    arguments: Dict[str, Any]
+
+class SegmentEventData(BaseStreamPayload):
+    event_type: str = Field(alias="type")
+    segment_id: str
+    segment_type: Optional[str] = None
+    payload: Dict[str, Any] = Field(default_factory=dict)
+
+    class Config:
+        populate_by_name = True
+
+# NEW PAYLOAD
+class SystemTaskNotificationData(BaseStreamPayload):
+    sender_id: str
+    content: str
+
+# NEW PAYLOAD: Inter-agent message surfaced to UI
+class InterAgentMessageData(BaseStreamPayload):
+    sender_agent_id: str
+    recipient_role_name: str
+    content: str
+    message_type: str
+
+class ToDoItemData(BaseStreamPayload):
+    description: str
+    todo_id: str
+    status: str
+
+class ToDoListUpdateData(BaseStreamPayload):
+    todos: List[ToDoItemData]
+
+class ArtifactPersistedData(BaseStreamPayload):
+    artifact_id: str
+    path: str
+    agent_id: str
+    type: str
+    workspace_root: Optional[str] = None
+    url: Optional[str] = None
+
+class ArtifactUpdatedData(BaseStreamPayload):
+    artifact_id: Optional[str] = None
+    path: str
+    agent_id: str
+    type: str
+    workspace_root: Optional[str] = None
+
+class EmptyData(BaseStreamPayload):
+    pass
+
+# Union of all possible data payload types
+StreamDataPayload = Union[
+    AssistantChunkData,
+    AssistantCompleteResponseData, 
+    ToolInteractionLogEntryData,
+    AgentStatusUpdateData, 
+    ErrorEventData,
+    ToolInvocationApprovalRequestedData,
+    ToolInvocationAutoExecutingData,
+    SegmentEventData,
+    SystemTaskNotificationData,
+    InterAgentMessageData,
+    ToDoListUpdateData,
+    ArtifactPersistedData,
+    ArtifactUpdatedData,
+    EmptyData
+]
+
+# Factory functions to create payload models from various inputs
+
+def create_assistant_chunk_data(chunk_obj: Any) -> AssistantChunkData:
+    """Factory function to create AssistantChunkData from a chunk object."""
+    usage_data = None
+    if hasattr(chunk_obj, 'usage'):
+        usage_data = getattr(chunk_obj, 'usage')
+    elif isinstance(chunk_obj, dict) and 'usage' in chunk_obj:
+        usage_data = chunk_obj.get('usage')
+
+    parsed_usage = None
+    if usage_data:
+        if isinstance(usage_data, TokenUsage):
+            parsed_usage = usage_data
+        elif isinstance(usage_data, dict):
+            try:
+                parsed_usage = TokenUsage(**usage_data)
+            except Exception as e:
+                logger.warning(f"Could not parse usage dict into TokenUsage for AssistantChunkData: {e}. Usage dict: {usage_data}")
+        else:
+            logger.warning(f"Unsupported usage type {type(usage_data)} for AssistantChunkData.")
+
+    if hasattr(chunk_obj, 'content') and hasattr(chunk_obj, 'is_complete'):
+        return AssistantChunkData(
+            content=str(getattr(chunk_obj, 'content', '')),
+            reasoning=getattr(chunk_obj, 'reasoning', None),
+            is_complete=bool(getattr(chunk_obj, 'is_complete', False)),
+            usage=parsed_usage,
+            image_urls=getattr(chunk_obj, 'image_urls', None),
+            audio_urls=getattr(chunk_obj, 'audio_urls', None),
+            video_urls=getattr(chunk_obj, 'video_urls', None)
+        )
+    elif isinstance(chunk_obj, dict): 
+         return AssistantChunkData(
+            content=str(chunk_obj.get('content', '')),
+            reasoning=chunk_obj.get('reasoning', None),
+            is_complete=bool(chunk_obj.get('is_complete', False)),
+            usage=parsed_usage,
+            image_urls=chunk_obj.get('image_urls', None),
+            audio_urls=chunk_obj.get('audio_urls', None),
+            video_urls=chunk_obj.get('video_urls', None)
+        )
+    raise ValueError(f"Cannot create AssistantChunkData from {type(chunk_obj)}")
+
+def create_assistant_complete_response_data(complete_resp_obj: Any) -> AssistantCompleteResponseData:
+    usage_data = None
+    if hasattr(complete_resp_obj, 'usage'):
+        usage_data = getattr(complete_resp_obj, 'usage')
+    elif isinstance(complete_resp_obj, dict) and 'usage' in complete_resp_obj:
+        usage_data = complete_resp_obj.get('usage')
+    
+    parsed_usage = None
+    if usage_data:
+        if isinstance(usage_data, TokenUsage):
+            parsed_usage = usage_data
+        elif isinstance(usage_data, dict):
+            try:
+                parsed_usage = TokenUsage(**usage_data)
+            except Exception as e: # pragma: no cover
+                logger.warning(f"Could not parse usage dict into TokenUsage for AssistantCompleteResponseData: {e}. Usage dict: {usage_data}")
+        else: # pragma: no cover
+            logger.warning(f"Unsupported usage type {type(usage_data)} for AssistantCompleteResponseData.")
+
+    if hasattr(complete_resp_obj, 'content'):
+        return AssistantCompleteResponseData(
+            content=str(getattr(complete_resp_obj, 'content', '')),
+            reasoning=getattr(complete_resp_obj, 'reasoning', None),
+            usage=parsed_usage,
+            image_urls=getattr(complete_resp_obj, 'image_urls', None),
+            audio_urls=getattr(complete_resp_obj, 'audio_urls', None),
+            video_urls=getattr(complete_resp_obj, 'video_urls', None)
+        )
+    elif isinstance(complete_resp_obj, dict): 
+        return AssistantCompleteResponseData(
+            content=str(complete_resp_obj.get('content', '')),
+            reasoning=complete_resp_obj.get('reasoning', None),
+            usage=parsed_usage,
+            image_urls=complete_resp_obj.get('image_urls', None),
+            audio_urls=complete_resp_obj.get('audio_urls', None),
+            video_urls=complete_resp_obj.get('video_urls', None)
+        )
+    raise ValueError(f"Cannot create AssistantCompleteResponseData from {type(complete_resp_obj)}")
+
+def create_tool_interaction_log_entry_data(log_data: Any) -> ToolInteractionLogEntryData:
+    if isinstance(log_data, dict):
+        if all(k in log_data for k in ['log_entry', 'tool_invocation_id', 'tool_name']):
+            return ToolInteractionLogEntryData(**log_data)
+    raise ValueError(f"Cannot create ToolInteractionLogEntryData from {type(log_data)}. Expected dict with 'log_entry', 'tool_invocation_id', and 'tool_name' keys.")
+
+def create_agent_status_update_data(status_data_dict: Any) -> AgentStatusUpdateData: 
+    if isinstance(status_data_dict, dict):
+        return AgentStatusUpdateData(**status_data_dict) 
+    raise ValueError(f"Cannot create AgentStatusUpdateData from {type(status_data_dict)}") 
+
+def create_error_event_data(error_data_dict: Any) -> ErrorEventData:
+    if isinstance(error_data_dict, dict):
+        return ErrorEventData(**error_data_dict)
+    raise ValueError(f"Cannot create ErrorEventData from {type(error_data_dict)}")
+
+def create_tool_invocation_approval_requested_data(approval_data_dict: Any) -> ToolInvocationApprovalRequestedData:
+    if isinstance(approval_data_dict, dict):
+        return ToolInvocationApprovalRequestedData(**approval_data_dict)
+    raise ValueError(f"Cannot create ToolInvocationApprovalRequestedData from {type(approval_data_dict)}")
+
+def create_tool_invocation_auto_executing_data(auto_exec_data_dict: Any) -> ToolInvocationAutoExecutingData:
+    if isinstance(auto_exec_data_dict, dict):
+        return ToolInvocationAutoExecutingData(**auto_exec_data_dict)
+    raise ValueError(f"Cannot create ToolInvocationAutoExecutingData from {type(auto_exec_data_dict)}")
+
+def create_segment_event_data(event_data: Any) -> SegmentEventData:
+    if isinstance(event_data, SegmentEventData):
+        return event_data
+    if isinstance(event_data, dict):
+        return SegmentEventData(**event_data)
+    raise ValueError(f"Cannot create SegmentEventData from {type(event_data)}")
+
+def create_inter_agent_message_data(msg_data: Any) -> InterAgentMessageData:
+    if isinstance(msg_data, dict):
+        required_keys = ["sender_agent_id", "recipient_role_name", "content", "message_type"]
+        missing = [k for k in required_keys if k not in msg_data]
+        if missing:
+            raise ValueError(f"InterAgentMessageData missing keys: {missing}")
+        return InterAgentMessageData(**msg_data)
+    raise ValueError(f"Cannot create InterAgentMessageData from {type(msg_data)}")
+
+def create_system_task_notification_data(notification_data_dict: Any) -> SystemTaskNotificationData:
+    if isinstance(notification_data_dict, dict):
+        return SystemTaskNotificationData(**notification_data_dict)
+    raise ValueError(f"Cannot create SystemTaskNotificationData from {type(notification_data_dict)}")
+
+def create_todo_list_update_data(todo_data_dict: Any) -> ToDoListUpdateData:
+    if isinstance(todo_data_dict, dict):
+        todos_payload = todo_data_dict.get('todos', [])
+        if not isinstance(todos_payload, list):
+            raise ValueError("Expected 'todos' to be a list when creating ToDoListUpdateData.")
+        todo_items = []
+        for todo_entry in todos_payload:
+            if not isinstance(todo_entry, dict):
+                logger.warning(f"Skipping non-dict todo entry when creating ToDoListUpdateData: {todo_entry!r}")
+                continue
+            try:
+                todo_items.append(ToDoItemData(**todo_entry))
+            except Exception as exc:
+                logger.warning(f"Failed to parse todo entry into ToDoItemData: {todo_entry!r}; error: {exc}")
+        return ToDoListUpdateData(todos=todo_items)
+    raise ValueError(f"Cannot create ToDoListUpdateData from {type(todo_data_dict)}")
+
+def create_artifact_persisted_data(data_dict: Any) -> ArtifactPersistedData:
+    if isinstance(data_dict, dict):
+        return ArtifactPersistedData(**data_dict)
+    raise ValueError(f"Cannot create ArtifactPersistedData from {type(data_dict)}")
+
+def create_artifact_updated_data(data_dict: Any) -> ArtifactUpdatedData:
+    if isinstance(data_dict, dict):
+        return ArtifactUpdatedData(**data_dict)
+    raise ValueError(f"Cannot create ArtifactUpdatedData from {type(data_dict)}")

autobyteus/agent/streaming/events/stream_events.py

@@ -0,0 +1,141 @@
+# file: autobyteus/autobyteus/agent/streaming/stream_events.py
+import logging
+from enum import Enum
+from typing import Dict, Any, Optional, Union, Type 
+from pydantic import BaseModel, Field, AwareDatetime, field_validator, ValidationInfo 
+import datetime
+import uuid 
+
+# Import the payload models
+from .stream_event_payloads import (
+    StreamDataPayload, 
+    AssistantChunkData,
+    AssistantCompleteResponseData,
+    ToolInteractionLogEntryData,
+    AgentStatusUpdateData, 
+    ErrorEventData,
+    ToolInvocationApprovalRequestedData,
+    ToolInvocationAutoExecutingData,
+    SegmentEventData,
+    SystemTaskNotificationData, # NEW
+    InterAgentMessageData, # NEW
+    ToDoListUpdateData,
+    ArtifactPersistedData, # NEW
+    ArtifactUpdatedData, # NEW
+)
+
+logger = logging.getLogger(__name__)
+
+class StreamEventType(str, Enum):
+    """
+    Defines the types of events that can appear in a unified agent output stream
+    provided by AgentEventStream.
+    """
+    ASSISTANT_CHUNK = "assistant_chunk"
+    ASSISTANT_COMPLETE_RESPONSE = "assistant_complete_response"
+    TOOL_INTERACTION_LOG_ENTRY = "tool_interaction_log_entry"
+    AGENT_STATUS_UPDATED = "agent_status_updated"
+    ERROR_EVENT = "error_event" 
+    TOOL_INVOCATION_APPROVAL_REQUESTED = "tool_invocation_approval_requested" 
+    TOOL_INVOCATION_AUTO_EXECUTING = "tool_invocation_auto_executing"
+    SEGMENT_EVENT = "segment_event"
+    SYSTEM_TASK_NOTIFICATION = "system_task_notification" # NEW
+    INTER_AGENT_MESSAGE = "inter_agent_message"  # NEW
+    AGENT_TODO_LIST_UPDATE = "agent_todo_list_updated"
+    ARTIFACT_PERSISTED = "artifact_persisted" # NEW
+    ARTIFACT_UPDATED = "artifact_updated" # NEW
+
+
+_STREAM_EVENT_TYPE_TO_PAYLOAD_CLASS: Dict[StreamEventType, Type[BaseModel]] = {
+    StreamEventType.ASSISTANT_CHUNK: AssistantChunkData,
+    StreamEventType.ASSISTANT_COMPLETE_RESPONSE: AssistantCompleteResponseData,
+    StreamEventType.TOOL_INTERACTION_LOG_ENTRY: ToolInteractionLogEntryData,
+    StreamEventType.AGENT_STATUS_UPDATED: AgentStatusUpdateData,
+    StreamEventType.ERROR_EVENT: ErrorEventData,
+    StreamEventType.TOOL_INVOCATION_APPROVAL_REQUESTED: ToolInvocationApprovalRequestedData,
+    StreamEventType.TOOL_INVOCATION_AUTO_EXECUTING: ToolInvocationAutoExecutingData,
+    StreamEventType.SEGMENT_EVENT: SegmentEventData,
+    StreamEventType.SYSTEM_TASK_NOTIFICATION: SystemTaskNotificationData, # NEW
+    StreamEventType.INTER_AGENT_MESSAGE: InterAgentMessageData, # NEW
+    StreamEventType.AGENT_TODO_LIST_UPDATE: ToDoListUpdateData,
+    StreamEventType.ARTIFACT_PERSISTED: ArtifactPersistedData, # NEW
+    StreamEventType.ARTIFACT_UPDATED: ArtifactUpdatedData, # NEW
+}
+
+
+class StreamEvent(BaseModel):
+    """
+    Pydantic model for a unified, typed event in an agent's output stream.
+    The 'data' field is now a discriminated union of specific payload models
+    based on 'event_type'.
+    """
+    event_id: str = Field(
+        default_factory=lambda: str(uuid.uuid4()), 
+        description="Unique identifier for the event."
+    )
+    timestamp: AwareDatetime = Field(
+        default_factory=lambda: datetime.datetime.now(datetime.timezone.utc),
+        description="Timestamp of when the event was created (UTC)."
+    )
+    event_type: StreamEventType = Field(
+        ..., 
+        description="The type of the event. This acts as the discriminator."
+    )
+    data: StreamDataPayload = Field( 
+        ..., 
+        description="Payload of the event, specific to the event_type."
+    )
+    agent_id: Optional[str] = Field(
+        default=None, 
+        description="Optional ID of the agent that originated this event."
+    )
+
+    @field_validator('data', mode='before')
+    def validate_data_based_on_event_type(cls, v, info: ValidationInfo):
+        event_type_value = info.data.get('event_type')
+        if not event_type_value: 
+            return v 
+
+        if isinstance(event_type_value, str):
+            try:
+                event_type = StreamEventType(event_type_value)
+            except ValueError: # pragma: no cover
+                logger.error(f"Invalid event_type string '{event_type_value}' for validation.")
+                raise ValueError(f"Invalid event_type string '{event_type_value}'")
+        elif isinstance(event_type_value, StreamEventType):
+            event_type = event_type_value
+        else: # pragma: no cover
+            logger.error(f"event_type is of unexpected type {type(event_type_value)} during validation.")
+            raise TypeError(f"event_type is of unexpected type {type(event_type_value)}")
+
+
+        payload_class = _STREAM_EVENT_TYPE_TO_PAYLOAD_CLASS.get(event_type)
+        
+        if payload_class:
+            if isinstance(v, payload_class): 
+                return v
+            if isinstance(v, dict):
+                try:
+                    return payload_class(**v)
+                except Exception as e:
+                    logger.error(f"Failed to parse dict into {payload_class.__name__} for event_type {event_type.value}: {e}. Dict was: {v}")
+                    raise ValueError(f"Data for event type {event_type.value} does not match expected model {payload_class.__name__}.") from e
+            logger.error(f"Data for event type {event_type.value} is of unexpected type {type(v)}. Expected dict or {payload_class.__name__}.")
+            raise ValueError(f"Data for event type {event_type.value} is of unexpected type {type(v)}.")
+        
+        logger.warning(f"No specific payload class mapped for event_type: {event_type.value}. Raw data: {v}")
+        if isinstance(v, dict): 
+            return v
+        return v
+
+
+    class Config:
+        populate_by_name = True 
+
+    def __repr__(self) -> str:
+        return (f"<StreamEvent event_id='{self.event_id}', agent_id='{self.agent_id}', "
+                f"type='{self.event_type.value}', timestamp='{self.timestamp.isoformat()}', data_type='{type(self.data).__name__}'>")
+
+    def __str__(self) -> str:
+        return (f"StreamEvent[{self.event_type.value}] (ID: {self.event_id}, Agent: {self.agent_id or 'N/A'}): "
+                f"Data: {self.data!r}")

autobyteus/agent/streaming/handlers/__init__.py

@@ -0,0 +1,15 @@
+"""Streaming response handlers."""
+
+from .streaming_response_handler import StreamingResponseHandler
+from .streaming_handler_factory import StreamingResponseHandlerFactory
+from .parsing_streaming_response_handler import ParsingStreamingResponseHandler
+from .pass_through_streaming_response_handler import PassThroughStreamingResponseHandler
+from .api_tool_call_streaming_response_handler import ApiToolCallStreamingResponseHandler
+
+__all__ = [
+    "StreamingResponseHandler",
+    "StreamingResponseHandlerFactory",
+    "ParsingStreamingResponseHandler",
+    "PassThroughStreamingResponseHandler",
+    "ApiToolCallStreamingResponseHandler",
+]