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

waldiez/running/step_by_step/breakpoints_mixin.py

@@ -0,0 +1,188 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+# pylint: disable=unused-argument
+"""Breakpoints management mixin for step-by-step debugging."""
+
+from typing import TYPE_CHECKING, Any, Iterable, Union
+
+from .step_by_step_models import (
+    WaldiezDebugBreakpointAdded,
+    WaldiezDebugBreakpointCleared,
+    WaldiezDebugBreakpointRemoved,
+    WaldiezDebugBreakpointsList,
+    WaldiezDebugError,
+    WaldiezDebugMessage,
+)
+
+if TYPE_CHECKING:
+    from autogen.events import BaseEvent  # type: ignore
+    from autogen.messages import BaseMessage  # type: ignore
+
+
+class BreakpointsMixin:
+    """Mixin class for managing breakpoints in step-by-step debugging."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Initialize breakpoints storage."""
+        self._breakpoints: set[str] = set()
+
+    def emit(self, message: WaldiezDebugMessage) -> None:
+        """Emit a debug message. Implemented by the class using this mixin.
+
+        Parameters
+        ----------
+        message : WaldiezDebugMessage
+            The debug message to emit.
+        """
+        raise NotImplementedError("emit method must be implemented")
+
+    def add_breakpoint(self, event_type: str) -> None:
+        """Add a breakpoint for an event type.
+
+        Parameters
+        ----------
+        event_type : str
+            The event type to add a breakpoint for.
+        """
+        if not event_type or not isinstance(event_type, str):  # pyright: ignore
+            self.emit(
+                WaldiezDebugError(
+                    error="Invalid event type: must be a non-empty string"
+                )
+            )
+            return
+
+        self._breakpoints.add(event_type)
+        self.emit(WaldiezDebugBreakpointAdded(breakpoint=event_type))
+
+    def remove_breakpoint(self, event_type: str) -> bool:
+        """Remove a breakpoint for an event type.
+
+        Parameters
+        ----------
+        event_type : str
+            The event type to remove the breakpoint for.
+
+        Returns
+        -------
+        bool
+            True if the breakpoint was removed, False if it didn't exist.
+        """
+        if not event_type or not isinstance(event_type, str):  # pyright: ignore
+            self.emit(
+                WaldiezDebugError(
+                    error="Invalid event type: must be a non-empty string"
+                )
+            )
+            return False
+
+        if event_type in self._breakpoints:
+            self._breakpoints.remove(event_type)
+            self.emit(WaldiezDebugBreakpointRemoved(breakpoint=event_type))
+            return True
+        self.emit(
+            WaldiezDebugError(
+                error=f"Breakpoint for '{event_type}' does not exist"
+            )
+        )
+        return False
+
+    def list_breakpoints(self) -> None:
+        """List all current breakpoints."""
+        self.emit(
+            WaldiezDebugBreakpointsList(breakpoints=sorted(self._breakpoints))
+        )
+
+    def clear_breakpoints(self) -> None:
+        """Clear all breakpoints."""
+        count = len(self._breakpoints)
+        self._breakpoints.clear()
+        if count > 0:
+            self.emit(
+                WaldiezDebugBreakpointCleared(
+                    message=f"Cleared {count} breakpoint(s)"
+                )
+            )
+
+    def set_breakpoints(self, event_types: Iterable[str]) -> None:
+        """Set which event types to break on.
+
+        Parameters
+        ----------
+        event_types : Iterable[str]
+            Iterable of event types to break on. Empty means break on all.
+        """
+        self._breakpoints = set(event_types)
+
+    def get_breakpoints(self) -> set[str]:
+        """Get current breakpoints.
+
+        Returns
+        -------
+        set[str]
+            Set of current breakpoint event types.
+        """
+        return self._breakpoints.copy()
+
+    def has_breakpoint(self, event_type: str) -> bool:
+        """Check if a breakpoint exists for an event type.
+
+        Parameters
+        ----------
+        event_type : str
+            The event type to check.
+
+        Returns
+        -------
+        bool
+            True if a breakpoint exists for this event type.
+        """
+        return event_type in self._breakpoints
+
+    def should_break_on_event(
+        self, event: Union["BaseEvent", "BaseMessage"], step_mode: bool = True
+    ) -> bool:
+        """Determine if we should break on this event.
+
+        Parameters
+        ----------
+        event : Union[BaseEvent, BaseMessage]
+            The event to check.
+        step_mode : bool, optional
+            Whether step mode is enabled, by default True.
+
+        Returns
+        -------
+        bool
+            True if we should break, False otherwise.
+        """
+        if not step_mode:
+            return False
+
+        # Get event type
+        event_type = getattr(event, "type", "unknown")
+
+        # Don't break on input requests - they're handled separately
+        if event_type == "input_request":
+            return False
+
+        # If no specific breakpoints set, break on all events
+        if not self._breakpoints:
+            return True
+
+        # Check if this event type has a breakpoint
+        return event_type in self._breakpoints
+
+    def get_breakpoint_stats(self) -> dict[str, Any]:
+        """Get breakpoint statistics.
+
+        Returns
+        -------
+        dict[str, Any]
+            Dictionary containing breakpoint statistics.
+        """
+        return {
+            "total_breakpoints": len(self._breakpoints),
+            "breakpoints": sorted(self._breakpoints),
+            "has_breakpoints": len(self._breakpoints) > 0,
+        }

waldiez/running/step_by_step/step_by_step_models.py

@@ -0,0 +1,224 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Step-by-step execution models for Waldiez."""
+
+from enum import Enum
+from typing import Annotated, Any, Dict, Literal, Union
+
+from pydantic import BaseModel, Field
+
+
+class WaldiezDebugStepAction(Enum):
+    """Available actions during step-by-step execution."""
+
+    CONTINUE = "c"  # Continue to next event
+    STEP = "s"  # Step through (same as continue, but explicit)
+    RUN = "r"  # Run without stopping (disable step mode)
+    QUIT = "q"  # Quit execution
+    INFO = "i"  # Show detailed event information
+    HELP = "h"  # Show help
+    STATS = "st"  # Show execution statistics
+    ADD_BREAKPOINT = "ab"  # Add a breakpoint
+    REMOVE_BREAKPOINT = "rb"  # Remove a breakpoint
+    LIST_BREAKPOINTS = "lb"  # List all breakpoints
+    CLEAR_BREAKPOINTS = "cb"  # Clear all breakpoints
+    UNKNOWN = "unknown"  # Unknown command
+
+
+VALID_CONTROL_COMMANDS = {
+    "",  # continue/step (allow empty input)
+    "c",  # continue
+    "r",  # run
+    "s",  # step
+    "h",  # help
+    "q",  # quit
+    "i",  # info
+    "st",  # stats
+    "ab",  # add_breakpoint
+    "rb",  # remove_breakpoint
+    "lb",  # list_breakpoints
+    "cb",  # clear_breakpoints
+}
+
+
+class WaldiezDebugHelpCommand(BaseModel):
+    """Help command information."""
+
+    cmds: list[str] = Field(
+        default_factory=list, description="List of command aliases"
+    )
+    desc: str
+
+
+class WaldiezDebugHelpCommandGroup(BaseModel):
+    """Help command group information."""
+
+    title: str
+    commands: list[WaldiezDebugHelpCommand]
+
+
+class WaldiezDebugPrint(BaseModel):
+    """Debug print message."""
+
+    type: Literal["debug_print"] = "debug_print"
+    content: str
+
+
+class WaldiezDebugInputRequest(BaseModel):
+    """Debug input request message."""
+
+    type: Literal["debug_input_request"] = "debug_input_request"
+    prompt: str
+    request_id: str
+
+
+class WaldiezDebugInputResponse(BaseModel):
+    """Debug input response message."""
+
+    type: Literal["debug_input_response"] = "debug_input_response"
+    request_id: str
+    data: str
+
+
+class WaldiezDebugEventInfo(BaseModel):
+    """Debug event info message."""
+
+    type: Literal["debug_event_info"] = "debug_event_info"
+    event: Dict[str, Any]
+
+
+class WaldiezDebugStats(BaseModel):
+    """Debug stats message."""
+
+    type: Literal["debug_stats"] = "debug_stats"
+    stats: Dict[str, Any]
+
+
+class WaldiezDebugHelp(BaseModel):
+    """Debug help message."""
+
+    type: Literal["debug_help"] = "debug_help"
+    help: list[WaldiezDebugHelpCommandGroup]
+
+
+class WaldiezDebugError(BaseModel):
+    """Debug error message."""
+
+    type: Literal["debug_error"] = "debug_error"
+    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."""
+
+    type: Literal["debug_breakpoint_cleared"] = "debug_breakpoint_cleared"
+    message: str
+
+
+WaldiezDebugMessage = Annotated[
+    Union[
+        WaldiezDebugPrint,
+        WaldiezDebugInputRequest,
+        WaldiezDebugInputResponse,
+        WaldiezDebugEventInfo,
+        WaldiezDebugStats,
+        WaldiezDebugHelp,
+        WaldiezDebugError,
+        WaldiezDebugBreakpointsList,
+        WaldiezDebugBreakpointAdded,
+        WaldiezDebugBreakpointRemoved,
+        WaldiezDebugBreakpointCleared,
+    ],
+    Field(discriminator="type"),
+]
+
+
+class WaldiezDebugMessageWrapper(BaseModel):
+    """Wrapper for debug messages."""
+
+    # noinspection PyTypeHints
+    message: WaldiezDebugMessage
+
+
+HELP_MESSAGE = WaldiezDebugHelp(
+    help=[
+        WaldiezDebugHelpCommandGroup(
+            title="Commands",
+            commands=[
+                WaldiezDebugHelpCommand(
+                    cmds=["continue", "c"], desc="Continue to the next step."
+                ),
+                WaldiezDebugHelpCommand(
+                    cmds=["step", "s"], desc="Step through the next event."
+                ),
+                WaldiezDebugHelpCommand(
+                    cmds=["run", "r"], desc="Run without stopping."
+                ),
+                WaldiezDebugHelpCommand(
+                    cmds=["quit", "q"], desc="Quit the debugger."
+                ),
+                WaldiezDebugHelpCommand(
+                    cmds=["info", "i"], desc="Show detailed event information."
+                ),
+                WaldiezDebugHelpCommand(
+                    cmds=["help", "h"], desc="Show this help message."
+                ),
+                WaldiezDebugHelpCommand(
+                    cmds=["stats", "st"], desc="Show execution statistics."
+                ),
+                WaldiezDebugHelpCommand(
+                    cmds=["add_breakpoint", "ab"],
+                    desc="Add breakpoint for event type.",
+                ),
+                WaldiezDebugHelpCommand(
+                    cmds=["remove_breakpoint", "rb"],
+                    desc="Remove breakpoint for event type.",
+                ),
+                WaldiezDebugHelpCommand(
+                    cmds=["list_breakpoints", "lb"],
+                    desc="List all breakpoints.",
+                ),
+                WaldiezDebugHelpCommand(
+                    cmds=["clear_breakpoints", "cb"],
+                    desc="Clear all breakpoints.",
+                ),
+            ],
+        ),
+        WaldiezDebugHelpCommandGroup(
+            title="Tips",
+            commands=[
+                WaldiezDebugHelpCommand(
+                    desc="Press Enter alone to continue (same as 'c')"
+                ),
+                WaldiezDebugHelpCommand(
+                    desc="Use (s)tep to go through events one by one."
+                ),
+                WaldiezDebugHelpCommand(
+                    desc="Use (r)un to continue without stopping."
+                ),
+            ],
+        ),
+    ]
+)