oagi 0.1.0__tar.gz → 0.2.0__tar.gz

oagi-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # For trusted publishing
+      contents: write  # For GitHub release
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+      
+      - name: Set up Python
+        run: uv python install 3.12
+      
+      - name: Build package
+        run: uv build
+      
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          # Another option: Use Trusted Publishing (recommended, no token needed)
+          # Configure at: https://pypi.org/manage/project/oagi/settings/publishing/
+          
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: dist/*
+          generate_release_notes: true

{oagi-0.1.0 → oagi-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: oagi
-Version: 0.1.0
+Version: 0.2.0
 Summary: Official API of OpenAGI Foundation
 Project-URL: Homepage, https://github.com/agiopen-org/oagi
 Author-email: OpenAGI Foundation <contact@agiopen.org>
@@ -33,3 +33,23 @@ Requires-Dist: pydantic>=2.0.0
 Description-Content-Type: text/markdown
 
 # OAGI Python SDK
+
+## Basic Usage
+```bash
+pip install oagi # python >= 3.10
+```
+```bash
+export OAGI_BASE_URL=""
+export OAGI_API_KEY="sk-xxxx"
+```
+
+```python
+from oagi import PyautoguiActionHandler, ScreenshotMaker, ShortTask
+short_task = ShortTask()
+is_completed = short_task.auto_mode(
+    "Search weather with Google",
+    max_steps=5,
+    executor=PyautoguiActionHandler(),
+    image_provider=(sm := ScreenshotMaker()),
+)
+```

oagi-0.2.0/README.md

@@ -0,0 +1,21 @@
+# OAGI Python SDK
+
+## Basic Usage
+```bash
+pip install oagi # python >= 3.10
+```
+```bash
+export OAGI_BASE_URL=""
+export OAGI_API_KEY="sk-xxxx"
+```
+
+```python
+from oagi import PyautoguiActionHandler, ScreenshotMaker, ShortTask
+short_task = ShortTask()
+is_completed = short_task.auto_mode(
+    "Search weather with Google",
+    max_steps=5,
+    executor=PyautoguiActionHandler(),
+    image_provider=(sm := ScreenshotMaker()),
+)
+```

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

@@ -6,23 +6,29 @@
 #  Licensed under the MIT License.
 # -----------------------------------------------------------------------------
 
-from oagi import PyautoguiActionHandler, ScreenshotMaker, ShortTask
+from oagi import PyautoguiActionHandler, ScreenshotMaker, Task
 
 
 def 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")
-    short_task = ShortTask()
-    short_task.init_task(task_desc, max_steps=max_steps)
+    task = Task()
+    task.init_task(task_desc, max_steps=max_steps)
     executor = (
         PyautoguiActionHandler()
     )  # executor = lambda actions: print(actions) for debugging
     image_provider = ScreenshotMaker()
 
     for i in range(max_steps):
+        # image can also be bytes
+        # with open("test_screenshot.png", "rb") as f:
+        #     image = f.read()
         image = image_provider()
-        # do something with image, maybe save it or OCR then break
-        step = short_task.step(image)
+
+        # For additional instructions
+        # step = task.step(image, instruction="some instruction")
+        step = task.step(image)
+
         # do something with step, maybe print to debug
         print(f"Step {i}: {step.reason=}")
 

oagi-0.2.0/examples/single_step.py

@@ -0,0 +1,19 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from oagi import single_step
+
+step = single_step(
+    task_description="Search weather with Google",
+    screenshot="some/path/to/local/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
+)
+
+print(step)

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oagi"
-version = "0.1.0"
+version = "0.2.0"
 description = "Official API of OpenAGI Foundation"
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -32,4 +32,4 @@ dev = [
 ]
 
 [tool.ruff.lint]
-extend-select = ["I"]
+extend-select = ["I", "PLC0415"]

oagi-0.2.0/src/oagi/__init__.py

@@ -0,0 +1,53 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from oagi.exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    NetworkError,
+    NotFoundError,
+    OAGIError,
+    RateLimitError,
+    RequestTimeoutError,
+    ServerError,
+    ValidationError,
+)
+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
+
+__all__ = [
+    # Core classes
+    "Task",
+    "ShortTask",
+    "SyncClient",
+    # Functions
+    "single_step",
+    # Handler classes
+    "PyautoguiActionHandler",
+    "ScreenshotMaker",
+    # Response models
+    "LLMResponse",
+    "ErrorResponse",
+    "ErrorDetail",
+    # Exceptions
+    "OAGIError",
+    "APIError",
+    "AuthenticationError",
+    "ConfigurationError",
+    "NetworkError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "RequestTimeoutError",
+    "ValidationError",
+]

oagi-0.2.0/src/oagi/exceptions.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 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

oagi-0.2.0/src/oagi/short_task.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.
+# -----------------------------------------------------------------------------
+
+from .logging import get_logger
+from .task import Task
+from .types import ActionHandler, ImageProvider
+
+logger = get_logger("short_task")
+
+
+class ShortTask(Task):
+    """Task implementation with automatic mode for short-duration tasks."""
+
+    def auto_mode(
+        self,
+        task_desc: str,
+        max_steps: int = 5,
+        executor: ActionHandler = None,
+        image_provider: ImageProvider = None,
+    ) -> bool:
+        """Run the task in automatic mode with the provided executor and image provider."""
+        logger.info(
+            f"Starting auto mode for task: '{task_desc}' (max_steps: {max_steps})"
+        )
+        self.init_task(task_desc, max_steps=max_steps)
+
+        for i in range(max_steps):
+            logger.debug(f"Auto mode step {i + 1}/{max_steps}")
+            image = image_provider()
+            step = self.step(image)
+            if step.stop:
+                logger.info(f"Auto mode completed successfully after {i + 1} steps")
+                return True
+            if executor:
+                logger.debug(f"Executing {len(step.actions)} actions")
+                executor(step.actions)
+
+        logger.warning(f"Auto mode reached max steps ({max_steps}) without completion")
+        return False

oagi-0.2.0/src/oagi/single_step.py

@@ -0,0 +1,82 @@
+# -----------------------------------------------------------------------------
+#  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 Task
+from .types import Image, Step
+
+
+def single_step(
+    task_description: str,
+    screenshot: str | bytes | Path | Image,
+    instruction: str | None = None,
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> Step:
+    """
+    Perform a single-step inference 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)
+
+    Returns:
+        Step: Object containing reasoning, actions, and completion status
+
+    Example:
+        >>> # Using with bytes
+        >>> with open("screenshot.png", "rb") as f:
+        ...     image_bytes = f.read()
+        >>> step = single_step(
+        ...     task_description="Click the submit button",
+        ...     screenshot=image_bytes
+        ... )
+
+        >>> # Using with file path
+        >>> step = single_step(
+        ...     task_description="Fill in the form",
+        ...     screenshot=Path("screenshot.png"),
+        ...     instruction="Use test@example.com for email"
+        ... )
+
+        >>> # Using with Image object
+        >>> from oagi.types import Image
+        >>> image = Image(...)
+        >>> step = single_step(
+        ...     task_description="Navigate to settings",
+        ...     screenshot=image
+        ... )
+    """
+    # Convert file paths to bytes
+    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()
+        else:
+            raise FileNotFoundError(f"Screenshot file not found: {path}")
+    elif isinstance(screenshot, bytes):
+        screenshot_bytes = screenshot
+    elif isinstance(screenshot, Image):
+        screenshot_bytes = screenshot.read()
+    else:
+        raise ValueError(
+            f"screenshot must be Image, bytes, str, or Path, got {type(screenshot)}"
+        )
+
+    # Use Task to perform single step
+    with Task(api_key=api_key, base_url=base_url) as task:
+        task.init_task(task_description)
+        return task.step(screenshot_bytes, instruction=instruction)

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

@@ -8,11 +8,21 @@
 
 import base64
 import os
-from typing import Optional
 
 import httpx
 from pydantic import BaseModel
 
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    RequestTimeoutError,
+    ServerError,
+    ValidationError,
+)
 from .logging import get_logger
 from .types import Action
 
@@ -25,6 +35,19 @@ class Usage(BaseModel):
     total_tokens: int
 
 
+class ErrorDetail(BaseModel):
+    """Detailed error information."""
+
+    code: str
+    message: str
+
+
+class ErrorResponse(BaseModel):
+    """Standard error response format."""
+
+    error: ErrorDetail | None
+
+
 class LLMResponse(BaseModel):
     id: str
     task_id: str
@@ -37,29 +60,24 @@ class LLMResponse(BaseModel):
     actions: list[Action]
     reason: str | None = None
     usage: Usage
-
-
-class ErrorResponse(BaseModel):
-    error: str
-    message: str
-    code: int
+    error: ErrorDetail | None = None
 
 
 class SyncClient:
-    def __init__(self, base_url: Optional[str] = None, api_key: Optional[str] = None):
+    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 ValueError(
+            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 ValueError(
+            raise ConfigurationError(
                 "OAGI API key must be provided either as 'api_key' parameter or "
                 "OAGI_API_KEY environment variable"
             )
@@ -84,10 +102,11 @@ class SyncClient:
         self,
         model: str,
         screenshot: str,  # base64 encoded
-        task_description: Optional[str] = None,
-        task_id: Optional[str] = None,
-        max_actions: Optional[int] = 5,
-        api_version: Optional[str] = None,
+        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
@@ -97,6 +116,7 @@ class SyncClient:
             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
 
@@ -118,6 +138,8 @@ class SyncClient:
             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
 
@@ -126,32 +148,92 @@ class SyncClient:
             f"Request includes task_description: {task_description is not None}, task_id: {task_id is not None}"
         )
 
-        response = self.client.post(
-            "/v1/message", json=payload, headers=headers, timeout=self.timeout
-        )
+        try:
+            response = 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)
 
-        if response.status_code == 200:
-            result = LLMResponse(**response.json())
-            logger.info(
-                f"API request successful - task_id: {result.task_id}, step: {result.current_step}, complete: {result.is_complete}"
+        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,
             )
-            logger.debug(f"Response included {len(result.actions)} actions")
-            return result
-        else:
-            # Handle error responses
-            try:
-                error_data = response.json()
-                error = ErrorResponse(**error_data)
-                logger.error(f"API Error {error.code}: {error.error} - {error.message}")
-                raise httpx.HTTPStatusError(
-                    f"API Error {error.code}: {error.error} - {error.message}",
-                    request=response.request,
+
+        # 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,
                 )
-            except ValueError:
-                # If response is not JSON, raise generic error
-                logger.error(f"Non-JSON API error response: {response.status_code}")
-                response.raise_for_status()
+
+        # 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"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)
 
     def health_check(self) -> dict:
         """