oagi 0.1.0__tar.gz → 0.2.1__tar.gz

oagi-0.2.1/.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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: oagi
-Version: 0.1.0
+Version: 0.2.1
 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.1/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.1}/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.1/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.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oagi"
-version = "0.1.0"
+version = "0.2.1"
 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.1/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.1/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.1/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.1/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)