droidrun 0.1.0__tar.gz

droidrun-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+dist/
+# Python bytecode files
+__pycache__/
+*.py[cod]
+*$py.class

droidrun-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Niels Schmidt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

droidrun-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE
+include README.md
+include pyproject.toml
+
+recursive-include droidrun *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[cod] 

droidrun-0.1.0/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: droidrun
+Version: 0.1.0
+Summary: A framework for controlling Android devices through LLM agents
+Project-URL: Homepage, https://github.com/droidrun/droidrun
+Project-URL: Bug Tracker, https://github.com/droidrun/droidrun/issues
+Project-URL: Documentation, https://docs.droidrun.ai/
+Author-email: Niels Schmidt <niels.schmidt@droidrun.ai>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Testing :: Acceptance
+Classifier: Topic :: System :: Emulators
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: aiofiles>=23.0.0
+Requires-Dist: anthropic>=0.7.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 🤖 DroidRun
+
+DroidRun is a powerful framework for controlling Android devices through LLM agents. It allows you to automate Android device interactions using natural language commands.
+
+## ✨ Features
+
+- Control Android devices with natural language commands
+- Supports multiple LLM providers (OpenAI, Anthropic, Gemini)
+- Easy to use CLI
+- Extendable Python API for custom automations
+- Screenshot analysis for visual understanding of the device
+
+## 📦 Installation
+
+### 🚀 Option 1: Install from PyPI (Recommended)
+
+```bash
+pip install droidrun
+```
+
+### 🔧 Option 2: Install from Source
+
+```bash
+git clone https://github.com/yourusername/droidrun.git
+cd droidrun
+pip install -e .
+```
+
+## 📋 Prerequisites
+
+1. An Android device connected via USB or ADB over TCP/IP
+2. ADB (Android Debug Bridge) installed and configured
+3. DroidRun Portal app installed on your Android device
+4. API key for at least one of the supported LLM providers:
+   - OpenAI
+   - Anthropic
+   - Google Gemini
+
+### 🔧 Setting up ADB
+
+ADB (Android Debug Bridge) is required for DroidRun to communicate with your Android device:
+
+1. **Install ADB**:
+   - **Windows**: Download [Android SDK Platform Tools](https://developer.android.com/studio/releases/platform-tools) and extract the ZIP file
+   - **macOS**: `brew install android-platform-tools`
+   - **Linux**: `sudo apt install adb` (Ubuntu/Debian) or `sudo pacman -S android-tools` (Arch)
+
+2. **Add ADB to your PATH**:
+   - **Windows**: Add the path to the extracted platform-tools folder to your system's PATH environment variable
+   - **macOS/Linux**: Add the following to your ~/.bashrc or ~/.zshrc:
+     ```bash
+     export PATH=$PATH:/path/to/platform-tools
+     ```
+
+3. **Verify ADB installation**:
+   ```bash
+   adb version
+   ```
+
+4. **Enable USB debugging on your Android device**:
+   - Go to **Settings → About phone**
+   - Tap **Build number** 7 times to enable Developer options
+   - Go to **Settings → System → Developer options** (location may vary by device)
+   - Enable **USB debugging**
+
+## 🛠️ Setup
+
+### 📱 1. Install DroidRun Portal App
+
+DroidRun requires the DroidRun Portal app to be installed on your Android device:
+
+1. Download the DroidRun Portal APK from the [DroidRun Portal repository](https://github.com/droidrun/droidrun-portal)
+2. Use DroidRun to install the portal app:
+   ```bash
+   droidrun setup --path=/path/to/droidrun-portal.apk
+   ```
+
+Alternatively, you can use ADB to install it manually:
+```bash
+adb install -r /path/to/droidrun-portal.apk
+```
+
+### 🔑 2. Set up API keys
+
+Create a `.env` file in your working directory or set environment variables:
+
+```bash
+# Choose at least one of these based on your preferred provider
+export OPENAI_API_KEY="your_openai_api_key_here"
+export ANTHROPIC_API_KEY="your_anthropic_api_key_here"
+export GEMINI_API_KEY="your_gemini_api_key_here"
+```
+
+To load the environment variables from the `.env` file:
+
+```bash
+source .env
+```
+
+### 📱 3. Connect to an Android device
+
+Connect your device via USB or set up wireless ADB:
+
+```bash
+# List connected devices
+droidrun devices
+
+# Connect to a device over Wi-Fi
+droidrun connect 192.168.1.100
+```
+
+### 🔄 4. Verify the setup
+
+Verify that everything is set up correctly:
+
+```bash
+# Should list your connected device and show portal status
+droidrun status
+```
+
+## 💻 Using the CLI
+
+DroidRun's CLI is designed to be simple and intuitive. You can use it in two ways:
+
+### 🚀 Basic Usage
+
+```bash
+# Format: droidrun "task description" [options]
+droidrun "Open the settings app"
+```
+
+### 🔌 With Provider Options
+
+```bash
+# Using OpenAI
+droidrun "Open the calculator app" --provider openai --model gpt-4o-mini
+
+# Using Anthropic
+droidrun "Check the battery level" --provider anthropic --model claude-3-sonnet-20240229
+
+# Using Gemini
+droidrun "Install and open Instagram" --provider gemini --model gemini-2.0-flash
+```
+
+### ⚙️ Additional Options
+
+```bash
+# Specify a particular device
+droidrun "Open Chrome and search for weather" --device abc123
+
+# Set maximum number of steps
+droidrun "Open settings and enable dark mode" --steps 20
+```
+
+## 📝 Creating a Minimal Test Script
+
+If you want to use DroidRun in your Python code rather than via the CLI, you can create a minimal test script:
+
+```python
+#!/usr/bin/env python3
+import asyncio
+import os
+from droidrun.agent.react_agent import ReActAgent
+from droidrun.agent.llm_reasoning import LLMReasoner
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+async def main():
+    # Create an LLM instance (choose your preferred provider)
+    llm = LLMReasoner(
+        llm_provider="gemini",  # Can be "openai", "anthropic", or "gemini"
+        model_name="gemini-2.0-flash",  # Choose appropriate model for your provider
+        api_key=os.environ.get("GEMINI_API_KEY"),  # Get API key from environment
+        temperature=0.2
+    )
+    
+    # Create and run the agent
+    agent = ReActAgent(
+        task="Open the Settings app and check the Android version",
+        llm=llm
+    )
+    
+    steps = await agent.run()
+    print(f"Execution completed with {len(steps)} steps")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Save this as `test_droidrun.py`, ensure your `.env` file has the appropriate API key, and run:
+
+```bash
+python test_droidrun.py
+```
+
+## ❓ Troubleshooting
+
+### 🔑 API Key Issues
+
+If you encounter errors about missing API keys, ensure:
+1. You've set the correct environment variable for your chosen provider
+2. The API key is valid and has appropriate permissions
+3. You've correctly sourced your `.env` file or exported the variables manually
+
+### 📱 Device Connection Issues
+
+If you have trouble connecting to your device:
+1. Ensure USB debugging is enabled on your Android device
+2. Check that your device is recognized by ADB: `adb devices`
+3. For wireless connections, make sure your device and computer are on the same network
+
+### 🤖 LLM Provider Selection
+
+If DroidRun is using the wrong LLM provider:
+1. Explicitly specify the provider with `--provider` (in CLI) or `llm_provider=` (in code)
+2. When using Gemini, ensure you have set `GEMINI_API_KEY` and specified `--provider gemini`
+
+## 💡 Example Use Cases
+
+- Automated UI testing of Android applications
+- Creating guided workflows for non-technical users
+- Automating repetitive tasks on Android devices
+- Remote assistance for less technical users
+- Exploring Android UI with natural language commands
+
+## 👥 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details. 

droidrun-0.1.0/README.md

@@ -0,0 +1,234 @@
+# 🤖 DroidRun
+
+DroidRun is a powerful framework for controlling Android devices through LLM agents. It allows you to automate Android device interactions using natural language commands.
+
+## ✨ Features
+
+- Control Android devices with natural language commands
+- Supports multiple LLM providers (OpenAI, Anthropic, Gemini)
+- Easy to use CLI
+- Extendable Python API for custom automations
+- Screenshot analysis for visual understanding of the device
+
+## 📦 Installation
+
+### 🚀 Option 1: Install from PyPI (Recommended)
+
+```bash
+pip install droidrun
+```
+
+### 🔧 Option 2: Install from Source
+
+```bash
+git clone https://github.com/yourusername/droidrun.git
+cd droidrun
+pip install -e .
+```
+
+## 📋 Prerequisites
+
+1. An Android device connected via USB or ADB over TCP/IP
+2. ADB (Android Debug Bridge) installed and configured
+3. DroidRun Portal app installed on your Android device
+4. API key for at least one of the supported LLM providers:
+   - OpenAI
+   - Anthropic
+   - Google Gemini
+
+### 🔧 Setting up ADB
+
+ADB (Android Debug Bridge) is required for DroidRun to communicate with your Android device:
+
+1. **Install ADB**:
+   - **Windows**: Download [Android SDK Platform Tools](https://developer.android.com/studio/releases/platform-tools) and extract the ZIP file
+   - **macOS**: `brew install android-platform-tools`
+   - **Linux**: `sudo apt install adb` (Ubuntu/Debian) or `sudo pacman -S android-tools` (Arch)
+
+2. **Add ADB to your PATH**:
+   - **Windows**: Add the path to the extracted platform-tools folder to your system's PATH environment variable
+   - **macOS/Linux**: Add the following to your ~/.bashrc or ~/.zshrc:
+     ```bash
+     export PATH=$PATH:/path/to/platform-tools
+     ```
+
+3. **Verify ADB installation**:
+   ```bash
+   adb version
+   ```
+
+4. **Enable USB debugging on your Android device**:
+   - Go to **Settings → About phone**
+   - Tap **Build number** 7 times to enable Developer options
+   - Go to **Settings → System → Developer options** (location may vary by device)
+   - Enable **USB debugging**
+
+## 🛠️ Setup
+
+### 📱 1. Install DroidRun Portal App
+
+DroidRun requires the DroidRun Portal app to be installed on your Android device:
+
+1. Download the DroidRun Portal APK from the [DroidRun Portal repository](https://github.com/droidrun/droidrun-portal)
+2. Use DroidRun to install the portal app:
+   ```bash
+   droidrun setup --path=/path/to/droidrun-portal.apk
+   ```
+
+Alternatively, you can use ADB to install it manually:
+```bash
+adb install -r /path/to/droidrun-portal.apk
+```
+
+### 🔑 2. Set up API keys
+
+Create a `.env` file in your working directory or set environment variables:
+
+```bash
+# Choose at least one of these based on your preferred provider
+export OPENAI_API_KEY="your_openai_api_key_here"
+export ANTHROPIC_API_KEY="your_anthropic_api_key_here"
+export GEMINI_API_KEY="your_gemini_api_key_here"
+```
+
+To load the environment variables from the `.env` file:
+
+```bash
+source .env
+```
+
+### 📱 3. Connect to an Android device
+
+Connect your device via USB or set up wireless ADB:
+
+```bash
+# List connected devices
+droidrun devices
+
+# Connect to a device over Wi-Fi
+droidrun connect 192.168.1.100
+```
+
+### 🔄 4. Verify the setup
+
+Verify that everything is set up correctly:
+
+```bash
+# Should list your connected device and show portal status
+droidrun status
+```
+
+## 💻 Using the CLI
+
+DroidRun's CLI is designed to be simple and intuitive. You can use it in two ways:
+
+### 🚀 Basic Usage
+
+```bash
+# Format: droidrun "task description" [options]
+droidrun "Open the settings app"
+```
+
+### 🔌 With Provider Options
+
+```bash
+# Using OpenAI
+droidrun "Open the calculator app" --provider openai --model gpt-4o-mini
+
+# Using Anthropic
+droidrun "Check the battery level" --provider anthropic --model claude-3-sonnet-20240229
+
+# Using Gemini
+droidrun "Install and open Instagram" --provider gemini --model gemini-2.0-flash
+```
+
+### ⚙️ Additional Options
+
+```bash
+# Specify a particular device
+droidrun "Open Chrome and search for weather" --device abc123
+
+# Set maximum number of steps
+droidrun "Open settings and enable dark mode" --steps 20
+```
+
+## 📝 Creating a Minimal Test Script
+
+If you want to use DroidRun in your Python code rather than via the CLI, you can create a minimal test script:
+
+```python
+#!/usr/bin/env python3
+import asyncio
+import os
+from droidrun.agent.react_agent import ReActAgent
+from droidrun.agent.llm_reasoning import LLMReasoner
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+async def main():
+    # Create an LLM instance (choose your preferred provider)
+    llm = LLMReasoner(
+        llm_provider="gemini",  # Can be "openai", "anthropic", or "gemini"
+        model_name="gemini-2.0-flash",  # Choose appropriate model for your provider
+        api_key=os.environ.get("GEMINI_API_KEY"),  # Get API key from environment
+        temperature=0.2
+    )
+    
+    # Create and run the agent
+    agent = ReActAgent(
+        task="Open the Settings app and check the Android version",
+        llm=llm
+    )
+    
+    steps = await agent.run()
+    print(f"Execution completed with {len(steps)} steps")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+Save this as `test_droidrun.py`, ensure your `.env` file has the appropriate API key, and run:
+
+```bash
+python test_droidrun.py
+```
+
+## ❓ Troubleshooting
+
+### 🔑 API Key Issues
+
+If you encounter errors about missing API keys, ensure:
+1. You've set the correct environment variable for your chosen provider
+2. The API key is valid and has appropriate permissions
+3. You've correctly sourced your `.env` file or exported the variables manually
+
+### 📱 Device Connection Issues
+
+If you have trouble connecting to your device:
+1. Ensure USB debugging is enabled on your Android device
+2. Check that your device is recognized by ADB: `adb devices`
+3. For wireless connections, make sure your device and computer are on the same network
+
+### 🤖 LLM Provider Selection
+
+If DroidRun is using the wrong LLM provider:
+1. Explicitly specify the provider with `--provider` (in CLI) or `llm_provider=` (in code)
+2. When using Gemini, ensure you have set `GEMINI_API_KEY` and specified `--provider gemini`
+
+## 💡 Example Use Cases
+
+- Automated UI testing of Android applications
+- Creating guided workflows for non-technical users
+- Automating repetitive tasks on Android devices
+- Remote assistance for less technical users
+- Exploring Android UI with natural language commands
+
+## 👥 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details. 

droidrun-0.1.0/docs/concepts/agent.mdx

@@ -0,0 +1,141 @@
+---
+title: 'ReAct Agent'
+description: 'Understanding the ReAct Agent system in DroidRun'
+---
+
+# 🤖 ReAct Agent
+
+DroidRun uses a ReAct (Reasoning + Acting) agent to control Android devices. This powerful approach combines LLM reasoning with concrete actions to achieve complex automation tasks.
+
+## 📚 What is ReAct?
+
+ReAct is a framework that combines:
+
+- **Reasoning**: Using an LLM to interpret tasks, make decisions, and plan steps
+- **Acting**: Executing concrete actions on an Android device
+- **Observing**: Getting feedback from actions to inform future reasoning
+
+This loop of reasoning, acting, and observing allows the agent to handle complex, multi-step tasks on Android devices.
+
+## 🔄 The ReAct Loop
+
+<Steps>
+  <Step title="Goal Setting">
+    The user provides a natural language task like "Open settings and enable dark mode"
+  </Step>
+  <Step title="Reasoning">
+    The LLM analyzes the task and determines what steps are needed
+  </Step>
+  <Step title="Action Selection">
+    The agent selects an appropriate action (e.g., tapping a UI element)
+  </Step>
+  <Step title="Execution">
+    The action is executed on the Android device
+  </Step>
+  <Step title="Observation">
+    The agent observes the result (e.g., a new screen appears)
+  </Step>
+  <Step title="Further Reasoning">
+    The agent evaluates progress and decides on the next action
+  </Step>
+</Steps>
+
+This cycle repeats until the task is completed or the maximum number of steps is reached.
+
+## 🛠️ Available Actions
+
+The ReAct agent can perform various actions on Android devices:
+
+<AccordionGroup>
+  <Accordion title="UI Interaction">
+    - `tap(index)` - Tap on a UI element by its index
+    - `swipe(start_x, start_y, end_x, end_y)` - Swipe from one point to another
+    - `input_text(text)` - Type text into the current field
+    - `press_key(keycode)` - Press a specific key (e.g., HOME, BACK)
+  </Accordion>
+
+  <Accordion title="App Management">
+    - `start_app(package)` - Launch an app by package name
+    - `list_packages()` - List installed packages
+    - `install_app(apk_path)` - Install an app from APK
+    - `uninstall_app(package)` - Uninstall an app
+  </Accordion>
+
+  <Accordion title="UI Analysis">
+    - `take_screenshot()` - Capture the current screen (vision mode only)
+    - `get_clickables()` - Identify clickable elements on screen
+    - `extract(filename)` - Save complete UI state to a JSON file
+  </Accordion>
+
+  <Accordion title="Task Management">
+    - `complete(result)` - Mark the task as complete with a summary
+  </Accordion>
+</AccordionGroup>
+
+## 📸 Vision Capabilities
+
+When vision mode is enabled, the ReAct agent can analyze screenshots to better understand the UI:
+
+```python
+agent = ReActAgent(
+    task="Open settings and enable dark mode",
+    llm=llm_instance,
+    vision=True  # Enable vision capabilities
+)
+```
+
+This provides several benefits:
+
+- **Visual Context**: The LLM can see exactly what's on screen
+- **Better UI Understanding**: Recognizes UI elements even if text detection is imperfect
+- **Complex Navigation**: Handles apps with unusual or complex interfaces more effectively
+
+## 📊 Token Usage Tracking
+
+The ReAct agent now tracks token usage for all LLM interactions:
+
+```python
+# After running the agent
+stats = llm.get_token_usage_stats()
+print(f"Total tokens: {stats['total_tokens']}")
+print(f"API calls: {stats['api_calls']}")
+```
+
+This information is useful for:
+
+- **Cost Management**: Track and optimize your API usage costs
+- **Performance Tuning**: Identify steps that require the most tokens
+- **Troubleshooting**: Debug issues with prompt sizes or response lengths
+
+## 🧠 Agent Parameters
+
+When creating a ReAct agent, you can configure several parameters:
+
+```python
+agent = ReActAgent(
+    task="Open settings and enable dark mode",  # The goal to achieve
+    llm=llm_instance,                           # LLM to use for reasoning
+    device_serial="DEVICE123",                  # Optional specific device
+    max_steps=15,                               # Maximum steps to attempt
+    vision=False                                # Whether to enable vision capabilities
+)
+```
+
+## 📊 Step Types
+
+The agent records its progress using different step types:
+
+- **Thought**: Internal reasoning about what to do
+- **Action**: An action to be executed on the device
+- **Observation**: Result of an action
+- **Plan**: A sequence of steps to achieve the goal
+- **Goal**: The target state to achieve
+
+## 💡 Best Practices
+
+1. **Clear Goals**: Provide specific, clear instructions
+2. **Realistic Tasks**: Break complex automation into manageable tasks
+3. **Vision for Complex UIs**: Enable vision mode for complex UI navigation
+4. **Step Limits**: Set reasonable max_steps to prevent infinite loops
+5. **Device Connectivity**: Ensure stable connection to your device
+6. **Token Optimization**: Monitor token usage for cost-effective automation