oagi-core 0.9.0__py3-none-any.whl

oagi/agent/tasker/tasker_agent.py

@@ -0,0 +1,323 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+import logging
+from typing import Any
+
+from oagi.types import AsyncActionHandler, AsyncImageProvider
+
+from ..protocol import AsyncAgent
+from .memory import PlannerMemory
+from .models import TodoStatus
+from .planner import Planner
+from .taskee_agent import TaskeeAgent
+
+logger = logging.getLogger(__name__)
+
+
+class TaskerAgent(AsyncAgent):
+    """Hierarchical agent that manages multi-todo workflows.
+
+    This agent orchestrates the execution of multiple todos by:
+    1. Managing a workflow with todos and deliverables
+    2. Executing todos sequentially using TaskeeAgent
+    3. Tracking progress and updating memory
+    4. Sharing context between todos for informed execution
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        model: str = "lux-v1",
+        max_steps: int = 30,
+        temperature: float = 0.0,
+        reflection_interval: int = 20,
+        planner: Planner | None = None,
+    ):
+        """Initialize the tasker agent.
+
+        Args:
+            api_key: OAGI API key
+            base_url: OAGI API base URL
+            model: Model to use for vision tasks
+            max_steps: Maximum steps per todo
+            temperature: Sampling temperature
+            reflection_interval: Actions before reflection
+            planner: Planner for planning and reflection
+        """
+        self.api_key = api_key
+        self.base_url = base_url
+        self.model = model
+        self.max_steps = max_steps
+        self.temperature = temperature
+        self.reflection_interval = reflection_interval
+        self.planner = planner or Planner()
+
+        # Memory for tracking workflow
+        self.memory = PlannerMemory()
+
+        # Current execution state
+        self.current_taskee_agent: TaskeeAgent | None = None
+        self.current_todo_index: int = -1
+
+    def set_task(
+        self,
+        task: str,
+        todos: list[str],
+        deliverables: list[str] | None = None,
+    ) -> None:
+        """Set the task, todos, and deliverables for the workflow.
+
+        Args:
+            task: Overall task description
+            todos: List of todo descriptions
+            deliverables: Optional list of deliverable descriptions
+        """
+        self.memory.set_task(task, todos, deliverables)
+        logger.info(
+            f"Task set with {len(todos)} todos and "
+            f"{len(deliverables) if deliverables else 0} deliverables"
+        )
+
+    async def execute(
+        self,
+        instruction: str,
+        action_handler: AsyncActionHandler,
+        image_provider: AsyncImageProvider,
+    ) -> bool:
+        """Execute the multi-todo workflow.
+
+        This method will execute todos sequentially until all are complete
+        or a failure occurs.
+
+        Args:
+            instruction: Overall instruction (can be same as task description)
+            action_handler: Handler for executing actions
+            image_provider: Provider for capturing screenshots
+
+        Returns:
+            True if all todos completed successfully, False otherwise
+        """
+        # If task not set, use instruction as task description
+        if not self.memory.task_description:
+            logger.warning("Task not set, using instruction as task description")
+            self.memory.task_description = instruction
+
+        overall_success = True
+
+        # Execute todos until none remain
+        while True:
+            # Prepare for next todo
+            todo_info = self._prepare()
+
+            if todo_info is None:
+                # No more todos to execute
+                logger.info("No more todos to execute")
+                break
+
+            todo, todo_index = todo_info
+            logger.info(f"Executing todo {todo_index}: {todo.description}")
+
+            # Execute the todo
+            success = await self._execute_todo(
+                todo_index,
+                action_handler,
+                image_provider,
+            )
+
+            if not success:
+                logger.warning(f"Todo {todo_index} failed")
+                overall_success = False
+                # If todo failed due to exception, it stays IN_PROGRESS
+                # Break to avoid infinite loop re-attempting same todo
+                current_status = self.memory.todos[todo_index].status
+                if current_status == TodoStatus.IN_PROGRESS:
+                    logger.error("Todo failed with exception, stopping execution")
+                    break
+                # Otherwise continue with next todo
+
+            # Update task execution summary
+            self._update_task_summary()
+
+        # Log final status
+        status_summary = self.memory.get_todo_status_summary()
+        logger.info(f"Workflow complete. Status summary: {status_summary}")
+
+        return overall_success
+
+    def _prepare(self) -> tuple[Any, int] | None:
+        """Prepare for the next todo execution.
+
+        Returns:
+            Tuple of (todo, index) or None if no todos remain
+        """
+        # Get current todo
+        todo, todo_index = self.memory.get_current_todo()
+
+        if todo is None:
+            return None
+
+        # Create taskee agent with external memory
+        self.current_taskee_agent = TaskeeAgent(
+            api_key=self.api_key,
+            base_url=self.base_url,
+            model=self.model,
+            max_steps_per_subtask=10,  # Smaller steps per subtask
+            reflection_interval=self.reflection_interval,
+            temperature=self.temperature,
+            planner=self.planner,
+            external_memory=self.memory,  # Share memory with child
+            todo_index=todo_index,  # Pass the todo index
+        )
+
+        self.current_todo_index = todo_index
+
+        # Update todo status to in_progress if it was pending
+        if todo.status == TodoStatus.PENDING:
+            self.memory.update_todo(todo_index, TodoStatus.IN_PROGRESS)
+
+        logger.info(f"Prepared taskee agent for todo {todo_index}")
+
+        return todo, todo_index
+
+    async def _execute_todo(
+        self,
+        todo_index: int,
+        action_handler: AsyncActionHandler,
+        image_provider: AsyncImageProvider,
+    ) -> bool:
+        """Execute a single todo using the todo agent.
+
+        Args:
+            todo_index: Index of the todo to execute
+            action_handler: Handler for executing actions
+            image_provider: Provider for capturing screenshots
+
+        Returns:
+            True if successful, False otherwise
+        """
+        if not self.current_taskee_agent or todo_index < 0:
+            logger.error("No taskee agent prepared")
+            return False
+
+        todo = self.memory.todos[todo_index]
+
+        try:
+            # Execute using taskee agent
+            success = await self.current_taskee_agent.execute(
+                todo.description,
+                action_handler,
+                image_provider,
+            )
+
+            # Get execution results
+            results = self.current_taskee_agent.return_execution_results()
+
+            # Update memory with results
+            self._update_memory_from_execution(todo_index, results, success)
+
+            return success
+
+        except Exception as e:
+            logger.error(f"Error executing todo {todo_index}: {e}")
+            # Mark as in_progress (not completed)
+            self.memory.update_todo(
+                todo_index,
+                TodoStatus.IN_PROGRESS,
+                summary=f"Execution failed: {str(e)}",
+            )
+            return False
+
+    def _update_memory_from_execution(
+        self,
+        todo_index: int,
+        results: Any,
+        success: bool,
+    ) -> None:
+        """Update memory based on execution results.
+
+        Args:
+            todo_index: Index of the executed todo
+            results: Execution results from todo agent
+            success: Whether execution was successful
+        """
+        # Update todo status
+        status = TodoStatus.COMPLETED if success else TodoStatus.IN_PROGRESS
+        self.memory.update_todo(
+            todo_index,
+            status,
+            summary=results.summary,
+        )
+
+        # Add to history
+        self.memory.add_history(
+            todo_index,
+            results.actions,
+            summary=results.summary,
+            completed=success,
+        )
+
+        # Update task execution summary
+        if success:
+            if self.memory.task_execution_summary:
+                self.memory.task_execution_summary += (
+                    f"\n- Completed todo {todo_index}: {results.summary}"
+                )
+            else:
+                self.memory.task_execution_summary = (
+                    f"- Completed todo {todo_index}: {results.summary}"
+                )
+
+        logger.info(
+            f"Updated memory for todo {todo_index}: "
+            f"status={status}, actions={len(results.actions)}"
+        )
+
+    def _update_task_summary(self) -> None:
+        """Update the overall task execution summary."""
+        status_summary = self.memory.get_todo_status_summary()
+        completed = status_summary.get(TodoStatus.COMPLETED, 0)
+        total = len(self.memory.todos)
+
+        summary_parts = [f"Progress: {completed}/{total} todos completed"]
+
+        # Add recent completions
+        for history in self.memory.history[-3:]:  # Last 3 entries
+            if history.completed and history.summary:
+                summary_parts.append(
+                    f"- Todo {history.todo_index}: {history.summary[:100]}"
+                )
+
+        self.memory.task_execution_summary = "\n".join(summary_parts)
+
+    def get_memory(self) -> PlannerMemory:
+        """Get the current memory state.
+
+        Returns:
+            Current PlannerMemory instance
+        """
+        return self.memory
+
+    def append_todo(self, description: str) -> None:
+        """Dynamically append a new todo to the workflow.
+
+        Args:
+            description: Description of the new todo
+        """
+        self.memory.append_todo(description)
+        logger.info(f"Appended new todo: {description}")
+
+    def append_deliverable(self, description: str) -> None:
+        """Dynamically append a new deliverable to the workflow.
+
+        Args:
+            description: Description of the new deliverable
+        """
+        self.memory.append_deliverable(description)
+        logger.info(f"Appended new deliverable: {description}")

oagi/async_pyautogui_action_handler.py

@@ -0,0 +1,44 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+import asyncio
+
+from .pyautogui_action_handler import PyautoguiActionHandler, PyautoguiConfig
+from .types import Action
+
+
+class AsyncPyautoguiActionHandler:
+    """
+    Async wrapper for PyautoguiActionHandler that runs actions in a thread pool.
+
+    This allows PyAutoGUI operations to be non-blocking in async contexts,
+    enabling concurrent execution of other async tasks while GUI actions are performed.
+    """
+
+    def __init__(self, config: PyautoguiConfig | None = None):
+        """Initialize with optional configuration.
+
+        Args:
+            config: PyautoguiConfig instance for customizing behavior
+        """
+        self.sync_handler = PyautoguiActionHandler(config=config)
+        self.config = config or PyautoguiConfig()
+
+    async def __call__(self, actions: list[Action]) -> None:
+        """
+        Execute actions asynchronously using a thread pool executor.
+
+        This prevents PyAutoGUI operations from blocking the async event loop,
+        allowing other coroutines to run while GUI actions are being performed.
+
+        Args:
+            actions: List of actions to execute
+        """
+        loop = asyncio.get_event_loop()
+        # Run the synchronous handler in a thread pool to avoid blocking
+        await loop.run_in_executor(None, self.sync_handler, actions)

oagi/async_screenshot_maker.py

@@ -0,0 +1,47 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+import asyncio
+
+from .screenshot_maker import ScreenshotMaker
+from .types import Image, ImageConfig
+
+
+class AsyncScreenshotMaker:
+    """
+    Async wrapper for ScreenshotMaker that captures screenshots in a thread pool.
+
+    This allows screenshot capture to be non-blocking in async contexts,
+    enabling concurrent execution of other async tasks while screenshots are taken.
+    """
+
+    def __init__(self, config: ImageConfig | None = None):
+        """Initialize with optional image configuration.
+
+        Args:
+            config: ImageConfig instance for customizing screenshot format and quality
+        """
+        self.sync_screenshot_maker = ScreenshotMaker(config=config)
+        self.config = config
+
+    async def __call__(self) -> Image:
+        """
+        Capture a screenshot asynchronously using a thread pool executor.
+
+        This prevents screenshot capture from blocking the async event loop,
+        allowing other coroutines to run while the screenshot is being taken.
+
+        Returns:
+            Image: The captured screenshot as a PILImage
+        """
+        loop = asyncio.get_event_loop()
+        # Run the synchronous screenshot capture in a thread pool to avoid blocking
+        return await loop.run_in_executor(None, self.sync_screenshot_maker)
+
+    async def last_image(self) -> Image:
+        return self.sync_screenshot_maker.last_image()

oagi/async_single_step.py

@@ -0,0 +1,85 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from pathlib import Path
+
+from .task import AsyncTask
+from .types import Image, Step
+
+
+async def async_single_step(
+    task_description: str,
+    screenshot: str | bytes | Path | Image,
+    instruction: str | None = None,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    temperature: float | None = None,
+) -> Step:
+    """
+    Perform a single-step inference asynchronously without maintaining task state.
+
+    This is useful for one-off analyses where you don't need to maintain
+    a conversation or task context across multiple steps.
+
+    Args:
+        task_description: Description of the task to perform
+        screenshot: Screenshot as Image, bytes, or file path
+        instruction: Optional additional instruction for the task
+        api_key: OAGI API key (uses environment variable if not provided)
+        base_url: OAGI base URL (uses environment variable if not provided)
+        temperature: Sampling temperature (0.0-2.0) for LLM inference
+
+    Returns:
+        Step: Object containing reasoning, actions, and completion status
+
+    Example:
+        >>> # Using with bytes
+        >>> import asyncio
+        >>> async def main():
+        ...     with open("screenshot.png", "rb") as f:
+        ...         screenshot_bytes = f.read()
+        ...     step = await async_single_step(
+        ...         "Click the submit button",
+        ...         screenshot=screenshot_bytes
+        ...     )
+        ...     print(f"Actions: {step.actions}")
+        >>> asyncio.run(main())
+
+        >>> # Using with file path
+        >>> step = await async_single_step(
+        ...     "Find the search box",
+        ...     screenshot="screenshot.png"
+        ... )
+
+        >>> # Using with PILImage
+        >>> image = PILImage.from_file("screenshot.png")
+        >>> step = await async_single_step(
+        ...     "Click next page",
+        ...     screenshot=image
+        ... )
+    """
+    # Lazy import PILImage only when needed
+    from .pil_image import PILImage  # noqa: PLC0415
+
+    # Handle different screenshot input types
+    if isinstance(screenshot, (str, Path)):
+        screenshot = PILImage.from_file(str(screenshot))
+    elif isinstance(screenshot, bytes):
+        screenshot = PILImage.from_bytes(screenshot)
+
+    # Create a temporary task instance
+    task = AsyncTask(api_key=api_key, base_url=base_url, temperature=temperature)
+
+    try:
+        # Initialize task and perform single step
+        await task.init_task(task_description)
+        result = await task.step(screenshot, instruction=instruction)
+        return result
+    finally:
+        # Clean up resources
+        await task.close()

oagi/cli/__init__.py

@@ -0,0 +1,11 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from oagi.cli.main import main
+
+__all__ = ["main"]

oagi/cli/agent.py

@@ -0,0 +1,125 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+import argparse
+import asyncio
+import os
+import sys
+
+from oagi.exceptions import check_optional_dependency
+
+
+def add_agent_parser(subparsers: argparse._SubParsersAction) -> None:
+    agent_parser = subparsers.add_parser("agent", help="Agent execution commands")
+    agent_subparsers = agent_parser.add_subparsers(dest="agent_command", required=True)
+
+    # agent run command
+    run_parser = agent_subparsers.add_parser(
+        "run", help="Run an agent with the given instruction"
+    )
+    run_parser.add_argument(
+        "instruction", type=str, help="Task instruction for the agent to execute"
+    )
+    run_parser.add_argument("--model", type=str, help="Model to use (default: lux-v1)")
+    run_parser.add_argument(
+        "--max-steps", type=int, help="Maximum number of steps (default: 30)"
+    )
+    run_parser.add_argument(
+        "--temperature", type=float, help="Sampling temperature (default: 0.0)"
+    )
+    run_parser.add_argument(
+        "--mode",
+        type=str,
+        default="actor",
+        help="Agent mode to use (default: actor). Available modes: actor, planner",
+    )
+    run_parser.add_argument(
+        "--oagi-api-key", type=str, help="OAGI API key (default: OAGI_API_KEY env var)"
+    )
+    run_parser.add_argument(
+        "--oagi-base-url",
+        type=str,
+        help="OAGI base URL (default: https://api.agiopen.org, or OAGI_BASE_URL env var)",
+    )
+
+
+def handle_agent_command(args: argparse.Namespace) -> None:
+    if args.agent_command == "run":
+        run_agent(args)
+
+
+def run_agent(args: argparse.Namespace) -> None:
+    # Check if desktop extras are installed
+    check_optional_dependency("pyautogui", "Agent execution", "desktop")
+    check_optional_dependency("PIL", "Agent execution", "desktop")
+
+    from oagi import AsyncPyautoguiActionHandler, AsyncScreenshotMaker  # noqa: PLC0415
+    from oagi.agent import create_agent  # noqa: PLC0415
+
+    # Get configuration
+    api_key = args.oagi_api_key or os.getenv("OAGI_API_KEY")
+    if not api_key:
+        print(
+            "Error: OAGI API key not provided.\n"
+            "Set OAGI_API_KEY environment variable or use --oagi-api-key flag.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    base_url = args.oagi_base_url or os.getenv(
+        "OAGI_BASE_URL", "https://api.agiopen.org"
+    )
+    model = args.model or "lux-v1"
+    max_steps = args.max_steps or 30
+    temperature = args.temperature if args.temperature is not None else 0.0
+    mode = args.mode or "actor"
+
+    # Create agent
+    agent = create_agent(
+        mode=mode,
+        api_key=api_key,
+        base_url=base_url,
+        model=model,
+        max_steps=max_steps,
+        temperature=temperature,
+    )
+
+    # Create handlers
+    action_handler = AsyncPyautoguiActionHandler()
+    image_provider = AsyncScreenshotMaker()
+
+    print(f"Starting agent with instruction: {args.instruction}")
+    print(
+        f"Mode: {mode}, Model: {model}, Max steps: {max_steps}, Temperature: {temperature}"
+    )
+    print("-" * 60)
+
+    # Run agent
+    try:
+        success = asyncio.run(
+            agent.execute(
+                instruction=args.instruction,
+                action_handler=action_handler,
+                image_provider=image_provider,
+            )
+        )
+
+        print("-" * 60)
+        if success:
+            print("Task completed successfully!")
+            sys.exit(0)
+        else:
+            print("Task failed or reached max steps without completion.")
+            sys.exit(1)
+
+    except KeyboardInterrupt:
+        print("\nAgent execution interrupted.")
+        sys.exit(130)
+    except Exception as e:
+        print(f"Error during agent execution: {e}", file=sys.stderr)
+        sys.exit(1)