oagi 0.2.1__tar.gz → 0.4.0__tar.gz

oagi-0.4.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.3
+Name: oagi
+Version: 0.4.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
+)
+```
+
+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:
+
+```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)
+```
+
+### 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:
+- `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.4.0/README.md

@@ -0,0 +1,127 @@
+# 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
+)
+```
+
+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:
+
+```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)
+```
+
+### 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:
+- `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.4.0/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.2.1 → oagi-0.4.0}/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.4.0/examples/execute_task_manual.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.
+# -----------------------------------------------------------------------------
+
+from oagi import (
+    AsyncPyautoguiActionHandler,
+    AsyncScreenshotMaker,
+    AsyncTask,
+    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")
+    task = Task()
+    task.init_task(task_desc, max_steps=max_steps)
+    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):
+        # image can also be bytes
+        # with open("test_screenshot.png", "rb") as f:
+        #     image = f.read()
+        image = image_provider()
+
+        # 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=}")
+
+        if step.stop:
+            print(f"Task completed after {i} steps.")
+            is_completed = True
+            screenshot = image_provider.last_image()
+            break
+
+        executor(step.actions)
+    else:
+        # If we didn't break out of the loop, we used up all our steps
+        is_completed = False
+        screenshot = image_provider()
+
+    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.4.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.1 → oagi-0.4.0}/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.2.1 → oagi-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "oagi"
-version = "0.2.1"
+version = "0.4.0"
 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.2.1 → oagi-0.4.0}/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,
@@ -18,23 +24,45 @@ from oagi.exceptions import (
     ServerError,
     ValidationError,
 )
-from oagi.pyautogui_action_handler import PyautoguiActionHandler
+from oagi.pil_image import PILImage
+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 (
+    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
     "LLMResponse",
     "ErrorResponse",