oagi 0.2.0__tar.gz → 0.3.0__tar.gz

oagi-0.3.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.3
+Name: oagi
+Version: 0.3.0
+Summary: Official API of OpenAGI Foundation
+Project-URL: Homepage, https://github.com/agiopen-org/oagi
+Author-email: OpenAGI Foundation <contact@agiopen.org>
+License: MIT License
+        
+        Copyright (c) 2025 OpenAGI Foundation
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pillow>=11.3.0
+Requires-Dist: pyautogui>=0.9.54
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# OAGI Python SDK
+
+Python SDK for the OAGI API - vision-based task automation.
+
+## Installation
+
+```bash
+pip install oagi  # requires Python >= 3.10
+```
+
+## Quick Start
+
+Set your API credentials:
+```bash
+export OAGI_API_KEY="your-api-key"
+export OAGI_BASE_URL="https://api.oagi.com"  # or your server URL
+```
+
+### Single-Step Analysis
+
+Analyze a screenshot and get recommended actions:
+
+```python
+from oagi import single_step
+
+step = single_step(
+    task_description="Click the submit button",
+    screenshot="screenshot.png"  # or bytes, or Image object
+)
+
+print(f"Actions: {step.actions}")
+print(f"Complete: {step.is_complete}")
+```
+
+### Automated Task Execution
+
+Run tasks automatically with screenshot capture and action execution:
+
+```python
+from oagi import ShortTask, ScreenshotMaker, PyautoguiActionHandler
+
+task = ShortTask()
+completed = task.auto_mode(
+    "Search weather on Google",
+    max_steps=10,
+    executor=PyautoguiActionHandler(),  # Executes mouse/keyboard actions
+    image_provider=ScreenshotMaker(),    # Captures screenshots
+)
+```
+
+### Image Processing
+
+Process and optimize images before sending to API:
+
+```python
+from oagi import PILImage, ImageConfig
+
+# Load and compress an image
+image = PILImage.from_file("large_screenshot.png")
+config = ImageConfig(
+    format="JPEG",
+    quality=85,
+    width=1260,
+    height=700
+)
+compressed = image.transform(config)
+
+# Use with single_step
+step = single_step("Click button", screenshot=compressed)
+```
+
+## Examples
+
+See the [`examples/`](examples/) directory for more usage patterns:
+- `google_weather.py` - Basic task execution with `ShortTask`
+- `single_step.py` - Basic single-step inference
+- `screenshot_with_config.py` - Image compression and optimization
+- `execute_task_auto.py` - Automated task execution
+
+## Documentation
+
+
+## License
+
+MIT

oagi-0.3.0/README.md

@@ -0,0 +1,85 @@
+# OAGI Python SDK
+
+Python SDK for the OAGI API - vision-based task automation.
+
+## Installation
+
+```bash
+pip install oagi  # requires Python >= 3.10
+```
+
+## Quick Start
+
+Set your API credentials:
+```bash
+export OAGI_API_KEY="your-api-key"
+export OAGI_BASE_URL="https://api.oagi.com"  # or your server URL
+```
+
+### Single-Step Analysis
+
+Analyze a screenshot and get recommended actions:
+
+```python
+from oagi import single_step
+
+step = single_step(
+    task_description="Click the submit button",
+    screenshot="screenshot.png"  # or bytes, or Image object
+)
+
+print(f"Actions: {step.actions}")
+print(f"Complete: {step.is_complete}")
+```
+
+### Automated Task Execution
+
+Run tasks automatically with screenshot capture and action execution:
+
+```python
+from oagi import ShortTask, ScreenshotMaker, PyautoguiActionHandler
+
+task = ShortTask()
+completed = task.auto_mode(
+    "Search weather on Google",
+    max_steps=10,
+    executor=PyautoguiActionHandler(),  # Executes mouse/keyboard actions
+    image_provider=ScreenshotMaker(),    # Captures screenshots
+)
+```
+
+### Image Processing
+
+Process and optimize images before sending to API:
+
+```python
+from oagi import PILImage, ImageConfig
+
+# Load and compress an image
+image = PILImage.from_file("large_screenshot.png")
+config = ImageConfig(
+    format="JPEG",
+    quality=85,
+    width=1260,
+    height=700
+)
+compressed = image.transform(config)
+
+# Use with single_step
+step = single_step("Click button", screenshot=compressed)
+```
+
+## Examples
+
+See the [`examples/`](examples/) directory for more usage patterns:
+- `google_weather.py` - Basic task execution with `ShortTask`
+- `single_step.py` - Basic single-step inference
+- `screenshot_with_config.py` - Image compression and optimization
+- `execute_task_auto.py` - Automated task execution
+
+## Documentation
+
+
+## License
+
+MIT

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

@@ -17,6 +17,9 @@ def execute_task_manual(task_desc, max_steps=5):
     executor = (
         PyautoguiActionHandler()
     )  # executor = lambda actions: print(actions) for debugging
+
+    # 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 = ScreenshotMaker()
 
     for i in range(max_steps):

oagi-0.3.0/examples/screenshot_with_config.py

@@ -0,0 +1,94 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from oagi import ImageConfig, PILImage, ScreenshotMaker, single_step
+
+
+def example_full_png_screenshot():
+    """Example 1: Full-quality PNG screenshot without resizing."""
+    print("Example 1: Full PNG screenshot without resizing")
+
+    png_config = ImageConfig(
+        format="PNG",
+        width=None,  # No resizing - keep original width
+        height=None,  # No resizing - keep original height
+        optimize=True,  # Optimize PNG file size
+    )
+
+    screenshot_maker = ScreenshotMaker(config=png_config)
+    full_png_screenshot = screenshot_maker()
+
+    print(f"PNG screenshot dimensions: {full_png_screenshot.image.size}")
+    print(f"PNG screenshot size: {len(full_png_screenshot.read())} bytes")
+    return full_png_screenshot
+
+
+def example_load_and_compress(file_name):
+    """Example 2: Load image from file and convert to compressed JPEG."""
+    print("\nExample 2: Load image from file and convert to JPEG")
+
+    # Load an existing screenshot
+    original_image = PILImage.from_file(file_name)
+    print(f"Original image dimensions: {original_image.image.size}")
+
+    # Create a config for compression
+    jpeg_config = ImageConfig(
+        format="JPEG",
+        quality=70,  # Lower quality for smaller size
+        width=1260,  # Resize to 1260px width
+        height=700,  # Resize to 700px height
+    )
+
+    # Transform the image
+    compressed_image = original_image.transform(jpeg_config)
+    compressed_bytes = compressed_image.read()
+
+    print(f"Compressed image dimensions: {compressed_image.image.size}")
+    print(f"Compressed JPEG size: {len(compressed_bytes)} bytes")
+    return compressed_image
+
+
+def example_with_single_step(file_name):
+    """Example 3: Use compressed image with single_step."""
+    print("\nExample 3: Use with single_step")
+
+    # Load and compress image
+    image = PILImage.from_file(file_name)
+    print(f"Original image dimensions: {image.image.size}")
+
+    config = ImageConfig(format="JPEG", quality=85, width=1260, height=700)
+    compressed = image.transform(config)
+    print(f"Compressed image dimensions: {compressed.image.size}")
+
+    # Use with single_step
+    step = single_step(
+        task_description="Click the submit button",
+        screenshot=compressed,
+        api_key="your-api-key-here",
+        base_url="http://127.0.0.1:8000",
+    )
+
+    print(f"Task complete: {step.is_complete}")
+    return step
+
+
+def example_default_config():
+    """Example 4: Default configuration (1260x700 JPEG with 85 quality)."""
+    print("\nExample 4: Default configuration")
+
+    default_maker = ScreenshotMaker()  # Uses default ImageConfig
+    default_screenshot = default_maker()
+
+    print(f"Default screenshot dimensions: {default_screenshot.image.size}")
+    print(f"Default JPEG size: {len(default_screenshot.read())} bytes")
+    return default_screenshot
+
+
+if __name__ == "__main__":
+    example_full_png_screenshot()
+    example_default_config()

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oagi"
-version = "0.2.0"
+version = "0.3.0"
 description = "Official API of OpenAGI Foundation"
 readme = "README.md"
 license = { file = "LICENSE" }

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

@@ -18,12 +18,14 @@ from oagi.exceptions import (
     ServerError,
     ValidationError,
 )
+from oagi.pil_image import PILImage
 from oagi.pyautogui_action_handler import PyautoguiActionHandler
 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
 
 __all__ = [
     # Core classes
@@ -32,9 +34,13 @@ __all__ = [
     "SyncClient",
     # Functions
     "single_step",
+    # Image classes
+    "PILImage",
     # Handler classes
     "PyautoguiActionHandler",
     "ScreenshotMaker",
+    # Configuration
+    "ImageConfig",
     # Response models
     "LLMResponse",
     "ErrorResponse",

oagi-0.3.0/src/oagi/pil_image.py

@@ -0,0 +1,98 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+import io
+from typing import Optional
+
+import pyautogui
+from PIL import Image as PILImageLib
+
+from .types.models.image_config import ImageConfig
+
+
+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: Optional[bytes] = 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."""
+        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

oagi-0.3.0/src/oagi/screenshot_maker.py

@@ -0,0 +1,41 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from typing import Optional
+
+from .pil_image import PILImage
+from .types import Image
+from .types.models.image_config import ImageConfig
+
+
+class ScreenshotMaker:
+    """Takes screenshots using pyautogui."""
+
+    def __init__(self, config: ImageConfig | None = None):
+        self.config = config or ImageConfig()
+        self._last_image: Optional[PILImage] = None
+
+    def __call__(self) -> Image:
+        """Take and process a screenshot."""
+        # Create PILImage from screenshot
+        pil_image = PILImage.from_screenshot()
+
+        # Apply transformation if config is set
+        if self.config:
+            pil_image = pil_image.transform(self.config)
+
+        # Store as the last image
+        self._last_image = pil_image
+
+        return pil_image
+
+    def last_image(self) -> Image:
+        """Return the last screenshot taken, or take a new one if none exists."""
+        if self._last_image is None:
+            return self()
+        return self._last_image

{oagi-0.2.0 → oagi-0.3.0}/src/oagi/short_task.py

@@ -16,6 +16,14 @@ logger = get_logger("short_task")
 class ShortTask(Task):
     """Task implementation with automatic mode for short-duration tasks."""
 
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        model: str = "vision-model-v1",
+    ):
+        super().__init__(api_key=api_key, base_url=base_url, model=model)
+
     def auto_mode(
         self,
         task_desc: str,

{oagi-0.2.0 → oagi-0.3.0}/src/oagi/single_step.py

@@ -8,6 +8,7 @@
 
 from pathlib import Path
 
+from .pil_image import PILImage
 from .task import Task
 from .types import Image, Step
 
@@ -59,12 +60,12 @@ def single_step(
         ...     screenshot=image
         ... )
     """
-    # Convert file paths to bytes
+    # Convert file paths to bytes using PILImage
     if isinstance(screenshot, (str, Path)):
         path = Path(screenshot) if isinstance(screenshot, str) else screenshot
         if path.exists():
-            with open(path, "rb") as f:
-                screenshot_bytes = f.read()
+            pil_image = PILImage.from_file(str(path))
+            screenshot_bytes = pil_image.read()
         else:
             raise FileNotFoundError(f"Screenshot file not found: {path}")
     elif isinstance(screenshot, bytes):

{oagi-0.2.0 → oagi-0.3.0}/src/oagi/sync_client.py

@@ -8,8 +8,10 @@
 
 import base64
 import os
+from functools import wraps
 
 import httpx
+from httpx import Response
 from pydantic import BaseModel
 
 from .exceptions import (
@@ -63,6 +65,27 @@ class LLMResponse(BaseModel):
     error: ErrorDetail | None = None
 
 
+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:
     def __init__(self, base_url: str | None = None, api_key: str | None = None):
         # Get from environment if not provided
@@ -98,6 +121,7 @@ class SyncClient:
         """Close the underlying httpx client"""
         self.client.close()
 
+    @log_trace_on_failure
     def create_message(
         self,
         model: str,

{oagi-0.2.0 → oagi-0.3.0}/src/oagi/task.py

@@ -16,13 +16,18 @@ logger = get_logger("task")
 class Task:
     """Base class for task automation with the OAGI API."""
 
-    def __init__(self, api_key: str | None = None, base_url: str | None = None):
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        model: str = "vision-model-v1",
+    ):
         self.client = SyncClient(base_url=base_url, api_key=api_key)
         self.api_key = self.client.api_key
         self.base_url = self.client.base_url
         self.task_id: str | None = None
         self.task_description: str | None = None
-        self.model = "vision-model-v1"  # default model
+        self.model = model
 
     def init_task(self, task_desc: str, max_steps: int = 5):
         """Initialize a new task with the given description."""

{oagi-0.2.0 → oagi-0.3.0}/src/oagi/types/__init__.py

@@ -9,6 +9,14 @@
 from .action_handler import ActionHandler
 from .image import Image
 from .image_provider import ImageProvider
-from .models import Action, ActionType, Step
+from .models import Action, ActionType, ImageConfig, Step
 
-__all__ = ["Action", "ActionType", "Image", "Step", "ActionHandler", "ImageProvider"]
+__all__ = [
+    "Action",
+    "ActionType",
+    "Image",
+    "ImageConfig",
+    "Step",
+    "ActionHandler",
+    "ImageProvider",
+]

{oagi-0.2.0 → oagi-0.3.0}/src/oagi/types/models/__init__.py

@@ -7,6 +7,7 @@
 # -----------------------------------------------------------------------------
 
 from .action import Action, ActionType
+from .image_config import ImageConfig
 from .step import Step
 
-__all__ = ["Action", "ActionType", "Step"]
+__all__ = ["Action", "ActionType", "ImageConfig", "Step"]

oagi-0.3.0/src/oagi/types/models/image_config.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.
+# -----------------------------------------------------------------------------
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class ImageConfig(BaseModel):
+    """Configuration for image capture and processing."""
+
+    format: Literal["PNG", "JPEG"] = Field(
+        default="JPEG", description="Image format for encoding"
+    )
+    quality: int = Field(
+        default=85,
+        ge=1,
+        le=100,
+        description="JPEG quality (1-100, only applies to JPEG format)",
+    )
+    width: int | None = Field(
+        default=1260, description="Target width in pixels (will resize to exact size)"
+    )
+    height: int | None = Field(
+        default=700, description="Target height in pixels (will resize to exact size)"
+    )
+    optimize: bool = Field(
+        default=False,
+        description="Enable PNG optimization (only applies to PNG format)",
+    )
+    resample: Literal["NEAREST", "BILINEAR", "BICUBIC", "LANCZOS"] = Field(
+        default="LANCZOS", description="Resampling filter for resizing"
+    )
+
+    @field_validator("quality")
+    @classmethod
+    def validate_quality(cls, v: int, info) -> int:
+        """Validate quality parameter based on format."""
+        values = info.data
+        if values.get("format") == "PNG" and v != 85:
+            return 85
+        return v