oagi-core 0.11.0__py3-none-any.whl → 0.12.1__py3-none-any.whl

oagi/client/sync.py

@@ -9,28 +9,24 @@
 from functools import wraps
 
 import httpx
-from httpx import Response
+from httpx import HTTPTransport
+from openai import OpenAI
 
 from ..constants import (
-    API_HEALTH_ENDPOINT,
     API_V1_FILE_UPLOAD_ENDPOINT,
     API_V1_GENERATE_ENDPOINT,
-    API_V2_MESSAGE_ENDPOINT,
+    DEFAULT_MAX_RETRIES,
     HTTP_CLIENT_TIMEOUT,
 )
 from ..logging import get_logger
 from ..types import Image
-from ..types.models import GenerateResponse, LLMResponse, UploadFileResponse
+from ..types.models import GenerateResponse, UploadFileResponse, Usage
+from ..types.models.step import Step
 from .base import BaseClient
 
 logger = get_logger("sync_client")
 
 
-def _log_trace_id(response: Response):
-    logger.error(f"Request Id: {response.headers.get('x-request-id', '')}")
-    logger.error(f"Trace Id: {response.headers.get('x-trace-id', '')}")
-
-
 def log_trace_on_failure(func):
     """Decorator that logs trace ID when a method fails."""
 
@@ -41,7 +37,7 @@ def log_trace_on_failure(func):
         except Exception as e:
             # Try to get response from the exception if it has one
             if (response := getattr(e, "response", None)) is not None:
-                _log_trace_id(response)
+                BaseClient._log_trace_id(response)
             raise
 
     return wrapper
@@ -50,113 +46,70 @@ def log_trace_on_failure(func):
 class SyncClient(BaseClient[httpx.Client]):
     """Synchronous HTTP client for the OAGI API."""
 
-    def __init__(self, base_url: str | None = None, api_key: str | None = None):
-        super().__init__(base_url, api_key)
-        self.client = httpx.Client(base_url=self.base_url)
-        self.upload_client = httpx.Client(timeout=HTTP_CLIENT_TIMEOUT)
+    def __init__(
+        self,
+        base_url: str | None = None,
+        api_key: str | None = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ):
+        super().__init__(base_url, api_key, max_retries)
+
+        # OpenAI client for chat completions (with retries)
+        self.openai_client = OpenAI(
+            api_key=self.api_key,
+            base_url=f"{self.base_url}/v1",
+            max_retries=self.max_retries,
+        )
+
+        # httpx clients for S3 uploads and other endpoints (with retries)
+        transport = HTTPTransport(retries=self.max_retries)
+        self.http_client = httpx.Client(transport=transport, base_url=self.base_url)
+        self.upload_client = httpx.Client(
+            transport=transport, timeout=HTTP_CLIENT_TIMEOUT
+        )
+
         logger.info(f"SyncClient initialized with base_url: {self.base_url}")
 
     def __enter__(self):
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
-        self.client.close()
-        self.upload_client.close()
+        self.close()
 
     def close(self):
-        """Close the underlying httpx clients."""
-        self.client.close()
+        """Close the underlying clients."""
+        self.openai_client.close()
+        self.http_client.close()
         self.upload_client.close()
 
-    @log_trace_on_failure
-    def create_message(
+    def chat_completion(
         self,
         model: str,
-        screenshot: bytes | None = None,
-        screenshot_url: str | None = None,
-        task_description: str | None = None,
-        task_id: str | None = None,
-        instruction: str | None = None,
-        messages_history: list | None = None,
+        messages: list,
         temperature: float | None = None,
-        api_version: str | None = None,
-    ) -> LLMResponse | None:
+        task_id: str | None = None,
+    ) -> tuple[Step, str, Usage | None]:
         """
-        Call the /v2/message endpoint to analyze task and screenshot
+        Call OpenAI-compatible /v1/chat/completions endpoint.
 
         Args:
-            model: The model to use for task analysis
-            screenshot: Screenshot image bytes (mutually exclusive with screenshot_url)
-            screenshot_url: Direct URL to screenshot (mutually exclusive with screenshot)
-            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
-            messages_history: OpenAI-compatible chat message history
-            temperature: Sampling temperature (0.0-2.0) for LLM inference
-            api_version: API version header
+            model: Model to use for inference
+            messages: Full message history (OpenAI-compatible format)
+            temperature: Sampling temperature (0.0-2.0)
+            task_id: Optional task ID for multi-turn conversations
 
         Returns:
-            LLMResponse: The response from the API
-
-        Raises:
-            ValueError: If both or neither screenshot and screenshot_url are provided
-            httpx.HTTPStatusError: For HTTP error responses
+            Tuple of (Step, raw_output, Usage)
+            - Step: Parsed actions and reasoning
+            - raw_output: Raw model output string (for message history)
+            - Usage: Token usage statistics (or None if not available)
         """
-        # Validate that exactly one is provided
-        if (screenshot is None) == (screenshot_url is None):
-            raise ValueError(
-                "Exactly one of 'screenshot' or 'screenshot_url' must be provided"
-            )
-
-        self._log_request_info(model, task_description, task_id)
-
-        # Upload screenshot to S3 if bytes provided, otherwise use URL directly
-        upload_file_response = None
-        if screenshot is not None:
-            upload_file_response = self.put_s3_presigned_url(screenshot, api_version)
-
-        # Prepare message payload
-        headers, payload = self._prepare_message_payload(
-            model=model,
-            upload_file_response=upload_file_response,
-            task_description=task_description,
-            task_id=task_id,
-            instruction=instruction,
-            messages_history=messages_history,
-            temperature=temperature,
-            api_version=api_version,
-            screenshot_url=screenshot_url,
+        logger.info(f"Making chat completion request with model: {model}")
+        kwargs = self._build_chat_completion_kwargs(
+            model, messages, temperature, task_id
         )
-
-        # Make request
-        try:
-            response = self.client.post(
-                API_V2_MESSAGE_ENDPOINT,
-                json=payload,
-                headers=headers,
-                timeout=self.timeout,
-            )
-            return self._process_response(response)
-        except (httpx.TimeoutException, httpx.NetworkError) as e:
-            self._handle_upload_http_errors(e)
-
-    def health_check(self) -> dict:
-        """
-        Call the /health endpoint for health check
-
-        Returns:
-            dict: Health check response
-        """
-        logger.debug("Making health check request")
-        try:
-            response = self.client.get(API_HEALTH_ENDPOINT)
-            response.raise_for_status()
-            result = response.json()
-            logger.debug("Health check successful")
-            return result
-        except httpx.HTTPStatusError as e:
-            logger.warning(f"Health check failed: {e}")
-            raise
+        response = self.openai_client.chat.completions.create(**kwargs)
+        return self._parse_chat_completion_response(response)
 
     def get_s3_presigned_url(
         self,
@@ -175,7 +128,7 @@ class SyncClient(BaseClient[httpx.Client]):
 
         try:
             headers = self._build_headers(api_version)
-            response = self.client.get(
+            response = self.http_client.get(
                 API_V1_FILE_UPLOAD_ENDPOINT, headers=headers, timeout=self.timeout
             )
             return self._process_upload_response(response)
@@ -295,7 +248,7 @@ class SyncClient(BaseClient[httpx.Client]):
 
         # Make request
         try:
-            response = self.client.post(
+            response = self.http_client.post(
                 API_V1_GENERATE_ENDPOINT,
                 json=payload,
                 headers=headers,

oagi/constants.py

@@ -9,10 +9,8 @@
 # URLs & API Endpoints
 DEFAULT_BASE_URL = "https://api.agiopen.org"
 API_KEY_HELP_URL = "https://developer.agiopen.org/api-keys"
-API_V2_MESSAGE_ENDPOINT = "/v2/message"
 API_V1_FILE_UPLOAD_ENDPOINT = "/v1/file/upload"
 API_V1_GENERATE_ENDPOINT = "/v1/generate"
-API_HEALTH_ENDPOINT = "/health"
 
 # Model identifiers
 MODEL_ACTOR = "lux-actor-1"
@@ -28,6 +26,10 @@ DEFAULT_MAX_STEPS = 20
 DEFAULT_MAX_STEPS_THINKER = 100
 DEFAULT_MAX_STEPS_TASKER = 60
 
+# Maximum allowed steps per model (hard limits)
+MAX_STEPS_ACTOR = 30
+MAX_STEPS_THINKER = 120
+
 # Reflection intervals
 DEFAULT_REFLECTION_INTERVAL = 4
 DEFAULT_REFLECTION_INTERVAL_TASKER = 20
@@ -41,3 +43,6 @@ DEFAULT_TEMPERATURE_LOW = 0.1
 
 # Timeout Values
 HTTP_CLIENT_TIMEOUT = 60
+
+# Retry Configuration
+DEFAULT_MAX_RETRIES = 2

oagi/handler/__init__.py

@@ -5,28 +5,43 @@
 #  This file is part of the official API project.
 #  Licensed under the MIT License.
 # -----------------------------------------------------------------------------
-from oagi.handler.async_pyautogui_action_handler import AsyncPyautoguiActionHandler
-from oagi.handler.async_screenshot_maker import AsyncScreenshotMaker
-from oagi.handler.pil_image import PILImage
-from oagi.handler.pyautogui_action_handler import (
-    PyautoguiActionHandler,
-    PyautoguiConfig,
-)
-from oagi.handler.screenshot_maker import ScreenshotMaker
-
-
-def reset_handler(handler) -> None:
-    """Reset handler state if supported.
-
-    Uses duck-typing to check if the handler has a reset() method.
-    This allows handlers to reset their internal state (e.g., capslock state)
-    at the start of a new automation task.
-
-    Args:
-        handler: The action handler to reset
-    """
-    if hasattr(handler, "reset"):
-        handler.reset()
+import importlib
+from typing import TYPE_CHECKING
+
+from .utils import reset_handler
+
+# Lazy imports for pyautogui-dependent modules to avoid import errors on headless systems
+_LAZY_IMPORTS: dict[str, str] = {
+    "AsyncPyautoguiActionHandler": "oagi.handler.async_pyautogui_action_handler",
+    "AsyncScreenshotMaker": "oagi.handler.async_screenshot_maker",
+    "PILImage": "oagi.handler.pil_image",
+    "PyautoguiActionHandler": "oagi.handler.pyautogui_action_handler",
+    "PyautoguiConfig": "oagi.handler.pyautogui_action_handler",
+    "ScreenshotMaker": "oagi.handler.screenshot_maker",
+}
+
+if TYPE_CHECKING:
+    from oagi.handler.async_pyautogui_action_handler import AsyncPyautoguiActionHandler
+    from oagi.handler.async_screenshot_maker import AsyncScreenshotMaker
+    from oagi.handler.pil_image import PILImage
+    from oagi.handler.pyautogui_action_handler import (
+        PyautoguiActionHandler,
+        PyautoguiConfig,
+    )
+    from oagi.handler.screenshot_maker import ScreenshotMaker
+
+
+def __getattr__(name: str):
+    """Lazy import for pyautogui-dependent modules."""
+    if name in _LAZY_IMPORTS:
+        module = importlib.import_module(_LAZY_IMPORTS[name])
+        return getattr(module, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Return all public names including lazy imports."""
+    return sorted(set(__all__) | set(_LAZY_IMPORTS.keys()))
 
 
 __all__ = [

oagi/handler/utils.py

@@ -0,0 +1,21 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+
+def reset_handler(handler) -> None:
+    """Reset handler state if supported.
+
+    Uses duck-typing to check if the handler has a reset() method.
+    This allows handlers to reset their internal state (e.g., capslock state)
+    at the start of a new automation task.
+
+    Args:
+        handler: The action handler to reset
+    """
+    if hasattr(handler, "reset"):
+        handler.reset()

oagi/task/__init__.py

@@ -6,16 +6,30 @@
 #  Licensed under the MIT License.
 # -----------------------------------------------------------------------------
 
-from .async_ import AsyncActor, AsyncTask
-from .async_short import AsyncShortTask
-from .short import ShortTask
-from .sync import Actor, Task
+"""Deprecated: Use oagi.actor instead. This module will be removed in a future version."""
+
+import warnings
+
+from oagi.actor import (
+    Actor,
+    AsyncActor,
+    AsyncShortTask,
+    AsyncTask,
+    ShortTask,
+    Task,
+)
+
+warnings.warn(
+    "oagi.task is deprecated, use oagi.actor instead",
+    DeprecationWarning,
+    stacklevel=2,
+)
 
 __all__ = [
     "Actor",
     "AsyncActor",
-    "Task",  # Deprecated: Use Actor instead
-    "AsyncTask",  # Deprecated: Use AsyncActor instead
-    "ShortTask",  # Deprecated
-    "AsyncShortTask",  # Deprecated
+    "Task",
+    "AsyncTask",
+    "ShortTask",
+    "AsyncShortTask",
 ]

oagi/types/models/__init__.py

@@ -17,7 +17,6 @@ from .client import (
     ErrorDetail,
     ErrorResponse,
     GenerateResponse,
-    LLMResponse,
     UploadFileResponse,
     Usage,
 )
@@ -31,7 +30,6 @@ __all__ = [
     "ErrorResponse",
     "GenerateResponse",
     "ImageConfig",
-    "LLMResponse",
     "Step",
     "UploadFileResponse",
     "Usage",

oagi/types/models/action.py

@@ -81,4 +81,7 @@ def parse_scroll(args_str: str) -> tuple[int, int, str] | None:
     match = re.match(r"(\d+),\s*(\d+),\s*(\w+)", args_str)
     if not match:
         return None
-    return int(match.group(1)), int(match.group(2)), match.group(3).lower()
+    direction = match.group(3).lower()
+    if direction not in ("up", "down"):
+        return None
+    return int(match.group(1)), int(match.group(2)), direction

oagi/types/models/client.py

@@ -8,8 +8,6 @@
 
 from pydantic import BaseModel, Field
 
-from .action import Action
-
 
 class Usage(BaseModel):
     prompt_tokens: int
@@ -30,21 +28,6 @@ class ErrorResponse(BaseModel):
     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."""
 
@@ -66,3 +49,4 @@ class GenerateResponse(BaseModel):
         deprecated=True,
         description="This field is deprecated",
     )
+    request_id: str | None = None

oagi/types/step_observer.py

@@ -35,6 +35,7 @@ class StepEvent(BaseEvent):
     step_num: int
     image: bytes | str
     step: Step
+    task_id: str | None = None
 
 
 class ActionEvent(BaseEvent):
@@ -68,6 +69,7 @@ class PlanEvent(BaseEvent):
     image: bytes | str | None = None
     reasoning: str
     result: str | None = None
+    request_id: str | None = None
 
 
 ObserverEvent = ImageEvent | StepEvent | ActionEvent | LogEvent | SplitEvent | PlanEvent

oagi/utils/__init__.py

@@ -0,0 +1,12 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+from .output_parser import parse_raw_output
+from .prompt_builder import build_prompt
+
+__all__ = ["build_prompt", "parse_raw_output"]

oagi/utils/output_parser.py

@@ -0,0 +1,166 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+import re
+
+from ..types.models.action import Action, ActionType
+from ..types.models.step import Step
+
+
+def parse_raw_output(raw_output: str) -> Step:
+    """Parse raw LLM output into structured Step format.
+
+    Expected format:
+    <|think_start|> reasoning text <|think_end|>
+    <|action_start|> action1(args) & action2(args) & ... <|action_end|>
+
+    Args:
+        raw_output: Raw text output from the LLM
+
+    Returns:
+        Step object with parsed reasoning and actions
+    """
+    # Extract reasoning/thinking
+    think_pattern = r"<\|think_start\|>(.*?)<\|think_end\|>"
+    think_match = re.search(think_pattern, raw_output, re.DOTALL)
+    reason = think_match.group(1).strip() if think_match else ""
+
+    # Extract action block
+    action_pattern = r"<\|action_start\|>(.*?)<\|action_end\|>"
+    action_match = re.search(action_pattern, raw_output, re.DOTALL)
+
+    actions: list[Action] = []
+    stop = False
+
+    if action_match:
+        action_block = action_match.group(1).strip()
+        action_texts = _split_actions(action_block)
+
+        for action_text in action_texts:
+            parsed_action = _parse_action(action_text.strip())
+            if parsed_action:
+                actions.append(parsed_action)
+                if parsed_action.type == ActionType.FINISH:
+                    stop = True
+
+    return Step(reason=reason, actions=actions, stop=stop)
+
+
+def _split_actions(action_block: str) -> list[str]:
+    """Split action block by & separator, but only when & is outside parentheses.
+
+    Note: This parser does NOT handle '&' inside quoted strings.
+    E.g., type("a&b") would incorrectly split. The LLM should avoid
+    this pattern by using alternative escape sequences.
+
+    Args:
+        action_block: String containing one or more actions separated by &
+
+    Returns:
+        List of individual action strings
+    """
+    actions: list[str] = []
+    current_action: list[str] = []
+    paren_level = 0
+
+    for char in action_block:
+        if char == "(":
+            paren_level += 1
+            current_action.append(char)
+        elif char == ")":
+            paren_level -= 1
+            current_action.append(char)
+        elif char == "&" and paren_level == 0:
+            action_str = "".join(current_action).strip()
+            if action_str:
+                actions.append(action_str)
+            current_action = []
+        else:
+            current_action.append(char)
+
+    # Add the last action
+    action_str = "".join(current_action).strip()
+    if action_str:
+        actions.append(action_str)
+
+    return actions
+
+
+def _parse_action(action_text: str) -> Action | None:
+    """Parse individual action text into Action object.
+
+    Expected formats:
+    - click(x, y) # left-click at position
+    - left_double(x, y) # left-double-click at position
+    - left_triple(x, y) # left-triple-click at position
+    - right_single(x, y) # right-click at position
+    - drag(x1, y1, x2, y2) # drag from (x1, y1) to (x2, y2)
+    - hotkey(key, c) # press key c times
+    - type(text) # type text string
+    - scroll(x, y, direction, c) # scroll at position
+    - wait() # wait for a while
+    - finish() # indicate task is finished
+
+    Args:
+        action_text: String representation of a single action
+
+    Returns:
+        Action object or None if parsing fails
+    """
+    # Match action format: action_type(arguments)
+    match = re.match(r"(\w+)\((.*)\)", action_text.strip())
+    if not match:
+        return None
+
+    action_type = match.group(1).lower()
+    arguments = match.group(2).strip()
+
+    # Parse count from arguments for actions that support it
+    count = 1
+
+    # Validate and map action type to enum
+    try:
+        action_enum = ActionType(action_type)
+    except ValueError:
+        return None
+
+    # Parse specific action types and extract count where applicable
+    match action_enum:
+        case ActionType.HOTKEY:
+            # hotkey(key, c) - press key c times
+            args = arguments.rsplit(",", 1)
+            if len(args) >= 2 and args[1].strip():
+                key = args[0].strip()
+                try:
+                    count = int(args[1].strip())
+                except ValueError:
+                    count = 1
+            else:
+                key = arguments.strip()
+                count = 1
+            arguments = key
+
+        case ActionType.SCROLL:
+            # scroll(x, y, direction, c) - scroll at position
+            args = arguments.split(",")
+            if len(args) >= 4:
+                x = args[0].strip()
+                y = args[1].strip()
+                direction = args[2].strip()
+                try:
+                    count = int(args[3].strip())
+                except (ValueError, IndexError):
+                    count = 1
+                # Reconstruct arguments without count
+                arguments = f"{x},{y},{direction}"
+
+        case _:
+            # For other actions, use default count of 1
+            pass
+
+    return Action(type=action_enum, argument=arguments, count=count)

oagi/utils/prompt_builder.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.
+# -----------------------------------------------------------------------------
+
+instruction_template = """You are a Desktop Agent completing computer use tasks from a user instruction.
+
+Every step, you will look at the screenshot and output the desired actions in a format as:
+
+<|think_start|> brief description of your intent and reasoning <|think_end|>
+<|action_start|> one of the allowed actions as below <|action_end|>
+
+In the action field, you have the following action formats:
+1. click(x, y) # left-click at the position (x, y), where x and y are integers normalized between 0 and 1000
+2. left_double(x, y) # left-double-click at the position (x, y), where x and y are integers normalized between 0 and 1000
+3. left_triple(x, y) # left-triple-click at the position (x, y), where x and y are integers normalized between 0 and 1000
+4. right_single(x, y) # right-click at the position (x, y), where x and y are integers normalized between 0 and 1000
+5. drag(x1, y1, x2, y2) # drag the mouse from (x1, y1) to (x2, y2) to select or move contents, where x1, y1, x2, y2 are integers normalized between 0 and 1000
+6. hotkey(key, c) # press the key for c times
+7. type(text) # type a text string on the keyboard
+8. scroll(x, y, direction, c) # scroll the mouse at position (x, y) in the direction of up or down for c times, where x and y are integers normalized between 0 and 1000
+9. wait() # wait for a while
+10. finish() # indicate the task is finished
+
+Directly output the text beginning with <|think_start|>, no additional text is needed for this scenario.
+
+The user instruction is:
+{instruction}
+"""
+
+
+def build_prompt(task_description: str) -> str:
+    """Build the instruction prompt for the OAGI model.
+
+    Args:
+        task_description: The task description to include in the prompt
+
+    Returns:
+        The formatted prompt string with action format documentation
+    """
+    return instruction_template.format(instruction=task_description)