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

oagi/client/base.py

@@ -11,6 +11,7 @@ from typing import Any, Generic, TypeVar
 
 import httpx
 
+from ..constants import API_KEY_HELP_URL, DEFAULT_BASE_URL, HTTP_CLIENT_TIMEOUT
 from ..exceptions import (
     APIError,
     AuthenticationError,
@@ -41,20 +42,19 @@ class BaseClient(Generic[HttpClientT]):
 
     def __init__(self, base_url: str | None = None, api_key: str | None = None):
         # Get from environment if not provided
-        self.base_url = (
-            base_url or os.getenv("OAGI_BASE_URL") or "https://api.agiopen.org"
-        )
+        self.base_url = base_url or os.getenv("OAGI_BASE_URL") or DEFAULT_BASE_URL
         self.api_key = api_key or os.getenv("OAGI_API_KEY")
 
         # Validate required configuration
         if not self.api_key:
             raise ConfigurationError(
                 "OAGI API key must be provided either as 'api_key' parameter or "
-                "OAGI_API_KEY environment variable"
+                "OAGI_API_KEY environment variable. "
+                f"Get your API key at {API_KEY_HELP_URL}"
             )
 
         self.base_url = self.base_url.rstrip("/")
-        self.timeout = 60
+        self.timeout = HTTP_CLIENT_TIMEOUT
         self.client: HttpClientT  # Will be set by subclasses
 
         logger.info(f"Client initialized with base_url: {self.base_url}")
@@ -273,22 +273,20 @@ class BaseClient(Generic[HttpClientT]):
             NetworkError: If network error occurs
             APIError: If API returns error or invalid response
         """
+        response_data = self._parse_response_json(response)
+
+        # Check for error status codes first (follows _process_response pattern)
+        if response.status_code != 200:
+            self._handle_response_error(response, response_data)
+
         try:
-            response_data = response.json()
             upload_file_response = UploadFileResponse(**response_data)
             logger.debug("Calling /v1/file/upload successful")
             return upload_file_response
-        except ValueError:
-            logger.error(f"Non-JSON API response: {response.status_code}")
-            raise APIError(
-                f"Invalid response format (status {response.status_code})",
-                status_code=response.status_code,
-                response=response,
-            )
-        except KeyError as e:
-            logger.error(f"Invalid response: {response.status_code}")
+        except Exception as e:
+            logger.error(f"Invalid upload response: {response.status_code}")
             raise APIError(
-                f"Invalid presigned S3 URL response: missing field {e}",
+                f"Invalid presigned S3 URL response: {e}",
                 status_code=response.status_code,
                 response=response,
             )

oagi/client/sync.py

@@ -11,6 +11,13 @@ from functools import wraps
 import httpx
 from httpx import Response
 
+from ..constants import (
+    API_HEALTH_ENDPOINT,
+    API_V1_FILE_UPLOAD_ENDPOINT,
+    API_V1_GENERATE_ENDPOINT,
+    API_V2_MESSAGE_ENDPOINT,
+    HTTP_CLIENT_TIMEOUT,
+)
 from ..logging import get_logger
 from ..types import Image
 from ..types.models import GenerateResponse, LLMResponse, UploadFileResponse
@@ -46,7 +53,7 @@ class SyncClient(BaseClient[httpx.Client]):
     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=60)  # client for uploading image
+        self.upload_client = httpx.Client(timeout=HTTP_CLIENT_TIMEOUT)
         logger.info(f"SyncClient initialized with base_url: {self.base_url}")
 
     def __enter__(self):
@@ -124,7 +131,10 @@ class SyncClient(BaseClient[httpx.Client]):
         # Make request
         try:
             response = self.client.post(
-                "/v2/message", json=payload, headers=headers, timeout=self.timeout
+                API_V2_MESSAGE_ENDPOINT,
+                json=payload,
+                headers=headers,
+                timeout=self.timeout,
             )
             return self._process_response(response)
         except (httpx.TimeoutException, httpx.NetworkError) as e:
@@ -139,7 +149,7 @@ class SyncClient(BaseClient[httpx.Client]):
         """
         logger.debug("Making health check request")
         try:
-            response = self.client.get("/health")
+            response = self.client.get(API_HEALTH_ENDPOINT)
             response.raise_for_status()
             result = response.json()
             logger.debug("Health check successful")
@@ -161,12 +171,12 @@ class SyncClient(BaseClient[httpx.Client]):
         Returns:
             UploadFileResponse: The response from /v1/file/upload with uuid and presigned S3 URL
         """
-        logger.debug("Making API request to /v1/file/upload")
+        logger.debug(f"Making API request to {API_V1_FILE_UPLOAD_ENDPOINT}")
 
         try:
             headers = self._build_headers(api_version)
             response = self.client.get(
-                "/v1/file/upload", headers=headers, timeout=self.timeout
+                API_V1_FILE_UPLOAD_ENDPOINT, headers=headers, timeout=self.timeout
             )
             return self._process_upload_response(response)
         except (httpx.TimeoutException, httpx.NetworkError, httpx.HTTPStatusError) as e:
@@ -286,7 +296,10 @@ class SyncClient(BaseClient[httpx.Client]):
         # Make request
         try:
             response = self.client.post(
-                "/v1/generate", json=payload, headers=headers, timeout=self.timeout
+                API_V1_GENERATE_ENDPOINT,
+                json=payload,
+                headers=headers,
+                timeout=self.timeout,
             )
             return self._process_generate_response(response)
         except (httpx.TimeoutException, httpx.NetworkError) as e:

oagi/constants.py

@@ -0,0 +1,43 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+# 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"
+MODEL_THINKER = "lux-thinker-1"
+
+# Agent modes
+MODE_ACTOR = "actor"
+MODE_THINKER = "thinker"
+MODE_TASKER = "tasker"
+
+# Default max steps per model
+DEFAULT_MAX_STEPS = 20
+DEFAULT_MAX_STEPS_THINKER = 100
+DEFAULT_MAX_STEPS_TASKER = 60
+
+# Reflection intervals
+DEFAULT_REFLECTION_INTERVAL = 4
+DEFAULT_REFLECTION_INTERVAL_TASKER = 20
+
+# Timing & Delays
+DEFAULT_STEP_DELAY = 0.3
+
+# Temperature Defaults
+DEFAULT_TEMPERATURE = 0.5
+DEFAULT_TEMPERATURE_LOW = 0.1
+
+# Timeout Values
+HTTP_CLIENT_TIMEOUT = 60

oagi/handler/__init__.py

@@ -14,6 +14,21 @@ from oagi.handler.pyautogui_action_handler import (
 )
 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()
+
+
 __all__ = [
     "PILImage",
     "PyautoguiActionHandler",
@@ -21,4 +36,5 @@ __all__ = [
     "AsyncPyautoguiActionHandler",
     "ScreenshotMaker",
     "AsyncScreenshotMaker",
+    "reset_handler",
 ]

oagi/handler/_macos.py

@@ -6,6 +6,15 @@
 #  Licensed under the MIT License.
 # -----------------------------------------------------------------------------
 
+"""macOS-specific keyboard and mouse input handling.
+
+This module provides:
+- macos_click(): Fix for PyAutoGUI multi-click bug on macOS
+- typewrite_exact(): Type text exactly, ignoring system capslock state
+"""
+
+import time
+
 import pyautogui
 
 from ..exceptions import check_optional_dependency
@@ -13,6 +22,134 @@ from ..exceptions import check_optional_dependency
 check_optional_dependency("Quartz", "macOS multiple clicks", "desktop")
 import Quartz  # noqa: E402
 
+# macOS virtual key codes for typeable characters
+KEYCODE_MAP = {
+    "a": 0x00,
+    "b": 0x0B,
+    "c": 0x08,
+    "d": 0x02,
+    "e": 0x0E,
+    "f": 0x03,
+    "g": 0x05,
+    "h": 0x04,
+    "i": 0x22,
+    "j": 0x26,
+    "k": 0x28,
+    "l": 0x25,
+    "m": 0x2E,
+    "n": 0x2D,
+    "o": 0x1F,
+    "p": 0x23,
+    "q": 0x0C,
+    "r": 0x0F,
+    "s": 0x01,
+    "t": 0x11,
+    "u": 0x20,
+    "v": 0x09,
+    "w": 0x0D,
+    "x": 0x07,
+    "y": 0x10,
+    "z": 0x06,
+    "1": 0x12,
+    "2": 0x13,
+    "3": 0x14,
+    "4": 0x15,
+    "5": 0x17,
+    "6": 0x16,
+    "7": 0x1A,
+    "8": 0x1C,
+    "9": 0x19,
+    "0": 0x1D,
+    " ": 0x31,  # space
+    "-": 0x1B,
+    "=": 0x18,
+    "[": 0x21,
+    "]": 0x1E,
+    "\\": 0x2A,
+    ";": 0x29,
+    "'": 0x27,
+    "`": 0x32,
+    ",": 0x2B,
+    ".": 0x2F,
+    "/": 0x2C,
+    "\t": 0x30,  # tab
+    "\n": 0x24,  # return
+}
+
+# Characters that require shift key (on US keyboard layout)
+SHIFT_CHARS = set('~!@#$%^&*()_+{}|:"<>?ABCDEFGHIJKLMNOPQRSTUVWXYZ')
+
+# Mapping of shifted characters to their base key
+SHIFT_KEY_MAP = {
+    "~": "`",
+    "!": "1",
+    "@": "2",
+    "#": "3",
+    "$": "4",
+    "%": "5",
+    "^": "6",
+    "&": "7",
+    "*": "8",
+    "(": "9",
+    ")": "0",
+    "_": "-",
+    "+": "=",
+    "{": "[",
+    "}": "]",
+    "|": "\\",
+    ":": ";",
+    '"': "'",
+    "<": ",",
+    ">": ".",
+    "?": "/",
+}
+
+
+def typewrite_exact(text: str, interval: float = 0.01) -> None:
+    """Type text exactly as specified, ignoring system capslock state.
+
+    This function uses Quartz CGEventCreateKeyboardEvent with explicit
+    flag control via CGEventSetFlags() to type each character with the
+    correct case, regardless of the system's capslock state.
+
+    Args:
+        text: The text to type exactly as specified
+        interval: Time in seconds between each character (default: 0.01)
+    """
+    for char in text:
+        # Determine if this character needs shift
+        needs_shift = char in SHIFT_CHARS
+
+        # Get the base key (for shifted chars, look up the unshifted version)
+        if char.isupper():
+            base_char = char.lower()
+        elif char in SHIFT_KEY_MAP:
+            base_char = SHIFT_KEY_MAP[char]
+        else:
+            base_char = char
+
+        # Get keycode for the base character
+        keycode = KEYCODE_MAP.get(base_char)
+        if keycode is None:
+            # Character not in our keycode map, skip it
+            continue
+
+        # Set flags: shift if needed, otherwise clear all flags
+        flags = Quartz.kCGEventFlagMaskShift if needs_shift else 0
+
+        # Key down
+        event_down = Quartz.CGEventCreateKeyboardEvent(None, keycode, True)
+        Quartz.CGEventSetFlags(event_down, flags)
+        Quartz.CGEventPost(Quartz.kCGHIDEventTap, event_down)
+
+        # Key up
+        event_up = Quartz.CGEventCreateKeyboardEvent(None, keycode, False)
+        Quartz.CGEventSetFlags(event_up, flags)
+        Quartz.CGEventPost(Quartz.kCGHIDEventTap, event_up)
+
+        if interval > 0:
+            time.sleep(interval)
+
 
 def macos_click(x: int, y: int, clicks: int = 1) -> None:
     """

oagi/handler/_windows.py

@@ -0,0 +1,101 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+"""Windows-specific keyboard input handling.
+
+This module provides typewrite_exact() which types text exactly as specified,
+ignoring the system's capslock state by using SendInput with KEYEVENTF_UNICODE.
+"""
+
+import ctypes
+import time
+from ctypes import wintypes
+
+INPUT_KEYBOARD = 1
+KEYEVENTF_UNICODE = 0x0004
+KEYEVENTF_KEYUP = 0x0002
+
+
+class KEYBDINPUT(ctypes.Structure):
+    _fields_ = [
+        ("wVk", wintypes.WORD),
+        ("wScan", wintypes.WORD),
+        ("dwFlags", wintypes.DWORD),
+        ("time", wintypes.DWORD),
+        ("dwExtraInfo", ctypes.POINTER(ctypes.c_ulong)),
+    ]
+
+
+class MOUSEINPUT(ctypes.Structure):
+    _fields_ = [
+        ("dx", ctypes.c_long),
+        ("dy", ctypes.c_long),
+        ("mouseData", wintypes.DWORD),
+        ("dwFlags", wintypes.DWORD),
+        ("time", wintypes.DWORD),
+        ("dwExtraInfo", ctypes.POINTER(ctypes.c_ulong)),
+    ]
+
+
+class HARDWAREINPUT(ctypes.Structure):
+    _fields_ = [
+        ("uMsg", wintypes.DWORD),
+        ("wParamL", wintypes.WORD),
+        ("wParamH", wintypes.WORD),
+    ]
+
+
+class INPUT(ctypes.Structure):
+    class _I(ctypes.Union):
+        _fields_ = [
+            ("ki", KEYBDINPUT),
+            ("mi", MOUSEINPUT),
+            ("hi", HARDWAREINPUT),
+        ]
+
+    _anonymous_ = ("i",)
+    _fields_ = [
+        ("type", wintypes.DWORD),
+        ("i", _I),
+    ]
+
+
+# Configure SendInput with proper argtypes for 64-bit compatibility
+SendInput = ctypes.windll.user32.SendInput
+SendInput.argtypes = [wintypes.UINT, ctypes.POINTER(INPUT), ctypes.c_int]
+SendInput.restype = wintypes.UINT
+
+
+def typewrite_exact(text: str, interval: float = 0.01) -> None:
+    """Type text exactly using Unicode input - ignores capslock, keyboard layout, etc.
+
+    This function uses SendInput with KEYEVENTF_UNICODE to send characters
+    directly by their Unicode codepoint, completely bypassing keyboard state
+    (capslock, layout, etc.).
+
+    Args:
+        text: The text to type exactly as specified
+        interval: Time in seconds between each character (default: 0.01)
+    """
+    for char in text:
+        inputs = (INPUT * 2)()
+
+        # Key down
+        inputs[0].type = INPUT_KEYBOARD
+        inputs[0].ki.wScan = ord(char)
+        inputs[0].ki.dwFlags = KEYEVENTF_UNICODE
+
+        # Key up
+        inputs[1].type = INPUT_KEYBOARD
+        inputs[1].ki.wScan = ord(char)
+        inputs[1].ki.dwFlags = KEYEVENTF_UNICODE | KEYEVENTF_KEYUP
+
+        SendInput(2, inputs, ctypes.sizeof(INPUT))
+
+        if interval > 0:
+            time.sleep(interval)

oagi/handler/async_pyautogui_action_handler.py

@@ -29,6 +29,14 @@ class AsyncPyautoguiActionHandler:
         self.sync_handler = PyautoguiActionHandler(config=config)
         self.config = config or PyautoguiConfig()
 
+    def reset(self):
+        """Reset handler state.
+
+        Delegates to the underlying synchronous handler's reset method.
+        Called at automation start/end and when FINISH action is received.
+        """
+        self.sync_handler.reset()
+
     async def __call__(self, actions: list[Action]) -> None:
         """
         Execute actions asynchronously using a thread pool executor.

oagi/handler/capslock_manager.py

@@ -0,0 +1,55 @@
+# -----------------------------------------------------------------------------
+#  Copyright (c) OpenAGI Foundation
+#  All rights reserved.
+#
+#  This file is part of the official API project.
+#  Licensed under the MIT License.
+# -----------------------------------------------------------------------------
+
+
+class CapsLockManager:
+    """Manages caps lock state for text transformation.
+
+    This class maintains an internal caps lock state that can be toggled
+    independently of the system's caps lock state. This allows for consistent
+    text case handling during automation regardless of the system state.
+    """
+
+    def __init__(self, mode: str = "session"):
+        """Initialize caps lock manager.
+
+        Args:
+            mode: Either "session" (internal state) or "system" (OS-level)
+        """
+        self.mode = mode
+        self.caps_enabled = False
+
+    def reset(self):
+        """Reset caps lock state to default (off).
+
+        Called at automation start/end and when FINISH action is received.
+        """
+        self.caps_enabled = False
+
+    def toggle(self):
+        """Toggle caps lock state in session mode."""
+        if self.mode == "session":
+            self.caps_enabled = not self.caps_enabled
+
+    def transform_text(self, text: str) -> str:
+        """Transform text based on caps lock state.
+
+        Args:
+            text: Input text to transform
+
+        Returns:
+            Transformed text (uppercase alphabets if caps enabled in session mode)
+        """
+        if self.mode == "session" and self.caps_enabled:
+            # Transform letters to uppercase, preserve special characters
+            return "".join(c.upper() if c.isalpha() else c for c in text)
+        return text
+
+    def should_use_system_capslock(self) -> bool:
+        """Check if system-level caps lock should be used."""
+        return self.mode == "system"

oagi/handler/pyautogui_action_handler.py

@@ -13,48 +13,15 @@ from pydantic import BaseModel, Field
 
 from ..exceptions import check_optional_dependency
 from ..types import Action, ActionType, parse_coords, parse_drag_coords, parse_scroll
+from .capslock_manager import CapsLockManager
 
 check_optional_dependency("pyautogui", "PyautoguiActionHandler", "desktop")
 import pyautogui  # noqa: E402
 
 if sys.platform == "darwin":
     from . import _macos
-
-
-class CapsLockManager:
-    """Manages caps lock state for text transformation."""
-
-    def __init__(self, mode: str = "session"):
-        """Initialize caps lock manager.
-
-        Args:
-            mode: Either "session" (internal state) or "system" (OS-level)
-        """
-        self.mode = mode
-        self.caps_enabled = False
-
-    def toggle(self):
-        """Toggle caps lock state in session mode."""
-        if self.mode == "session":
-            self.caps_enabled = not self.caps_enabled
-
-    def transform_text(self, text: str) -> str:
-        """Transform text based on caps lock state.
-
-        Args:
-            text: Input text to transform
-
-        Returns:
-            Transformed text (uppercase if caps enabled in session mode)
-        """
-        if self.mode == "session" and self.caps_enabled:
-            # Transform letters to uppercase, preserve special characters
-            return "".join(c.upper() if c.isalpha() else c for c in text)
-        return text
-
-    def should_use_system_capslock(self) -> bool:
-        """Check if system-level caps lock should be used."""
-        return self.mode == "system"
+elif sys.platform == "win32":
+    from . import _windows
 
 
 class PyautoguiConfig(BaseModel):
@@ -64,7 +31,8 @@ class PyautoguiConfig(BaseModel):
         default=0.5, description="Duration for drag operations in seconds"
     )
     scroll_amount: int = Field(
-        default=30, description="Amount to scroll (positive for up, negative for down)"
+        default=2 if sys.platform == "darwin" else 100,
+        description="Amount to scroll (positive for up, negative for down)",
     )
     wait_duration: float = Field(
         default=1.0, description="Duration for wait actions in seconds"
@@ -110,6 +78,14 @@ class PyautoguiActionHandler:
         # Initialize caps lock manager
         self.caps_manager = CapsLockManager(mode=self.config.capslock_mode)
 
+    def reset(self):
+        """Reset handler state.
+
+        Called at automation start/end and when FINISH action is received.
+        Resets the internal capslock state.
+        """
+        self.caps_manager.reset()
+
     def _denormalize_coords(self, x: float, y: float) -> tuple[int, int]:
         """Convert coordinates from 0-1000 range to actual screen coordinates.
 
@@ -237,7 +213,14 @@ class PyautoguiActionHandler:
                 text = arg.strip("\"'")
                 # Apply caps lock transformation if needed
                 text = self.caps_manager.transform_text(text)
-                pyautogui.typewrite(text)
+                # Use platform-specific typing that ignores system capslock
+                if sys.platform == "darwin":
+                    _macos.typewrite_exact(text)
+                elif sys.platform == "win32":
+                    _windows.typewrite_exact(text)
+                else:
+                    # Fallback for other platforms
+                    pyautogui.typewrite(text)
 
             case ActionType.SCROLL:
                 x, y, direction = self._parse_scroll(arg)
@@ -250,8 +233,8 @@ class PyautoguiActionHandler:
                 pyautogui.scroll(scroll_amount)
 
             case ActionType.FINISH:
-                # Task completion - no action needed
-                pass
+                # Task completion - reset handler state
+                self.reset()
 
             case ActionType.WAIT:
                 # Wait for a short period

oagi/server/config.py

@@ -8,6 +8,7 @@
 
 from pydantic import Field
 
+from ..constants import DEFAULT_MAX_STEPS, MODEL_ACTOR
 from ..exceptions import check_optional_dependency
 
 check_optional_dependency("pydantic_settings", "Server features", "server")
@@ -20,7 +21,7 @@ class ServerConfig(BaseSettings):
     oagi_base_url: str = Field(default="https://api.agiopen.org", alias="OAGI_BASE_URL")
 
     # Server settings
-    server_host: str = Field(default="0.0.0.0", alias="OAGI_SERVER_HOST")
+    server_host: str = Field(default="127.0.0.1", alias="OAGI_SERVER_HOST")
     server_port: int = Field(default=8000, alias="OAGI_SERVER_PORT")
     cors_allowed_origins: str = Field(default="*", alias="OAGI_CORS_ORIGINS")
 
@@ -28,11 +29,13 @@ class ServerConfig(BaseSettings):
     session_timeout_seconds: float = Field(default=10.0)
 
     # Model settings
-    default_model: str = Field(default="lux-actor-1", alias="OAGI_DEFAULT_MODEL")
+    default_model: str = Field(default=MODEL_ACTOR, alias="OAGI_DEFAULT_MODEL")
     default_temperature: float = Field(default=0.5, ge=0.0, le=2.0)
 
     # Agent settings
-    max_steps: int = Field(default=20, alias="OAGI_MAX_STEPS", ge=1, le=100)
+    max_steps: int = Field(
+        default=DEFAULT_MAX_STEPS, alias="OAGI_MAX_STEPS", ge=1, le=200
+    )
 
     # Socket.IO settings
     socketio_path: str = Field(default="/socket.io")

oagi/server/models.py

@@ -10,13 +10,15 @@ from typing import Literal
 
 from pydantic import BaseModel, Field
 
+from ..constants import DEFAULT_TEMPERATURE_LOW, MODE_ACTOR, MODEL_ACTOR
+
 
 # Client-to-server events
 class InitEventData(BaseModel):
     instruction: str = Field(...)
-    mode: str | None = Field(default="actor")
-    model: str | None = Field(default="lux-actor-1")
-    temperature: float | None = Field(default=0.1, ge=0.0, le=2.0)
+    mode: str | None = Field(default=MODE_ACTOR)
+    model: str | None = Field(default=MODEL_ACTOR)
+    temperature: float | None = Field(default=DEFAULT_TEMPERATURE_LOW, ge=0.0, le=2.0)
 
 
 # Server-to-client events