janito 3.3.0__py3-none-any.whl → 3.5.0__py3-none-any.whl

janito/tools/loop_protection_decorator.py

@@ -1,143 +1,140 @@
 import functools
 import time
 import threading
-from typing import Callable, Any
-from janito.tools.loop_protection import LoopProtection
-from janito.tools.tool_use_tracker import normalize_path
-
+from typing import Any, Tuple
 
 # Global tracking for decorator-based loop protection
 _decorator_call_tracker = {}
 _decorator_call_tracker_lock = threading.Lock()
 
 
+def _normalize_key_value(key_field: str, key_value: Any) -> Any:
+    """Normalize key values, especially paths, so different representations map to the same key."""
+    if key_value is None:
+        return None
+
+    try:
+        if isinstance(key_field, str) and "path" in key_field.lower():
+            from janito.tools.tool_use_tracker import (
+                normalize_path as _norm,  # reuse existing normalization
+            )
+
+            if isinstance(key_value, str):
+                return _norm(key_value)
+            if isinstance(key_value, (list, tuple)):
+                return tuple(_norm(v) if isinstance(v, str) else v for v in key_value)
+    except Exception:
+        # Best-effort normalization – fall back to original value
+        pass
+
+    return key_value
+
+
+def _get_param_value(func, args, kwargs, key_field: str):
+    """Extract the watched parameter value from args/kwargs using function signature."""
+    if key_field in kwargs:
+        return kwargs[key_field]
+
+    # Handle positional arguments by mapping to parameter names
+    if len(args) > 1:  # args[0] is self
+        import inspect
+
+        try:
+            sig = inspect.signature(func)
+            param_names = list(sig.parameters.keys())
+            if key_field in param_names:
+                idx = param_names.index(key_field)
+                if idx < len(args):
+                    return args[idx]
+        except Exception:
+            return None
+
+    return None
+
+
+def _determine_operation_name(func, args, kwargs, key_field: str) -> str:
+    """Build the operation name for rate limiting, optionally including a normalized key value."""
+    if key_field:
+        raw_value = _get_param_value(func, args, kwargs, key_field)
+        if raw_value is not None:
+            norm_value = _normalize_key_value(key_field, raw_value)
+            return f"{func.__name__}_{norm_value}"
+    return func.__name__
+
+
+def _check_and_record(
+    op_name: str,
+    current_time: float,
+    time_window: float,
+    max_calls: int,
+    tool_instance: Any,
+) -> Tuple[bool, str]:
+    """Check loop limits for op_name and record the call. Returns (exceeded, message)."""
+    with _decorator_call_tracker_lock:
+        # Clean old timestamps
+        if op_name in _decorator_call_tracker:
+            _decorator_call_tracker[op_name] = [
+                ts
+                for ts in _decorator_call_tracker[op_name]
+                if current_time - ts <= time_window
+            ]
+
+        # Check limit
+        if (
+            op_name in _decorator_call_tracker
+            and len(_decorator_call_tracker[op_name]) >= max_calls
+        ):
+            if all(
+                current_time - ts <= time_window
+                for ts in _decorator_call_tracker[op_name]
+            ):
+                msg = (
+                    f"Loop protection: Too many {op_name} operations in a short time period "
+                    f"({max_calls} calls in {time_window}s). Please try a different approach or wait before retrying."
+                )
+                if hasattr(tool_instance, "report_error"):
+                    try:
+                        tool_instance.report_error(msg)
+                    except Exception:
+                        pass
+                return True, msg
+
+        # Record this call
+        if op_name not in _decorator_call_tracker:
+            _decorator_call_tracker[op_name] = []
+        _decorator_call_tracker[op_name].append(current_time)
+
+    return False, ""
+
+
 def protect_against_loops(
     max_calls: int = 5, time_window: float = 10.0, key_field: str = None
 ):
     """
     Decorator that adds loop protection to tool run methods.
 
-    This decorator monitors tool executions and prevents excessive calls within
-    a configurable time window. It helps prevent infinite loops or excessive
-    resource consumption when tools are called repeatedly.
-
-    When the configured limits are exceeded, the decorator raises a RuntimeError
-    with a descriptive message. This exception will propagate up the call stack
-    unless caught by a try/except block in the calling code.
-
-    The decorator works by:
-    1. Tracking the number of calls to the decorated function
-    2. Checking if the calls exceed the configured limits
-    3. Raising a RuntimeError if a potential loop is detected
-    4. Allowing the method to proceed normally if the operation is safe
-
-    Args:
-        max_calls (int): Maximum number of calls allowed within the time window.
-                        Defaults to 5 calls.
-        time_window (float): Time window in seconds for detecting excessive calls.
-                            Defaults to 10.0 seconds.
-        key_field (str, optional): The parameter name to use for key matching instead of function name.
-                                 If provided, the decorator will track calls based on the value of this
-                                 parameter rather than the function name. Useful for tools that operate
-                                 on specific files or resources.
-
-    Example:
-        >>> @protect_against_loops(max_calls=3, time_window=5.0)
-        >>> def run(self, path: str) -> str:
-        >>>     # Implementation here
-        >>>     pass
-
-        >>> @protect_against_loops(max_calls=10, time_window=30.0)
-        >>> def run(self, file_paths: list) -> str:
-        >>>     # Implementation here
-        >>>     pass
-
-        >>> @protect_against_loops(max_calls=5, time_window=10.0, key_field='path')
-        >>> def run(self, path: str) -> str:
-        >>>     # This will track calls per unique path value
-        >>>     pass
-
-    Note:
-        When loop protection is triggered, a RuntimeError will be raised with a
-        descriptive message. This exception will propagate up the call stack
-        unless caught by a try/except block in the calling code.
+    Tracks calls within a sliding time window and prevents excessive repeated operations.
+    When key_field is provided, the limit is applied per unique normalized value of that parameter
+    (e.g., per-path protection for file tools).
     """
 
     def decorator(func):
         @functools.wraps(func)
         def wrapper(*args, **kwargs):
-            # Get the tool instance (self)
+            # Methods should always have self; if not, execute directly.
             if not args:
-                # This shouldn't happen in normal usage as methods need self
                 return func(*args, **kwargs)
 
-            # Determine the operation key
-            if key_field:
-                # Use the key_field parameter value as the operation key
-                key_value = None
-                if key_field in kwargs:
-                    key_value = kwargs[key_field]
-                elif len(args) > 1:
-                    # Handle positional arguments - need to map parameter names
-                    import inspect
-
-                    try:
-                        sig = inspect.signature(func)
-                        param_names = list(sig.parameters.keys())
-                        if key_field in param_names:
-                            field_index = param_names.index(key_field)
-                            if field_index < len(args):
-                                key_value = args[field_index]
-                    except (ValueError, TypeError):
-                        pass
-
-                if key_value is not None:
-                    op_name = f"{func.__name__}_{key_value}"
-                else:
-                    op_name = func.__name__
-            else:
-                # Use the function name as the operation name
-                op_name = func.__name__
-
-            # Check call limits
-            current_time = time.time()
-
-            with _decorator_call_tracker_lock:
-                # Clean up old entries outside the time window
-                if op_name in _decorator_call_tracker:
-                    _decorator_call_tracker[op_name] = [
-                        timestamp
-                        for timestamp in _decorator_call_tracker[op_name]
-                        if current_time - timestamp <= time_window
-                    ]
-
-                # Check if we're exceeding the limit
-                if op_name in _decorator_call_tracker:
-                    if len(_decorator_call_tracker[op_name]) >= max_calls:
-                        # Check if all recent calls are within the time window
-                        if all(
-                            current_time - timestamp <= time_window
-                            for timestamp in _decorator_call_tracker[op_name]
-                        ):
-                            # Return loop protection message as string instead of raising exception
-                            error_msg = f"Loop protection: Too many {op_name} operations in a short time period ({max_calls} calls in {time_window}s). Please try a different approach or wait before retrying."
-
-                            # Try to report the error through the tool's reporting mechanism
-                            tool_instance = args[0] if args else None
-                            if hasattr(tool_instance, "report_error"):
-                                try:
-                                    tool_instance.report_error(error_msg)
-                                except Exception:
-                                    pass  # If reporting fails, we still return the message
-
-                            return error_msg
-
-                # Record this call
-                if op_name not in _decorator_call_tracker:
-                    _decorator_call_tracker[op_name] = []
-                _decorator_call_tracker[op_name].append(current_time)
-
-            # Proceed with the original function
+            op_name = _determine_operation_name(func, args, kwargs, key_field)
+            exceeded, msg = _check_and_record(
+                op_name=op_name,
+                current_time=time.time(),
+                time_window=time_window,
+                max_calls=max_calls,
+                tool_instance=args[0],
+            )
+            if exceeded:
+                return msg
             return func(*args, **kwargs)
 
         return wrapper

janito/tools/tool_base.py

@@ -1,142 +1,114 @@
-from janito.report_events import ReportEvent, ReportSubtype, ReportAction
-from janito.event_bus.bus import event_bus as default_event_bus
-
-
-from collections import namedtuple
-
-
-class ToolPermissions(namedtuple("ToolPermissions", ["read", "write", "execute"])):
-    __slots__ = ()
-
-    def __new__(cls, read=False, write=False, execute=False):
-        return super().__new__(cls, read, write, execute)
-
-    def __repr__(self):
-        return f"ToolPermissions(read={self.read}, write={self.write}, execute={self.execute})"
-
-
-class ToolBase:
-    """
-    Base class for all tools in the janito project.
-    Extend this class to implement specific tool functionality.
-    
-    Parameters:
-        path (str): Target file path for file operations
-        content (str): File content to write or process
-        overwrite (bool): Whether to overwrite existing files (default: False)
-        sources (str): Source file(s) to copy from
-        target (str): Destination path for copy operations
-        recursive (bool): Whether to process directories recursively
-        from_line (int): Starting line number for file reading
-        to_line (int): Ending line number for file reading
-        search_text (str): Text to search for in files
-        replacement_text (str): Text to replace search matches with
-        use_regex (bool): Whether to treat search as regex pattern
-        case_sensitive (bool): Whether search should be case sensitive
-        max_depth (int): Maximum directory depth to search
-        include_gitignored (bool): Whether to include .gitignored files
-        timeout (int): Timeout in seconds for operations
-        require_confirmation (bool): Whether to require user confirmation
-        data (dict): Chart data for visualization tools
-        title (str): Chart title
-        width (int): Chart width in pixels
-        height (int): Chart height in pixels
-        query (str): Search query for text search
-        paths (str): Directory or file paths to search in
-        src_path (str): Source path for move operations
-        dest_path (str): Destination path for move operations
-        code (str): Python code to execute
-        pattern (str): File pattern to match (e.g., '*.py')
-    """
-
-    permissions: "ToolPermissions" = None  # Required: must be set by subclasses
-
-    def __init__(self, name=None, event_bus=None):
-        if self.permissions is None or not isinstance(
-            self.permissions, ToolPermissions
-        ):
-            raise ValueError(
-                f"Tool '{self.__class__.__name__}' must define a 'permissions' attribute of type ToolPermissions."
-            )
-        self.name = name or self.__class__.__name__
-        self._event_bus = event_bus or default_event_bus
-
-    @property
-    def event_bus(self):
-        return self._event_bus
-
-    @event_bus.setter
-    def event_bus(self, bus):
-        self._event_bus = bus or default_event_bus
-
-    def report_action(self, message: str, action: ReportAction, context: dict = None):
-        """
-        Report that a tool action is starting. This should be the first reporting call for every tool action.
-        """
-        self._event_bus.publish(
-            ReportEvent(
-                subtype=ReportSubtype.ACTION_INFO,
-                message="  " + message,
-                action=action,
-                tool=self.name,
-                context=context,
-            )
-        )
-
-    def report_error(self, message: str, context: dict = None):
-        self._event_bus.publish(
-            ReportEvent(
-                subtype=ReportSubtype.ERROR,
-                message=message,
-                action=None,
-                tool=self.name,
-                context=context,
-            )
-        )
-
-    def report_success(self, message: str, context: dict = None):
-        self._event_bus.publish(
-            ReportEvent(
-                subtype=ReportSubtype.SUCCESS,
-                message=message,
-                action=None,
-                tool=self.name,
-                context=context,
-            )
-        )
-
-    def report_warning(self, message: str, context: dict = None):
-        self._event_bus.publish(
-            ReportEvent(
-                subtype=ReportSubtype.WARNING,
-                message=message,
-                action=None,
-                tool=self.name,
-                context=context,
-            )
-        )
-
-    def report_stdout(self, message: str, context: dict = None):
-        self._event_bus.publish(
-            ReportEvent(
-                subtype=ReportSubtype.STDOUT,
-                message=message,
-                action=None,
-                tool=self.name,
-                context=context,
-            )
-        )
-
-    def report_stderr(self, message: str, context: dict = None):
-        self._event_bus.publish(
-            ReportEvent(
-                subtype=ReportSubtype.STDERR,
-                message=message,
-                action=None,
-                tool=self.name,
-                context=context,
-            )
-        )
-
-    def run(self, *args, **kwargs):
-        raise NotImplementedError("Subclasses must implement the run method.")
+from janito.report_events import ReportEvent, ReportSubtype, ReportAction
+from janito.event_bus.bus import event_bus as default_event_bus
+
+
+from collections import namedtuple
+
+
+class ToolPermissions(namedtuple("ToolPermissions", ["read", "write", "execute"])):
+    __slots__ = ()
+
+    def __new__(cls, read=False, write=False, execute=False):
+        return super().__new__(cls, read, write, execute)
+
+    def __repr__(self):
+        return f"ToolPermissions(read={self.read}, write={self.write}, execute={self.execute})"
+
+
+class ToolBase:
+    """
+    Base class for all tools in the janito project.
+    Extend this class to implement specific tool functionality.
+    """
+
+    permissions: "ToolPermissions" = None  # Required: must be set by subclasses
+
+    def __init__(self, name=None, event_bus=None):
+        if self.permissions is None or not isinstance(
+            self.permissions, ToolPermissions
+        ):
+            raise ValueError(
+                f"Tool '{self.__class__.__name__}' must define a 'permissions' attribute of type ToolPermissions."
+            )
+        self.name = name or self.__class__.__name__
+        self._event_bus = event_bus or default_event_bus
+
+    @property
+    def event_bus(self):
+        return self._event_bus
+
+    @event_bus.setter
+    def event_bus(self, bus):
+        self._event_bus = bus or default_event_bus
+
+    def report_action(self, message: str, action: ReportAction, context: dict = None):
+        """
+        Report that a tool action is starting. This should be the first reporting call for every tool action.
+        """
+        self._event_bus.publish(
+            ReportEvent(
+                subtype=ReportSubtype.ACTION_INFO,
+                message="  " + message,
+                action=action,
+                tool=self.name,
+                context=context,
+            )
+        )
+
+    def report_error(self, message: str, context: dict = None):
+        self._event_bus.publish(
+            ReportEvent(
+                subtype=ReportSubtype.ERROR,
+                message=message,
+                action=None,
+                tool=self.name,
+                context=context,
+            )
+        )
+
+    def report_success(self, message: str, context: dict = None):
+        self._event_bus.publish(
+            ReportEvent(
+                subtype=ReportSubtype.SUCCESS,
+                message=message,
+                action=None,
+                tool=self.name,
+                context=context,
+            )
+        )
+
+    def report_warning(self, message: str, context: dict = None):
+        self._event_bus.publish(
+            ReportEvent(
+                subtype=ReportSubtype.WARNING,
+                message=message,
+                action=None,
+                tool=self.name,
+                context=context,
+            )
+        )
+
+    def report_stdout(self, message: str, context: dict = None):
+        self._event_bus.publish(
+            ReportEvent(
+                subtype=ReportSubtype.STDOUT,
+                message=message,
+                action=None,
+                tool=self.name,
+                context=context,
+            )
+        )
+
+    def report_stderr(self, message: str, context: dict = None):
+        self._event_bus.publish(
+            ReportEvent(
+                subtype=ReportSubtype.STDERR,
+                message=message,
+                action=None,
+                tool=self.name,
+                context=context,
+            )
+        )
+
+    def run(self, *args, **kwargs):
+        raise NotImplementedError("Subclasses must implement the run method.")

janito/tools/tools_schema.py

@@ -7,8 +7,6 @@ class ToolSchemaBase:
     def parse_param_section(self, lines, param_section_headers):
         param_descs = {}
         in_params = False
-        current_param = None
-        
         for line in lines:
             stripped_line = line.strip()
             if any(
@@ -18,21 +16,17 @@ class ToolSchemaBase:
                 in_params = True
                 continue
             if in_params:
-                # Check for parameter definition: "param_name (type): description"
                 m = re.match(
-                    r"([a-zA-Z_][a-zA-Z0-9_]*)\s*(?:\([^)]+\))?\s*:\s*(.+)",
+                    r"([a-zA-Z_][a-zA-Z0-9_]*)\s*(?:\(([^)]+)\))?\s*[:\-]?\s*(.+)",
                     stripped_line,
                 )
                 if m:
-                    param, desc = m.groups()
+                    param, _, desc = m.groups()
                     param_descs[param] = desc.strip()
-                    current_param = param
-                elif current_param and stripped_line and not (
-                    stripped_line.lower().startswith("returns:") or 
-                    stripped_line.lower() == "returns"
-                ):
-                    # Continuation of current parameter description
-                    param_descs[current_param] += " " + stripped_line.strip()
+                elif stripped_line and stripped_line[0] != "-":
+                    if param_descs:
+                        last = list(param_descs)[-1]
+                        param_descs[last] += " " + stripped_line
             if (
                 stripped_line.lower().startswith("returns:")
                 or stripped_line.lower() == "returns"