oagi-core 0.9.0__py3-none-any.whl

oagi/__init__.py

@@ -0,0 +1,108 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+import importlib
+
+from oagi.async_single_step import async_single_step
+from oagi.client import AsyncClient, SyncClient
+from oagi.exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    NetworkError,
+    NotFoundError,
+    OAGIError,
+    RateLimitError,
+    RequestTimeoutError,
+    ServerError,
+    ValidationError,
+)
+from oagi.single_step import single_step
+from oagi.task import AsyncShortTask, AsyncTask, ShortTask, Task
+from oagi.types import (
+    AsyncActionHandler,
+    AsyncImageProvider,
+    ImageConfig,
+)
+from oagi.types.models import ErrorDetail, ErrorResponse, LLMResponse
+
+# Lazy imports for pyautogui-dependent modules
+# These will only be imported when actually accessed
+_LAZY_IMPORTS = {
+    "AsyncPyautoguiActionHandler": "oagi.async_pyautogui_action_handler",
+    "AsyncScreenshotMaker": "oagi.async_screenshot_maker",
+    "PILImage": "oagi.pil_image",
+    "PyautoguiActionHandler": "oagi.pyautogui_action_handler",
+    "PyautoguiConfig": "oagi.pyautogui_action_handler",
+    "ScreenshotMaker": "oagi.screenshot_maker",
+    # Agent modules (to avoid circular imports)
+    "TaskerAgent": "oagi.agent.tasker",
+    # Server modules (optional - requires server dependencies)
+    "create_app": "oagi.server.main",
+    "ServerConfig": "oagi.server.config",
+    "sio": "oagi.server.socketio_server",
+}
+
+
+def __getattr__(name: str):
+    """Lazy import for pyautogui-dependent modules."""
+    if name in _LAZY_IMPORTS:
+        module_name = _LAZY_IMPORTS[name]
+        module = importlib.import_module(module_name)
+        return getattr(module, name)
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
+__all__ = [
+    # Core sync classes
+    "Task",
+    "ShortTask",
+    "SyncClient",
+    # Core async classes
+    "AsyncTask",
+    "AsyncShortTask",
+    "AsyncClient",
+    # Agent classes
+    "TaskerAgent",
+    # Functions
+    "single_step",
+    "async_single_step",
+    # Async protocols
+    "AsyncActionHandler",
+    "AsyncImageProvider",
+    # Configuration
+    "ImageConfig",
+    # Response models
+    "LLMResponse",
+    "ErrorResponse",
+    "ErrorDetail",
+    # Exceptions
+    "OAGIError",
+    "APIError",
+    "AuthenticationError",
+    "ConfigurationError",
+    "NetworkError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "RequestTimeoutError",
+    "ValidationError",
+    # Lazy imports
+    # Image classes
+    "PILImage",
+    # Handler classes
+    "PyautoguiActionHandler",
+    "PyautoguiConfig",
+    "ScreenshotMaker",
+    # Async handler classes
+    "AsyncPyautoguiActionHandler",
+    "AsyncScreenshotMaker",
+    # Server modules (optional)
+    "create_app",
+    "ServerConfig",
+    "sio",
+]

oagi/agent/__init__.py

@@ -0,0 +1,31 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+# Import factories to trigger registration
+from . import factories  # noqa: F401
+from .default import AsyncDefaultAgent
+from .protocol import Agent, AsyncAgent
+from .registry import (
+    async_agent_register,
+    create_agent,
+    get_agent_factory,
+    list_agent_modes,
+)
+from .tasker import TaskeeAgent, TaskerAgent
+
+__all__ = [
+    "Agent",
+    "AsyncAgent",
+    "AsyncDefaultAgent",
+    "TaskerAgent",
+    "TaskeeAgent",
+    "async_agent_register",
+    "create_agent",
+    "get_agent_factory",
+    "list_agent_modes",
+]

oagi/agent/default.py

@@ -0,0 +1,75 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+import logging
+
+from .. import AsyncTask
+from ..types import (
+    AsyncActionHandler,
+    AsyncImageProvider,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncDefaultAgent:
+    """Default asynchronous agent implementation using OAGI client."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        model: str = "lux-v1",
+        max_steps: int = 30,
+        temperature: float | None = None,
+    ):
+        self.api_key = api_key
+        self.base_url = base_url
+        self.model = model
+        self.max_steps = max_steps
+        self.temperature = temperature
+
+    async def execute(
+        self,
+        instruction: str,
+        action_handler: AsyncActionHandler,
+        image_provider: AsyncImageProvider,
+    ) -> bool:
+        async with AsyncTask(
+            api_key=self.api_key, base_url=self.base_url, model=self.model
+        ) as self.task:
+            logger.info(f"Starting async task execution: {instruction}")
+            await self.task.init_task(instruction, max_steps=self.max_steps)
+
+            for i in range(self.max_steps):
+                logger.debug(f"Executing step {i + 1}/{self.max_steps}")
+
+                # Capture current state
+                image = await image_provider()
+
+                # Get next step from OAGI
+                step = await self.task.step(image, temperature=self.temperature)
+
+                # Log reasoning
+                if step.reason:
+                    logger.debug(f"Step {i + 1} reasoning: {step.reason}")
+
+                # Execute actions if any
+                if step.actions:
+                    logger.debug(f"Executing {len(step.actions)} actions")
+                    await action_handler(step.actions)
+
+                # Check if task is complete
+                if step.stop:
+                    logger.info(f"Task completed successfully after {i + 1} steps")
+                    return True
+
+            logger.warning(
+                f"Task reached max steps ({self.max_steps}) without completion"
+            )
+            return False

oagi/agent/factories.py

@@ -0,0 +1,50 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+from oagi.agent.tasker import TaskerAgent
+
+from .default import AsyncDefaultAgent
+from .protocol import AsyncAgent
+from .registry import async_agent_register
+
+
+@async_agent_register(mode="actor")
+def create_default_agent(
+    api_key: str | None = None,
+    base_url: str | None = None,
+    model: str = "lux-v1",
+    max_steps: int = 20,
+    temperature: float = 0.1,
+) -> AsyncAgent:
+    return AsyncDefaultAgent(
+        api_key=api_key,
+        base_url=base_url,
+        model=model,
+        max_steps=max_steps,
+        temperature=temperature,
+    )
+
+
+@async_agent_register(mode="tasker")
+def create_planner_agent(
+    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,
+) -> AsyncAgent:
+    tasker = TaskerAgent(
+        api_key=api_key,
+        base_url=base_url,
+        model=model,
+        max_steps=max_steps,
+        temperature=temperature,
+        reflection_interval=reflection_interval,
+    )
+    # tasker.set_task()
+    return tasker

oagi/agent/protocol.py

@@ -0,0 +1,55 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from typing import Protocol
+
+from ..types import ActionHandler, AsyncActionHandler, AsyncImageProvider, ImageProvider
+
+
+class Agent(Protocol):
+    """Protocol for synchronous task execution agents."""
+
+    def execute(
+        self,
+        instruction: str,
+        action_handler: ActionHandler,
+        image_provider: ImageProvider,
+    ) -> bool:
+        """Execute a task with the given handlers.
+
+        Args:
+            instruction: Task instruction to execute
+            action_handler: Handler for executing actions
+            image_provider: Provider for capturing images
+
+        Returns:
+            True if task completed successfully, False otherwise
+        """
+        ...
+
+
+class AsyncAgent(Protocol):
+    """Protocol for asynchronous task execution agents."""
+
+    async def execute(
+        self,
+        instruction: str,
+        action_handler: AsyncActionHandler,
+        image_provider: AsyncImageProvider,
+    ) -> bool:
+        """Asynchronously execute a task with the given handlers.
+
+        Args:
+            instruction: Task instruction to execute
+            action_handler: Handler for executing actions
+            image_provider: Provider for capturing images
+
+        Returns:
+            True if task completed successfully, False otherwise
+        """
+        ...

oagi/agent/registry.py

@@ -0,0 +1,155 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from .protocol import AsyncAgent
+
+# Type alias for agent factory functions
+AgentFactory = Callable[..., AsyncAgent]
+
+# Global registry mapping mode names to factory functions
+_agent_registry: dict[str, AgentFactory] = {}
+
+
+def async_agent_register(mode: str) -> Callable[[AgentFactory], AgentFactory]:
+    """Decorator to register agent factory functions for specific modes.
+
+    The decorator performs the following:
+    1. Registers the factory function under the specified mode name
+    2. Validates that duplicate modes are not registered
+    3. Enables runtime validation of returned AsyncAgent instances
+
+    Args:
+        mode: The agent mode identifier (e.g., "actor", "planner", "todo")
+
+    Returns:
+        Decorator function that registers the factory
+
+    Raises:
+        ValueError: If the mode is already registered
+    """
+
+    def decorator(func: AgentFactory) -> AgentFactory:
+        # Check if mode is already registered
+        if mode in _agent_registry:
+            raise ValueError(
+                f"Agent mode '{mode}' is already registered. "
+                f"Cannot register the same mode twice."
+            )
+
+        # Register the factory
+        _agent_registry[mode] = func
+        return func
+
+    return decorator
+
+
+def get_agent_factory(mode: str) -> AgentFactory:
+    """Get the registered agent factory for a mode.
+
+    Args:
+        mode: The agent mode identifier
+
+    Returns:
+        The registered factory function
+
+    Raises:
+        ValueError: If the mode is not registered
+    """
+    if mode not in _agent_registry:
+        available_modes = list(_agent_registry.keys())
+        raise ValueError(
+            f"Unknown agent mode: '{mode}'. Available modes: {available_modes}"
+        )
+    return _agent_registry[mode]
+
+
+def list_agent_modes() -> list[str]:
+    """List all registered agent modes.
+
+    Returns:
+        List of registered mode names
+    """
+    return list(_agent_registry.keys())
+
+
+def create_agent(mode: str, **kwargs: Any) -> AsyncAgent:
+    """Create an agent instance using the registered factory for the given mode.
+
+    This function automatically introspects the factory's signature and only passes
+    parameters that the factory accepts. This allows factories to have flexible
+    signatures while callers can provide a standard set of parameters.
+
+    Standard parameters typically include:
+    - api_key: OAGI API key
+    - base_url: OAGI API base URL
+    - model: Model identifier (e.g., "lux-v1")
+    - max_steps: Maximum number of steps to execute
+    - temperature: Sampling temperature
+
+    Args:
+        mode: The agent mode identifier
+        **kwargs: Parameters to pass to the factory function
+
+    Returns:
+        AsyncAgent instance created by the factory
+
+    Raises:
+        ValueError: If the mode is not registered
+        TypeError: If the factory returns an object that doesn't implement AsyncAgent
+
+    Example:
+        agent = create_agent(
+            mode="actor",
+            api_key="...",
+            base_url="...",
+            model="lux-v1",
+            max_steps=30,
+            temperature=0.0,
+        )
+    """
+    factory = get_agent_factory(mode)
+
+    # Introspect factory signature to determine which parameters it accepts
+    sig = inspect.signature(factory)
+
+    # Check if factory has **kwargs parameter (VAR_KEYWORD)
+    has_var_keyword = any(
+        param.kind == inspect.Parameter.VAR_KEYWORD for param in sig.parameters.values()
+    )
+
+    if has_var_keyword:
+        # If factory has **kwargs, pass all parameters
+        filtered_kwargs = kwargs
+    else:
+        # Otherwise, filter kwargs to only include parameters the factory accepts
+        accepted_params = set(sig.parameters.keys())
+        filtered_kwargs = {
+            key: value for key, value in kwargs.items() if key in accepted_params
+        }
+
+    agent = factory(**filtered_kwargs)
+
+    if not hasattr(agent, "execute"):
+        raise TypeError(
+            f"Factory for mode '{mode}' returned an object that doesn't "
+            f"implement AsyncAgent protocol. Expected an object with an "
+            f"'execute' method, got {type(agent).__name__}"
+        )
+
+    if not inspect.iscoroutinefunction(agent.execute):
+        raise TypeError(
+            f"Factory for mode '{mode}' returned an object with a non-async "
+            f"'execute' method. AsyncAgent protocol requires 'execute' to be "
+            f"an async method."
+        )
+
+    return agent

oagi/agent/tasker/__init__.py

@@ -0,0 +1,35 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from .memory import PlannerMemory
+from .models import (
+    Action,
+    Deliverable,
+    PlannerOutput,
+    ReflectionOutput,
+    Todo,
+    TodoHistory,
+    TodoStatus,
+)
+from .planner import Planner
+from .taskee_agent import TaskeeAgent
+from .tasker_agent import TaskerAgent
+
+__all__ = [
+    "TaskerAgent",
+    "TaskeeAgent",
+    "PlannerMemory",
+    "Planner",
+    "Todo",
+    "TodoStatus",
+    "Deliverable",
+    "Action",
+    "TodoHistory",
+    "PlannerOutput",
+    "ReflectionOutput",
+]

oagi/agent/tasker/memory.py

@@ -0,0 +1,184 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from typing import Any
+
+from .models import Action, Deliverable, Todo, TodoHistory, TodoStatus
+
+
+class PlannerMemory:
+    """In-memory state management for the planner agent.
+
+    This class manages the hierarchical task execution state for TaskerAgent.
+    It provides methods for:
+    - Task/todo/deliverable management
+    - Execution history tracking
+    - Memory state serialization
+
+    Context formatting for backend API calls is handled by the backend.
+    """
+
+    def __init__(self):
+        """Initialize empty memory."""
+        self.task_description: str = ""
+        self.todos: list[Todo] = []
+        self.deliverables: list[Deliverable] = []
+        self.history: list[TodoHistory] = []
+        self.task_execution_summary: str = ""
+        self.todo_execution_summaries: dict[int, str] = {}
+
+    def set_task(
+        self,
+        task_description: str,
+        todos: list[str] | list[Todo],
+        deliverables: list[str] | list[Deliverable] | None = None,
+    ) -> None:
+        """Set the task, todos, and deliverables.
+
+        Args:
+            task_description: Overall task description
+            todos: List of todo items (strings or Todo objects)
+            deliverables: Optional list of deliverables (strings or Deliverable objects)
+        """
+        self.task_description = task_description
+
+        # Convert todos
+        self.todos = []
+        for todo in todos:
+            if isinstance(todo, str):
+                self.todos.append(Todo(description=todo))
+            else:
+                self.todos.append(todo)
+
+        # Convert deliverables
+        self.deliverables = []
+        if deliverables:
+            for deliverable in deliverables:
+                if isinstance(deliverable, str):
+                    self.deliverables.append(Deliverable(description=deliverable))
+                else:
+                    self.deliverables.append(deliverable)
+
+    def get_current_todo(self) -> tuple[Todo | None, int]:
+        """Get the next pending or in-progress todo.
+
+        Returns:
+            Tuple of (Todo object, index) or (None, -1) if no todos remain
+        """
+        for idx, todo in enumerate(self.todos):
+            if todo.status in [TodoStatus.PENDING, TodoStatus.IN_PROGRESS]:
+                return todo, idx
+        return None, -1
+
+    def update_todo(
+        self,
+        index: int,
+        status: TodoStatus | str,
+        summary: str | None = None,
+    ) -> None:
+        """Update a todo's status and optionally its summary.
+
+        Args:
+            index: Index of the todo to update
+            status: New status for the todo
+            summary: Optional execution summary
+        """
+        if 0 <= index < len(self.todos):
+            if isinstance(status, str):
+                status = TodoStatus(status)
+            self.todos[index].status = status
+            if summary:
+                self.todo_execution_summaries[index] = summary
+
+    def add_history(
+        self,
+        todo_index: int,
+        actions: list[Action],
+        summary: str | None = None,
+        completed: bool = False,
+    ) -> None:
+        """Add execution history for a todo.
+
+        Args:
+            todo_index: Index of the todo
+            actions: List of actions taken
+            summary: Optional execution summary
+            completed: Whether the todo was completed
+        """
+        if 0 <= todo_index < len(self.todos):
+            self.history.append(
+                TodoHistory(
+                    todo_index=todo_index,
+                    todo=self.todos[todo_index].description,
+                    actions=actions,
+                    summary=summary,
+                    completed=completed,
+                )
+            )
+
+    def get_context(self) -> dict[str, Any]:
+        """Get the full context for planning/reflection.
+
+        Returns:
+            Dictionary containing all memory state
+        """
+        return {
+            "task_description": self.task_description,
+            "todos": [
+                {"index": i, "description": t.description, "status": t.status}
+                for i, t in enumerate(self.todos)
+            ],
+            "deliverables": [
+                {"description": d.description, "achieved": d.achieved}
+                for d in self.deliverables
+            ],
+            "history": [
+                {
+                    "todo_index": h.todo_index,
+                    "todo": h.todo,
+                    "action_count": len(h.actions),
+                    "summary": h.summary,
+                    "completed": h.completed,
+                }
+                for h in self.history
+            ],
+            "task_execution_summary": self.task_execution_summary,
+            "todo_execution_summaries": self.todo_execution_summaries,
+        }
+
+    def get_todo_status_summary(self) -> dict[str, int]:
+        """Get a summary of todo statuses.
+
+        Returns:
+            Dictionary with counts for each status
+        """
+        summary = {
+            TodoStatus.PENDING: 0,
+            TodoStatus.IN_PROGRESS: 0,
+            TodoStatus.COMPLETED: 0,
+            TodoStatus.SKIPPED: 0,
+        }
+        for todo in self.todos:
+            summary[todo.status] += 1
+        return summary
+
+    def append_todo(self, description: str) -> None:
+        """Append a new todo to the list.
+
+        Args:
+            description: Description of the new todo
+        """
+        self.todos.append(Todo(description=description))
+
+    def append_deliverable(self, description: str) -> None:
+        """Append a new deliverable to the list.
+
+        Args:
+            description: Description of the new deliverable
+        """
+        self.deliverables.append(Deliverable(description=description))