oagi 0.3.0__tar.gz → 0.4.1__tar.gz

{oagi-0.3.0 → oagi-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: oagi
-Version: 0.3.0
+Version: 0.4.1
 Summary: Official API of OpenAGI Foundation
 Project-URL: Homepage, https://github.com/agiopen-org/oagi
 Author-email: OpenAGI Foundation <contact@agiopen.org>
@@ -82,6 +82,23 @@ completed = task.auto_mode(
 )
 ```
 
+Configure PyAutoGUI behavior with custom settings:
+
+```python
+from oagi import PyautoguiActionHandler, PyautoguiConfig
+
+# Customize action behavior
+config = PyautoguiConfig(
+    drag_duration=1.0,      # Slower drags for precision (default: 0.5)
+    scroll_amount=50,       # Larger scroll steps (default: 30)
+    wait_duration=2.0,      # Longer waits (default: 1.0)
+    action_pause=0.2,       # More pause between actions (default: 0.1)
+)
+
+executor = PyautoguiActionHandler(config=config)
+task.auto_mode("Complete form", executor=executor, image_provider=ScreenshotMaker())
+```
+
 ### Image Processing
 
 Process and optimize images before sending to API:
@@ -103,6 +120,31 @@ compressed = image.transform(config)
 step = single_step("Click button", screenshot=compressed)
 ```
 
+### Async Support
+
+Use async client for non-blocking operations and better concurrency:
+
+```python
+import asyncio
+from oagi import async_single_step, AsyncShortTask
+
+async def main():
+    # Single-step async analysis
+    step = await async_single_step(
+        "Find the search bar",
+        screenshot="screenshot.png"
+    )
+    print(f"Found {len(step.actions)} actions")
+    
+    # Async task automation
+    task = AsyncShortTask()
+    async with task:
+        await task.init_task("Complete the form")
+        # ... continue with async operations
+
+asyncio.run(main())
+```
+
 ## Examples
 
 See the [`examples/`](examples/) directory for more usage patterns:

{oagi-0.3.0 → oagi-0.4.1}/README.md

@@ -48,6 +48,23 @@ completed = task.auto_mode(
 )
 ```
 
+Configure PyAutoGUI behavior with custom settings:
+
+```python
+from oagi import PyautoguiActionHandler, PyautoguiConfig
+
+# Customize action behavior
+config = PyautoguiConfig(
+    drag_duration=1.0,      # Slower drags for precision (default: 0.5)
+    scroll_amount=50,       # Larger scroll steps (default: 30)
+    wait_duration=2.0,      # Longer waits (default: 1.0)
+    action_pause=0.2,       # More pause between actions (default: 0.1)
+)
+
+executor = PyautoguiActionHandler(config=config)
+task.auto_mode("Complete form", executor=executor, image_provider=ScreenshotMaker())
+```
+
 ### Image Processing
 
 Process and optimize images before sending to API:
@@ -69,6 +86,31 @@ compressed = image.transform(config)
 step = single_step("Click button", screenshot=compressed)
 ```
 
+### Async Support
+
+Use async client for non-blocking operations and better concurrency:
+
+```python
+import asyncio
+from oagi import async_single_step, AsyncShortTask
+
+async def main():
+    # Single-step async analysis
+    step = await async_single_step(
+        "Find the search bar",
+        screenshot="screenshot.png"
+    )
+    print(f"Found {len(step.actions)} actions")
+    
+    # Async task automation
+    task = AsyncShortTask()
+    async with task:
+        await task.init_task("Complete the form")
+        # ... continue with async operations
+
+asyncio.run(main())
+```
+
 ## Examples
 
 See the [`examples/`](examples/) directory for more usage patterns:

oagi-0.4.1/examples/async_google_weather.py

@@ -0,0 +1,23 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+import asyncio
+
+from examples.execute_task_manual import async_execute_task_manual
+
+
+async def main():
+    is_completed, screenshot = await async_execute_task_manual(
+        desc := "Search weather with Google", max_steps=5
+    )
+
+    print(f"is_completed: {is_completed}, desc: {desc}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{oagi-0.3.0 → oagi-0.4.1}/examples/execute_task_auto.py

@@ -5,7 +5,14 @@
 #  This file is part of the official API project.
 #  Licensed under the MIT License.
 # -----------------------------------------------------------------------------
-from oagi import PyautoguiActionHandler, ScreenshotMaker, ShortTask
+from oagi import (
+    AsyncPyautoguiActionHandler,
+    AsyncScreenshotMaker,
+    AsyncShortTask,
+    PyautoguiActionHandler,
+    ScreenshotMaker,
+    ShortTask,
+)
 
 
 def execute_task_auto(task_desc, max_steps=5):
@@ -21,3 +28,15 @@ def execute_task_auto(task_desc, max_steps=5):
     )
 
     return is_completed, sm.last_image()
+
+
+async def async_execute_task_auto(task_desc, max_steps=5):
+    async with AsyncShortTask() as async_short_task:
+        is_completed = await async_short_task.auto_mode(
+            task_desc,
+            max_steps=max_steps,
+            executor=AsyncPyautoguiActionHandler(),
+            image_provider=(sm := AsyncScreenshotMaker()),
+        )
+
+        return is_completed, await sm.last_image()

{oagi-0.3.0 → oagi-0.4.1}/examples/execute_task_manual.py

@@ -6,7 +6,14 @@
 #  Licensed under the MIT License.
 # -----------------------------------------------------------------------------
 
-from oagi import PyautoguiActionHandler, ScreenshotMaker, Task
+from oagi import (
+    AsyncPyautoguiActionHandler,
+    AsyncScreenshotMaker,
+    AsyncTask,
+    PyautoguiActionHandler,
+    ScreenshotMaker,
+    Task,
+)
 
 
 def execute_task_manual(task_desc, max_steps=5):
@@ -49,3 +56,43 @@ def execute_task_manual(task_desc, max_steps=5):
 
     print(f"manual execution completed: {is_completed=}, {task_desc=}\n")
     return is_completed, screenshot
+
+
+async def async_execute_task_manual(task_desc, max_steps=5):
+    # set OAGI_API_KEY and OAGI_BASE_URL
+    # or ShortTask(api_key="your_api_key", base_url="your_base_url")
+    async with AsyncTask() as task:
+        await task.init_task(task_desc, max_steps=max_steps)
+        executor = AsyncPyautoguiActionHandler()
+
+        # by default, screenshot will be resized to 1260 * 700 and jpeg with quality 85
+        # for best image quality, use ScreenshotMaker(config=ImageConfig(format="PNG"))
+        image_provider = AsyncScreenshotMaker()
+
+        for i in range(max_steps):
+            # image can also be bytes
+            # with open("test_screenshot.png", "rb") as f:
+            #     image = f.read()
+            image = await image_provider()
+
+            # For additional instructions
+            # step = task.step(image, instruction="some instruction")
+            step = await task.step(image)
+
+            # do something with step, maybe print to debug
+            print(f"Step {i}: {step.reason=}")
+
+            if step.stop:
+                print(f"Task completed after {i} steps.")
+                is_completed = True
+                screenshot = await image_provider.last_image()
+                break
+
+            await executor(step.actions)
+        else:
+            # If we didn't break out of the loop, we used up all our steps
+            is_completed = False
+            screenshot = await image_provider()
+
+        print(f"manual execution completed: {is_completed=}, {task_desc=}\n")
+        return is_completed, screenshot

{oagi-0.3.0 → oagi-0.4.1}/examples/single_step.py

@@ -6,14 +6,16 @@
 #  Licensed under the MIT License.
 # -----------------------------------------------------------------------------
 
-from oagi import single_step
+from oagi import ScreenshotMaker, single_step
 
+image_provider = ScreenshotMaker()
+image = image_provider()
 step = single_step(
     task_description="Search weather with Google",
-    screenshot="some/path/to/local/image",  # bytes or Path object or Image object
+    screenshot=image,  # bytes or Path object or Image object
     instruction="The operating system is macos",  # optional instruction
-    # api_key="your-api-key", if not set with OAGI_API_KEY env var
-    # base_url="https://api.example.com" if not set with OAGI_BASE_URL env var
+    api_key="sk-50DPDW87GnlNcH_0cAPRFZ4ntweCEdUrLEFIcQFaBhc",
+    base_url="http://127.0.0.1:8000",
 )
 
 print(step)

{oagi-0.3.0 → oagi-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oagi"
-version = "0.3.0"
+version = "0.4.1"
 description = "Official API of OpenAGI Foundation"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -29,6 +29,7 @@ dev = [
     "ruff>=0.12.9",
     "pytest>=8.0.0",
     "pytest-mock>=3.12.0",
+    "pytest-asyncio>=0.21.0",
 ]
 
 [tool.ruff.lint]

{oagi-0.3.0 → oagi-0.4.1}/src/oagi/__init__.py

@@ -6,6 +6,12 @@
 #  Licensed under the MIT License.
 # -----------------------------------------------------------------------------
 
+from oagi.async_client import AsyncClient
+from oagi.async_pyautogui_action_handler import AsyncPyautoguiActionHandler
+from oagi.async_screenshot_maker import AsyncScreenshotMaker
+from oagi.async_short_task import AsyncShortTask
+from oagi.async_single_step import async_single_step
+from oagi.async_task import AsyncTask
 from oagi.exceptions import (
     APIError,
     AuthenticationError,
@@ -19,26 +25,42 @@ from oagi.exceptions import (
     ValidationError,
 )
 from oagi.pil_image import PILImage
-from oagi.pyautogui_action_handler import PyautoguiActionHandler
+from oagi.pyautogui_action_handler import PyautoguiActionHandler, PyautoguiConfig
 from oagi.screenshot_maker import ScreenshotMaker
 from oagi.short_task import ShortTask
 from oagi.single_step import single_step
 from oagi.sync_client import ErrorDetail, ErrorResponse, LLMResponse, SyncClient
 from oagi.task import Task
-from oagi.types import ImageConfig
+from oagi.types import (
+    AsyncActionHandler,
+    AsyncImageProvider,
+    ImageConfig,
+)
 
 __all__ = [
-    # Core classes
+    # Core sync classes
     "Task",
     "ShortTask",
     "SyncClient",
+    # Core async classes
+    "AsyncTask",
+    "AsyncShortTask",
+    "AsyncClient",
     # Functions
     "single_step",
+    "async_single_step",
     # Image classes
     "PILImage",
     # Handler classes
     "PyautoguiActionHandler",
+    "PyautoguiConfig",
     "ScreenshotMaker",
+    # Async handler classes
+    "AsyncPyautoguiActionHandler",
+    "AsyncScreenshotMaker",
+    # Async protocols
+    "AsyncActionHandler",
+    "AsyncImageProvider",
     # Configuration
     "ImageConfig",
     # Response models

oagi-0.4.1/src/oagi/async_client.py

@@ -0,0 +1,239 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+import os
+from functools import wraps
+
+import httpx
+
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    RequestTimeoutError,
+    ServerError,
+    ValidationError,
+)
+from .logging import get_logger
+from .sync_client import ErrorResponse, LLMResponse
+
+logger = get_logger("async_client")
+
+
+def async_log_trace_on_failure(func):
+    """Async decorator that logs trace ID when a method fails."""
+
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        try:
+            return await func(*args, **kwargs)
+        except Exception as e:
+            # Try to get response from the exception if it has one
+            if (response := getattr(e, "response", None)) is not None:
+                logger.error(f"Request Id: {response.headers.get('x-request-id', '')}")
+                logger.error(f"Trace Id: {response.headers.get('x-trace-id', '')}")
+            raise
+
+    return wrapper
+
+
+class AsyncClient:
+    """Async HTTP client for the OAGI API."""
+
+    def __init__(self, base_url: str | None = None, api_key: str | None = None):
+        # Get from environment if not provided
+        self.base_url = base_url or os.getenv("OAGI_BASE_URL")
+        self.api_key = api_key or os.getenv("OAGI_API_KEY")
+
+        # Validate required configuration
+        if not self.base_url:
+            raise ConfigurationError(
+                "OAGI base URL must be provided either as 'base_url' parameter or "
+                "OAGI_BASE_URL environment variable"
+            )
+
+        if not self.api_key:
+            raise ConfigurationError(
+                "OAGI API key must be provided either as 'api_key' parameter or "
+                "OAGI_API_KEY environment variable"
+            )
+
+        self.base_url = self.base_url.rstrip("/")
+        self.client = httpx.AsyncClient(base_url=self.base_url)
+        self.timeout = 60
+
+        logger.info(f"AsyncClient initialized with base_url: {self.base_url}")
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.client.aclose()
+
+    async def close(self):
+        """Close the underlying httpx async client"""
+        await self.client.aclose()
+
+    @async_log_trace_on_failure
+    async def create_message(
+        self,
+        model: str,
+        screenshot: str,  # base64 encoded
+        task_description: str | None = None,
+        task_id: str | None = None,
+        instruction: str | None = None,
+        max_actions: int | None = 5,
+        api_version: str | None = None,
+    ) -> LLMResponse:
+        """
+        Call the /v1/message endpoint to analyze task and screenshot
+
+        Args:
+            model: The model to use for task analysis
+            screenshot: Base64-encoded screenshot image
+            task_description: Description of the task (required for new sessions)
+            task_id: Task ID for continuing existing task
+            instruction: Additional instruction when continuing a session (only works with task_id)
+            max_actions: Maximum number of actions to return (1-20)
+            api_version: API version header
+
+        Returns:
+            LLMResponse: The response from the API
+
+        Raises:
+            httpx.HTTPStatusError: For HTTP error responses
+        """
+        headers = {}
+        if api_version:
+            headers["x-api-version"] = api_version
+        if self.api_key:
+            headers["x-api-key"] = self.api_key
+
+        payload = {"model": model, "screenshot": screenshot}
+
+        if task_description is not None:
+            payload["task_description"] = task_description
+        if task_id is not None:
+            payload["task_id"] = task_id
+        if instruction is not None:
+            payload["instruction"] = instruction
+        if max_actions is not None:
+            payload["max_actions"] = max_actions
+
+        logger.info(f"Making async API request to /v1/message with model: {model}")
+        logger.debug(
+            f"Request includes task_description: {task_description is not None}, task_id: {task_id is not None}"
+        )
+
+        try:
+            response = await self.client.post(
+                "/v1/message", json=payload, headers=headers, timeout=self.timeout
+            )
+        except httpx.TimeoutException as e:
+            logger.error(f"Request timed out after {self.timeout} seconds")
+            raise RequestTimeoutError(
+                f"Request timed out after {self.timeout} seconds", e
+            )
+        except httpx.NetworkError as e:
+            logger.error(f"Network error: {e}")
+            raise NetworkError(f"Network error: {e}", e)
+
+        try:
+            response_data = response.json()
+        except ValueError:
+            # If response is not JSON, raise API error
+            logger.error(f"Non-JSON API response: {response.status_code}")
+            raise APIError(
+                f"Invalid response format (status {response.status_code})",
+                status_code=response.status_code,
+                response=response,
+            )
+
+        # Check if it's an error response (non-200 status or has error field)
+        if response.status_code != 200:
+            error_resp = ErrorResponse(**response_data)
+            if error_resp.error:
+                error_code = error_resp.error.code
+                error_msg = error_resp.error.message
+                logger.error(f"API Error [{error_code}]: {error_msg}")
+
+                # Map to specific exception types based on status code
+                exception_class = self._get_exception_class(response.status_code)
+                raise exception_class(
+                    error_msg,
+                    code=error_code,
+                    status_code=response.status_code,
+                    response=response,
+                )
+            else:
+                # Error response without error details
+                logger.error(
+                    f"API error response without details: {response.status_code}"
+                )
+                exception_class = self._get_exception_class(response.status_code)
+                raise exception_class(
+                    f"API error (status {response.status_code})",
+                    status_code=response.status_code,
+                    response=response,
+                )
+
+        # Parse successful response
+        result = LLMResponse(**response_data)
+
+        # Check if the response contains an error (even with 200 status)
+        if result.error:
+            logger.error(
+                f"API Error in response: [{result.error.code}]: {result.error.message}"
+            )
+            raise APIError(
+                result.error.message,
+                code=result.error.code,
+                status_code=200,
+                response=response,
+            )
+
+        logger.info(
+            f"Async API request successful - task_id: {result.task_id}, step: {result.current_step}, complete: {result.is_complete}"
+        )
+        logger.debug(f"Response included {len(result.actions)} actions")
+        return result
+
+    def _get_exception_class(self, status_code: int) -> type[APIError]:
+        """Get the appropriate exception class based on status code."""
+        status_map = {
+            401: AuthenticationError,
+            404: NotFoundError,
+            422: ValidationError,
+            429: RateLimitError,
+        }
+
+        if status_code >= 500:
+            return ServerError
+
+        return status_map.get(status_code, APIError)
+
+    async def health_check(self) -> dict:
+        """
+        Call the /health endpoint for health check
+
+        Returns:
+            dict: Health check response
+        """
+        logger.debug("Making async health check request")
+        try:
+            response = await self.client.get("/health")
+            response.raise_for_status()
+            result = response.json()
+            logger.debug("Async health check successful")
+            return result
+        except httpx.HTTPStatusError as e:
+            logger.warning(f"Async health check failed: {e}")
+            raise

oagi-0.4.1/src/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-0.4.1/src/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()