oagi-core 0.9.0__py3-none-any.whl

oagi/task/__init__.py

@@ -0,0 +1,14 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from .async_ import AsyncTask
+from .async_short import AsyncShortTask
+from .short import ShortTask
+from .sync import Task
+
+__all__ = ["Task", "AsyncTask", "ShortTask", "AsyncShortTask"]

oagi/task/async_.py

@@ -0,0 +1,97 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from ..client import AsyncClient
+from ..logging import get_logger
+from ..types import Image, Step
+from .base import BaseTask
+
+logger = get_logger("async_task")
+
+
+class AsyncTask(BaseTask):
+    """Async base class for task automation with the OAGI API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        model: str = "vision-model-v1",
+        temperature: float | None = None,
+    ):
+        super().__init__(api_key, base_url, model, temperature)
+        self.client = AsyncClient(base_url=base_url, api_key=api_key)
+        self.api_key = self.client.api_key
+        self.base_url = self.client.base_url
+
+    async def init_task(
+        self,
+        task_desc: str,
+        max_steps: int = 5,
+    ):
+        """Initialize a new task with the given description.
+
+        Args:
+            task_desc: Task description
+            max_steps: Maximum number of steps (for logging)
+        """
+        self._prepare_init_task(task_desc, max_steps)
+
+    async def step(
+        self,
+        screenshot: Image | bytes,
+        instruction: str | None = None,
+        temperature: float | None = None,
+    ) -> Step:
+        """Send screenshot to the server and get the next actions.
+
+        Args:
+            screenshot: Screenshot as Image object or raw bytes
+            instruction: Optional additional instruction for this step
+            temperature: Sampling temperature for this step (overrides task default if provided)
+
+        Returns:
+            Step: The actions and reasoning for this step
+        """
+        self._validate_step_preconditions()
+        self._log_step_execution(prefix="async ")
+
+        try:
+            # Use provided temperature or fall back to task default
+            temp = self._get_temperature(temperature)
+
+            # Prepare screenshot kwargs (handles URLImage vs bytes/Image)
+            screenshot_kwargs = self._prepare_screenshot_kwargs(screenshot)
+
+            # Call API with dynamically determined screenshot argument
+            response = await self.client.create_message(
+                model=self.model,
+                task_description=self.task_description,
+                task_id=self.task_id,
+                instruction=instruction,
+                messages_history=self.message_history,
+                temperature=temp,
+                **screenshot_kwargs,
+            )
+
+            # Convert API response to Step (also updates message_history)
+            return self._build_step_response(response, prefix="Async ")
+
+        except Exception as e:
+            logger.error(f"Error during async step execution: {e}")
+            raise
+
+    async def close(self):
+        """Close the underlying HTTP client to free resources."""
+        await self.client.close()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()

oagi/task/async_short.py

@@ -0,0 +1,64 @@
+# -----------------------------------------------------------------------------
+#  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 ..types import AsyncActionHandler, AsyncImageProvider
+from .async_ import AsyncTask
+from .base import BaseAutoMode
+
+logger = get_logger("async_short_task")
+
+
+class AsyncShortTask(AsyncTask, BaseAutoMode):
+    """Async 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",
+        temperature: float | None = None,
+    ):
+        super().__init__(
+            api_key=api_key, base_url=base_url, model=model, temperature=temperature
+        )
+
+    async def auto_mode(
+        self,
+        task_desc: str,
+        max_steps: int = 5,
+        executor: AsyncActionHandler = None,
+        image_provider: AsyncImageProvider = None,
+        temperature: float | None = None,
+    ) -> bool:
+        """Run the task in automatic mode with the provided executor and image provider.
+
+        Args:
+            task_desc: Task description
+            max_steps: Maximum number of steps
+            executor: Async handler to execute actions
+            image_provider: Async provider for screenshots
+            temperature: Sampling temperature for all steps (overrides task default if provided)
+        """
+        self._log_auto_mode_start(task_desc, max_steps, prefix="async ")
+
+        await self.init_task(task_desc, max_steps=max_steps)
+
+        for i in range(max_steps):
+            self._log_auto_mode_step(i + 1, max_steps, prefix="async ")
+            image = await image_provider()
+            step = await self.step(image, temperature=temperature)
+            if executor:
+                self._log_auto_mode_actions(len(step.actions), prefix="async ")
+                await executor(step.actions)
+            if step.stop:
+                self._log_auto_mode_completion(i + 1, prefix="async ")
+                return True
+
+        self._log_auto_mode_max_steps(max_steps, prefix="async ")
+        return False

oagi/task/base.py

@@ -0,0 +1,121 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from uuid import uuid4
+
+from ..logging import get_logger
+from ..types import Image, Step, URLImage
+from ..types.models import LLMResponse
+
+logger = get_logger("task.base")
+
+
+class BaseTask:
+    """Base class with shared task management logic for sync/async tasks."""
+
+    def __init__(
+        self,
+        api_key: str | None,
+        base_url: str | None,
+        model: str,
+        temperature: float | None,
+    ):
+        self.task_id: str = uuid4().hex  # Client-side generated UUID
+        self.task_description: str | None = None
+        self.model = model
+        self.temperature = temperature
+        self.message_history: list = []  # OpenAI-compatible message history
+        # Client will be set by subclasses
+        self.api_key: str | None = None
+        self.base_url: str | None = None
+
+    def _prepare_init_task(
+        self,
+        task_desc: str,
+        max_steps: int,
+    ):
+        """Prepare task initialization (v2 API does not call server for init).
+
+        Args:
+            task_desc: Task description
+            max_steps: Maximum number of steps
+        """
+        self.task_description = task_desc
+        logger.info(f"Task initialized: '{task_desc}' (max_steps: {max_steps})")
+
+    def _validate_step_preconditions(self):
+        if not self.task_description:
+            raise ValueError("Task description must be set. Call init_task() first.")
+
+    def _prepare_screenshot(self, screenshot: Image | bytes) -> bytes:
+        if isinstance(screenshot, Image):
+            return screenshot.read()
+        return screenshot
+
+    def _get_temperature(self, temperature: float | None) -> float | None:
+        return temperature if temperature is not None else self.temperature
+
+    def _prepare_screenshot_kwargs(self, screenshot: Image | bytes) -> dict:
+        if isinstance(screenshot, URLImage):
+            return {"screenshot_url": screenshot.get_url()}
+        return {"screenshot": self._prepare_screenshot(screenshot)}
+
+    def _handle_response_message_history(self, response: LLMResponse):
+        if response.raw_output:
+            self.message_history.append(
+                {
+                    "role": "assistant",
+                    "content": [{"type": "text", "text": response.raw_output}],
+                }
+            )
+
+    def _build_step_response(self, response: LLMResponse, prefix: str = "") -> Step:
+        # Update message history with assistant response
+        self._handle_response_message_history(response)
+
+        result = Step(
+            reason=response.reason,
+            actions=response.actions,
+            stop=response.is_complete,
+        )
+
+        if response.is_complete:
+            logger.info(f"{prefix}Task completed.")
+        else:
+            logger.debug(f"{prefix}Step completed with {len(response.actions)} actions")
+
+        return result
+
+    def _log_step_execution(self, prefix: str = ""):
+        logger.debug(f"Executing {prefix}step for task: '{self.task_description}'")
+
+
+class BaseAutoMode:
+    """Base class with shared auto_mode logic for ShortTask implementations."""
+
+    def _log_auto_mode_start(self, task_desc: str, max_steps: int, prefix: str = ""):
+        logger.info(
+            f"Starting {prefix}auto mode for task: '{task_desc}' (max_steps: {max_steps})"
+        )
+
+    def _log_auto_mode_step(self, step_num: int, max_steps: int, prefix: str = ""):
+        logger.debug(f"{prefix.capitalize()}auto mode step {step_num}/{max_steps}")
+
+    def _log_auto_mode_actions(self, action_count: int, prefix: str = ""):
+        verb = "asynchronously" if "async" in prefix else ""
+        logger.debug(f"Executing {action_count} actions {verb}".strip())
+
+    def _log_auto_mode_completion(self, steps: int, prefix: str = ""):
+        logger.info(
+            f"{prefix.capitalize()}auto mode completed successfully after {steps} steps"
+        )
+
+    def _log_auto_mode_max_steps(self, max_steps: int, prefix: str = ""):
+        logger.warning(
+            f"{prefix.capitalize()}auto mode reached max steps ({max_steps}) without completion"
+        )

oagi/task/short.py

@@ -0,0 +1,64 @@
+# -----------------------------------------------------------------------------
+#  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 ..types import ActionHandler, ImageProvider
+from .base import BaseAutoMode
+from .sync import Task
+
+logger = get_logger("short_task")
+
+
+class ShortTask(Task, BaseAutoMode):
+    """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",
+        temperature: float | None = None,
+    ):
+        super().__init__(
+            api_key=api_key, base_url=base_url, model=model, temperature=temperature
+        )
+
+    def auto_mode(
+        self,
+        task_desc: str,
+        max_steps: int = 5,
+        executor: ActionHandler = None,
+        image_provider: ImageProvider = None,
+        temperature: float | None = None,
+    ) -> bool:
+        """Run the task in automatic mode with the provided executor and image provider.
+
+        Args:
+            task_desc: Task description
+            max_steps: Maximum number of steps
+            executor: Handler to execute actions
+            image_provider: Provider for screenshots
+            temperature: Sampling temperature for all steps (overrides task default if provided)
+        """
+        self._log_auto_mode_start(task_desc, max_steps)
+
+        self.init_task(task_desc, max_steps=max_steps)
+
+        for i in range(max_steps):
+            self._log_auto_mode_step(i + 1, max_steps)
+            image = image_provider()
+            step = self.step(image, temperature=temperature)
+            if executor:
+                self._log_auto_mode_actions(len(step.actions))
+                executor(step.actions)
+            if step.stop:
+                self._log_auto_mode_completion(i + 1)
+                return True
+
+        self._log_auto_mode_max_steps(max_steps)
+        return False

oagi/task/sync.py

@@ -0,0 +1,97 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from ..client import SyncClient
+from ..logging import get_logger
+from ..types import Image, Step
+from .base import BaseTask
+
+logger = get_logger("task")
+
+
+class Task(BaseTask):
+    """Base class for task automation with the OAGI API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        model: str = "vision-model-v1",
+        temperature: float | None = None,
+    ):
+        super().__init__(api_key, base_url, model, temperature)
+        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
+
+    def init_task(
+        self,
+        task_desc: str,
+        max_steps: int = 5,
+    ):
+        """Initialize a new task with the given description.
+
+        Args:
+            task_desc: Task description
+            max_steps: Maximum number of steps (for logging)
+        """
+        self._prepare_init_task(task_desc, max_steps)
+
+    def step(
+        self,
+        screenshot: Image | bytes,
+        instruction: str | None = None,
+        temperature: float | None = None,
+    ) -> Step:
+        """Send screenshot to the server and get the next actions.
+
+        Args:
+            screenshot: Screenshot as Image object or raw bytes
+            instruction: Optional additional instruction for this step
+            temperature: Sampling temperature for this step (overrides task default if provided)
+
+        Returns:
+            Step: The actions and reasoning for this step
+        """
+        self._validate_step_preconditions()
+        self._log_step_execution()
+
+        try:
+            # Use provided temperature or fall back to task default
+            temp = self._get_temperature(temperature)
+
+            # Prepare screenshot kwargs (handles URLImage vs bytes/Image)
+            screenshot_kwargs = self._prepare_screenshot_kwargs(screenshot)
+
+            # Call API with dynamically determined screenshot argument
+            response = self.client.create_message(
+                model=self.model,
+                task_description=self.task_description,
+                task_id=self.task_id,
+                instruction=instruction,
+                messages_history=self.message_history,
+                temperature=temp,
+                **screenshot_kwargs,
+            )
+
+            # Convert API response to Step (also updates message_history)
+            return self._build_step_response(response)
+
+        except Exception as e:
+            logger.error(f"Error during step execution: {e}")
+            raise
+
+    def close(self):
+        """Close the underlying HTTP client to free resources."""
+        self.client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()

oagi/types/__init__.py

@@ -0,0 +1,28 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from .action_handler import ActionHandler
+from .async_action_handler import AsyncActionHandler
+from .async_image_provider import AsyncImageProvider
+from .image import Image
+from .image_provider import ImageProvider
+from .models import Action, ActionType, ImageConfig, Step
+from .url_image import URLImage
+
+__all__ = [
+    "Action",
+    "ActionType",
+    "Image",
+    "ImageConfig",
+    "Step",
+    "ActionHandler",
+    "AsyncActionHandler",
+    "ImageProvider",
+    "AsyncImageProvider",
+    "URLImage",
+]

oagi/types/action_handler.py

@@ -0,0 +1,30 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from typing import Protocol
+
+from .models import Action
+
+
+class ActionHandler(Protocol):
+    def __call__(self, actions: list[Action]) -> None:
+        """
+        Executes a list of actions.
+
+        This method takes a list of `Action` objects and executes them. It is used
+        to perform operations represented by the `Action` instances. This method
+        does not return any value and modifies the system based on the input actions.
+
+        Parameters:
+            actions (list[Action]): A list of `Action` objects to be executed. Each
+            `Action` must encapsulate the logic that is intended to be applied
+            during the call.
+
+        Raises:
+            RuntimeError: If an error occurs during the execution of the actions.
+        """

oagi/types/async_action_handler.py

@@ -0,0 +1,30 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from typing import Protocol
+
+from .models import Action
+
+
+class AsyncActionHandler(Protocol):
+    async def __call__(self, actions: list[Action]) -> None:
+        """
+        Asynchronously executes a list of actions.
+
+        This method takes a list of `Action` objects and executes them asynchronously.
+        It is used to perform operations represented by the `Action` instances. This
+        method does not return any value and modifies the system based on the input actions.
+
+        Parameters:
+            actions (list[Action]): A list of `Action` objects to be executed. Each
+            `Action` must encapsulate the logic that is intended to be applied
+            during the call.
+
+        Raises:
+            RuntimeError: If an error occurs during the execution of the actions.
+        """

oagi/types/async_image_provider.py

@@ -0,0 +1,37 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from typing import Protocol
+
+from .image import Image
+
+
+class AsyncImageProvider(Protocol):
+    async def __call__(self) -> Image:
+        """
+        Asynchronously provides an image.
+
+        This method is responsible for asynchronously capturing, generating, or retrieving
+        an image that can be used for task execution or analysis. The method should return
+        an object that implements the Image protocol.
+
+        Returns:
+            Image: An object implementing the Image protocol that represents
+                  the captured or generated image.
+
+        Raises:
+            RuntimeError: If an error occurs during image capture or generation.
+        """
+
+    async def last_image(self) -> Image:
+        """
+        Asynchronously returns the last captured image.
+
+        Returns:
+            Image: The last captured image.
+        """

oagi/types/image.py

@@ -0,0 +1,17 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class Image(Protocol):
+    """Protocol for image objects that can be read as bytes."""
+
+    def read(self) -> bytes:
+        """Read the image data as bytes."""

oagi/types/image_provider.py

@@ -0,0 +1,34 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from typing import Protocol
+
+from .image import Image
+
+
+class ImageProvider(Protocol):
+    def __call__(self) -> Image:
+        """
+        Represents the functionality to invoke the callable object and produce an Image
+        result. Typically used to process or generate images using the defined logic
+        within the __call__ method.
+
+        Returns:
+            Image: The resulting image output from the callable logic.
+        """
+
+    def last_image(self) -> Image:
+        """
+        Returns the last captured image.
+
+        This method retrieves the most recent image that was captured and stored
+        in memory. If there are no images available, the method may return None.
+
+        Returns:
+            Image: The last captured image, or None if no images are available.
+        """

oagi/types/models/__init__.py

@@ -0,0 +1,32 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from .action import Action, ActionType
+from .client import (
+    ErrorDetail,
+    ErrorResponse,
+    GenerateResponse,
+    LLMResponse,
+    UploadFileResponse,
+    Usage,
+)
+from .image_config import ImageConfig
+from .step import Step
+
+__all__ = [
+    "Action",
+    "ActionType",
+    "ErrorDetail",
+    "ErrorResponse",
+    "GenerateResponse",
+    "ImageConfig",
+    "LLMResponse",
+    "Step",
+    "UploadFileResponse",
+    "Usage",
+]