droidrun 0.3.2__py3-none-any.whl → 0.3.4__py3-none-any.whl

droidrun/macro/__init__.py

@@ -0,0 +1,14 @@
+"""
+DroidRun Macro Module - Record and replay UI automation sequences.
+
+This module provides functionality to replay macro sequences that were
+recorded during DroidAgent execution.
+"""
+
+from .replay import MacroPlayer, replay_macro_file, replay_macro_folder
+
+__all__ = [
+    "MacroPlayer",
+    "replay_macro_file", 
+    "replay_macro_folder"
+] 

droidrun/macro/__main__.py

@@ -0,0 +1,10 @@
+"""
+Entry point for running DroidRun macro CLI as a module.
+
+Usage: python -m droidrun.macro <command>
+"""
+
+from droidrun.macro.cli import macro_cli
+
+if __name__ == "__main__":
+    macro_cli() 

droidrun/macro/cli.py

@@ -0,0 +1,228 @@
+"""
+Command-line interface for DroidRun macro replay.
+"""
+
+import asyncio
+import click
+import logging
+import os
+from typing import Optional
+from rich.console import Console
+from rich.table import Table
+from droidrun.macro.replay import MacroPlayer, replay_macro_file, replay_macro_folder
+from droidrun.agent.utils.trajectory import Trajectory
+from adbutils import adb
+
+console = Console()
+
+
+def configure_logging(debug: bool = False):
+    """Configure logging for the macro CLI."""
+    logger = logging.getLogger("droidrun-macro")
+    logger.handlers = []
+    
+    handler = logging.StreamHandler()
+    
+    if debug:
+        level = logging.DEBUG
+        formatter = logging.Formatter("%(levelname)s %(name)s %(message)s", "%H:%M:%S")
+    else:
+        level = logging.INFO
+        formatter = logging.Formatter("%(message)s", "%H:%M:%S")
+    
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.setLevel(level)
+    logger.propagate = False
+    
+    return logger
+
+
+@click.group()
+def macro_cli():
+    """Replay recorded automation sequences."""
+    pass
+
+
+@macro_cli.command()
+@click.argument("path", type=click.Path(exists=True))
+@click.option("--device", "-d", help="Device serial number", default=None)
+@click.option("--delay", "-t", help="Delay between actions (seconds)", default=1.0, type=float)
+@click.option("--start-from", "-s", help="Start from step number (1-based)", default=1, type=int)
+@click.option("--max-steps", "-m", help="Maximum steps to execute", default=None, type=int)
+@click.option("--debug", is_flag=True, help="Enable debug logging", default=False)
+@click.option("--dry-run", is_flag=True, help="Show actions without executing", default=False)
+def replay(path: str, device: Optional[str], delay: float, start_from: int, max_steps: Optional[int], debug: bool, dry_run: bool):
+    """Replay a macro from a file or trajectory folder."""
+    logger = configure_logging(debug)
+    
+    logger.info("🎬 DroidRun Macro Replay")
+    
+    # Convert start_from from 1-based to 0-based
+    start_from_zero = max(0, start_from - 1)
+    
+    if device is None:
+        logger.info("🔍 Finding connected device...")
+        devices = adb.list()
+        if not devices:
+            raise ValueError("No connected devices found.")
+        device = devices[0].serial
+        logger.info(f"📱 Using device: {device}")
+    else:
+        logger.info(f"📱 Using device: {device}")
+    
+    asyncio.run(_replay_async(path, device, delay, start_from_zero, max_steps, dry_run, logger))
+
+
+async def _replay_async(path: str, device: str, delay: float, start_from: int, max_steps: Optional[int], dry_run: bool, logger: logging.Logger):
+    """Async function to handle macro replay."""
+    try:
+        if os.path.isfile(path):
+            logger.info(f"📄 Loading macro from file: {path}")
+            player = MacroPlayer(device_serial=device, delay_between_actions=delay)
+            macro_data = player.load_macro_from_file(path)
+        elif os.path.isdir(path):
+            logger.info(f"📁 Loading macro from folder: {path}")
+            player = MacroPlayer(device_serial=device, delay_between_actions=delay)
+            macro_data = player.load_macro_from_folder(path)
+        else:
+            logger.error(f"❌ Invalid path: {path}")
+            return
+        
+        if not macro_data:
+            logger.error("❌ Failed to load macro data")
+            return
+        
+        # Show macro information
+        description = macro_data.get("description", "No description")
+        total_actions = macro_data.get("total_actions", 0)
+        version = macro_data.get("version", "unknown")
+        
+        logger.info("📋 Macro Information:")
+        logger.info(f"   Description: {description}")
+        logger.info(f"   Version: {version}")
+        logger.info(f"   Total actions: {total_actions}")
+        logger.info(f"   Device: {device}")
+        logger.info(f"   Delay between actions: {delay}s")
+        
+        if start_from > 0:
+            logger.info(f"   Starting from step: {start_from + 1}")
+        if max_steps:
+            logger.info(f"   Maximum steps: {max_steps}")
+        
+        if dry_run:
+            logger.info("🔍 DRY RUN MODE - Actions will be shown but not executed")
+            await _show_dry_run(macro_data, start_from, max_steps, logger)
+        else:
+            logger.info("▶️  Starting macro replay...")
+            success = await player.replay_macro(macro_data, start_from_step=start_from, max_steps=max_steps)
+            
+            if success:
+                logger.info("🎉 Macro replay completed successfully!")
+            else:
+                logger.error("💥 Macro replay completed with errors")
+    
+    except Exception as e:
+        logger.error(f"💥 Error: {e}")
+        if logger.isEnabledFor(logging.DEBUG):
+            import traceback
+            logger.debug(traceback.format_exc())
+
+
+async def _show_dry_run(macro_data: dict, start_from: int, max_steps: Optional[int], logger: logging.Logger):
+    """Show what actions would be executed in dry run mode."""
+    actions = macro_data.get("actions", [])
+    
+    # Apply filters
+    if start_from > 0:
+        actions = actions[start_from:]
+    if max_steps:
+        actions = actions[:max_steps]
+    
+    logger.info(f"📋 Found {len(actions)} actions to execute:")
+    
+    table = Table(title="Actions to Execute")
+    table.add_column("Step", style="cyan")
+    table.add_column("Type", style="green")
+    table.add_column("Details", style="white")
+    table.add_column("Description", style="yellow")
+    
+    for i, action in enumerate(actions, start=start_from + 1):
+        action_type = action.get("action_type", action.get("type", "unknown"))
+        details = ""
+        
+        if action_type == "tap":
+            x, y = action.get("x", 0), action.get("y", 0)
+            element_text = action.get("element_text", "")
+            details = f"({x}, {y}) - '{element_text}'"
+        elif action_type == "swipe":
+            start_x, start_y = action.get("start_x", 0), action.get("start_y", 0)
+            end_x, end_y = action.get("end_x", 0), action.get("end_y", 0)
+            details = f"({start_x}, {start_y}) → ({end_x}, {end_y})"
+        elif action_type == "input_text":
+            text = action.get("text", "")
+            details = f"'{text}'"
+        elif action_type == "key_press":
+            key_name = action.get("key_name", "UNKNOWN")
+            details = f"{key_name}"
+        
+        description = action.get("description", "")
+        table.add_row(str(i), action_type, details, description[:50] + "..." if len(description) > 50 else description)
+    
+    # Still use console for table display as it's structured data
+    console.print(table)
+
+
+@macro_cli.command()
+@click.argument("directory", type=click.Path(exists=True), default="trajectories")
+@click.option("--debug", is_flag=True, help="Enable debug logging", default=False)
+def list(directory: str, debug: bool):
+    """List available trajectory folders in a directory."""
+    logger = configure_logging(debug)
+    
+    logger.info(f"📁 Scanning directory: {directory}")
+    
+    try:
+        folders = []
+        for item in os.listdir(directory):
+            item_path = os.path.join(directory, item)
+            if os.path.isdir(item_path):
+                macro_file = os.path.join(item_path, "macro.json")
+                if os.path.exists(macro_file):
+                    # Load macro info
+                    try:
+                        macro_data = Trajectory.load_macro_sequence(item_path)
+                        description = macro_data.get("description", "No description")
+                        total_actions = macro_data.get("total_actions", 0)
+                        folders.append((item, description, total_actions))
+                    except Exception as e:
+                        logger.debug(f"Error loading macro from {item}: {e}")
+                        folders.append((item, "Error loading", 0))
+        
+        if not folders:
+            logger.info("📭 No trajectory folders found")
+            return
+        
+        logger.info(f"🎯 Found {len(folders)} trajectory(s):")
+        
+        table = Table(title=f"Available Trajectories in {directory}")
+        table.add_column("Folder", style="cyan")
+        table.add_column("Description", style="white")
+        table.add_column("Actions", style="green")
+        
+        for folder, description, actions in sorted(folders):
+            table.add_row(folder, description[:80] + "..." if len(description) > 80 else description, str(actions))
+        
+        # Still use console for table display as it's structured data
+        console.print(table)
+        logger.info(f"💡 Use 'droidrun macro replay {directory}/<folder>' to replay a trajectory")
+    
+    except Exception as e:
+        logger.error(f"💥 Error: {e}")
+        if logger.isEnabledFor(logging.DEBUG):
+            import traceback
+            logger.debug(traceback.format_exc())
+
+
+if __name__ == "__main__":
+    macro_cli() 

droidrun/macro/replay.py

@@ -0,0 +1,309 @@
+"""
+Macro Replay Module - Replay recorded UI automation sequences.
+
+This module provides functionality to load and replay macro JSON files
+that were generated during DroidAgent trajectory recording.
+"""
+
+import json
+import asyncio
+import logging
+import time
+import os
+from typing import Dict, List, Any, Optional
+from droidrun.tools.adb import AdbTools
+from droidrun.agent.utils.trajectory import Trajectory
+
+logger = logging.getLogger("droidrun-macro")
+
+
+class MacroPlayer:
+    """
+    A class for loading and replaying DroidRun macro sequences.
+
+    This player can execute recorded UI actions (taps, swipes, text input, key presses)
+    on Android devices using AdbTools.
+    """
+
+    def __init__(self, device_serial: str = None, delay_between_actions: float = 1.0):
+        """
+        Initialize the MacroPlayer.
+
+        Args:
+            device_serial: Serial number of the target device. If None, will use first available device.
+            delay_between_actions: Delay in seconds between each action (default: 1.0s)
+        """
+        self.device_serial = device_serial
+        self.delay_between_actions = delay_between_actions
+        self.adb_tools = None
+
+    def _initialize_tools(self) -> AdbTools:
+        """Initialize ADB tools for the target device."""
+        if self.adb_tools is None:
+            self.adb_tools = AdbTools(serial=self.device_serial)
+            logger.info(f"🤖 Initialized ADB tools for device: {self.device_serial}")
+        return self.adb_tools
+
+    def load_macro_from_file(self, macro_file_path: str) -> Dict[str, Any]:
+        """
+        Load macro data from a JSON file.
+
+        Args:
+            macro_file_path: Path to the macro JSON file
+
+        Returns:
+            Dictionary containing the macro data
+        """
+        return Trajectory.load_macro_sequence(macro_file_path)
+
+    def load_macro_from_folder(self, trajectory_folder: str) -> Dict[str, Any]:
+        """
+        Load macro data from a trajectory folder.
+
+        Args:
+            trajectory_folder: Path to the trajectory folder containing macro.json
+
+        Returns:
+            Dictionary containing the macro data
+        """
+        return Trajectory.load_macro_sequence(trajectory_folder)
+
+    def replay_action(self, action: Dict[str, Any]) -> bool:
+        """
+        Replay a single action.
+
+        Args:
+            action: Action dictionary containing type and parameters
+
+        Returns:
+            True if action was executed successfully, False otherwise
+        """
+        tools = self._initialize_tools()
+        action_type = action.get("action_type", action.get("type", "unknown"))
+
+        try:
+
+            if action_type == "start_app":
+                package = action.get("package")
+                activity = action.get("activity", None)
+                tools.start_app(package, activity)
+                return True
+
+            elif action_type == "tap":
+                x = action.get("x", 0)
+                y = action.get("y", 0)
+                element_text = action.get("element_text", "")
+
+                logger.info(f"🫰 Tapping at ({x}, {y}) - Element: '{element_text}'")
+                result = tools.tap_by_coordinates(x, y)
+                logger.debug(f"   Result: {result}")
+                return True
+
+            elif action_type == "swipe":
+                start_x = action.get("start_x", 0)
+                start_y = action.get("start_y", 0)
+                end_x = action.get("end_x", 0)
+                end_y = action.get("end_y", 0)
+                duration_ms = action.get("duration_ms", 300)
+
+                logger.info(
+                    f"👆 Swiping from ({start_x}, {start_y}) to ({end_x}, {end_y}) in {duration_ms} milliseconds"
+                )
+                result = tools.swipe(start_x, start_y, end_x, end_y, duration_ms)
+                logger.debug(f"   Result: {result}")
+                return True
+
+            elif action_type == "drag":
+                start_x = action.get("start_x", 0)
+                start_y = action.get("start_y", 0)
+                end_x = action.get("end_x", 0)
+                end_y = action.get("end_y", 0)
+                duration_ms = action.get("duration_ms", 300)
+
+                logger.info(
+                    f"👆 Dragging from ({start_x}, {start_y}) to ({end_x}, {end_y}) in {duration_ms} milliseconds"
+                )
+                result = tools.drag(start_x, start_y, end_x, end_y, duration_ms)
+                logger.debug(f"   Result: {result}")
+                return True
+
+            elif action_type == "input_text":
+                text = action.get("text", "")
+
+                logger.info(f"⌨️  Inputting text: '{text}'")
+                result = tools.input_text(text)
+                logger.debug(f"   Result: {result}")
+                return True
+
+            elif action_type == "key_press":
+                keycode = action.get("keycode", 0)
+                key_name = action.get("key_name", "UNKNOWN")
+
+                logger.info(f"🔘 Pressing key: {key_name} (keycode: {keycode})")
+                result = tools.press_key(keycode)
+                logger.debug(f"   Result: {result}")
+                return True
+
+            elif action_type == "back":
+                logger.info(f"⬅️  Pressing back button")
+                result = tools.back()
+                logger.debug(f"   Result: {result}")
+                return True
+
+            else:
+                logger.warning(f"⚠️  Unknown action type: {action_type}")
+                return False
+
+        except Exception as e:
+            logger.error(f"❌ Error executing action {action_type}: {e}")
+            return False
+
+    async def replay_macro(
+        self,
+        macro_data: Dict[str, Any],
+        start_from_step: int = 0,
+        max_steps: Optional[int] = None,
+    ) -> bool:
+        """
+        Replay a complete macro sequence.
+
+        Args:
+            macro_data: Macro data dictionary loaded from JSON
+            start_from_step: Step number to start from (0-based, default: 0)
+            max_steps: Maximum number of steps to execute (default: all)
+
+        Returns:
+            True if all actions were executed successfully, False otherwise
+        """
+        if not macro_data or "actions" not in macro_data:
+            logger.error("❌ Invalid macro data - no actions found")
+            return False
+
+        actions = macro_data["actions"]
+        description = macro_data.get("description", "Unknown macro")
+        total_actions = len(actions)
+
+        # Apply start_from_step and max_steps filters
+        if start_from_step > 0:
+            actions = actions[start_from_step:]
+            logger.info(f"📍 Starting from step {start_from_step + 1}")
+
+        if max_steps is not None:
+            actions = actions[:max_steps]
+            logger.info(f"🎯 Limiting to {max_steps} steps")
+
+        logger.info(f"🎬 Starting macro replay: '{description}'")
+        logger.info(f"📊 Total actions to execute: {len(actions)} / {total_actions}")
+
+        success_count = 0
+        failed_count = 0
+
+        for i, action in enumerate(actions, start=start_from_step + 1):
+            action_type = action.get("action_type", action.get("type", "unknown"))
+            description_text = action.get("description", "")
+
+            logger.info(f"\n📍 Step {i}/{total_actions}: {action_type}")
+            if description_text:
+                logger.info(f"   Description: {description_text}")
+
+            # Execute the action
+            success = self.replay_action(action)
+
+            if success:
+                success_count += 1
+                logger.info(f"   ✅ Action completed successfully")
+            else:
+                failed_count += 1
+                logger.error(f"   ❌ Action failed")
+
+            # Wait between actions (except for the last one)
+            if i < len(actions):
+                logger.debug(f"   ⏳ Waiting {self.delay_between_actions}s...")
+                await asyncio.sleep(self.delay_between_actions)
+
+        # Summary
+        total_executed = success_count + failed_count
+        success_rate = (
+            (success_count / total_executed * 100) if total_executed > 0 else 0
+        )
+
+        logger.info(f"\n🎉 Macro replay completed!")
+        logger.info(
+            f"📊 Success: {success_count}/{total_executed} ({success_rate:.1f}%)"
+        )
+
+        if failed_count > 0:
+            logger.warning(f"⚠️  Failed actions: {failed_count}")
+
+        return failed_count == 0
+
+
+# Utility functions for convenience
+
+
+async def replay_macro_file(
+    macro_file_path: str,
+    device_serial: str = None,
+    delay_between_actions: float = 1.0,
+    start_from_step: int = 0,
+    max_steps: Optional[int] = None,
+) -> bool:
+    """
+    Convenience function to replay a macro from a file.
+
+    Args:
+        macro_file_path: Path to the macro JSON file
+        device_serial: Target device serial (optional)
+        delay_between_actions: Delay between actions in seconds
+        start_from_step: Step to start from (0-based)
+        max_steps: Maximum steps to execute
+
+    Returns:
+        True if replay was successful, False otherwise
+    """
+    player = MacroPlayer(
+        device_serial=device_serial, delay_between_actions=delay_between_actions
+    )
+
+    try:
+        macro_data = player.load_macro_from_file(macro_file_path)
+        return await player.replay_macro(
+            macro_data, start_from_step=start_from_step, max_steps=max_steps
+        )
+    except Exception as e:
+        logger.error(f"❌ Error replaying macro file {macro_file_path}: {e}")
+        return False
+
+
+async def replay_macro_folder(
+    trajectory_folder: str,
+    device_serial: str = None,
+    delay_between_actions: float = 1.0,
+    start_from_step: int = 0,
+    max_steps: Optional[int] = None,
+) -> bool:
+    """
+    Convenience function to replay a macro from a trajectory folder.
+
+    Args:
+        trajectory_folder: Path to the trajectory folder containing macro.json
+        device_serial: Target device serial (optional)
+        delay_between_actions: Delay between actions in seconds
+        start_from_step: Step to start from (0-based)
+        max_steps: Maximum steps to execute
+
+    Returns:
+        True if replay was successful, False otherwise
+    """
+    player = MacroPlayer(
+        device_serial=device_serial, delay_between_actions=delay_between_actions
+    )
+
+    try:
+        macro_data = player.load_macro_from_folder(trajectory_folder)
+        return await player.replay_macro(
+            macro_data, start_from_step=start_from_step, max_steps=max_steps
+        )
+    except Exception as e:
+        logger.error(f"❌ Error replaying macro folder {trajectory_folder}: {e}")
+        return False