droidrun 0.1.0__py3-none-any.whl

droidrun/__init__.py

@@ -0,0 +1,19 @@
+"""
+DroidRun - A framework for controlling Android devices through LLM agents.
+"""
+
+__version__ = "0.1.0"
+
+# Import main classes for easier access
+from droidrun.agent.react_agent import ReActAgent as Agent
+from droidrun.agent.react_agent import ReActStep, ReActStepType
+from droidrun.llm import OpenAILLM, AnthropicLLM
+
+# Make main components available at package level
+__all__ = [
+    "Agent",
+    "ReActStep",
+    "ReActStepType",
+    "OpenAILLM",
+    "AnthropicLLM",
+] 

droidrun/__main__.py

@@ -0,0 +1,8 @@
+"""
+DroidRun main entry point
+"""
+
+from droidrun.cli.main import cli
+
+if __name__ == '__main__':
+    cli() 

droidrun/adb/__init__.py

@@ -0,0 +1,13 @@
+"""
+ADB Package - Android Debug Bridge functionality.
+"""
+
+from .device import Device
+from .manager import DeviceManager
+from .wrapper import ADBWrapper
+
+__all__ = [
+    'Device',
+    'DeviceManager',
+    'ADBWrapper',
+] 

droidrun/adb/device.py

@@ -0,0 +1,315 @@
+"""
+Device - High-level representation of an Android device.
+"""
+
+import os
+import tempfile
+import time
+import random
+import string
+from typing import Dict, Optional, Tuple, List
+from .wrapper import ADBWrapper
+
+class Device:
+    """High-level representation of an Android device."""
+
+    def __init__(self, serial: str, adb: ADBWrapper):
+        """Initialize device.
+        
+        Args:
+            serial: Device serial number
+            adb: ADB wrapper instance
+        """
+        self._serial = serial
+        self._adb = adb
+        self._properties_cache: Dict[str, str] = {}
+
+    @property
+    def serial(self) -> str:
+        """Get device serial number."""
+        return self._serial
+
+    async def get_properties(self) -> Dict[str, str]:
+        """Get all device properties."""
+        if not self._properties_cache:
+            self._properties_cache = await self._adb.get_properties(self._serial)
+        return self._properties_cache
+
+    async def get_property(self, name: str) -> str:
+        """Get a specific device property."""
+        props = await self.get_properties()
+        return props.get(name, "")
+
+    @property
+    async def model(self) -> str:
+        """Get device model."""
+        return await self.get_property("ro.product.model")
+
+    @property
+    async def brand(self) -> str:
+        """Get device brand."""
+        return await self.get_property("ro.product.brand")
+
+    @property
+    async def android_version(self) -> str:
+        """Get Android version."""
+        return await self.get_property("ro.build.version.release")
+
+    @property
+    async def sdk_level(self) -> str:
+        """Get SDK level."""
+        return await self.get_property("ro.build.version.sdk")
+
+    async def tap(self, x: int, y: int) -> None:
+        """Tap at coordinates.
+        
+        Args:
+            x: X coordinate
+            y: Y coordinate
+        """
+        await self._adb.shell(self._serial, f"input tap {x} {y}")
+
+    async def swipe(
+        self,
+        start_x: int,
+        start_y: int,
+        end_x: int,
+        end_y: int,
+        duration_ms: int = 300
+    ) -> None:
+        """Perform swipe gesture.
+        
+        Args:
+            start_x: Starting X coordinate
+            start_y: Starting Y coordinate
+            end_x: Ending X coordinate
+            end_y: Ending Y coordinate
+            duration_ms: Swipe duration in milliseconds
+        """
+        await self._adb.shell(
+            self._serial,
+            f"input swipe {start_x} {start_y} {end_x} {end_y} {duration_ms}"
+        )
+
+    async def input_text(self, text: str) -> None:
+        """Input text.
+        
+        Args:
+            text: Text to input
+        """
+        await self._adb.shell(self._serial, f"input text {text}")
+
+    async def press_key(self, keycode: int) -> None:
+        """Press a key.
+        
+        Args:
+            keycode: Android keycode to press
+        """
+        await self._adb.shell(self._serial, f"input keyevent {keycode}")
+
+    async def start_activity(
+        self,
+        package: str,
+        activity: str = ".MainActivity",
+        extras: Optional[Dict[str, str]] = None
+    ) -> None:
+        """Start an app activity.
+        
+        Args:
+            package: Package name
+            activity: Activity name
+            extras: Intent extras
+        """
+        cmd = f"am start -n {package}/{activity}"
+        if extras:
+            for key, value in extras.items():
+                cmd += f" -e {key} {value}"
+        await self._adb.shell(self._serial, cmd)
+        
+    async def start_app(self, package: str, activity: str = "") -> str:
+        """Start an app on the device.
+        
+        Args:
+            package: Package name
+            activity: Optional activity name (if empty, launches default activity)
+            
+        Returns:
+            Result message
+        """
+        if activity:
+            if not activity.startswith(".") and "." not in activity:
+                activity = f".{activity}"
+                
+            if not activity.startswith(".") and "." in activity and not activity.startswith(package):
+                # Fully qualified activity name
+                component = activity.split("/", 1)
+                return await self.start_activity(component[0], component[1] if len(component) > 1 else activity)
+                
+            # Relative activity name
+            return await self.start_activity(package, activity)
+            
+        # Start main activity using monkey
+        cmd = f"monkey -p {package} -c android.intent.category.LAUNCHER 1"
+        result = await self._adb.shell(self._serial, cmd)
+        return f"Started {package}"
+        
+    async def install_app(self, apk_path: str, reinstall: bool = False, grant_permissions: bool = True) -> str:
+        """Install an APK on the device.
+        
+        Args:
+            apk_path: Path to the APK file
+            reinstall: Whether to reinstall if app exists
+            grant_permissions: Whether to grant all requested permissions
+            
+        Returns:
+            Installation result
+        """
+        if not os.path.exists(apk_path):
+            return f"Error: APK file not found: {apk_path}"
+            
+        # Build install command args
+        install_args = ["install"]
+        if reinstall:
+            install_args.append("-r")
+        if grant_permissions:
+            install_args.append("-g")
+        install_args.append(apk_path)
+        
+        try:
+            stdout, stderr = await self._adb._run_device_command(
+                self._serial,
+                install_args,
+                timeout=120  # Longer timeout for installation
+            )
+            
+            if "success" in stdout.lower():
+                return f"Successfully installed {os.path.basename(apk_path)}"
+            return f"Installation failed: {stdout or stderr}"
+            
+        except Exception as e:
+            return f"Installation failed: {str(e)}"
+            
+    async def uninstall_app(self, package: str, keep_data: bool = False) -> str:
+        """Uninstall an app from the device.
+        
+        Args:
+            package: Package name to uninstall
+            keep_data: Whether to keep app data and cache directories
+            
+        Returns:
+            Uninstallation result
+        """
+        cmd = ["pm", "uninstall"]
+        if keep_data:
+            cmd.append("-k")
+        cmd.append(package)
+        
+        result = await self._adb.shell(self._serial, " ".join(cmd))
+        return result.strip()
+        
+    async def take_screenshot(self, quality: int = 75) -> Tuple[str, bytes]:
+        """Take a screenshot of the device and compress it.
+        
+        Args:
+            quality: JPEG quality (1-100, lower means smaller file size)
+        
+        Returns:
+            Tuple of (local file path, screenshot data as bytes)
+        """
+        # Create a temporary file for the screenshot
+        with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as temp:
+            screenshot_path = temp.name
+            
+        try:
+            # Generate a random filename for the device
+            timestamp = int(time.time())
+            random_suffix = "".join(random.choices(string.ascii_lowercase + string.digits, k=8))
+            device_path = f"/sdcard/screenshot_{timestamp}_{random_suffix}.png"
+            
+            # Take screenshot using screencap command
+            await self._adb.shell(self._serial, f"screencap -p {device_path}")
+            
+            # Pull screenshot to local machine
+            await self._adb._run_device_command(
+                self._serial,
+                ["pull", device_path, screenshot_path]
+            )
+            
+            # Clean up on device
+            await self._adb.shell(self._serial, f"rm {device_path}")
+            
+            # Read the screenshot file
+            with open(screenshot_path, "rb") as f:
+                screenshot_data = f.read()
+
+            # Convert and compress the image
+            try:
+                from PIL import Image
+                import io
+
+                # Create buffer for the compressed image
+                buffer = io.BytesIO()
+                
+                # Load the PNG data into a PIL Image
+                with Image.open(io.BytesIO(screenshot_data)) as img:
+                    # Convert to RGB (removing alpha channel if present) and save as JPEG
+                    converted_img = img.convert("RGB") if img.mode == "RGBA" else img
+                    converted_img.save(buffer, format="JPEG", quality=quality, optimize=True)
+                    compressed_data = buffer.getvalue()
+
+                # Get size reduction info for logging
+                png_size = len(screenshot_data) / 1024
+                jpg_size = len(compressed_data) / 1024
+                reduction = 100 - (jpg_size / png_size * 100) if png_size > 0 else 0
+
+                import logging
+                logger = logging.getLogger("droidrun")
+                logger.info(
+                    f"Screenshot compressed successfully: {png_size:.1f}KB → {jpg_size:.1f}KB ({reduction:.1f}% reduction)"
+                )
+
+                return screenshot_path, compressed_data
+            except ImportError:
+                # If PIL is not available, return the original PNG data
+                logger.warning("PIL not available, returning uncompressed screenshot")
+                return screenshot_path, screenshot_data
+            except Exception as e:
+                # If compression fails, return the original PNG data
+                logger.warning(f"Screenshot compression failed: {e}, returning uncompressed")
+                return screenshot_path, screenshot_data
+            
+        except Exception as e:
+            # Clean up in case of error
+            try:
+                os.unlink(screenshot_path)
+            except OSError:
+                pass
+            raise RuntimeError(f"Screenshot capture failed: {str(e)}")
+            
+    async def list_packages(self, include_system_apps: bool = False) -> List[Dict[str, str]]:
+        """List installed packages on the device.
+        
+        Args:
+            include_system_apps: Whether to include system apps
+            
+        Returns:
+            List of package dictionaries with 'package' and 'path' keys
+        """
+        cmd = ["pm", "list", "packages", "-f"]
+        if not include_system_apps:
+            cmd.append("-3")
+            
+        output = await self._adb.shell(self._serial, " ".join(cmd))
+        
+        packages = []
+        for line in output.splitlines():
+            if line.startswith("package:"):
+                parts = line[8:].split("=")
+                if len(parts) == 2:
+                    path, package = parts
+                    packages.append({
+                        "package": package,
+                        "path": path
+                    })
+                    
+        return packages 

droidrun/adb/manager.py

@@ -0,0 +1,93 @@
+"""
+Device Manager - Manages Android device connections.
+"""
+
+from typing import Dict, List, Optional
+from .wrapper import ADBWrapper
+from .device import Device
+
+class DeviceManager:
+    """Manages Android device connections."""
+
+    def __init__(self, adb_path: Optional[str] = None):
+        """Initialize device manager.
+        
+        Args:
+            adb_path: Path to ADB binary
+        """
+        self._adb = ADBWrapper(adb_path)
+        self._devices: Dict[str, Device] = {}
+
+    async def list_devices(self) -> List[Device]:
+        """List connected devices.
+        
+        Returns:
+            List of connected devices
+        """
+        devices_info = await self._adb.get_devices()
+        
+        # Update device cache
+        current_serials = set()
+        for device_info in devices_info:
+            serial = device_info["serial"]
+            current_serials.add(serial)
+            
+            if serial not in self._devices:
+                self._devices[serial] = Device(serial, self._adb)
+                
+        # Remove disconnected devices
+        for serial in list(self._devices.keys()):
+            if serial not in current_serials:
+                del self._devices[serial]
+                
+        return list(self._devices.values())
+
+    async def get_device(self, serial: str) -> Optional[Device]:
+        """Get a specific device.
+        
+        Args:
+            serial: Device serial number
+            
+        Returns:
+            Device instance if found, None otherwise
+        """
+        if serial in self._devices:
+            return self._devices[serial]
+            
+        # Try to find the device
+        devices = await self.list_devices()
+        for device in devices:
+            if device.serial == serial:
+                return device
+                
+        return None
+
+    async def connect(self, host: str, port: int = 5555) -> Optional[Device]:
+        """Connect to a device over TCP/IP.
+        
+        Args:
+            host: Device IP address
+            port: Device port
+            
+        Returns:
+            Connected device instance
+        """
+        try:
+            serial = await self._adb.connect(host, port)
+            return await self.get_device(serial)
+        except Exception:
+            return None
+
+    async def disconnect(self, serial: str) -> bool:
+        """Disconnect from a device.
+        
+        Args:
+            serial: Device serial number
+            
+        Returns:
+            True if disconnected successfully
+        """
+        success = await self._adb.disconnect(serial)
+        if success and serial in self._devices:
+            del self._devices[serial]
+        return success 

droidrun/adb/wrapper.py

@@ -0,0 +1,226 @@
+"""
+ADB Wrapper - Lightweight wrapper around ADB for Android device control.
+"""
+
+import asyncio
+import os
+import shlex
+from typing import Dict, List, Optional, Tuple
+
+class ADBWrapper:
+    """Lightweight wrapper around ADB for Android device control."""
+
+    def __init__(self, adb_path: Optional[str] = None):
+        """Initialize ADB wrapper.
+        
+        Args:
+            adb_path: Path to ADB binary (defaults to 'adb' in PATH)
+        """
+        self.adb_path = adb_path or "adb"
+        self._devices_cache: List[Dict[str, str]] = []
+
+    async def _run_command(
+        self, 
+        args: List[str], 
+        timeout: Optional[float] = None,
+        check: bool = True
+    ) -> Tuple[str, str]:
+        """Run an ADB command.
+        
+        Args:
+            args: Command arguments
+            timeout: Command timeout in seconds
+            check: Whether to check return code
+            
+        Returns:
+            Tuple of (stdout, stderr)
+        """
+        cmd = [self.adb_path, *args]
+        
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+
+            if timeout is not None:
+                stdout_bytes, stderr_bytes = await asyncio.wait_for(
+                    process.communicate(), timeout
+                )
+            else:
+                stdout_bytes, stderr_bytes = await process.communicate()
+
+            stdout = stdout_bytes.decode("utf-8", errors="replace").strip()
+            stderr = stderr_bytes.decode("utf-8", errors="replace").strip()
+
+            if check and process.returncode != 0:
+                raise RuntimeError(f"ADB command failed: {stderr or stdout}")
+
+            return stdout, stderr
+
+        except asyncio.TimeoutError:
+            raise TimeoutError(f"ADB command timed out: {' '.join(cmd)}")
+        except FileNotFoundError:
+            raise FileNotFoundError(f"ADB not found at {self.adb_path}")
+
+    async def _run_device_command(
+        self, 
+        serial: str, 
+        args: List[str], 
+        timeout: Optional[float] = None,
+        check: bool = True
+    ) -> Tuple[str, str]:
+        """Run an ADB command for a specific device."""
+        return await self._run_command(["-s", serial, *args], timeout, check)
+
+    async def get_devices(self) -> List[Dict[str, str]]:
+        """Get list of connected devices.
+        
+        Returns:
+            List of device info dictionaries with 'serial' and 'status' keys
+        """
+        stdout, _ = await self._run_command(["devices", "-l"])
+        
+        devices = []
+        for line in stdout.splitlines()[1:]:  # Skip first line (header)
+            if not line.strip():
+                continue
+                
+            parts = line.split()
+            if not parts:
+                continue
+                
+            serial = parts[0]
+            status = parts[1] if len(parts) > 1 else "unknown"
+            
+            devices.append({
+                "serial": serial,
+                "status": status
+            })
+            
+        self._devices_cache = devices
+        return devices
+
+    async def connect(self, host: str, port: int = 5555) -> str:
+        """Connect to a device over TCP/IP.
+        
+        Args:
+            host: Device IP address
+            port: Device port
+            
+        Returns:
+            Device serial number (host:port)
+        """
+        serial = f"{host}:{port}"
+        
+        # Check if already connected
+        devices = await self.get_devices()
+        if any(d["serial"] == serial for d in devices):
+            return serial
+            
+        stdout, _ = await self._run_command(["connect", serial], timeout=10.0)
+        
+        if "connected" not in stdout.lower():
+            raise RuntimeError(f"Failed to connect: {stdout}")
+            
+        return serial
+
+    async def disconnect(self, serial: str) -> bool:
+        """Disconnect from a device.
+        
+        Args:
+            serial: Device serial number
+            
+        Returns:
+            True if disconnected successfully
+        """
+        try:
+            stdout, _ = await self._run_command(["disconnect", serial])
+            return "disconnected" in stdout.lower()
+        except Exception:
+            return False
+
+    async def shell(self, serial: str, command: str, timeout: Optional[float] = None) -> str:
+        """Run a shell command on the device.
+        
+        Args:
+            serial: Device serial number
+            command: Shell command to run
+            timeout: Command timeout in seconds
+            
+        Returns:
+            Command output
+        """
+        stdout, _ = await self._run_device_command(serial, ["shell", command], timeout=timeout)
+        return stdout
+
+    async def get_properties(self, serial: str) -> Dict[str, str]:
+        """Get device properties.
+        
+        Args:
+            serial: Device serial number
+            
+        Returns:
+            Dictionary of device properties
+        """
+        output = await self.shell(serial, "getprop")
+        
+        properties = {}
+        for line in output.splitlines():
+            if not line or "[" not in line or "]" not in line:
+                continue
+                
+            try:
+                key = line.split("[")[1].split("]")[0]
+                value = line.split("[")[2].split("]")[0]
+                properties[key] = value
+            except IndexError:
+                continue
+                
+        return properties
+        
+    async def install_app(
+        self, 
+        serial: str, 
+        apk_path: str, 
+        reinstall: bool = False, 
+        grant_permissions: bool = True
+    ) -> Tuple[str, str]:
+        """Install an APK on the device.
+        
+        Args:
+            serial: Device serial number
+            apk_path: Path to the APK file
+            reinstall: Whether to reinstall if app exists
+            grant_permissions: Whether to grant all permissions
+            
+        Returns:
+            Tuple of (stdout, stderr)
+        """
+        args = ["install"]
+        if reinstall:
+            args.append("-r")
+        if grant_permissions:
+            args.append("-g")
+        args.append(apk_path)
+        
+        return await self._run_device_command(serial, args, timeout=120.0)
+        
+    async def pull_file(self, serial: str, device_path: str, local_path: str) -> Tuple[str, str]:
+        """Pull a file from the device.
+        
+        Args:
+            serial: Device serial number
+            device_path: Path on the device
+            local_path: Path on the local machine
+            
+        Returns:
+            Tuple of (stdout, stderr)
+        """
+        # Create directory if it doesn't exist
+        local_dir = os.path.dirname(local_path)
+        if local_dir and not os.path.exists(local_dir):
+            os.makedirs(local_dir)
+            
+        return await self._run_device_command(serial, ["pull", device_path, local_path], timeout=60.0) 

droidrun/agent/__init__.py

@@ -0,0 +1,16 @@
+"""
+Droidrun Agent Module.
+
+This module provides a ReAct agent for automating Android devices using reasoning and acting.
+"""
+
+from .react_agent import ReActAgent, ReActStep, ReActStepType, run_agent
+from .llm_reasoning import LLMReasoner
+
+__all__ = [
+    "ReActAgent",
+    "ReActStep",
+    "ReActStepType",
+    "run_agent",
+    "LLMReasoner",
+]