Merge pull request #234 from askui/feat/add-time-tools

feat(tools): add time and wait tools to universal tool store

Author: mlikasam-askui

src/askui/tools/store/universal/__init__.py

@@ -4,16 +4,24 @@
 AndroidAgent, or any other agent type.
 """
 
+from .get_current_time import GetCurrentTimeTool
 from .list_files_tool import ListFilesTool
 from .load_image_tool import LoadImageTool
 from .print_to_console import PrintToConsoleTool
 from .read_from_file_tool import ReadFromFileTool
+from .wait_tool import WaitTool
+from .wait_until_condition_tool import WaitUntilConditionTool
+from .wait_with_progress_tool import WaitWithProgressTool
 from .write_to_file_tool import WriteToFileTool
 
 __all__ = [
+    "GetCurrentTimeTool",
     "ListFilesTool",
     "PrintToConsoleTool",
     "ReadFromFileTool",
+    "WaitTool",
+    "WaitUntilConditionTool",
+    "WaitWithProgressTool",
     "WriteToFileTool",
     "LoadImageTool",
 ]

src/askui/tools/store/universal/get_current_time.py

@@ -0,0 +1,57 @@
+"""Tool that returns the current date and time in the local timezone."""
+
+from datetime import datetime
+
+from askui.models.shared.tools import Tool
+
+
+class GetCurrentTimeTool(Tool):
+    """
+    Tool for returning the current date and time in the local timezone.
+
+    This tool allows the agent to know the current time when scheduling,
+    logging, or time-dependent decisions. The time is formatted in a
+    human-readable way including the timezone.
+
+    Example:
+        ```python
+        from askui import VisionAgent
+        from askui.tools.store.universal import GetCurrentTimeTool
+
+        with VisionAgent() as agent:
+            agent.act(
+                "What time is it? Plan the next step based on current time.",
+                tools=[GetCurrentTimeTool()]
+            )
+        ```
+    """
+
+    def __init__(self) -> None:
+        super().__init__(
+            name="get_current_time_tool",
+            description=(
+                "Returns the current date and time in the local timezone. "
+                "Use this tool when you need to know the current time for scheduling, "
+                "logging, or time-dependent decisions."
+            ),
+            input_schema={
+                "type": "object",
+                "properties": {},
+                "required": [],
+            },
+        )
+
+    def __call__(self) -> str:
+        """
+        Return the current date and time in the local timezone.
+
+        Returns:
+            str: Human-readable string with today's date, current time, and
+                timezone (e.g. "Today is February 18, 2025 and currently
+                it is 14:30:00 CET").
+        """
+        now = datetime.now().astimezone()
+        date_str = now.strftime("%B %d, %Y")
+        time_str = now.strftime("%H:%M:%S")
+        tz_str = now.strftime("%Z") or now.strftime("%z")
+        return f"Today is {date_str} and currently it is {time_str} {tz_str}"

src/askui/tools/store/universal/wait_tool.py

@@ -0,0 +1,84 @@
+"""Tool that waits for a specified duration without console output."""
+
+import time
+
+from askui.models.shared.tools import Tool
+
+
+class WaitTool(Tool):
+    """
+    Tool for waiting a specified number of seconds without any console output.
+
+    Use when a short, silent pause is needed between actions (e.g. after
+    clicking before taking a screenshot). For longer waits or when the user
+    should see progress, prefer `WaitWithProgressTool`.
+
+    Args:
+        max_wait_time (int, optional): Maximum allowed wait duration in seconds.
+            Defaults to 3600 (1 hour).
+
+    Example:
+        ```python
+        from askui import VisionAgent
+        from askui.tools.store.universal import WaitTool
+
+        with VisionAgent() as agent:
+            agent.act(
+                "Click the button then wait 2 seconds and take a screenshot",
+                tools=[WaitTool(max_wait_time=60)]
+            )
+        ```
+    """
+
+    def __init__(self, max_wait_time: int = 10 * 60) -> None:
+        if max_wait_time < 1:
+            msg = "Max wait time must be at least 1 second"
+            raise ValueError(msg)
+        super().__init__(
+            name="wait_tool",
+            description=(
+                "Waits for a specified number of seconds without any console output. "
+                "Use for short, silent waits (e.g. brief pause between actions). "
+                "For longer waits or visible progress, use wait_with_progress_tool."
+            ),
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "wait_duration": {
+                        "type": "integer",
+                        "description": (
+                            "Duration of the wait in seconds "
+                            "(must be an integer, e.g. 5 for 5 seconds)."
+                        ),
+                        "minimum": 1,
+                        "maximum": max_wait_time,
+                    },
+                },
+                "required": ["wait_duration"],
+            },
+        )
+        self._max_wait_time = max_wait_time
+
+    def __call__(self, wait_duration: int) -> str:
+        """
+        Wait for the specified number of seconds.
+
+        Args:
+            wait_duration (int): Duration to wait in seconds (at least 1, at
+                most the `max_wait_time` set at construction).
+
+        Returns:
+            str: Confirmation message after the wait completes.
+
+        Raises:
+            ValueError: If `wait_duration` is less than 1 or exceeds
+                `max_wait_time`.
+        """
+        if wait_duration < 1:
+            msg = "Wait duration must be at least 1 second"
+            raise ValueError(msg)
+        if wait_duration > self._max_wait_time:
+            msg = f"Wait duration must not exceed {self._max_wait_time} seconds"
+            raise ValueError(msg)
+        time.sleep(wait_duration)
+        return f"Finished waiting for {wait_duration} seconds."

src/askui/tools/store/universal/wait_until_condition_tool.py

@@ -0,0 +1,140 @@
+"""Tool that waits until a condition is met or a maximum wait time is reached."""
+
+import time
+from typing import Callable
+
+from askui.models.shared.tools import Tool
+from askui.tools.utils import wait_with_progress
+
+
+class WaitUntilConditionTool(Tool):
+    """
+    Tool for waiting until a condition is met or a timeout is reached.
+
+    Polls a callable at a fixed interval. Returns as soon as the condition
+    returns `True`, or when the maximum wait time is reached. During each
+    interval between checks, a progress bar is shown in the console.
+
+    Args:
+        condition_check (Callable[[], bool]): Callable with no arguments
+            invoked at each poll; return `True` when the condition is met,
+            `False` otherwise.
+        description (str): Short description of what the condition checks for,
+            used in the tool description for the agent.
+        max_wait_time (float, optional): Maximum time to wait in seconds.
+            Defaults to 3600 (1 hour).
+
+    Example:
+        ```python
+        from pathlib import Path
+        from askui import VisionAgent
+        from askui.tools.store.universal import WaitUntilConditionTool
+
+        def file_ready() -> bool:
+            return Path("output/result.json").exists()
+
+        with VisionAgent() as agent:
+            agent.act(
+                "Wait until the result file appears",
+                tools=[WaitUntilConditionTool(
+                    condition_check=file_ready,
+                    description="result file exists",
+                    max_wait_time=300
+                )]
+            )
+        ```
+    """
+
+    def __init__(
+        self,
+        condition_check: Callable[[], bool],
+        description: str,
+        max_wait_time: int = 60 * 60,
+    ) -> None:
+        if max_wait_time < 1:
+            msg = "Max wait time must be at least 1 second"
+            raise ValueError(msg)
+        super().__init__(
+            name="wait_until_condition_tool",
+            description=(
+                f"Waits for: {description}. "
+                "Polls a condition at a given interval up to a maximum time; "
+                "returns early if the condition is met, otherwise after timeout."
+            ),
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "max_wait_time": {
+                        "type": "integer",
+                        "description": (
+                            "Maximum time to wait in seconds before giving up."
+                        ),
+                        "minimum": 1,
+                        "maximum": int(max_wait_time),
+                    },
+                    "check_interval": {
+                        "type": "integer",
+                        "description": (
+                            "Interval in seconds between condition checks "
+                            "(e.g. 5 for every 5 seconds). Must be at least 1."
+                        ),
+                        "minimum": 1,
+                        "maximum": int(max_wait_time),
+                    },
+                },
+                "required": ["max_wait_time"],
+            },
+        )
+        self._condition_check = condition_check
+        self._max_wait_time = max_wait_time
+
+    def __call__(self, max_wait_time: int, check_interval: int = 1) -> str:
+        """
+        Wait until the condition is met or the given timeout is reached.
+
+        Args:
+            max_wait_time (int): Maximum time to wait in seconds (must not
+                exceed the limit set at construction).
+            check_interval (int, optional): Seconds between condition checks.
+                Defaults to 1. Must be at least 1 and not greater than
+                `max_wait_time`.
+
+        Returns:
+            str: Message indicating either that the condition was met (with
+                elapsed time) or that the timeout was reached.
+
+        Raises:
+            ValueError: If `max_wait_time` or `check_interval` are out of
+                valid range.
+        """
+        if max_wait_time > self._max_wait_time:
+            msg = f"max_wait_time must not exceed {self._max_wait_time} seconds"
+            raise ValueError(msg)
+        if check_interval < 1:
+            msg = "check_interval must be at least 1 second"
+            raise ValueError(msg)
+        if check_interval > max_wait_time:
+            msg = "check_interval must not exceed max_wait_time"
+            raise ValueError(msg)
+
+        start = time.monotonic()
+        num_checks = 0
+        while True:
+            num_checks += 1
+            if self._condition_check():
+                elapsed = time.monotonic() - start
+                return (
+                    f"Condition met after {elapsed:.1f} seconds ({num_checks} checks)."
+                )
+            elapsed = time.monotonic() - start
+            if elapsed >= max_wait_time:
+                return (
+                    f"Timeout after {max_wait_time} seconds "
+                    f"(condition not met after {num_checks} checks)."
+                )
+            sleep_for = min(check_interval, max_wait_time - elapsed)
+            if sleep_for > 0:
+                wait_with_progress(
+                    sleep_for,
+                    f"Waiting for condition (check {num_checks})",
+                )