oagi-core 0.10.1__py3-none-any.whl

oagi/client/sync.py

@@ -0,0 +1,293 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from functools import wraps
+
+import httpx
+from httpx import Response
+
+from ..logging import get_logger
+from ..types import Image
+from ..types.models import GenerateResponse, LLMResponse, UploadFileResponse
+from .base import BaseClient
+
+logger = get_logger("sync_client")
+
+
+def _log_trace_id(response: Response):
+    logger.error(f"Request Id: {response.headers.get('x-request-id', '')}")
+    logger.error(f"Trace Id: {response.headers.get('x-trace-id', '')}")
+
+
+def log_trace_on_failure(func):
+    """Decorator that logs trace ID when a method fails."""
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            return 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:
+                _log_trace_id(response)
+            raise
+
+    return wrapper
+
+
+class SyncClient(BaseClient[httpx.Client]):
+    """Synchronous HTTP client for the OAGI API."""
+
+    def __init__(self, base_url: str | None = None, api_key: str | None = None):
+        super().__init__(base_url, api_key)
+        self.client = httpx.Client(base_url=self.base_url)
+        self.upload_client = httpx.Client(timeout=60)  # client for uploading image
+        logger.info(f"SyncClient initialized with base_url: {self.base_url}")
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.client.close()
+        self.upload_client.close()
+
+    def close(self):
+        """Close the underlying httpx clients."""
+        self.client.close()
+        self.upload_client.close()
+
+    @log_trace_on_failure
+    def create_message(
+        self,
+        model: str,
+        screenshot: bytes | None = None,
+        screenshot_url: str | None = None,
+        task_description: str | None = None,
+        task_id: str | None = None,
+        instruction: str | None = None,
+        messages_history: list | None = None,
+        temperature: float | None = None,
+        api_version: str | None = None,
+    ) -> LLMResponse | None:
+        """
+        Call the /v2/message endpoint to analyze task and screenshot
+
+        Args:
+            model: The model to use for task analysis
+            screenshot: Screenshot image bytes (mutually exclusive with screenshot_url)
+            screenshot_url: Direct URL to screenshot (mutually exclusive with screenshot)
+            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
+            messages_history: OpenAI-compatible chat message history
+            temperature: Sampling temperature (0.0-2.0) for LLM inference
+            api_version: API version header
+
+        Returns:
+            LLMResponse: The response from the API
+
+        Raises:
+            ValueError: If both or neither screenshot and screenshot_url are provided
+            httpx.HTTPStatusError: For HTTP error responses
+        """
+        # Validate that exactly one is provided
+        if (screenshot is None) == (screenshot_url is None):
+            raise ValueError(
+                "Exactly one of 'screenshot' or 'screenshot_url' must be provided"
+            )
+
+        self._log_request_info(model, task_description, task_id)
+
+        # Upload screenshot to S3 if bytes provided, otherwise use URL directly
+        upload_file_response = None
+        if screenshot is not None:
+            upload_file_response = self.put_s3_presigned_url(screenshot, api_version)
+
+        # Prepare message payload
+        headers, payload = self._prepare_message_payload(
+            model=model,
+            upload_file_response=upload_file_response,
+            task_description=task_description,
+            task_id=task_id,
+            instruction=instruction,
+            messages_history=messages_history,
+            temperature=temperature,
+            api_version=api_version,
+            screenshot_url=screenshot_url,
+        )
+
+        # Make request
+        try:
+            response = self.client.post(
+                "/v2/message", json=payload, headers=headers, timeout=self.timeout
+            )
+            return self._process_response(response)
+        except (httpx.TimeoutException, httpx.NetworkError) as e:
+            self._handle_upload_http_errors(e)
+
+    def health_check(self) -> dict:
+        """
+        Call the /health endpoint for health check
+
+        Returns:
+            dict: Health check response
+        """
+        logger.debug("Making health check request")
+        try:
+            response = self.client.get("/health")
+            response.raise_for_status()
+            result = response.json()
+            logger.debug("Health check successful")
+            return result
+        except httpx.HTTPStatusError as e:
+            logger.warning(f"Health check failed: {e}")
+            raise
+
+    def get_s3_presigned_url(
+        self,
+        api_version: str | None = None,
+    ) -> UploadFileResponse:
+        """
+        Call the /v1/file/upload endpoint to get a S3 presigned URL
+
+        Args:
+            api_version: API version header
+
+        Returns:
+            UploadFileResponse: The response from /v1/file/upload with uuid and presigned S3 URL
+        """
+        logger.debug("Making API request to /v1/file/upload")
+
+        try:
+            headers = self._build_headers(api_version)
+            response = self.client.get(
+                "/v1/file/upload", headers=headers, timeout=self.timeout
+            )
+            return self._process_upload_response(response)
+        except (httpx.TimeoutException, httpx.NetworkError, httpx.HTTPStatusError) as e:
+            self._handle_upload_http_errors(e, getattr(e, "response", None))
+
+    def upload_to_s3(
+        self,
+        url: str,
+        content: bytes | Image,
+    ) -> None:
+        """
+        Upload image bytes to S3 using presigned URL
+
+        Args:
+            url: S3 presigned URL
+            content: Image bytes or Image object to upload
+
+        Raises:
+            APIError: If upload fails
+        """
+        logger.debug("Uploading image to S3")
+
+        # Convert Image to bytes if needed
+        if isinstance(content, Image):
+            content = content.read()
+
+        response = None
+        try:
+            response = self.upload_client.put(url=url, content=content)
+            response.raise_for_status()
+        except Exception as e:
+            self._handle_s3_upload_error(e, response)
+
+    def put_s3_presigned_url(
+        self,
+        screenshot: bytes | Image,
+        api_version: str | None = None,
+    ) -> UploadFileResponse:
+        """
+        Get S3 presigned URL and upload image (convenience method)
+
+        Args:
+            screenshot: Screenshot image bytes or Image object
+            api_version: API version header
+
+        Returns:
+            UploadFileResponse: The response from /v1/file/upload with uuid and presigned S3 URL
+        """
+        upload_file_response = self.get_s3_presigned_url(api_version)
+        self.upload_to_s3(upload_file_response.url, screenshot)
+        return upload_file_response
+
+    @log_trace_on_failure
+    def call_worker(
+        self,
+        worker_id: str,
+        overall_todo: str,
+        task_description: str,
+        todos: list[dict],
+        history: list[dict] | None = None,
+        current_todo_index: int | None = None,
+        task_execution_summary: str | None = None,
+        current_screenshot: str | None = None,
+        current_subtask_instruction: str | None = None,
+        window_steps: list[dict] | None = None,
+        window_screenshots: list[str] | None = None,
+        result_screenshot: str | None = None,
+        prior_notes: str | None = None,
+        latest_todo_summary: str | None = None,
+        api_version: str | None = None,
+    ) -> GenerateResponse:
+        """Call the /v1/generate endpoint for OAGI worker processing.
+
+        Args:
+            worker_id: One of "oagi_first", "oagi_follow", "oagi_task_summary"
+            overall_todo: Current todo description
+            task_description: Overall task description
+            todos: List of todo dicts with index, description, status, execution_summary
+            history: List of history dicts with todo_index, todo_description, action_count, summary, completed
+            current_todo_index: Index of current todo being executed
+            task_execution_summary: Summary of overall task execution
+            current_screenshot: Uploaded file UUID for screenshot (oagi_first)
+            current_subtask_instruction: Subtask instruction (oagi_follow)
+            window_steps: Action steps list (oagi_follow)
+            window_screenshots: Uploaded file UUIDs list (oagi_follow)
+            result_screenshot: Uploaded file UUID for result screenshot (oagi_follow)
+            prior_notes: Execution notes (oagi_follow)
+            latest_todo_summary: Latest summary (oagi_task_summary)
+            api_version: API version header
+
+        Returns:
+            GenerateResponse with LLM output and usage stats
+
+        Raises:
+            ValueError: If worker_id is invalid
+            APIError: If API returns error
+        """
+        # Prepare request (validation, payload, headers)
+        payload, headers = self._prepare_worker_request(
+            worker_id=worker_id,
+            overall_todo=overall_todo,
+            task_description=task_description,
+            todos=todos,
+            history=history,
+            current_todo_index=current_todo_index,
+            task_execution_summary=task_execution_summary,
+            current_screenshot=current_screenshot,
+            current_subtask_instruction=current_subtask_instruction,
+            window_steps=window_steps,
+            window_screenshots=window_screenshots,
+            result_screenshot=result_screenshot,
+            prior_notes=prior_notes,
+            latest_todo_summary=latest_todo_summary,
+            api_version=api_version,
+        )
+
+        # Make request
+        try:
+            response = self.client.post(
+                "/v1/generate", json=payload, headers=headers, timeout=self.timeout
+            )
+            return self._process_generate_response(response)
+        except (httpx.TimeoutException, httpx.NetworkError) as e:
+            self._handle_upload_http_errors(e)

oagi/exceptions.py

@@ -0,0 +1,118 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+import importlib.util
+
+import httpx
+
+
+class OAGIError(Exception):
+    pass
+
+
+class APIError(OAGIError):
+    def __init__(
+        self,
+        message: str,
+        code: str | None = None,
+        status_code: int | None = None,
+        response: httpx.Response | None = None,
+    ):
+        """Initialize APIError.
+
+        Args:
+            message: Human-readable error message
+            code: API error code for programmatic handling
+            status_code: HTTP status code
+            response: Original HTTP response object
+        """
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.status_code = status_code
+        self.response = response
+
+    def __str__(self) -> str:
+        if self.code:
+            return f"API Error [{self.code}]: {self.message}"
+        return f"API Error: {self.message}"
+
+
+class AuthenticationError(APIError):
+    pass
+
+
+class RateLimitError(APIError):
+    pass
+
+
+class ValidationError(APIError):
+    pass
+
+
+class NotFoundError(APIError):
+    pass
+
+
+class ServerError(APIError):
+    pass
+
+
+class NetworkError(OAGIError):
+    def __init__(self, message: str, original_error: Exception | None = None):
+        super().__init__(message)
+        self.original_error = original_error
+
+
+class RequestTimeoutError(NetworkError):
+    pass
+
+
+class ConfigurationError(OAGIError):
+    pass
+
+
+def check_optional_dependency(
+    name: str,
+    feature: str,
+    extra: str,
+    raise_error: bool = True,
+) -> bool:
+    """Check if an optional dependency is available, raise helpful error if not.
+
+    This function validates that an optional dependency is installed without
+    returning the module, allowing the caller to use a regular import statement
+    afterward. This preserves IDE features like type hints, autocomplete, and
+    go-to-definition.
+
+    Args:
+        name: Module name to check (e.g., "pyautogui", "PIL")
+        feature: Feature name for error message (e.g., "PyautoguiActionHandler")
+        extra: extras_require key (e.g., "desktop", "server")
+        raise_error: Whether to raise an ImportError if the module is not installed
+
+    Raises:
+        ImportError: If the module is not installed, with installation instructions
+
+    Example:
+        >>> check_optional_dependency("pyautogui", "PyautoguiActionHandler", "desktop")
+        >>> import pyautogui  # Full IDE support: types, autocomplete, navigation
+        >>> pyautogui.click(100, 100)
+    """
+    spec = importlib.util.find_spec(name)
+    if spec is not None:
+        return True
+
+    msg = (
+        f"{feature} requires {extra} dependencies. "
+        f"Install with: pip install oagi[{extra}]"
+    )
+    if raise_error:
+        raise ImportError(msg)
+    else:
+        return False

oagi/handler/__init__.py

@@ -0,0 +1,24 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+from oagi.handler.async_pyautogui_action_handler import AsyncPyautoguiActionHandler
+from oagi.handler.async_screenshot_maker import AsyncScreenshotMaker
+from oagi.handler.pil_image import PILImage
+from oagi.handler.pyautogui_action_handler import (
+    PyautoguiActionHandler,
+    PyautoguiConfig,
+)
+from oagi.handler.screenshot_maker import ScreenshotMaker
+
+__all__ = [
+    "PILImage",
+    "PyautoguiActionHandler",
+    "PyautoguiConfig",
+    "AsyncPyautoguiActionHandler",
+    "ScreenshotMaker",
+    "AsyncScreenshotMaker",
+]

oagi/handler/_macos.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.
+# -----------------------------------------------------------------------------
+
+import pyautogui
+
+from ..exceptions import check_optional_dependency
+
+check_optional_dependency("Quartz", "macOS multiple clicks", "desktop")
+import Quartz  # noqa: E402
+
+
+def macos_click(x: int, y: int, clicks: int = 1) -> None:
+    """
+    Execute a mouse click sequence on macOS with correct click state.
+
+    This avoids the PyAutoGUI bug where multi-clicks are sent as separate
+    single clicks (clickState=1), which macOS interprets as distinct events
+    rather than double/triple clicks.
+
+    Check https://github.com/asweigart/pyautogui/issues/672
+
+    Args:
+        x: X coordinate
+        y: Y coordinate
+        clicks: Number of clicks (1=single, 2=double, 3=triple)
+    """
+    # Move to position first using pyautogui to ensure consistency
+    pyautogui.moveTo(x, y)
+
+    point = Quartz.CGPoint(x=x, y=y)
+
+    # Create and post events for each click in the sequence
+    for i in range(1, clicks + 1):
+        # Create Down/Up events
+        mouse_down = Quartz.CGEventCreateMouseEvent(
+            None, Quartz.kCGEventLeftMouseDown, point, Quartz.kCGMouseButtonLeft
+        )
+        mouse_up = Quartz.CGEventCreateMouseEvent(
+            None, Quartz.kCGEventLeftMouseUp, point, Quartz.kCGMouseButtonLeft
+        )
+
+        # Set the click state (1 for first click, 2 for second, etc.)
+        Quartz.CGEventSetIntegerValueField(
+            mouse_down, Quartz.kCGMouseEventClickState, i
+        )
+        Quartz.CGEventSetIntegerValueField(mouse_up, Quartz.kCGMouseEventClickState, i)
+
+        # Post events
+        Quartz.CGEventPost(Quartz.kCGHIDEventTap, mouse_down)
+        Quartz.CGEventPost(Quartz.kCGHIDEventTap, mouse_up)

oagi/handler/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 ..types import Action
+from .pyautogui_action_handler import PyautoguiActionHandler, PyautoguiConfig
+
+
+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/handler/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 ..types import Image, ImageConfig
+from .screenshot_maker import ScreenshotMaker
+
+
+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/handler/pil_image.py

@@ -0,0 +1,102 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+import io
+
+from ..exceptions import check_optional_dependency
+from ..types.models.image_config import ImageConfig
+
+check_optional_dependency("PIL", "PILImage", "desktop")
+from PIL import Image as PILImageLib  # noqa: E402
+
+
+class PILImage:
+    """PIL image wrapper with transformation capabilities."""
+
+    def __init__(self, image: PILImageLib.Image, config: ImageConfig | None = None):
+        """Initialize with a PIL image and optional config."""
+        self.image = image
+        self.config = config or ImageConfig()
+        self._cached_bytes: bytes | None = None
+
+    @classmethod
+    def from_file(cls, path: str, config: ImageConfig | None = None) -> "PILImage":
+        """Create PILImage from file path."""
+        image = PILImageLib.open(path)
+        return cls(image, config)
+
+    @classmethod
+    def from_bytes(cls, data: bytes, config: ImageConfig | None = None) -> "PILImage":
+        """Create PILImage from raw bytes."""
+        image = PILImageLib.open(io.BytesIO(data))
+        return cls(image, config)
+
+    @classmethod
+    def from_screenshot(cls, config: ImageConfig | None = None) -> "PILImage":
+        """Create PILImage from screenshot."""
+        # Lazy import to avoid DISPLAY issues in headless environments
+        check_optional_dependency("pyautogui", "PILImage.from_screenshot()", "desktop")
+        import pyautogui  # noqa: PLC0415
+
+        screenshot = pyautogui.screenshot()
+        return cls(screenshot, config)
+
+    def transform(self, config: ImageConfig) -> "PILImage":
+        """Apply transformations (resize) based on config and return new PILImage."""
+        # Apply resize if needed
+        transformed = self._resize(self.image, config)
+        # Return new PILImage with the config (format conversion happens on read())
+        return PILImage(transformed, config)
+
+    def _resize(
+        self, image: PILImageLib.Image, config: ImageConfig
+    ) -> PILImageLib.Image:
+        """Resize image based on config."""
+        if config.width or config.height:
+            # Get target dimensions (use original if not specified)
+            target_width = config.width or image.width
+            target_height = config.height or image.height
+
+            # Map resample string to PIL constant
+            resample_map = {
+                "NEAREST": PILImageLib.NEAREST,
+                "BILINEAR": PILImageLib.BILINEAR,
+                "BICUBIC": PILImageLib.BICUBIC,
+                "LANCZOS": PILImageLib.LANCZOS,
+            }
+            resample = resample_map[config.resample]
+
+            # Resize to exact dimensions
+            return image.resize((target_width, target_height), resample)
+        return image
+
+    def _convert_format(self, image: PILImageLib.Image) -> bytes:
+        """Convert image to configured format (PNG or JPEG)."""
+        buffer = io.BytesIO()
+        save_kwargs = {"format": self.config.format}
+
+        if self.config.format == "JPEG":
+            save_kwargs["quality"] = self.config.quality
+            # Convert RGBA to RGB for JPEG if needed
+            if image.mode == "RGBA":
+                rgb_image = PILImageLib.new("RGB", image.size, (255, 255, 255))
+                rgb_image.paste(image, mask=image.split()[3])
+                rgb_image.save(buffer, **save_kwargs)
+            else:
+                image.save(buffer, **save_kwargs)
+        elif self.config.format == "PNG":
+            save_kwargs["optimize"] = self.config.optimize
+            image.save(buffer, **save_kwargs)
+
+        return buffer.getvalue()
+
+    def read(self) -> bytes:
+        """Read image as bytes with current config (implements Image protocol)."""
+        if self._cached_bytes is None:
+            self._cached_bytes = self._convert_format(self.image)
+        return self._cached_bytes