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

autobyteus/agent/streaming/handlers/streaming_response_handler.py

@@ -0,0 +1,58 @@
+"""
+StreamingResponseHandler: Abstract Base Class for response handlers.
+"""
+from abc import ABC, abstractmethod
+from typing import List, Optional, Callable, Union
+from autobyteus.agent.tool_invocation import ToolInvocation
+from autobyteus.llm.utils.response_types import ChunkResponse
+from ..segments.segment_events import SegmentEvent
+
+class StreamingResponseHandler(ABC):
+    """
+    Abstract base class for handling streaming LLM responses.
+    
+    Handlers receive the full ChunkResponse object and decide which fields to use:
+    - Text parsers use chunk.content
+    - API tool call handlers use chunk.tool_calls
+    """
+
+    @abstractmethod
+    def feed(self, chunk: ChunkResponse) -> List[SegmentEvent]:
+        """
+        Process a chunk of LLM response.
+        
+        Args:
+            chunk: The full ChunkResponse containing text, tool calls, etc.
+            
+        Returns:
+            List of SegmentEvents emitted while processing this chunk.
+        """
+        pass
+
+    @abstractmethod
+    def finalize(self) -> List[SegmentEvent]:
+        """
+        Finalize parsing and emit any remaining segments.
+        """
+        pass
+
+    @abstractmethod
+    def get_all_invocations(self) -> List[ToolInvocation]:
+        """
+        Get all ToolInvocations created so far.
+        """
+        pass
+
+    @abstractmethod
+    def get_all_events(self) -> List[SegmentEvent]:
+        """
+        Get all SegmentEvents emitted so far.
+        """
+        pass
+    
+    @abstractmethod
+    def reset(self) -> None:
+        """
+        Reset the handler for reuse.
+        """
+        pass

autobyteus/agent/streaming/parser/__init__.py

@@ -0,0 +1,61 @@
+# Parser package
+"""
+Streaming Parser: Character-by-character LLM response parser.
+
+Main components:
+- StreamingParser: Main entry point for parsing
+- StreamingResponseHandler: High-level handler with callbacks
+- ToolInvocationAdapter: Converts tool segments to ToolInvocations
+- SegmentEvent: Structured events emitted during parsing
+"""
+from .streaming_parser import StreamingParser, parse_complete_response, extract_segments
+from .parser_factory import (
+    create_streaming_parser,
+    resolve_parser_name,
+    StreamingParserProtocol,
+)
+from .events import SegmentEvent, SegmentType, SegmentEventType
+from .invocation_adapter import ToolInvocationAdapter
+from .parser_context import ParserConfig
+from .xml_tool_parsing_state_registry import XmlToolParsingStateRegistry
+from .states.xml_tool_parsing_state import XmlToolParsingState
+from .states.xml_write_file_tool_parsing_state import XmlWriteFileToolParsingState
+from .states.xml_patch_file_tool_parsing_state import XmlPatchFileToolParsingState
+
+def register_xml_tool_parsing_state(tool_name: str, state_class):
+    """
+    Public API to register a custom parsing state for a specific tool.
+    
+    Args:
+        tool_name: The name of the tool (e.g., 'patch_prompt').
+        state_class: The parsing state class (must inherit from XmlToolParsingState or BaseState).
+    """
+    XmlToolParsingStateRegistry().register_tool_state(tool_name, state_class)
+
+__all__ = [
+    # Main classes
+    "StreamingParser",
+    "ToolInvocationAdapter",
+    "ParserConfig",
+    "StreamingParserProtocol",
+    "create_streaming_parser",
+    "resolve_parser_name",
+    
+    # Event types
+    "SegmentEvent",
+    "SegmentType",
+    "SegmentEventType",
+    
+    # Convenience functions
+    "parse_complete_response",
+    "extract_segments",
+    
+    # Public Registry API
+    "register_xml_tool_parsing_state",
+    "XmlToolParsingStateRegistry",
+    
+    # Base States for inheritance
+    "XmlToolParsingState",
+    "XmlWriteFileToolParsingState",
+    "XmlPatchFileToolParsingState",
+]

autobyteus/agent/streaming/parser/event_emitter.py

@@ -0,0 +1,181 @@
+"""
+EventEmitter: Manages segment event emission for the streaming parser.
+
+This class is responsible for:
+- Generating unique segment IDs
+- Tracking the current active segment
+- Building and queuing SegmentEvents
+- Managing the event queue
+"""
+from typing import Optional, List, Dict, Any
+import logging
+
+from .events import SegmentEvent, SegmentType, SegmentEventType
+
+logger = logging.getLogger(__name__)
+
+
+class EventEmitter:
+    """
+    Manages segment event emission for the streaming parser.
+    
+    Extracted from ParserContext to improve single responsibility.
+    """
+    
+    def __init__(self, segment_id_prefix: Optional[str] = None):
+        self._event_queue: List[SegmentEvent] = []
+        self._segment_counter: int = 0
+        self._current_segment_id: Optional[str] = None
+        self._current_segment_type: Optional[SegmentType] = None
+        self._current_segment_content: str = ""
+        self._current_segment_metadata: Dict[str, Any] = {}
+        self._segment_id_prefix: Optional[str] = segment_id_prefix
+
+    def _generate_segment_id(self) -> str:
+        """Generate a unique segment ID."""
+        self._segment_counter += 1
+        base_id = f"seg_{self._segment_counter}"
+        if self._segment_id_prefix:
+            return f"{self._segment_id_prefix}{base_id}"
+        return base_id
+
+    def emit_segment_start(
+        self, 
+        segment_type: SegmentType, 
+        **metadata
+    ) -> str:
+        """
+        Emit a SEGMENT_START event and begin tracking a new segment.
+        
+        Args:
+            segment_type: The type of segment starting.
+            **metadata: Additional metadata for the segment.
+            
+        Returns:
+            The generated segment ID.
+        """
+        segment_id = self._generate_segment_id()
+        self._current_segment_id = segment_id
+        self._current_segment_type = segment_type
+        self._current_segment_content = ""
+        self._current_segment_metadata = dict(metadata)
+        
+        event = SegmentEvent.start(segment_id, segment_type, **metadata)
+        self._event_queue.append(event)
+        return segment_id
+
+    def emit_segment_content(self, delta: Any) -> None:
+        """
+        Emit a SEGMENT_CONTENT event for the current segment.
+        
+        Args:
+            delta: The content delta to emit.
+            
+        Raises:
+            RuntimeError: If no segment is active.
+        """
+        if self._current_segment_id is None:
+            raise RuntimeError("Cannot emit content without an active segment.")
+        
+        # Accumulate string content
+        if isinstance(delta, str):
+            self._current_segment_content += delta
+        
+        event = SegmentEvent.content(self._current_segment_id, delta)
+        self._event_queue.append(event)
+
+    def emit_segment_end(self) -> Optional[str]:
+        """
+        Emit a SEGMENT_END event and stop tracking the current segment.
+        
+        The END event includes the current segment metadata for downstream
+        processing (e.g., tool invocation creation).
+        
+        Returns:
+            The segment ID that was ended, or None if no active segment.
+        """
+        if self._current_segment_id is None:
+            return None
+        
+        segment_id = self._current_segment_id
+        
+        # Include metadata in END event for downstream processing
+        event = SegmentEvent(
+            event_type=SegmentEventType.END,
+            segment_id=segment_id,
+            payload={"metadata": self._current_segment_metadata.copy()} if self._current_segment_metadata else {}
+        )
+        self._event_queue.append(event)
+        
+        # Clear tracking
+        self._current_segment_id = None
+        self._current_segment_type = None
+        
+        return segment_id
+
+    # --- Query Methods ---
+    
+    def get_current_segment_id(self) -> Optional[str]:
+        """Get the ID of the currently active segment."""
+        return self._current_segment_id
+
+    def get_current_segment_type(self) -> Optional[SegmentType]:
+        """Get the type of the currently active segment."""
+        return self._current_segment_type
+
+    def get_current_segment_content(self) -> str:
+        """Get the accumulated content of the current segment."""
+        return self._current_segment_content
+
+    def get_current_segment_metadata(self) -> Dict[str, Any]:
+        """Get the metadata of the current segment."""
+        return self._current_segment_metadata.copy()
+
+    def update_current_segment_metadata(self, **metadata) -> None:
+        """Update metadata for the current segment."""
+        self._current_segment_metadata.update(metadata)
+
+    # --- Event Queue Management ---
+    
+    def get_and_clear_events(self) -> List[SegmentEvent]:
+        """
+        Get all queued events and clear the queue.
+        
+        Returns:
+            List of SegmentEvents that were queued.
+        """
+        events = self._event_queue.copy()
+        self._event_queue.clear()
+        return events
+
+    def get_events(self) -> List[SegmentEvent]:
+        """Get all queued events without clearing."""
+        return self._event_queue.copy()
+
+    # --- Convenience Methods ---
+    
+    def append_text_segment(self, text: str) -> None:
+        """
+        Convenience method to emit a complete text segment.
+        
+        Emits START (if needed) and CONTENT events for a text segment.
+        The segment remains open until explicitly ended by the caller.
+        
+        Args:
+            text: The text content to emit.
+        """
+        if not text:
+            return
+
+        if self._current_segment_type != SegmentType.TEXT:
+            if self._current_segment_id is not None:
+                logger.warning(
+                    "append_text_segment called while non-text segment is active (%s); "
+                    "ending it before starting a text segment.",
+                    self._current_segment_type,
+                )
+                self.emit_segment_end()
+
+            self.emit_segment_start(SegmentType.TEXT)
+
+        self.emit_segment_content(text)

autobyteus/agent/streaming/parser/events.py

@@ -0,0 +1,4 @@
+"""Compatibility shim for SegmentEvent definitions."""
+from ..segments.segment_events import *
+
+__all__ = ["SegmentEvent", "SegmentType", "SegmentEventType"]

autobyteus/agent/streaming/parser/invocation_adapter.py

@@ -0,0 +1,4 @@
+"""Compatibility shim for ToolInvocationAdapter."""
+from ..adapters.invocation_adapter import ToolInvocationAdapter
+
+__all__ = ["ToolInvocationAdapter"]

autobyteus/agent/streaming/parser/json_parsing_strategies/__init__.py

@@ -0,0 +1,19 @@
+"""JSON tool parsing strategies and registry."""
+from .base import JsonToolParsingStrategy, ToolCallData
+from .default import DefaultJsonToolParsingStrategy
+from .gemini import GeminiJsonToolParsingStrategy
+from .openai import OpenAiJsonToolParsingStrategy
+from .registry import (
+    JsonToolParsingProfile,
+    get_json_tool_parsing_profile,
+)
+
+__all__ = [
+    "JsonToolParsingStrategy",
+    "ToolCallData",
+    "DefaultJsonToolParsingStrategy",
+    "GeminiJsonToolParsingStrategy",
+    "OpenAiJsonToolParsingStrategy",
+    "JsonToolParsingProfile",
+    "get_json_tool_parsing_profile",
+]

autobyteus/agent/streaming/parser/json_parsing_strategies/base.py

@@ -0,0 +1,32 @@
+"""
+Shared types and helpers for JSON tool-call parsing strategies.
+"""
+from typing import Protocol, List, Dict, Any, TypedDict
+import json
+
+
+class ToolCallData(TypedDict):
+    name: str
+    arguments: Dict[str, Any]
+
+
+class JsonToolParsingStrategy(Protocol):
+    """Interface for provider-aware JSON tool parsing."""
+
+    def parse(self, raw_json: str) -> List[ToolCallData]:
+        """Parse JSON string into zero or more tool calls."""
+        ...
+
+
+def coerce_arguments(value: Any) -> Dict[str, Any]:
+    """Normalize argument payload into a dict when possible."""
+    if isinstance(value, dict):
+        return value
+    if isinstance(value, str):
+        try:
+            parsed = json.loads(value)
+            if isinstance(parsed, dict):
+                return parsed
+        except json.JSONDecodeError:
+            return {}
+    return {}

autobyteus/agent/streaming/parser/json_parsing_strategies/default.py

@@ -0,0 +1,34 @@
+"""Default JSON tool-call parsing for generic formats."""
+from typing import Any, List
+import json
+
+from .base import ToolCallData, coerce_arguments
+
+
+class DefaultJsonToolParsingStrategy:
+    """Parses the default Autobyteus JSON tool call format."""
+
+    def parse(self, raw_json: str) -> List[ToolCallData]:
+        try:
+            data = json.loads(raw_json)
+        except json.JSONDecodeError:
+            return []
+
+        tool = None
+        if isinstance(data, dict):
+            tool = data.get("tool")
+        if not isinstance(tool, dict):
+            return []
+
+        name = tool.get("function")
+        if isinstance(name, dict):
+            name = name.get("name")
+        if not isinstance(name, str) or not name:
+            return []
+
+        args = tool.get("parameters")
+        if args is None:
+            args = tool.get("arguments")
+        arguments = coerce_arguments(args)
+
+        return [{"name": name, "arguments": arguments}]

autobyteus/agent/streaming/parser/json_parsing_strategies/gemini.py

@@ -0,0 +1,31 @@
+"""Gemini-style JSON tool-call parsing."""
+from typing import Any, List
+import json
+
+from .base import ToolCallData, coerce_arguments
+
+
+class GeminiJsonToolParsingStrategy:
+    """Parses Gemini tool call JSON formats (name + args)."""
+
+    def parse(self, raw_json: str) -> List[ToolCallData]:
+        try:
+            data = json.loads(raw_json)
+        except json.JSONDecodeError:
+            return []
+
+        calls: List[Any] = data if isinstance(data, list) else [data]
+        parsed: List[ToolCallData] = []
+
+        for call in calls:
+            if not isinstance(call, dict):
+                continue
+
+            name = call.get("name")
+            if not isinstance(name, str) or not name:
+                continue
+
+            arguments = coerce_arguments(call.get("args"))
+            parsed.append({"name": name, "arguments": arguments})
+
+        return parsed

autobyteus/agent/streaming/parser/json_parsing_strategies/openai.py

@@ -0,0 +1,64 @@
+"""OpenAI-style JSON tool-call parsing."""
+from typing import Any, Dict, List
+import json
+
+from .base import ToolCallData, coerce_arguments
+
+
+class OpenAiJsonToolParsingStrategy:
+    """Parses OpenAI-compatible tool call JSON formats."""
+
+    def parse(self, raw_json: str) -> List[ToolCallData]:
+        try:
+            data = json.loads(raw_json)
+        except json.JSONDecodeError:
+            return []
+
+        tool_calls = self._extract_tool_calls(data)
+        parsed: List[ToolCallData] = []
+
+        for call in tool_calls:
+            if not isinstance(call, dict):
+                continue
+
+            # Unwrap if nested under "tool"
+            if isinstance(call.get("tool"), dict):
+                call = call.get("tool")
+                if not isinstance(call, dict):
+                    continue
+
+            function_data: Dict[str, Any] = {}
+            function_value = call.get("function")
+            if isinstance(function_value, dict):
+                function_data = function_value
+            elif isinstance(function_value, str):
+                # Default JSON format uses function as a string tool name.
+                function_data = call
+            elif "name" in call or "arguments" in call or "parameters" in call:
+                function_data = call
+
+            name = function_data.get("name") or function_data.get("function")
+            if not isinstance(name, str) or not name:
+                continue
+
+            args = function_data.get("arguments")
+            if args is None:
+                args = function_data.get("parameters")
+            arguments = coerce_arguments(args)
+
+            parsed.append({"name": name, "arguments": arguments})
+
+        return parsed
+
+    def _extract_tool_calls(self, data: Any) -> List[Any]:
+        if isinstance(data, dict):
+            if isinstance(data.get("tool_calls"), list):
+                return data.get("tool_calls")
+            if isinstance(data.get("tools"), list):
+                return data.get("tools")
+            if isinstance(data.get("tool"), dict):
+                return [data.get("tool")]
+            return [data]
+        if isinstance(data, list):
+            return data
+        return []

autobyteus/agent/streaming/parser/json_parsing_strategies/registry.py

@@ -0,0 +1,75 @@
+"""Provider-aware JSON tool parsing profiles."""
+from dataclasses import dataclass
+from typing import List, Optional
+
+from autobyteus.llm.providers import LLMProvider
+from autobyteus.utils.tool_call_format import resolve_tool_call_format
+
+from .base import JsonToolParsingStrategy
+from .default import DefaultJsonToolParsingStrategy
+from .gemini import GeminiJsonToolParsingStrategy
+from .openai import OpenAiJsonToolParsingStrategy
+
+
+@dataclass(frozen=True)
+class JsonToolParsingProfile:
+    parser: JsonToolParsingStrategy
+    signature_patterns: List[str]
+
+
+OPENAI_JSON_PATTERNS = [
+    '{"tool":',
+    '{"tool_calls":',
+    '{"tools":',
+    '{"function":',
+    '[{"tool":',
+    '[{"function":',
+]
+
+GEMINI_JSON_PATTERNS = [
+    '{"name":',
+    '[{"name":',
+]
+
+DEFAULT_JSON_PATTERNS = [
+    '{"tool":',
+    '{"function":',
+]
+
+
+OPENAI_PROFILE = JsonToolParsingProfile(
+    parser=OpenAiJsonToolParsingStrategy(),
+    signature_patterns=OPENAI_JSON_PATTERNS,
+)
+
+GEMINI_PROFILE = JsonToolParsingProfile(
+    parser=GeminiJsonToolParsingStrategy(),
+    signature_patterns=GEMINI_JSON_PATTERNS,
+)
+
+DEFAULT_PROFILE = JsonToolParsingProfile(
+    parser=DefaultJsonToolParsingStrategy(),
+    signature_patterns=DEFAULT_JSON_PATTERNS,
+)
+
+
+OPENAI_LIKE_PROVIDERS = {
+    LLMProvider.OPENAI,
+    LLMProvider.MISTRAL,
+    LLMProvider.DEEPSEEK,
+    LLMProvider.GROK,
+}
+
+
+def get_json_tool_parsing_profile(provider: Optional[LLMProvider]) -> JsonToolParsingProfile:
+    """Return the JSON tool parsing profile for a provider, honoring overrides."""
+    override = resolve_tool_call_format()
+    if override == "json":
+        return DEFAULT_PROFILE
+
+    if provider == LLMProvider.GEMINI:
+        return GEMINI_PROFILE
+    if provider in OPENAI_LIKE_PROVIDERS:
+        return OPENAI_PROFILE
+
+    return DEFAULT_PROFILE