droidrun 0.1.0__py3-none-any.whl

droidrun/tools/device.py

@@ -0,0 +1,29 @@
+"""
+Device Manager - Handles Android device connections and management.
+"""
+
+from typing import Optional, List
+from droidrun.adb import Device, DeviceManager as ADBDeviceManager
+
+class DeviceManager:
+    """Manages Android device connections and operations."""
+    
+    def __init__(self):
+        """Initialize the device manager."""
+        self._manager = ADBDeviceManager()
+        
+    async def connect(self, ip_address: str, port: int = 5555) -> Optional[Device]:
+        """Connect to an Android device over TCP/IP."""
+        return await self._manager.connect(ip_address, port)
+        
+    async def disconnect(self, serial: str) -> bool:
+        """Disconnect from an Android device."""
+        return await self._manager.disconnect(serial)
+        
+    async def list_devices(self) -> List[Device]:
+        """List all connected devices."""
+        return await self._manager.list_devices()
+        
+    async def get_device(self, serial: str) -> Optional[Device]:
+        """Get a specific device by serial number."""
+        return await self._manager.get_device(serial)

droidrun-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,20 @@
+droidrun/__init__.py,sha256=DPbx6xuxtowuPuPnfWH-XnksAWxxvG4b4cPbqxtlhB8,472
+droidrun/__main__.py,sha256=BOXhRBIDmfRJ4LKm3fw4ZNAT6L_IGP0EC4uU-WI_QVU,107
+droidrun/adb/__init__.py,sha256=tBhoSFmkevb_xQcCfdrigPut9zAU1J4bagpT-TgBj8c,221
+droidrun/adb/device.py,sha256=4dvK2oN-lyaXElBvqVHCeCX2ZLRZl3o4y6z2vy05enk,10991
+droidrun/adb/manager.py,sha256=9xohDCbw8XvWW2Esglpcnk9H24hKJG3e9SkCBiFWlDI,2704
+droidrun/adb/wrapper.py,sha256=Yz3_JSIidq-5bf-t0UfawTutMaLrINS_1Y15m_Uss4g,7093
+droidrun/agent/__init__.py,sha256=BWfZFZPBJeWMCaZEv7A_EDnEa2ibWDcqWnl_Z8NxNMA,346
+droidrun/agent/llm_reasoning.py,sha256=POCszMmr-bn2aKG8Cduk4BIZCO38ZytIDLyLMP2cXwk,24383
+droidrun/agent/react_agent.py,sha256=Nx3Qc4E8h_IHn5fwNQblmslEMaJD6nciehjcQ2dmVnQ,20857
+droidrun/cli/__init__.py,sha256=ra9bKoHTIkgRsVFRlWztROPPRswMv_A-wc2b2e0plmo,155
+droidrun/cli/main.py,sha256=phd8UEKOYdS8OYcX1d6iLwd-afez1ueatjLBAvbOS8U,10920
+droidrun/llm/__init__.py,sha256=5v6Bw0904ihmyvFPgDwd8hROUVjWz3Re5JDOQfziIMY,687
+droidrun/tools/__init__.py,sha256=vKcI1qP8yzdq3mNQ53EFgBJILikQz3GDPZJyoxnDOa0,569
+droidrun/tools/actions.py,sha256=GC4hVXw-OjENphDahGEHKKbRAIONxPtMBFZEUAmS4ms,32963
+droidrun/tools/device.py,sha256=5y2FAfhJIRksb40HGo6ENe9krozz0MwFykaoclLZw5Y,1085
+droidrun-0.1.0.dist-info/METADATA,sha256=UIZUdp3fZg7fweI1Or1zoUZu-k-T9VgbvDv25IXO8wI,8450
+droidrun-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+droidrun-0.1.0.dist-info/entry_points.txt,sha256=o259U66js8TIybQ7zs814Oe_LQ_GpZsp6a9Cr-xm5zE,51
+droidrun-0.1.0.dist-info/licenses/LICENSE,sha256=s-uxn9qChu-kFdRXUp6v_0HhsaJ_5OANmfNOFVm2zdk,1069
+droidrun-0.1.0.dist-info/RECORD,,

droidrun-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

droidrun-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+droidrun = droidrun.cli.main:cli

droidrun-0.1.0.dist-info/licenses/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.