oagi-core 0.10.1__py3-none-any.whl

oagi/task/base.py

@@ -0,0 +1,157 @@
+# -----------------------------------------------------------------------------
+#  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 URL, Image, Step
+from ..types.models import LLMResponse
+
+logger = get_logger("task.base")
+
+
+class BaseActor:
+    """Base class with shared task management logic for sync/async actors."""
+
+    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
+        self.max_steps: int = 20  # Maximum steps allowed
+        self.current_step: int = 0  # Current step counter
+        # 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_id = uuid4().hex
+        self.task_description = task_desc
+        self.message_history = []
+        self.max_steps = max_steps
+        self.current_step = 0
+        logger.info(f"Task initialized: '{task_desc}' (max_steps: {max_steps})")
+
+    def _validate_and_increment_step(self):
+        if not self.task_description:
+            raise ValueError("Task description must be set. Call init_task() first.")
+        if self.current_step >= self.max_steps:
+            raise ValueError(
+                f"Max steps limit ({self.max_steps}) reached. "
+                "Call init_task() to start a new task."
+            )
+        self.current_step += 1
+
+    def _prepare_step(
+        self,
+        screenshot: Image | URL | bytes,
+        instruction: str | None,
+        temperature: float | None,
+        prefix: str = "",
+    ) -> dict:
+        self._validate_and_increment_step()
+        self._log_step_execution(prefix=prefix)
+
+        return {
+            "model": self.model,
+            "task_description": self.task_description,
+            "task_id": self.task_id,
+            "instruction": instruction,
+            "messages_history": self.message_history,
+            "temperature": self._get_temperature(temperature),
+            **self._prepare_screenshot_kwargs(screenshot),
+        }
+
+    def _handle_step_error(self, error: Exception, prefix: str = ""):
+        logger.error(f"Error during {prefix}step execution: {error}")
+        raise
+
+    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 | URL | bytes) -> dict:
+        if isinstance(screenshot, str):
+            return {"screenshot_url": screenshot}
+        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,76 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+import warnings
+
+from ..logging import get_logger
+from ..types import ActionHandler, ImageProvider
+from .base import BaseAutoMode
+from .sync import Actor
+
+logger = get_logger("short_task")
+
+
+class ShortTask(Actor, BaseAutoMode):
+    """Deprecated: This class is deprecated and will be removed in a future version.
+
+    Task implementation with automatic mode for short-duration tasks.
+    Please use Actor directly with custom automation logic instead.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        model: str = "lux-actor-1",
+        temperature: float | None = None,
+    ):
+        warnings.warn(
+            "ShortTask is deprecated and will be removed in a future version. "
+            "Please use Actor with custom automation logic instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(
+            api_key=api_key, base_url=base_url, model=model, temperature=temperature
+        )
+
+    def auto_mode(
+        self,
+        task_desc: str,
+        max_steps: int = 20,
+        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,99 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+import warnings
+
+from ..client import SyncClient
+from ..types import URL, Image, Step
+from .base import BaseActor
+
+
+class Actor(BaseActor):
+    """Base class for task automation with the OAGI API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        model: str = "lux-actor-1",
+        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 = 20,
+    ):
+        """Initialize a new task with the given description.
+
+        Args:
+            task_desc: Task description
+            max_steps: Maximum number of steps allowed
+        """
+        self._prepare_init_task(task_desc, max_steps)
+
+    def step(
+        self,
+        screenshot: Image | URL | 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
+        """
+        kwargs = self._prepare_step(screenshot, instruction, temperature)
+
+        try:
+            response = self.client.create_message(**kwargs)
+            return self._build_step_response(response)
+        except Exception as e:
+            self._handle_step_error(e)
+
+    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()
+
+
+class Task(Actor):
+    """Deprecated: Use Actor instead.
+
+    This class is deprecated and will be removed in a future version.
+    Please use Actor instead.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        model: str = "lux-actor-1",
+        temperature: float | None = None,
+    ):
+        warnings.warn(
+            "Task is deprecated and will be removed in a future version. "
+            "Please use Actor instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(api_key, base_url, model, temperature)

oagi/types/__init__.py

@@ -0,0 +1,50 @@
+# -----------------------------------------------------------------------------
+#  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 .step_observer import (
+    ActionEvent,
+    AsyncObserver,
+    AsyncStepObserver,
+    BaseEvent,
+    ImageEvent,
+    LogEvent,
+    ObserverEvent,
+    PlanEvent,
+    SplitEvent,
+    StepEvent,
+)
+from .url import URL
+
+__all__ = [
+    "Action",
+    "ActionEvent",
+    "ActionType",
+    "AsyncObserver",
+    "AsyncStepObserver",
+    "BaseEvent",
+    "Image",
+    "ImageConfig",
+    "ImageEvent",
+    "LogEvent",
+    "ObserverEvent",
+    "PlanEvent",
+    "SplitEvent",
+    "Step",
+    "StepEvent",
+    "ActionHandler",
+    "AsyncActionHandler",
+    "ImageProvider",
+    "AsyncImageProvider",
+    "URL",
+]

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,38 @@
+# -----------------------------------------------------------------------------
+#  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
+from .url import URL
+
+
+class AsyncImageProvider(Protocol):
+    async def __call__(self) -> Image | URL:
+        """
+        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 | URL:
+        """
+        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,35 @@
+# -----------------------------------------------------------------------------
+#  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
+from .url import URL
+
+
+class ImageProvider(Protocol):
+    def __call__(self) -> Image | URL:
+        """
+        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 | URL:
+        """
+        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",
+]

oagi/types/models/action.py

@@ -0,0 +1,33 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class ActionType(str, Enum):
+    CLICK = "click"
+    LEFT_DOUBLE = "left_double"
+    LEFT_TRIPLE = "left_triple"
+    RIGHT_SINGLE = "right_single"
+    DRAG = "drag"
+    HOTKEY = "hotkey"
+    TYPE = "type"
+    SCROLL = "scroll"
+    FINISH = "finish"
+    WAIT = "wait"
+    CALL_USER = "call_user"
+
+
+class Action(BaseModel):
+    type: ActionType = Field(..., description="Type of action to perform")
+    argument: str = Field(..., description="Action argument in the specified format")
+    count: int | None = Field(
+        default=1, ge=1, description="Number of times to repeat the action"
+    )

oagi/types/models/client.py

@@ -0,0 +1,68 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from pydantic import BaseModel, Field
+
+from .action import Action
+
+
+class Usage(BaseModel):
+    prompt_tokens: int
+    completion_tokens: int
+    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
+    object: str = "task.completion"
+    created: int
+    model: str
+    task_description: str
+    is_complete: bool
+    actions: list[Action]
+    reason: str | None = None
+    usage: Usage
+    error: ErrorDetail | None = None
+    raw_output: str | None = None
+
+
+class UploadFileResponse(BaseModel):
+    """Response from S3 presigned URL upload."""
+
+    url: str
+    uuid: str
+    expires_at: int
+    file_expires_at: int
+    download_url: str
+
+
+class GenerateResponse(BaseModel):
+    """Response from /v1/generate endpoint."""
+
+    response: str
+    prompt_tokens: int
+    completion_tokens: int
+    cost: float | None = Field(
+        default=None,
+        deprecated=True,
+        description="This field is deprecated",
+    )