waldiez 0.5.10__py3-none-any.whl → 0.6.0__py3-none-any.whl

waldiez/running/step_by_step/events_processor.py

@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+# pylint: disable=unused-argument,no-self-use
+"""Command handler for step-by-step execution."""
+
+from typing import TYPE_CHECKING, Any, Union
+
+if TYPE_CHECKING:
+    from autogen.events.base_event import BaseEvent  # type: ignore
+    from autogen.messages.base_message import BaseMessage  # type: ignore
+
+    # noinspection PyUnusedImports
+    from .step_by_step_runner import WaldiezStepByStepRunner
+
+
+# pylint: disable=too-few-public-methods
+class EventProcessor:
+    """Processes events for the step-by-step runner."""
+
+    def __init__(self, runner: "WaldiezStepByStepRunner"):
+        self.runner = runner
+
+    def process_event(
+        self, event: Union["BaseEvent", "BaseMessage"]
+    ) -> dict[str, Any]:
+        """Shared logic for both sync and async event processing.
+
+        Parameters
+        ----------
+        event : BaseEvent | BaseMessage
+            The event to process.
+
+        Returns
+        -------
+        dict[str, Any]
+            The result of processing the event.
+        """
+        self.runner.event_plus_one()
+        self.runner.current_event = event
+
+        if self.runner.is_stop_requested():
+            return {"action": "stop", "reason": "stop_requested"}
+
+        event_info = self._create_event_info(event)
+        self._update_participant_info(event_info)
+        self._manage_event_history(event_info)
+        self._check_for_input_request(event_info)
+
+        should_break = self.runner.should_break_on_event(
+            event, self.runner.step_mode
+        )
+
+        return {
+            "action": "continue",
+            "should_break": should_break,
+            "event_info": event_info,
+        }
+
+    def _create_event_info(
+        self, event: Union["BaseEvent", "BaseMessage"]
+    ) -> dict[str, Any]:
+        """Create event info dictionary from event object.
+
+        Parameters
+        ----------
+        event : BaseEvent | BaseMessage
+            The event to convert to info dict.
+
+        Returns
+        -------
+        dict[str, Any]
+            Event information dictionary.
+        """
+        event_info = event.model_dump(
+            mode="json", exclude_none=True, fallback=str
+        )
+        event_info["count"] = self.runner.event_count
+        event_info["sender"] = getattr(event, "sender", self.runner.last_sender)
+        event_info["recipient"] = getattr(
+            event, "recipient", self.runner.last_recipient
+        )
+        return event_info
+
+    def _update_participant_info(self, event_info: dict[str, Any]) -> None:
+        """Update sender and recipient information in event_info.
+
+        Parameters
+        ----------
+        event_info : dict[str, Any]
+            Event information dictionary to update.
+        """
+        if not event_info["sender"] or not event_info["recipient"]:
+            self._extract_participants_from_content(event_info)
+
+        self._handle_group_chat_speaker(event_info)
+        self._extract_participants_from_direct_content(event_info)
+
+        # Update last known participants
+        self.runner.last_sender = event_info["sender"]
+        self.runner.last_recipient = event_info["recipient"]
+
+    def _extract_participants_from_content(
+        self, event_info: dict[str, Any]
+    ) -> None:
+        """Extract sender/recipient from nested content structure.
+
+        Parameters
+        ----------
+        event_info : dict[str, Any]
+            Event information dictionary to update.
+        """
+        content = event_info.get("content", {})
+        if (
+            isinstance(content, dict)
+            and "chat_info" in content
+            and isinstance(content["chat_info"], dict)
+        ):
+            content = content.get("chat_info", {})  # pyright: ignore
+
+        if not event_info["sender"] and "sender" in content:
+            event_info["sender"] = content["sender"]
+        if not event_info["recipient"] and "recipient" in content:
+            event_info["recipient"] = content["recipient"]
+
+    def _handle_group_chat_speaker(self, event_info: dict[str, Any]) -> None:
+        """Handle speaker information for group chat events.
+
+        Parameters
+        ----------
+        event_info : dict[str, Any]
+            Event information dictionary to update.
+        """
+        if (
+            event_info.get("type") == "group_chat_run_chat"
+            and "content" in event_info
+            and isinstance(event_info["content"], dict)
+        ):
+            content = event_info.get("content", {})
+            speaker = content.get("speaker")
+            if isinstance(speaker, str) and speaker:
+                event_info["sender"] = speaker
+
+    def _extract_participants_from_direct_content(
+        self, event_info: dict[str, Any]
+    ) -> None:
+        """Extract sender/recipient directly from content dictionary.
+
+        Parameters
+        ----------
+        event_info : dict[str, Any]
+            Event information dictionary to update.
+        """
+        if "content" in event_info and isinstance(event_info["content"], dict):
+            content = event_info.get("content", {})
+
+            sender = content.get("sender", "")
+            if isinstance(sender, str) and sender:
+                event_info["sender"] = sender
+
+            recipient = content.get("recipient", "")
+            if isinstance(recipient, str) and recipient:
+                event_info["recipient"] = recipient
+
+    def _manage_event_history(self, event_info: dict[str, Any]) -> None:
+        """Add event to history and manage history size limits.
+
+        Parameters
+        ----------
+        event_info : dict[str, Any]
+            Event information to add to history.
+        """
+        self.runner.add_to_history(event_info)
+        self._trim_history_if_needed()
+
+    def _trim_history_if_needed(self) -> None:
+        """Remove oldest events from history if over size limit."""
+        current_history = self.runner.event_history
+        if len(current_history) > self.runner.max_event_history:
+            excess = len(current_history) - self.runner.max_event_history
+            for _ in range(excess):
+                self.runner.pop_event()
+
+    def _check_for_input_request(self, event_info: dict[str, Any]) -> None:
+        """Swap participant names if we have an input request."""
+        if (
+            event_info["type"] in ("input_request", "debug_input_request")
+            and "sender" in event_info
+            and "recipient" in event_info
+        ):
+            # swap them,
+            # before:
+            # "recipient" is the user (the one received the input request),
+            # make her the "sender" (the one typing...)
+            sender = event_info["sender"]
+            recipient = event_info["recipient"]
+            event_info["sender"] = recipient
+            event_info["recipient"] = sender
+            self.runner.last_sender = recipient
+            self.runner.last_recipient = sender

waldiez/running/step_by_step/step_by_step_models.py

@@ -1,11 +1,23 @@
 # SPDX-License-Identifier: Apache-2.0.
 # Copyright (c) 2024 - 2025 Waldiez and contributors.
+# pylint: disable=unused-argument,disable=line-too-long
+# flake8: noqa: E501
 """Step-by-step execution models for Waldiez."""
 
+import re
 from enum import Enum
-from typing import Annotated, Any, Dict, Literal, Union
+from typing import Annotated, Any, Literal, Union
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, ValidationInfo, field_validator
+
+
+class WaldiezBreakpointType(Enum):
+    """Types of breakpoints available."""
+
+    EVENT = "event"  # Break on specific event type
+    AGENT = "agent"  # Break on any event from specific agent
+    AGENT_EVENT = "agent_event"  # Break on specific event from specific agent
+    ALL = "all"  # Break on all events (default step mode)
 
 
 class WaldiezDebugStepAction(Enum):
@@ -41,6 +53,302 @@ VALID_CONTROL_COMMANDS = {
 }
 
 
+class WaldiezBreakpoint(BaseModel):
+    """Breakpoint definition with enhanced validation."""
+
+    type: WaldiezBreakpointType
+    event_type: str | None = None  # Required for EVENT and AGENT_EVENT
+    agent_name: str | None = None  # Required for AGENT and AGENT_EVENT
+    description: str | None = None  # Human-readable description
+
+    # noinspection PyNestedDecorators,PyUnusedLocal
+    @field_validator("event_type")
+    @classmethod
+    def validate_event_type(
+        cls,
+        v: str | None,
+        info: ValidationInfo,
+    ) -> str | None:
+        """Validate event type format.
+
+        Parameters
+        ----------
+        v : str | None
+            The event type to validate.
+        info : ValidationInfo
+            Validation context information.
+
+        Returns
+        -------
+        str | None
+            The validated event type or None if not provided.
+
+        Raises
+        ------
+        ValueError
+            If the event type format is invalid.
+        """
+        if v is None:
+            return v
+
+        # Basic validation - event types should be alphanumeric with underscores
+        if not re.match(r"^[a-zA-Z][a-zA-Z0-9_]*$", v):
+            raise ValueError(
+                "Invalid breakpoint format. Event type must start with a letter and contain only "
+                "letters, numbers, and underscores"
+            )
+        return v
+
+    # noinspection PyNestedDecorators,PyUnusedLocal
+    @field_validator("agent_name")
+    @classmethod
+    def validate_agent_name(
+        cls,
+        v: str | None,
+        info: ValidationInfo,
+    ) -> str | None:
+        """Validate agent name format.
+
+        Parameters
+        ----------
+        v : str | None
+            The agent name to validate.
+        info : ValidationInfo
+            Validation context information.
+
+        Returns
+        -------
+        str | None
+            The validated agent name or None if not provided.
+
+        Raises
+        ------
+        ValueError
+            If the agent name format is invalid.
+        """
+        if v is None:
+            return v
+
+        # Agent names should not be empty or just whitespace
+        if not v.strip():
+            raise ValueError("Agent name cannot be empty or just whitespace")
+
+        return v.strip()
+
+    def model_post_init(self, __context: Any, /) -> None:
+        """Validate breakpoint consistency after initialization.
+
+        Raises
+        ------
+        ValueError
+            If the breakpoint configuration is invalid.
+        """
+        if self.type == WaldiezBreakpointType.EVENT and not self.event_type:
+            raise ValueError("EVENT breakpoints require an event_type")
+
+        if self.type == WaldiezBreakpointType.AGENT and not self.agent_name:
+            raise ValueError("AGENT breakpoints require an agent_name")
+
+        if self.type == WaldiezBreakpointType.AGENT_EVENT:
+            if not self.event_type or not self.agent_name:
+                raise ValueError(
+                    "AGENT_EVENT breakpoints require both"
+                    " event_type and agent_name"
+                )
+
+    def __hash__(self) -> int:
+        """Get the hash value for the breakpoint."""
+        return hash((self.type, self.event_type, self.agent_name))
+
+    def __str__(self) -> str:
+        """Get the string representation for display."""
+        if self.type == WaldiezBreakpointType.EVENT:
+            return f"event:{self.event_type}"
+        if self.type == WaldiezBreakpointType.AGENT:
+            return f"agent:{self.agent_name}"
+        if self.type == WaldiezBreakpointType.AGENT_EVENT:
+            return f"{self.agent_name}:{self.event_type}"
+        # else:  # ALL
+        return "all"
+
+    # pylint: disable=too-complex
+    @classmethod
+    def from_string(  # noqa: C901
+        cls,
+        breakpoint_str: str,
+    ) -> "WaldiezBreakpoint":
+        """Parse breakpoint from string format with enhanced validation.
+
+        Parameters
+        ----------
+        breakpoint_str : str
+            The string representation of the breakpoint.
+
+        Returns
+        -------
+        WaldiezBreakpoint
+            The parsed breakpoint object.
+
+        Raises
+        ------
+        ValueError
+            If the breakpoint string format is invalid.
+        """
+        if not breakpoint_str or not isinstance(  # pyright: ignore
+            breakpoint_str,
+            str,
+        ):
+            raise ValueError("Breakpoint specification cannot be empty")
+
+        breakpoint_str = breakpoint_str.strip()
+        if not breakpoint_str:
+            raise ValueError(
+                "Breakpoint specification cannot be just whitespace"
+            )
+
+        if breakpoint_str == "all":
+            return cls(type=WaldiezBreakpointType.ALL)
+
+        if breakpoint_str.startswith("event:"):
+            event_type = breakpoint_str[6:]  # Remove "event:" prefix
+            if not event_type:
+                raise ValueError("Event type cannot be empty after 'event:'")
+            return cls(type=WaldiezBreakpointType.EVENT, event_type=event_type)
+
+        if breakpoint_str.startswith("agent:"):
+            agent_name = breakpoint_str[6:]  # Remove "agent:" prefix
+            if not agent_name:
+                raise ValueError("Agent name cannot be empty after 'agent:'")
+            return cls(type=WaldiezBreakpointType.AGENT, agent_name=agent_name)
+
+        if ":" in breakpoint_str and not breakpoint_str.startswith(
+            ("event:", "agent:")
+        ):
+            # Format: "agent_name:event_type"
+            parts = breakpoint_str.split(":", 1)
+            if len(parts) != 2:
+                raise ValueError("Invalid agent:event format")
+
+            agent_name, event_type = parts
+            if not agent_name or not event_type:
+                raise ValueError(
+                    "Both agent name and event type must be specified"
+                )
+
+            return cls(
+                type=WaldiezBreakpointType.AGENT_EVENT,
+                agent_name=agent_name,
+                event_type=event_type,
+            )
+
+        # Default to event type - but validate it's reasonable
+        if ":" in breakpoint_str:
+            raise ValueError(
+                "Invalid breakpoint format. Use 'event:type', 'agent:name', "
+                "'agent:event', or 'all'"
+            )
+
+        return cls(type=WaldiezBreakpointType.EVENT, event_type=breakpoint_str)
+
+    def matches(self, event: dict[str, Any]) -> bool:
+        """Check if this breakpoint matches the given event.
+
+        Parameters
+        ----------
+        event : dict[str, Any]
+            The event to check against.
+
+        Returns
+        -------
+        bool
+            True if the event matches the breakpoint, False otherwise.
+        """
+        if self.type == WaldiezBreakpointType.ALL:
+            return True
+
+        if self.type == WaldiezBreakpointType.EVENT:
+            return event.get("type") == self.event_type
+
+        if self.type == WaldiezBreakpointType.AGENT:
+            return (
+                event.get("sender") == self.agent_name
+                or event.get("recipient") == self.agent_name
+            )
+
+        if self.type == WaldiezBreakpointType.AGENT_EVENT:
+            return event.get("type") == self.event_type and (
+                event.get("sender") == self.agent_name
+                or event.get("recipient") == self.agent_name
+            )
+
+        # noinspection PyUnreachableCode
+        return False
+
+
+# Enhanced configuration class for runtime settings
+class WaldiezDebugConfig(BaseModel):
+    """Configuration for debug session settings."""
+
+    max_event_history: int = Field(default=1000, ge=1, le=10000)
+    auto_continue: bool = Field(default=False)
+    step_mode: bool = Field(default=True)
+    enable_stats_collection: bool = Field(default=True)
+    command_timeout_seconds: float = Field(default=300.0, gt=0)
+
+
+# Rest of the existing message classes remain the same...
+class WaldiezDebugBreakpointsList(BaseModel):
+    """Debug breakpoints message."""
+
+    type: Literal["debug_breakpoints_list"] = "debug_breakpoints_list"
+    breakpoints: (
+        list[str | WaldiezBreakpoint] | list[str] | list[WaldiezBreakpoint]
+    )
+
+    @property
+    def breakpoint_objects(self) -> list[WaldiezBreakpoint]:
+        """Get all breakpoints as WaldiezBreakpoint objects."""
+        result: list[WaldiezBreakpoint] = []
+        for bp in self.breakpoints:
+            if isinstance(bp, str):
+                try:
+                    result.append(WaldiezBreakpoint.from_string(bp))
+                except ValueError:
+                    # Skip invalid breakpoints rather than failing
+                    continue
+            else:
+                result.append(bp)
+        return result
+
+
+class WaldiezDebugBreakpointAdded(BaseModel):
+    """Debug breakpoint added message."""
+
+    type: Literal["debug_breakpoint_added"] = "debug_breakpoint_added"
+    breakpoint: Union[str, WaldiezBreakpoint]
+
+    @property
+    def breakpoint_object(self) -> WaldiezBreakpoint:
+        """Get breakpoint as WaldiezBreakpoint object."""
+        if isinstance(self.breakpoint, str):
+            return WaldiezBreakpoint.from_string(self.breakpoint)
+        return self.breakpoint
+
+
+class WaldiezDebugBreakpointRemoved(BaseModel):
+    """Debug breakpoint removed message."""
+
+    type: Literal["debug_breakpoint_removed"] = "debug_breakpoint_removed"
+    breakpoint: Union[str, WaldiezBreakpoint]
+
+    @property
+    def breakpoint_object(self) -> WaldiezBreakpoint:
+        """Get breakpoint as WaldiezBreakpoint object."""
+        if isinstance(self.breakpoint, str):
+            return WaldiezBreakpoint.from_string(self.breakpoint)
+        return self.breakpoint
+
+
 class WaldiezDebugHelpCommand(BaseModel):
     """Help command information."""
 
@@ -84,14 +392,14 @@ class WaldiezDebugEventInfo(BaseModel):
     """Debug event info message."""
 
     type: Literal["debug_event_info"] = "debug_event_info"
-    event: Dict[str, Any]
+    event: dict[str, Any]
 
 
 class WaldiezDebugStats(BaseModel):
     """Debug stats message."""
 
     type: Literal["debug_stats"] = "debug_stats"
-    stats: Dict[str, Any]
+    stats: dict[str, Any]
 
 
 class WaldiezDebugHelp(BaseModel):
@@ -108,28 +416,6 @@ class WaldiezDebugError(BaseModel):
     error: str
 
 
-class WaldiezDebugBreakpointsList(BaseModel):
-    """Debug breakpoints message."""
-
-    type: Literal["debug_breakpoints_list"] = "debug_breakpoints_list"
-    breakpoints: list[str]  # Event types
-    # Optional: Could extend to include agent+event combinations
-
-
-class WaldiezDebugBreakpointAdded(BaseModel):
-    """Debug breakpoint added message."""
-
-    type: Literal["debug_breakpoint_added"] = "debug_breakpoint_added"
-    breakpoint: str
-
-
-class WaldiezDebugBreakpointRemoved(BaseModel):
-    """Debug breakpoint removed message."""
-
-    type: Literal["debug_breakpoint_removed"] = "debug_breakpoint_removed"
-    breakpoint: str
-
-
 class WaldiezDebugBreakpointCleared(BaseModel):
     """Debug breakpoint cleared message."""
 
@@ -165,44 +451,69 @@ class WaldiezDebugMessageWrapper(BaseModel):
 HELP_MESSAGE = WaldiezDebugHelp(
     help=[
         WaldiezDebugHelpCommandGroup(
-            title="Commands",
+            title="Basic Commands",
             commands=[
                 WaldiezDebugHelpCommand(
-                    cmds=["continue", "c"], desc="Continue to the next step."
+                    cmds=["continue", "c"], desc="Continue to the next step"
                 ),
                 WaldiezDebugHelpCommand(
-                    cmds=["step", "s"], desc="Step through the next event."
+                    cmds=["step", "s"], desc="Step through the next event"
                 ),
                 WaldiezDebugHelpCommand(
-                    cmds=["run", "r"], desc="Run without stopping."
+                    cmds=["run", "r"], desc="Run without stopping"
                 ),
                 WaldiezDebugHelpCommand(
-                    cmds=["quit", "q"], desc="Quit the debugger."
+                    cmds=["quit", "q"], desc="Quit the debugger"
                 ),
                 WaldiezDebugHelpCommand(
-                    cmds=["info", "i"], desc="Show detailed event information."
+                    cmds=["info", "i"], desc="Show detailed event information"
                 ),
                 WaldiezDebugHelpCommand(
-                    cmds=["help", "h"], desc="Show this help message."
+                    cmds=["help", "h"], desc="Show this help message"
                 ),
                 WaldiezDebugHelpCommand(
-                    cmds=["stats", "st"], desc="Show execution statistics."
+                    cmds=["stats", "st"], desc="Show execution statistics"
                 ),
+            ],
+        ),
+        WaldiezDebugHelpCommandGroup(
+            title="Breakpoint Commands",
+            commands=[
                 WaldiezDebugHelpCommand(
                     cmds=["add_breakpoint", "ab"],
-                    desc="Add breakpoint for event type.",
+                    desc="Add breakpoint. Usage: 'ab [spec]' where spec is 'event:<type>', 'agent:<name>', '<name>:<event>', or 'all'",
                 ),
                 WaldiezDebugHelpCommand(
                     cmds=["remove_breakpoint", "rb"],
-                    desc="Remove breakpoint for event type.",
+                    desc="Remove breakpoint. Usage: 'rb [spec]' with same format as add",
                 ),
                 WaldiezDebugHelpCommand(
-                    cmds=["list_breakpoints", "lb"],
-                    desc="List all breakpoints.",
+                    cmds=["list_breakpoints", "lb"], desc="List all breakpoints"
                 ),
                 WaldiezDebugHelpCommand(
                     cmds=["clear_breakpoints", "cb"],
-                    desc="Clear all breakpoints.",
+                    desc="Clear all breakpoints",
+                ),
+            ],
+        ),
+        WaldiezDebugHelpCommandGroup(
+            title="Breakpoint Examples",
+            commands=[
+                WaldiezDebugHelpCommand(
+                    desc="'ab' - Add breakpoint for the current event type"
+                ),
+                WaldiezDebugHelpCommand(
+                    desc="'ab event:tool_call' - Break on all 'tool_call' events"
+                ),
+                WaldiezDebugHelpCommand(
+                    desc="'ab agent:user' - Break on any event from 'user' agent"
+                ),
+                WaldiezDebugHelpCommand(
+                    desc="'ab assistant:tool_call' - Break on 'tool_call' events from 'assistant'"
+                ),
+                WaldiezDebugHelpCommand(desc="'ab all' - Break on all events"),
+                WaldiezDebugHelpCommand(
+                    desc="'rb event:tool_call' - Remove 'tool_call' event breakpoint"
                 ),
             ],
         ),
@@ -213,10 +524,16 @@ HELP_MESSAGE = WaldiezDebugHelp(
                     desc="Press Enter alone to continue (same as 'c')"
                 ),
                 WaldiezDebugHelpCommand(
-                    desc="Use (s)tep to go through events one by one."
+                    desc="Use (s)tep to go through events one by one"
+                ),
+                WaldiezDebugHelpCommand(
+                    desc="Use (r)un to continue without stopping"
+                ),
+                WaldiezDebugHelpCommand(
+                    desc="Set specific breakpoints to avoid noise: 'ab event:message'"
                 ),
                 WaldiezDebugHelpCommand(
-                    desc="Use (r)un to continue without stopping."
+                    desc="Check (st)ats regularly to monitor progress"
                 ),
             ],
         ),