autoglm-gui 1.3.1__py3-none-any.whl → 1.4.1__py3-none-any.whl

AutoGLM_GUI/device_protocol.py

@@ -0,0 +1,266 @@
+"""Device Protocol - Abstract interface for device operations.
+
+This module defines the protocol (interface) that all device implementations
+must follow. The actual implementation can be:
+- ADB (local subprocess calls)
+- Accessibility Service
+- Remote HTTP/gRPC calls
+- Mock (for testing)
+
+Example:
+    >>> from AutoGLM_GUI.devices import ADBDevice, MockDevice
+    >>>
+    >>> # Production: use ADB
+    >>> device = ADBDevice("emulator-5554")
+    >>> screenshot = device.get_screenshot()
+    >>> device.tap(100, 200)
+    >>>
+    >>> # Testing: use Mock with state machine
+    >>> mock = MockDevice("mock_001", state_machine)
+    >>> screenshot = mock.get_screenshot()  # Returns state machine's screenshot
+"""
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+
+@dataclass
+class Screenshot:
+    """Screenshot result from device."""
+
+    base64_data: str
+    width: int
+    height: int
+    is_sensitive: bool = False
+
+
+@dataclass
+class DeviceInfo:
+    """Information about a connected device."""
+
+    device_id: str
+    status: str  # "online" | "offline" | "unauthorized"
+    model: str | None = None
+    platform: str = "android"  # "android" | "ios" | "harmonyos"
+    connection_type: str = "usb"  # "usb" | "wifi" | "remote"
+
+
+@runtime_checkable
+class DeviceProtocol(Protocol):
+    """
+    Device operation protocol - all device implementations must follow this interface.
+
+    This protocol abstracts device operations, allowing the control logic to be
+    independent of the actual device implementation (ADB, Accessibility, Remote, etc.).
+
+    The concrete implementation decides HOW to perform operations:
+    - ADBDevice: Uses `adb shell input tap` commands
+    - AccessibilityDevice: Uses Android Accessibility Service
+    - RemoteDevice: Sends HTTP/gRPC requests to a remote agent
+    - MockDevice: Routes operations through a state machine for testing
+    """
+
+    @property
+    def device_id(self) -> str:
+        """Unique device identifier."""
+        ...
+
+    # === Screenshot ===
+    def get_screenshot(self, timeout: int = 10) -> Screenshot:
+        """
+        Capture current screen.
+
+        Args:
+            timeout: Timeout in seconds for the operation.
+
+        Returns:
+            Screenshot object containing base64 data and dimensions.
+        """
+        ...
+
+    # === Input Operations ===
+    def tap(self, x: int, y: int, delay: float | None = None) -> None:
+        """
+        Tap at specified coordinates.
+
+        Args:
+            x: X coordinate.
+            y: Y coordinate.
+            delay: Optional delay after tap in seconds.
+        """
+        ...
+
+    def double_tap(self, x: int, y: int, delay: float | None = None) -> None:
+        """
+        Double tap at specified coordinates.
+
+        Args:
+            x: X coordinate.
+            y: Y coordinate.
+            delay: Optional delay after double tap in seconds.
+        """
+        ...
+
+    def long_press(
+        self, x: int, y: int, duration_ms: int = 3000, delay: float | None = None
+    ) -> None:
+        """
+        Long press at specified coordinates.
+
+        Args:
+            x: X coordinate.
+            y: Y coordinate.
+            duration_ms: Duration of press in milliseconds.
+            delay: Optional delay after long press in seconds.
+        """
+        ...
+
+    def swipe(
+        self,
+        start_x: int,
+        start_y: int,
+        end_x: int,
+        end_y: int,
+        duration_ms: int | None = None,
+        delay: float | None = None,
+    ) -> None:
+        """
+        Swipe from start to end coordinates.
+
+        Args:
+            start_x: Starting X coordinate.
+            start_y: Starting Y coordinate.
+            end_x: Ending X coordinate.
+            end_y: Ending Y coordinate.
+            duration_ms: Duration of swipe in milliseconds.
+            delay: Optional delay after swipe in seconds.
+        """
+        ...
+
+    def type_text(self, text: str) -> None:
+        """
+        Type text into the currently focused input field.
+
+        Args:
+            text: The text to type.
+        """
+        ...
+
+    def clear_text(self) -> None:
+        """Clear text in the currently focused input field."""
+        ...
+
+    # === Navigation ===
+    def back(self, delay: float | None = None) -> None:
+        """
+        Press the back button.
+
+        Args:
+            delay: Optional delay after pressing back in seconds.
+        """
+        ...
+
+    def home(self, delay: float | None = None) -> None:
+        """
+        Press the home button.
+
+        Args:
+            delay: Optional delay after pressing home in seconds.
+        """
+        ...
+
+    def launch_app(self, app_name: str, delay: float | None = None) -> bool:
+        """
+        Launch an app by name.
+
+        Args:
+            app_name: The app name to launch.
+            delay: Optional delay after launching in seconds.
+
+        Returns:
+            True if app was launched successfully, False otherwise.
+        """
+        ...
+
+    # === State Query ===
+    def get_current_app(self) -> str:
+        """
+        Get the currently focused app name.
+
+        Returns:
+            The app name if recognized, otherwise "System Home".
+        """
+        ...
+
+    # === Keyboard Management ===
+    def detect_and_set_adb_keyboard(self) -> str:
+        """
+        Detect current keyboard and switch to ADB Keyboard if needed.
+
+        Returns:
+            The original keyboard IME identifier for later restoration.
+        """
+        ...
+
+    def restore_keyboard(self, ime: str) -> None:
+        """
+        Restore the original keyboard IME.
+
+        Args:
+            ime: The IME identifier to restore.
+        """
+        ...
+
+
+@runtime_checkable
+class DeviceManagerProtocol(Protocol):
+    """Device manager protocol - manages multiple devices."""
+
+    def list_devices(self) -> list[DeviceInfo]:
+        """
+        List all available devices.
+
+        Returns:
+            List of DeviceInfo objects.
+        """
+        ...
+
+    def get_device(self, device_id: str) -> DeviceProtocol:
+        """
+        Get a device instance by ID.
+
+        Args:
+            device_id: The device ID.
+
+        Returns:
+            DeviceProtocol implementation for the device.
+
+        Raises:
+            KeyError: If device not found.
+        """
+        ...
+
+    def connect(self, address: str, timeout: int = 10) -> tuple[bool, str]:
+        """
+        Connect to a remote device.
+
+        Args:
+            address: Device address (e.g., "192.168.1.100:5555").
+            timeout: Connection timeout in seconds.
+
+        Returns:
+            Tuple of (success, message).
+        """
+        ...
+
+    def disconnect(self, device_id: str) -> tuple[bool, str]:
+        """
+        Disconnect from a device.
+
+        Args:
+            device_id: The device ID to disconnect.
+
+        Returns:
+            Tuple of (success, message).
+        """
+        ...

AutoGLM_GUI/devices/__init__.py

@@ -0,0 +1,49 @@
+"""Device implementations for the DeviceProtocol interface.
+
+This package provides concrete implementations of DeviceProtocol:
+- ADBDevice: Local ADB subprocess calls
+- MockDevice: State machine driven mock for testing
+- RemoteDevice: HTTP client for remote device agents
+
+Example:
+    >>> from AutoGLM_GUI.devices import ADBDevice, RemoteDevice, get_device_manager
+    >>>
+    >>> # Local ADB device
+    >>> device = ADBDevice("emulator-5554")
+    >>> device.tap(100, 200)
+    >>>
+    >>> # Remote device via HTTP
+    >>> remote = RemoteDevice("phone_001", "http://device-agent:8001")
+    >>> remote.tap(100, 200)
+"""
+
+from AutoGLM_GUI.devices.adb_device import ADBDevice, ADBDeviceManager
+from AutoGLM_GUI.devices.mock_device import MockDevice
+from AutoGLM_GUI.devices.remote_device import RemoteDevice, RemoteDeviceManager
+
+_device_manager: "ADBDeviceManager | None" = None
+
+
+def get_device_manager() -> ADBDeviceManager:
+    """Get the global device manager instance."""
+    global _device_manager
+    if _device_manager is None:
+        _device_manager = ADBDeviceManager()
+    return _device_manager
+
+
+def set_device_manager(manager: "ADBDeviceManager") -> None:
+    """Set the global device manager instance (useful for testing)."""
+    global _device_manager
+    _device_manager = manager
+
+
+__all__ = [
+    "ADBDevice",
+    "ADBDeviceManager",
+    "MockDevice",
+    "RemoteDevice",
+    "RemoteDeviceManager",
+    "get_device_manager",
+    "set_device_manager",
+]

AutoGLM_GUI/devices/adb_device.py

@@ -0,0 +1,205 @@
+"""ADB Device implementation of DeviceProtocol.
+
+This module wraps the existing phone_agent.adb module to provide
+a DeviceProtocol-compliant implementation.
+"""
+
+from phone_agent import adb
+from phone_agent.adb import ADBConnection
+
+from AutoGLM_GUI.device_protocol import (
+    DeviceInfo,
+    DeviceManagerProtocol,
+    DeviceProtocol,
+    Screenshot,
+)
+
+
+class ADBDevice:
+    """
+    ADB device implementation using local subprocess calls.
+
+    Wraps the existing phone_agent.adb module to provide a clean
+    DeviceProtocol interface.
+
+    Example:
+        >>> device = ADBDevice("emulator-5554")
+        >>> screenshot = device.get_screenshot()
+        >>> device.tap(100, 200)
+        >>> device.swipe(100, 200, 300, 400)
+    """
+
+    def __init__(self, device_id: str):
+        """
+        Initialize ADB device.
+
+        Args:
+            device_id: ADB device ID (e.g., "emulator-5554", "192.168.1.100:5555").
+        """
+        self._device_id = device_id
+
+    @property
+    def device_id(self) -> str:
+        """Unique device identifier."""
+        return self._device_id
+
+    # === Screenshot ===
+    def get_screenshot(self, timeout: int = 10) -> Screenshot:
+        """Capture current screen."""
+        result = adb.get_screenshot(self._device_id, timeout)
+        return Screenshot(
+            base64_data=result.base64_data,
+            width=result.width,
+            height=result.height,
+            is_sensitive=result.is_sensitive,
+        )
+
+    # === Input Operations ===
+    def tap(self, x: int, y: int, delay: float | None = None) -> None:
+        """Tap at specified coordinates."""
+        adb.tap(x, y, self._device_id, delay)
+
+    def double_tap(self, x: int, y: int, delay: float | None = None) -> None:
+        """Double tap at specified coordinates."""
+        adb.double_tap(x, y, self._device_id, delay)
+
+    def long_press(
+        self, x: int, y: int, duration_ms: int = 3000, delay: float | None = None
+    ) -> None:
+        """Long press at specified coordinates."""
+        adb.long_press(x, y, duration_ms, self._device_id, delay)
+
+    def swipe(
+        self,
+        start_x: int,
+        start_y: int,
+        end_x: int,
+        end_y: int,
+        duration_ms: int | None = None,
+        delay: float | None = None,
+    ) -> None:
+        """Swipe from start to end coordinates."""
+        adb.swipe(start_x, start_y, end_x, end_y, duration_ms, self._device_id, delay)
+
+    def type_text(self, text: str) -> None:
+        """Type text into the currently focused input field."""
+        adb.type_text(text, self._device_id)
+
+    def clear_text(self) -> None:
+        """Clear text in the currently focused input field."""
+        adb.clear_text(self._device_id)
+
+    # === Navigation ===
+    def back(self, delay: float | None = None) -> None:
+        """Press the back button."""
+        adb.back(self._device_id, delay)
+
+    def home(self, delay: float | None = None) -> None:
+        """Press the home button."""
+        adb.home(self._device_id, delay)
+
+    def launch_app(self, app_name: str, delay: float | None = None) -> bool:
+        """Launch an app by name."""
+        return adb.launch_app(app_name, self._device_id, delay)
+
+    # === State Query ===
+    def get_current_app(self) -> str:
+        """Get the currently focused app name."""
+        return adb.get_current_app(self._device_id)
+
+    # === Keyboard Management ===
+    def detect_and_set_adb_keyboard(self) -> str:
+        """Detect current keyboard and switch to ADB Keyboard if needed."""
+        return adb.detect_and_set_adb_keyboard(self._device_id)
+
+    def restore_keyboard(self, ime: str) -> None:
+        """Restore the original keyboard IME."""
+        adb.restore_keyboard(ime, self._device_id)
+
+
+# Verify ADBDevice implements DeviceProtocol
+assert isinstance(ADBDevice("test"), DeviceProtocol)
+
+
+class ADBDeviceManager:
+    """
+    ADB device manager implementation.
+
+    Manages multiple ADB devices and provides DeviceProtocol instances.
+
+    Example:
+        >>> manager = ADBDeviceManager()
+        >>> devices = manager.list_devices()
+        >>> device = manager.get_device("emulator-5554")
+        >>> device.tap(100, 200)
+    """
+
+    def __init__(self, adb_path: str = "adb"):
+        """
+        Initialize the device manager.
+
+        Args:
+            adb_path: Path to ADB executable.
+        """
+        self._connection = ADBConnection(adb_path)
+        self._devices: dict[str, ADBDevice] = {}
+
+    def list_devices(self) -> list[DeviceInfo]:
+        """List all available devices."""
+        adb_devices = self._connection.list_devices()
+        result = []
+
+        for dev in adb_devices:
+            result.append(
+                DeviceInfo(
+                    device_id=dev.device_id,
+                    status="online" if dev.status == "device" else dev.status,
+                    model=dev.model,
+                    platform="android",
+                    connection_type=dev.connection_type.value,
+                )
+            )
+
+        return result
+
+    def get_device(self, device_id: str) -> ADBDevice:
+        """
+        Get a device instance by ID.
+
+        Args:
+            device_id: The device ID.
+
+        Returns:
+            ADBDevice instance.
+
+        Raises:
+            KeyError: If device not found or offline.
+        """
+        # Check if device exists and is online
+        devices = self.list_devices()
+        device_info = next((d for d in devices if d.device_id == device_id), None)
+
+        if device_info is None:
+            raise KeyError(f"Device '{device_id}' not found")
+        if device_info.status != "online":
+            raise KeyError(f"Device '{device_id}' is {device_info.status}")
+
+        # Cache and return device instance
+        if device_id not in self._devices:
+            self._devices[device_id] = ADBDevice(device_id)
+
+        return self._devices[device_id]
+
+    def connect(self, address: str, timeout: int = 10) -> tuple[bool, str]:
+        """Connect to a remote device."""
+        return self._connection.connect(address, timeout)
+
+    def disconnect(self, device_id: str) -> tuple[bool, str]:
+        """Disconnect from a device."""
+        # Remove from cache
+        self._devices.pop(device_id, None)
+        return self._connection.disconnect(device_id)
+
+
+# Verify ADBDeviceManager implements DeviceManagerProtocol
+assert isinstance(ADBDeviceManager(), DeviceManagerProtocol)

AutoGLM_GUI/devices/mock_device.py

@@ -0,0 +1,183 @@
+"""Mock Device implementation for testing.
+
+This module provides a MockDevice that routes all operations through
+a state machine, enabling controlled testing without real devices.
+"""
+
+from typing import TYPE_CHECKING
+
+from AutoGLM_GUI.device_protocol import (
+    DeviceInfo,
+    Screenshot,
+)
+
+if TYPE_CHECKING:
+    from tests.integration.state_machine import StateMachine
+
+
+class MockDevice:
+    """
+    Mock device implementation driven by a state machine.
+
+    All operations are routed through the state machine, which controls
+    screenshots and validates actions (tap coordinates, etc.).
+
+    Example:
+        >>> from tests.integration.state_machine import load_test_case
+        >>> state_machine, instruction, max_steps = load_test_case("scenario.yaml")
+        >>>
+        >>> device = MockDevice("mock_001", state_machine)
+        >>> screenshot = device.get_screenshot()  # Returns current state's screenshot
+        >>> device.tap(100, 200)  # State machine validates and transitions
+    """
+
+    def __init__(self, device_id: str, state_machine: "StateMachine"):
+        """
+        Initialize mock device.
+
+        Args:
+            device_id: Mock device ID.
+            state_machine: State machine that controls test flow.
+        """
+        self._device_id = device_id
+        self._state_machine = state_machine
+
+    @property
+    def device_id(self) -> str:
+        """Unique device identifier."""
+        return self._device_id
+
+    @property
+    def state_machine(self) -> "StateMachine":
+        """Get the underlying state machine."""
+        return self._state_machine
+
+    # === Screenshot ===
+    def get_screenshot(self, timeout: int = 10) -> Screenshot:
+        """Get screenshot from current state."""
+        result = self._state_machine.get_current_screenshot()
+        return Screenshot(
+            base64_data=result.base64_data,
+            width=result.width,
+            height=result.height,
+        )
+
+    # === Input Operations ===
+    def tap(self, x: int, y: int, delay: float | None = None) -> None:
+        """Handle tap action through state machine."""
+        self._state_machine.handle_tap(x, y)
+
+    def double_tap(self, x: int, y: int, delay: float | None = None) -> None:
+        """Handle double tap (treated as single tap)."""
+        self._state_machine.handle_tap(x, y)
+
+    def long_press(
+        self, x: int, y: int, duration_ms: int = 3000, delay: float | None = None
+    ) -> None:
+        """Handle long press (treated as tap for testing)."""
+        self._state_machine.handle_tap(x, y)
+
+    def swipe(
+        self,
+        start_x: int,
+        start_y: int,
+        end_x: int,
+        end_y: int,
+        duration_ms: int | None = None,
+        delay: float | None = None,
+    ) -> None:
+        """Handle swipe action."""
+        self._state_machine.handle_swipe(start_x, start_y, end_x, end_y)
+
+    def type_text(self, text: str) -> None:
+        """Handle text input (no-op in testing)."""
+        pass
+
+    def clear_text(self) -> None:
+        """Handle text clear (no-op in testing)."""
+        pass
+
+    # === Navigation ===
+    def back(self, delay: float | None = None) -> None:
+        """Handle back button (no-op in testing)."""
+        pass
+
+    def home(self, delay: float | None = None) -> None:
+        """Handle home button (no-op in testing)."""
+        pass
+
+    def launch_app(self, app_name: str, delay: float | None = None) -> bool:
+        """Handle app launch (always succeeds in testing)."""
+        return True
+
+    # === State Query ===
+    def get_current_app(self) -> str:
+        """Get current app name from the current state."""
+        return self._state_machine.current_state.current_app
+
+    # === Keyboard Management ===
+    def detect_and_set_adb_keyboard(self) -> str:
+        """Mock keyboard detection."""
+        return "com.mock.keyboard"
+
+    def restore_keyboard(self, ime: str) -> None:
+        """Mock keyboard restore."""
+        pass
+
+
+class MockDeviceManager:
+    """
+    Mock device manager for testing.
+
+    Provides a single mock device backed by a state machine.
+
+    Example:
+        >>> state_machine, _, _ = load_test_case("scenario.yaml")
+        >>> manager = MockDeviceManager(state_machine)
+        >>> device = manager.get_device("mock_001")
+    """
+
+    def __init__(
+        self,
+        state_machine: "StateMachine",
+        device_id: str = "mock_device_001",
+    ):
+        """
+        Initialize mock device manager.
+
+        Args:
+            state_machine: State machine for the mock device.
+            device_id: ID for the mock device.
+        """
+        self._device_id = device_id
+        self._device = MockDevice(device_id, state_machine)
+
+    def list_devices(self) -> list[DeviceInfo]:
+        """List the mock device."""
+        return [
+            DeviceInfo(
+                device_id=self._device_id,
+                status="online",
+                model="MockPhone",
+                platform="android",
+                connection_type="mock",
+            )
+        ]
+
+    def get_device(self, device_id: str) -> MockDevice:
+        """Get the mock device."""
+        if device_id != self._device_id:
+            raise KeyError(f"Device '{device_id}' not found")
+        return self._device
+
+    def connect(self, address: str, timeout: int = 10) -> tuple[bool, str]:
+        """Mock connect (always succeeds)."""
+        return True, f"Connected to {address}"
+
+    def disconnect(self, device_id: str) -> tuple[bool, str]:
+        """Mock disconnect (always succeeds)."""
+        return True, f"Disconnected from {device_id}"
+
+
+# Verify MockDeviceManager implements DeviceManagerProtocol
+# Same issue as above - can't verify at import time