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

waldiez/running/step_by_step/breakpoints_mixin.py

@@ -0,0 +1,512 @@
+# 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."""
+
+import logging
+from functools import lru_cache
+from typing import TYPE_CHECKING, Any, Callable, Iterable, Union
+
+from .step_by_step_models import (
+    WaldiezBreakpoint,
+    WaldiezDebugBreakpointAdded,
+    WaldiezDebugBreakpointCleared,
+    WaldiezDebugBreakpointRemoved,
+    WaldiezDebugBreakpointsList,
+    WaldiezDebugError,
+    WaldiezDebugMessage,
+)
+
+if TYPE_CHECKING:
+    from autogen.events import BaseEvent  # type: ignore
+    from autogen.messages import BaseMessage  # type: ignore
+
+
+def handle_breakpoint_errors(func: Callable[..., bool]) -> Callable[..., bool]:
+    """Handle breakpoint-related errors.
+
+    Parameters
+    ----------
+    func : Callable
+        The function to decorate.
+
+    Returns
+    -------
+    Callable
+        The decorated function.
+    """
+
+    def _wrapper(self: "BreakpointsMixin", *args: Any, **kwargs: Any) -> bool:
+        try:
+            return func(self, *args, **kwargs)
+        except ValueError as e:
+            self.emit(WaldiezDebugError(error=f"Breakpoint error: {e}"))
+            return False
+        except Exception as e:  # pylint: disable=broad-exception-caught
+            self.emit(
+                WaldiezDebugError(
+                    error=f"Unexpected error in {func.__name__}: {e}"
+                )
+            )
+            logging.exception("Error in %s", func.__name__)
+            return False
+
+    return _wrapper
+
+
+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[WaldiezBreakpoint] = set()
+
+        # Statistics for monitoring
+        self._breakpoint_stats = {
+            "total_matches": 0,
+            "cache_hits": 0,
+            "cache_misses": 0,
+        }
+
+        # Create the cached function with proper binding
+        self._check_breakpoint_match_cached = lru_cache(maxsize=1000)(
+            self._check_breakpoint_match_impl
+        )
+
+    # noinspection PyTypeHints
+    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 _invalidate_cache(self) -> None:
+        """Invalidate the event matching cache when breakpoints change."""
+        self._check_breakpoint_match_cached.cache_clear()
+
+    def _get_breakpoints_signature(self) -> frozenset[str]:
+        """Get a hashable signature of current breakpoints."""
+        return frozenset(str(bp) for bp in self._breakpoints)
+
+    def _check_breakpoint_match_impl(
+        self,
+        event_type: str,
+        sender: str,
+        recipient: str,
+        breakpoints_sig: frozenset[str],
+    ) -> bool:
+        """Check if the event matches any breakpoints.
+
+        Parameters
+        ----------
+        event_type : str
+            The event type to check.
+        sender : str
+            The event sender.
+        recipient : str
+            The event recipient.
+        breakpoints_sig : frozenset[str]
+            Signature of current breakpoints for cache invalidation.
+
+        Returns
+        -------
+        bool
+            True if any breakpoint matches, False otherwise.
+        """
+        event_dict = {
+            "type": event_type,
+            "sender": sender,
+            "recipient": recipient,
+        }
+
+        # Reconstruct breakpoints from signature for cache safety
+        # noinspection PyBroadException
+        try:
+            breakpoints = {
+                WaldiezBreakpoint.from_string(bp_str)
+                for bp_str in breakpoints_sig
+            }
+            return any(bp.matches(event_dict) for bp in breakpoints)
+        except Exception:  # pylint: disable=broad-exception-caught
+            # Fallback to current breakpoints if signature is malformed
+            return any(bp.matches(event_dict) for bp in self._breakpoints)
+
+    @handle_breakpoint_errors
+    def add_breakpoint(self, spec: str) -> bool:
+        """Add a breakpoint for an event type.
+
+        Parameters
+        ----------
+        spec : str
+            The event type specification to add a breakpoint for.
+
+        Returns
+        -------
+        bool
+            True if the breakpoint was added successfully, False otherwise.
+        """
+        if not spec or not isinstance(spec, str):  # pyright: ignore
+            self.emit(
+                WaldiezDebugError(
+                    error="Invalid event type: must be a non-empty string"
+                )
+            )
+            return False
+        # pylint: disable=too-many-try-statements
+        try:
+            breakpoint_obj = WaldiezBreakpoint.from_string(spec)
+
+            # Check if breakpoint already exists
+            if breakpoint_obj in self._breakpoints:
+                self.emit(
+                    WaldiezDebugError(
+                        error=f"Breakpoint for '{spec}' already exists"
+                    )
+                )
+                return False
+
+            self._breakpoints.add(breakpoint_obj)
+            self._invalidate_cache()
+            self.emit(WaldiezDebugBreakpointAdded(breakpoint=spec))
+            return True
+
+        except ValueError as e:
+            self.emit(
+                WaldiezDebugError(error=f"Invalid breakpoint format: {e}")
+            )
+            return False
+
+    @handle_breakpoint_errors
+    def remove_breakpoint(self, spec: str | WaldiezBreakpoint) -> bool:
+        """Remove a breakpoint based on its specification.
+
+        Parameters
+        ----------
+        spec : str | WaldiezBreakpoint
+            The event type to remove the breakpoint for.
+
+        Returns
+        -------
+        bool
+            True if the breakpoint was removed, False if it didn't exist.
+        """
+        if isinstance(spec, WaldiezBreakpoint):
+            breakpoint_obj = spec
+            spec_str = str(spec)
+        elif isinstance(spec, str) and spec:  # pyright: ignore
+            try:
+                breakpoint_obj = WaldiezBreakpoint.from_string(spec)
+                spec_str = spec
+            except ValueError as e:
+                self.emit(
+                    WaldiezDebugError(error=f"Invalid breakpoint format: {e}")
+                )
+                return False
+        else:
+            self.emit(
+                WaldiezDebugError(error="Invalid breakpoint specification")
+            )
+            return False
+
+        if breakpoint_obj in self._breakpoints:
+            self._breakpoints.remove(breakpoint_obj)
+            self._invalidate_cache()
+            self.emit(WaldiezDebugBreakpointRemoved(breakpoint=spec_str))
+            return True
+
+        self.emit(
+            WaldiezDebugError(
+                error=f"Breakpoint for '{spec_str}' does not exist"
+            )
+        )
+        return False
+
+    def list_breakpoints(self) -> None:
+        """List all current breakpoints."""
+        breakpoints_list = sorted(self._breakpoints, key=str)
+        self.emit(WaldiezDebugBreakpointsList(breakpoints=breakpoints_list))
+
+    def clear_breakpoints(self) -> None:
+        """Clear all breakpoints."""
+        count = len(self._breakpoints)
+        self._breakpoints.clear()
+        self._invalidate_cache()
+
+        if count > 0:
+            self.emit(
+                WaldiezDebugBreakpointCleared(
+                    message=f"Cleared {count} breakpoint(s)"
+                )
+            )
+        else:
+            self.emit(
+                WaldiezDebugBreakpointCleared(message="No breakpoints to clear")
+            )
+
+    @handle_breakpoint_errors
+    def set_breakpoints(self, specs: Iterable[str | WaldiezBreakpoint]) -> bool:
+        """Set which breakpoints to activate.
+
+        Parameters
+        ----------
+        specs : Iterable[str | WaldiezBreakpoint]
+            Iterable of event types to break on. Empty means no breakpoints.
+
+        Returns
+        -------
+        bool
+            True if all breakpoints were set successfully, False if any failed.
+        """
+        new_breakpoints: set[WaldiezBreakpoint] = set()
+        errors: list[str] = []
+
+        for spec in specs:
+            try:
+                if isinstance(spec, WaldiezBreakpoint):
+                    new_breakpoints.add(spec)
+                else:
+                    new_breakpoints.add(WaldiezBreakpoint.from_string(spec))
+            except ValueError as e:
+                errors.append(f"Invalid breakpoint '{spec}': {e}")
+
+        if errors:
+            for error in errors:
+                self.emit(WaldiezDebugError(error=error))
+            return False
+
+        old_count = len(self._breakpoints)
+        self._breakpoints = new_breakpoints
+        new_count = len(self._breakpoints)
+        self._invalidate_cache()
+
+        self.emit(
+            WaldiezDebugBreakpointCleared(
+                message=f"Updated breakpoints: {old_count} -> {new_count}"
+            )
+        )
+        return True
+
+    def get_breakpoints(self) -> set[WaldiezBreakpoint]:
+        """Get current breakpoints.
+
+        Returns
+        -------
+        set[WaldiezBreakpoint]
+            Set of current breakpoint event types.
+        """
+        return self._breakpoints.copy()
+
+    def has_breakpoint(self, spec: str | WaldiezBreakpoint) -> bool:
+        """Check if a breakpoint exists.
+
+        Parameters
+        ----------
+        spec : str | WaldiezBreakpoint
+            The breakpoint specification to check.
+
+        Returns
+        -------
+        bool
+            True if a breakpoint exists for this event type.
+        """
+        try:
+            if isinstance(spec, WaldiezBreakpoint):
+                return spec in self._breakpoints
+            return WaldiezBreakpoint.from_string(spec) in self._breakpoints
+        except ValueError:
+            return False
+
+    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.
+        """
+        # 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
+
+        # Quick path: if no breakpoints and not in step mode, don't break
+        if not self._breakpoints and not step_mode:
+            return False
+
+        # Quick path: if step mode and no specific breakpoints,
+        # break on everything
+        if step_mode and not self._breakpoints:
+            return True
+
+        # Check if this event matches any breakpoint using caching
+        if hasattr(event, "model_dump"):
+            # pylint: disable=too-many-try-statements,broad-exception-caught
+            try:
+                event_dict = event.model_dump(
+                    mode="python", exclude_none=True, fallback=str
+                )
+
+                # Extract event details for cache key
+                event_type_key = event_dict.get("type", "unknown")
+                sender = event_dict.get("sender", "")
+                recipient = event_dict.get("recipient", "")
+
+                # Get current breakpoints signature for cache invalidation
+                breakpoints_sig = self._get_breakpoints_signature()
+
+                # Check cached result
+                # noinspection PyBroadException
+                try:
+                    matches_breakpoint = self._check_breakpoint_match_cached(
+                        event_type_key, sender, recipient, breakpoints_sig
+                    )
+                    self._breakpoint_stats["cache_hits"] += 1
+                except Exception:
+                    # Fallback to non-cached check
+                    matches_breakpoint = any(
+                        bp.matches(event_dict) for bp in self._breakpoints
+                    )
+                    self._breakpoint_stats["cache_misses"] += 1
+
+                self._breakpoint_stats["total_matches"] += 1
+
+                # If any breakpoint matches: break regardless of step_mode
+                if matches_breakpoint:
+                    return True
+
+            except Exception as e:  # pylint: disable=broad-exception-caught
+                logging.warning("Error processing event for breakpoints: %s", e)
+                self._breakpoint_stats["cache_misses"] += 1
+
+        # No specific breakpoints matched:
+        # - If step_mode, break on every event (single-step behavior)
+        # - If not step_mode, do not break
+        return bool(step_mode)
+
+    def get_breakpoint_stats(self) -> dict[str, Any]:
+        """Get breakpoint statistics including performance metrics.
+
+        Returns
+        -------
+        dict[str, Any]
+            Dictionary containing breakpoint statistics.
+        """
+        breakpoints: list[dict[str, Any]] = [
+            {
+                "type": bp.type.value,
+                "event_type": bp.event_type,
+                "agent_name": bp.agent_name,
+                "description": bp.description,
+                "string_repr": str(bp),
+            }
+            for bp in self._breakpoints
+        ]
+
+        # Calculate cache efficiency
+        total_checks = (
+            self._breakpoint_stats["cache_hits"]
+            + self._breakpoint_stats["cache_misses"]
+        )
+        cache_hit_rate = (
+            self._breakpoint_stats["cache_hits"] / total_checks
+            if total_checks > 0
+            else 0
+        )
+
+        # Get cache info from lru_cache
+        cache_info = self._check_breakpoint_match_cached.cache_info()
+
+        return {
+            "total_breakpoints": len(self._breakpoints),
+            "breakpoints": breakpoints,
+            "has_breakpoints": len(self._breakpoints) > 0,
+            "cache_stats": {
+                "cache_hit_rate": f"{cache_hit_rate:.2%}",
+                "cache_size": cache_info.currsize,
+                "cache_maxsize": cache_info.maxsize,
+                "total_matches": self._breakpoint_stats["total_matches"],
+                "cache_hits": cache_info.hits,
+                "cache_misses": cache_info.misses,
+            },
+            "performance": {
+                "lru_cache_info": {
+                    "hits": cache_info.hits,
+                    "misses": cache_info.misses,
+                    "maxsize": cache_info.maxsize,
+                    "currsize": cache_info.currsize,
+                }
+            },
+        }
+
+    def reset_stats(self) -> None:
+        """Reset breakpoint statistics."""
+        self._breakpoint_stats = {
+            "total_matches": 0,
+            "cache_hits": 0,
+            "cache_misses": 0,
+        }
+        self._invalidate_cache()
+
+    def optimize_cache(self) -> None:
+        """Manually optimize the cache by clearing it."""
+        self._invalidate_cache()
+
+    def export_breakpoints(self) -> list[str]:
+        """Export breakpoints as a list of strings for persistence.
+
+        Returns
+        -------
+        list[str]
+            List of breakpoint specifications as strings.
+        """
+        return [str(bp) for bp in sorted(self._breakpoints, key=str)]
+
+    def import_breakpoints(
+        self, breakpoint_specs: list[str]
+    ) -> tuple[int, list[str]]:
+        """Import breakpoints from a list of string specifications.
+
+        Parameters
+        ----------
+        breakpoint_specs : list[str]
+            List of breakpoint specifications as strings.
+
+        Returns
+        -------
+        tuple[int, list[str]]
+            Tuple of (successful_imports, error_messages).
+        """
+        successful = 0
+        errors: list[str] = []
+
+        for spec in breakpoint_specs:
+            # pylint: disable=too-many-try-statements
+            try:
+                breakpoint_obj = WaldiezBreakpoint.from_string(spec)
+                if breakpoint_obj not in self._breakpoints:
+                    self._breakpoints.add(breakpoint_obj)
+                    successful += 1
+                else:
+                    errors.append(f"Breakpoint '{spec}' already exists")
+            except ValueError as e:
+                errors.append(f"Invalid breakpoint '{spec}': {e}")
+
+        if successful > 0:
+            self._invalidate_cache()
+
+        return successful, errors

waldiez/running/step_by_step/command_handler.py

@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+# pylint: disable=unused-argument
+"""Command handler for step-by-step execution."""
+
+from typing import TYPE_CHECKING, Callable
+
+from .step_by_step_models import (
+    HELP_MESSAGE,
+    WaldiezDebugError,
+    WaldiezDebugStepAction,
+)
+
+if TYPE_CHECKING:
+    # noinspection PyUnusedImports
+    from .step_by_step_runner import WaldiezStepByStepRunner
+
+
+# pylint: disable=too-few-public-methods
+class CommandHandler:
+    """Handler for debug commands to reduce complexity in main runner."""
+
+    def __init__(self, runner: "WaldiezStepByStepRunner"):
+        self.runner = runner
+        self._command_map: dict[
+            str, Callable[[str | None], WaldiezDebugStepAction]
+        ] = {
+            "c": self._handle_continue,
+            "s": self._handle_step,
+            "r": self._handle_run,
+            "q": self._handle_quit,
+            "i": self._handle_info,
+            "h": self._handle_help,
+            "st": self._handle_stats,
+            "ab": self._handle_add_breakpoint,
+            "rb": self._handle_remove_breakpoint,
+            "lb": self._handle_list_breakpoints,
+            "cb": self._handle_clear_breakpoints,
+        }
+
+    def handle_command(self, command_line: str) -> WaldiezDebugStepAction:
+        """Handle a command line input.
+
+        Parameters
+        ----------
+        command_line : str
+            The command line input to handle.
+
+        Returns
+        -------
+        WaldiezDebugStepAction
+            The action to take for the command.
+        """
+        if not command_line or not command_line.strip():
+            return self._handle_step(None)  # Enter = step
+        parts = command_line.strip().split(maxsplit=1)
+        if not parts or not parts[0]:
+            return self._handle_unknown(None)
+        command = parts[0].lower()
+        args = parts[1] if len(parts) > 1 else None
+
+        handler = self._command_map.get(command, self._handle_unknown)
+        return handler(args)
+
+    def _handle_continue(self, args: str | None) -> WaldiezDebugStepAction:
+        self.runner.step_mode = True
+        return WaldiezDebugStepAction.CONTINUE
+
+    def _handle_step(self, args: str | None) -> WaldiezDebugStepAction:
+        self.runner.step_mode = True
+        return WaldiezDebugStepAction.STEP
+
+    def _handle_run(self, args: str | None) -> WaldiezDebugStepAction:
+        self.runner.step_mode = False
+        return WaldiezDebugStepAction.RUN
+
+    def _handle_quit(self, args: str | None) -> WaldiezDebugStepAction:
+        self.runner.set_stop_requested()
+        return WaldiezDebugStepAction.QUIT
+
+    def _handle_info(self, args: str | None) -> WaldiezDebugStepAction:
+        self.runner.show_event_info()
+        return WaldiezDebugStepAction.INFO
+
+    def _handle_help(self, args: str | None) -> WaldiezDebugStepAction:
+        self.runner.emit(HELP_MESSAGE)
+        return WaldiezDebugStepAction.HELP
+
+    def _handle_stats(self, args: str | None) -> WaldiezDebugStepAction:
+        self.runner.show_stats()
+        return WaldiezDebugStepAction.STATS
+
+    def _handle_add_breakpoint(
+        self, args: str | None
+    ) -> WaldiezDebugStepAction:
+        if args:
+            self.runner.add_breakpoint(args)
+            return WaldiezDebugStepAction.ADD_BREAKPOINT
+        current_event = self.runner.current_event
+        if current_event and hasattr(current_event, "type"):
+            self.runner.add_breakpoint(getattr(current_event, "type", ""))
+            return WaldiezDebugStepAction.ADD_BREAKPOINT
+        # else:
+        self.runner.emit(
+            WaldiezDebugError(
+                error=(
+                    "No breakpoint specification provided "
+                    "and no current event available"
+                )
+            )
+        )
+        return WaldiezDebugStepAction.ADD_BREAKPOINT
+
+    def _handle_remove_breakpoint(
+        self, args: str | None
+    ) -> WaldiezDebugStepAction:
+        if args:
+            self.runner.remove_breakpoint(args)
+            return WaldiezDebugStepAction.REMOVE_BREAKPOINT
+        current_event = self.runner.current_event
+        if current_event and hasattr(current_event, "type"):
+            self.runner.remove_breakpoint(getattr(current_event, "type", ""))
+            return WaldiezDebugStepAction.REMOVE_BREAKPOINT
+        # else:
+        self.runner.emit(
+            WaldiezDebugError(
+                error=(
+                    "No breakpoint specification provided and "
+                    "no current event available"
+                )
+            )
+        )
+        return WaldiezDebugStepAction.REMOVE_BREAKPOINT
+
+    def _handle_list_breakpoints(
+        self, args: str | None
+    ) -> WaldiezDebugStepAction:
+        self.runner.list_breakpoints()
+        return WaldiezDebugStepAction.LIST_BREAKPOINTS
+
+    def _handle_clear_breakpoints(
+        self, args: str | None
+    ) -> WaldiezDebugStepAction:
+        self.runner.clear_breakpoints()
+        return WaldiezDebugStepAction.CLEAR_BREAKPOINTS
+
+    def _handle_unknown(self, args: str | None) -> WaldiezDebugStepAction:
+        self.runner.emit(
+            WaldiezDebugError(error="Unknown command. Use 'h' for help")
+        )
+        return WaldiezDebugStepAction.UNKNOWN