droidrun 0.3.1__tar.gz → 0.3.2__tar.gz

{droidrun-0.3.1 → droidrun-0.3.2}/.gitignore

@@ -1,4 +1,5 @@
 dist/
+build/
 # Python bytecode files
 __pycache__/
 *.py[cod]

{droidrun-0.3.1 → droidrun-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: droidrun
-Version: 0.3.1
+Version: 0.3.2
 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
@@ -40,6 +40,7 @@ Requires-Dist: llama-index-llms-openai
 Requires-Dist: llama-index-llms-openai-like
 Requires-Dist: openai>=1.0.0
 Requires-Dist: pillow>=10.0.0
+Requires-Dist: posthog==6.0.2
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: rich>=13.0.0
@@ -67,6 +68,8 @@ Description-Content-Type: text/markdown
 
 DroidRun is a powerful framework for controlling Android and iOS devices through LLM agents. It allows you to automate device interactions using natural language commands. [Checkout our benchmark results](https://droidrun.ai/benchmark)
 
+## Why Droidrun?
+
 - 🤖 Control Android and iOS devices with natural language commands
 - 🔀 Supports multiple LLM providers (OpenAI, Anthropic, Gemini, Ollama, DeepSeek)
 - 🧠 Planning capabilities for complex multi-step tasks
@@ -82,22 +85,24 @@ pip install droidrun
 ```
 
 ## 🚀 Quickstart
-Read on how to get droidrun up and running within seconds in [our docs](https://docs.droidrun.ai/v3/quickstart)!
+Read on how to get droidrun up and running within seconds in [our docs](https://docs.droidrun.ai/v3/quickstart)!   
 
+[![Quickstart Video](https://img.youtube.com/vi/4WT7FXJah2I/0.jpg)](https://www.youtube.com/watch?v=4WT7FXJah2I)
 
 ## 🎬 Demo Videos
 
-1. **Shopping Assistant**: Watch how DroidRun searches Amazon for headphones and sends the top 3 products to a colleague on WhatsApp.
-   
-   Prompt: "Go to Amazon, search for headphones and write the top 3 products to my colleague on WhatsApp."
-   
-   [![Shopping Assistant Demo](https://img.youtube.com/vi/VQK3JcifgwU/0.jpg)](https://www.youtube.com/watch?v=VQK3JcifgwU)
+1. **Group Chat Summarization**: Let DroidRun summarize an escalated group chat for you.   
+
+   [![Group Chat Summarizer](https://img.youtube.com/vi/ofEnSUHHxX8/0.jpg)](https://www.youtube.com/watch?v=ofEnSUHHxX8)
+
+2. **Travel Search Assistant**: Wittness DroidRun looking for the cheapest stay and share it with a colleague on telegram.    
+
+   [![Travel Search Assistant](https://img.youtube.com/vi/QgtRaLS3NBM/0.jpg)](https://www.youtube.com/watch?v=QgtRaLS3NBM)
+
+3. **Automate TikTok Shopping**: See how DroidRun looks for a stanley cup on TikTok Shop and send the product details via email.    
+
+    [![TikTok Shopping Assistant](https://img.youtube.com/vi/ol3bivBAmn4/0.jpg)](https://www.youtube.com/watch?v=ol3bivBAmn4)
 
-2. **Social Media Automation**: See DroidRun open X (Twitter) and post "Hello World".
-   
-   Prompt: "Open up X and post Hello World."
-   
-   [![Social Media Automation Demo](https://img.youtube.com/vi/i4-sDQhzt_M/0.jpg)](https://www.youtube.com/watch?v=i4-sDQhzt_M)
 
 ## 💡 Example Use Cases
 
@@ -107,22 +112,6 @@ Read on how to get droidrun up and running within seconds in [our docs](https://
 - Remote assistance for less technical users
 - Exploring mobile UI with natural language commands
 
-## 🗺️ Roadmap
-
-### 🤖 Agent:
-- **Improve memory**: Enhance context retention for complex multi-step tasks
-- **Expand planning capabilities**: Add support for more complex reasoning strategies
-- **Add Integrations**: Support more LLM providers and agent frameworks (LangChain, Agno etc.)
-
-### ⚙️ Automations:
-- **Create Automation Scripts**: Generate reusable scripts from agent actions that can be scheduled or shared
-
-### ☁️ Cloud:
-- **Hosted version**: Remote device control via web interface without local setup
-- **Add-Ons**: Marketplace for extensions serving specific use cases
-- **Proxy Hours**: Cloud compute time with tiered pricing for running automations
-- **Droidrun AppStore**: Simple installation of Apps on your hosted devices
-
 ## 👥 Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.

{droidrun-0.3.1 → droidrun-0.3.2}/README.md

@@ -14,6 +14,8 @@
 
 DroidRun is a powerful framework for controlling Android and iOS devices through LLM agents. It allows you to automate device interactions using natural language commands. [Checkout our benchmark results](https://droidrun.ai/benchmark)
 
+## Why Droidrun?
+
 - 🤖 Control Android and iOS devices with natural language commands
 - 🔀 Supports multiple LLM providers (OpenAI, Anthropic, Gemini, Ollama, DeepSeek)
 - 🧠 Planning capabilities for complex multi-step tasks
@@ -29,22 +31,24 @@ pip install droidrun
 ```
 
 ## 🚀 Quickstart
-Read on how to get droidrun up and running within seconds in [our docs](https://docs.droidrun.ai/v3/quickstart)!
+Read on how to get droidrun up and running within seconds in [our docs](https://docs.droidrun.ai/v3/quickstart)!   
 
+[![Quickstart Video](https://img.youtube.com/vi/4WT7FXJah2I/0.jpg)](https://www.youtube.com/watch?v=4WT7FXJah2I)
 
 ## 🎬 Demo Videos
 
-1. **Shopping Assistant**: Watch how DroidRun searches Amazon for headphones and sends the top 3 products to a colleague on WhatsApp.
-   
-   Prompt: "Go to Amazon, search for headphones and write the top 3 products to my colleague on WhatsApp."
-   
-   [![Shopping Assistant Demo](https://img.youtube.com/vi/VQK3JcifgwU/0.jpg)](https://www.youtube.com/watch?v=VQK3JcifgwU)
+1. **Group Chat Summarization**: Let DroidRun summarize an escalated group chat for you.   
+
+   [![Group Chat Summarizer](https://img.youtube.com/vi/ofEnSUHHxX8/0.jpg)](https://www.youtube.com/watch?v=ofEnSUHHxX8)
+
+2. **Travel Search Assistant**: Wittness DroidRun looking for the cheapest stay and share it with a colleague on telegram.    
+
+   [![Travel Search Assistant](https://img.youtube.com/vi/QgtRaLS3NBM/0.jpg)](https://www.youtube.com/watch?v=QgtRaLS3NBM)
+
+3. **Automate TikTok Shopping**: See how DroidRun looks for a stanley cup on TikTok Shop and send the product details via email.    
+
+    [![TikTok Shopping Assistant](https://img.youtube.com/vi/ol3bivBAmn4/0.jpg)](https://www.youtube.com/watch?v=ol3bivBAmn4)
 
-2. **Social Media Automation**: See DroidRun open X (Twitter) and post "Hello World".
-   
-   Prompt: "Open up X and post Hello World."
-   
-   [![Social Media Automation Demo](https://img.youtube.com/vi/i4-sDQhzt_M/0.jpg)](https://www.youtube.com/watch?v=i4-sDQhzt_M)
 
 ## 💡 Example Use Cases
 
@@ -54,22 +58,6 @@ Read on how to get droidrun up and running within seconds in [our docs](https://
 - Remote assistance for less technical users
 - Exploring mobile UI with natural language commands
 
-## 🗺️ Roadmap
-
-### 🤖 Agent:
-- **Improve memory**: Enhance context retention for complex multi-step tasks
-- **Expand planning capabilities**: Add support for more complex reasoning strategies
-- **Add Integrations**: Support more LLM providers and agent frameworks (LangChain, Agno etc.)
-
-### ⚙️ Automations:
-- **Create Automation Scripts**: Generate reusable scripts from agent actions that can be scheduled or shared
-
-### ☁️ Cloud:
-- **Hosted version**: Remote device control via web interface without local setup
-- **Add-Ons**: Marketplace for extensions serving specific use cases
-- **Proxy Hours**: Cloud compute time with tiered pricing for running automations
-- **Droidrun AppStore**: Simple installation of Apps on your hosted devices
-
 ## 👥 Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.

droidrun-0.3.2/docs/.generated-files.txt

@@ -0,0 +1,5 @@
+md5 1075080038db59977da1586c48d421fb v3/sdk/droid-agent.mdx
+md5 cbccf5efa2fd001f990078cbb05a8d98 v3/sdk/base-tools.mdx
+md5 58f64ddcf2c976b6804894c5c4798a6f v3/sdk/adb-tools.mdx
+md5 3e8a7d303e264b8a8f22b16f45fbde1a v3/sdk/ios-tools.mdx
+md5 fa5a80e8c823f705fce0ea914b85ea41 v3/sdk/adb-utils.mdx

{droidrun-0.3.1 → droidrun-0.3.2}/docs/docs.json

@@ -11,24 +11,43 @@
   "navigation": {
     "versions": [
       {
-        "version": "0.3.0",
+        "version": "0.3.2",
         "groups": [
           {
-            "group": "Getting Started",
+            "group": "Introduction",
             "pages": [
               "v3/overview",
               "v3/quickstart"
             ]
           },
+          {
+            "group": "Guides",
+            "pages": [
+              "v3/guides/overview",
+              "v3/guides/cli",
+              "v3/guides/gemini",
+              "v3/guides/openailike",
+              "v3/guides/ollama",
+              "v3/guides/telemetry"
+            ]
+          },
           {
             "group": "Core Concepts",
             "pages": [
               "v3/concepts/agent",
-              "v3/concepts/planning",
-              "v3/concepts/android-control",
-              "v3/concepts/ios-control",
-              "v3/concepts/portal-app",
-              "v3/concepts/tracing"
+              "v3/concepts/models",
+              "v3/concepts/android-tools",
+              "v3/concepts/portal-app"
+            ]
+          },
+          {
+            "group": "SDK Reference",
+            "pages": [
+              "v3/sdk/droid-agent",
+              "v3/sdk/adb-tools",
+              "v3/sdk/ios-tools",
+              "v3/sdk/base-tools",
+              "v3/sdk/adb-utils"
             ]
           }
         ]
@@ -94,14 +113,21 @@
     ],
     "primary": {
       "type": "button",
-      "label": "Get Started",
-      "href": "https://github.com/droidrun/droidrun"
+      "label": "Join Discord",
+      "href": "https://discord.gg/gdekvkJFvn"
     }
   },
   "footer": {
     "socials": {
       "github": "https://github.com/droidrun/droidrun",
-      "x": "https://x.com/droid_run"
+      "x": "https://x.com/droid_run",
+      "discord": "https://discord.gg/gdekvkJFvn",
+      "website": "https://droidrun.ai"
+    }
+  },
+  "errors": {
+    "404": {
+      "redirect": false
     }
   }
 }

droidrun-0.3.2/docs/v3/concepts/agent.mdx

@@ -0,0 +1,122 @@
+---
+title: 'Agent & Execution Modes'
+description: 'Understanding the DroidAgent system in DroidRun'
+---
+
+
+## Configuration
+
+```python
+# The parameters for the DroidAgent
+def __init__(
+    self, 
+    goal: str,                                  # The goal for the agent to reach
+    llm: LLM,                                   # Language model to use
+    tools: Tools,                               # Loaded tools
+    personas: List[AgentPersona] = [DEFAULT],   # Experimental: custom system prompt for agent
+    max_steps: int = 15,                        # Maximum steps the agent takes
+    timeout: int = 1000,                        # Global Timeout
+    vision: bool = False,                       # Whether the agent shall also utilize screenshots
+    reasoning: bool = False,                    # Enable reasoning
+    reflection: bool = False,                   # Enable reflection
+    enable_tracing: bool = False,               # Enable tracing (this requires arize phoenix)
+    debug: bool = False,                        # Enable additional debug logs
+    save_trajectories: bool = False,            # Save the Trajectory data of the run (GIF + logs)
+    *args,
+    **kwargs
+)
+```
+
+## Execution Modes
+
+The agent operates in three distinct modes, each optimized for different complexity levels and use cases.
+
+### Direct Execution
+<div style={{display: 'flex', gap: '8px', marginBottom: '16px'}}>
+  <span style={{background: 'rgba(107, 114, 128, 0.2)', color: '#6b7280', padding: '4px 8px', borderRadius: '8px', fontSize: '12px', fontWeight: 'bold'}}>REASONING: LOW</span>
+  <span style={{background: 'rgba(13, 147, 115, 0.2)', color: '#0D9373', padding: '4px 8px', borderRadius: '8px', fontSize: '12px', fontWeight: 'bold'}}>SPEED: HIGH</span>
+</div>
+
+```python
+# Simple tasks
+agent = DroidAgent(
+    goal="Take a screenshot of the current screen",
+    llm=llm,
+    tools=tools,
+    reasoning=False
+)
+```
+**Flow:** Goal → Direct Execution → Result
+
+**Best Practices:**
+- Use for single-action tasks (1-15 steps)
+- Keep goals specific and atomic
+- Faster execution with no planning overhead
+
+### Planning Mode
+<div style={{display: 'flex', gap: '8px', marginBottom: '16px'}}>
+  <span style={{background: 'rgba(217, 119, 6, 0.2)', color: '#d97706', padding: '4px 8px', borderRadius: '8px', fontSize: '12px', fontWeight: 'bold'}}>REASONING: MEDIUM</span>
+  <span style={{background: 'rgba(217, 119, 6, 0.2)', color: '#d97706', padding: '4px 8px', borderRadius: '8px', fontSize: '12px', fontWeight: 'bold'}}>SPEED: MEDIUM</span>
+</div>
+
+```python
+# Multi-step tasks requiring navigation and decision-making
+agent = DroidAgent(
+    goal="Set up a new alarm for 7 AM with custom ringtone and label 'Work'",
+    llm=llm,
+    tools=tools,
+    reasoning=True
+)
+```
+**Flow:** Goal → Planning → Step-by-step Execution → Result
+
+**Best Practices:**
+- Use for multi-step tasks (15-50 steps)
+- Ideal for navigation between apps/screens
+- Good for tasks requiring step-by-step breakdown
+
+
+### Reflection Mode
+<div style={{display: 'flex', gap: '8px', marginBottom: '16px'}}>
+  <span style={{background: 'rgba(13, 147, 115, 0.2)', color: '#0D9373', padding: '4px 8px', borderRadius: '8px', fontSize: '12px', fontWeight: 'bold'}}>REASONING: HIGH</span>
+  <span style={{background: 'rgba(107, 114, 128, 0.2)', color: '#6b7280', padding: '4px 8px', borderRadius: '8px', fontSize: '12px', fontWeight: 'bold'}}>SPEED: LOW</span>
+</div>
+
+```python
+# Complex, multi-app workflows requiring verification and adaptive planning
+agent = DroidAgent(
+    goal="Find the cheapest hotel in Manhattan for next weekend, compare prices across multiple booking apps, and share the best option with my team on Slack",
+    llm=llm,
+    tools=tools,
+    reasoning=True,
+    reflection=True
+)
+```
+**Flow:** Goal → Planning → Execution → Reflection → Re-planning (if needed) → Result
+
+**Best Practice:**
+- Use for complex workflows (50+ steps)
+- Essential for quality control and verification
+- Best when context preservation is critical
+
+## Vision capabilities
+<Warning>Vision capabilities are deactivated for the DeepSeek provider and require an LLM model with vision capabilities (e.g., GPT-4o, Gemini-2.5-Flash etc.).</Warning>
+
+By default, DroidAgent operates entirely without vision by leveraging Android's Accessibility API to extract the UI hierarchy as XML. This approach is efficient and works well for most automation tasks.
+
+However, enabling vision capabilities allows the agent to take screenshots and visually analyze the device screen, which can be beneficial in specific scenarios:
+```python
+# To enable vision capabilities, set `vision=True` in your agent configuration. 
+agent = DroidAgent(
+    goal="Open up TikTok and describe the content of the video you are seeing",
+    llm=llm,
+    tools=tools,
+    vision=True
+)
+```
+
+
+- **Content-heavy applications**: When apps contain complex visual elements, images, or layouts that aren't fully captured by the XML hierarchy
+- **Visual verification**: For tasks requiring confirmation of visual elements or layouts
+- **Enhanced context understanding**: When UI structure alone doesn't provide sufficient information for decision-making
+

droidrun-0.3.2/docs/v3/concepts/android-tools.mdx

@@ -0,0 +1,103 @@
+---
+title: 'Android Control'
+description: 'Learn how to control Android devices in DroidRun using the comprehensive tools API.
+Tools provide the bridge between your AI agents and Android devices, enabling UI interaction, app management, and state analysis. Use tools directly or through DroidAgent for automated Android testing and control.'
+---
+
+```python
+from droidrun import DroidAgent, AdbTools
+
+# Load tools for a device
+tools = AdbTools(serial="device_serial")
+
+# Create agent with tools
+agent = DroidAgent(
+    goal="Your task",
+    llm=llm,
+    tools=tools
+)
+```
+
+## UI Interaction Tools
+
+**`tap_by_index(index: int) -> str`**  
+Tap on a UI element by its index from cached elements. Must call `get_state()` first.
+
+**`swipe(start_x: int, start_y: int, end_x: int, end_y: int, duration_ms: int = 300) -> bool`**  
+Perform swipe gesture. For long press, use same start/end coordinates with longer duration.
+
+**`input_text(text: str) -> str`**  
+Input text into focused element. Supports special characters and non-ASCII text.
+
+**`press_key(keycode: int) -> str`**  
+Press Android keys using keycodes. Common: HOME (3), BACK (4), ENTER (66), DELETE (67).
+
+**`back() -> str`**  
+Convenience method to press the Android back button.
+
+```python
+# UI interaction examples
+await tools.get_state()  # Cache elements first
+await tools.tap_by_index(2)  # Tap element
+await tools.swipe(500, 200, 500, 800, 400)  # Swipe down
+await tools.input_text("Hello, World!")
+await tools.press_key(66)  # Enter key
+await tools.back()
+```
+
+## App Management Tools
+
+**`start_app(package: str, activity: str = "") -> str`**  
+Start application by package name and optional activity.
+
+**`list_packages(include_system_apps: bool = False) -> List[str]`**  
+List installed packages. Optionally include system apps.
+
+**`install_app(apk_path: str, reinstall: bool = False, grant_permissions: bool = True) -> str`**  
+Install APK file with optional reinstall and permission granting.
+
+```python
+# App management examples
+await tools.start_app("com.android.settings")
+packages = await tools.list_packages()
+all_packages = await tools.list_packages(include_system_apps=True)
+await tools.install_app("/path/to/app.apk", reinstall=True)
+```
+
+## State Analysis Tools
+
+**`get_state(serial: Optional[str] = None) -> Dict[str, Any]`**  
+Get comprehensive device state including accessibility tree and phone state. Caches UI elements.
+
+**`take_screenshot() -> Tuple[str, bytes]`**  
+Capture device screen and return format and image data. Stores screenshots for GIF creation.
+
+```python
+# State analysis examples
+state = await tools.get_state()
+a11y_tree = state["a11y_tree"]
+phone_state = state["phone_state"]
+
+format, image_data = await tools.take_screenshot()
+```
+
+## Quick Reference
+
+| Function | Purpose | Returns |
+|----------|---------|---------|
+| `tap_by_index(index)` | Tap UI element by index | Status message |
+| `swipe(x1, y1, x2, y2, duration)` | Swipe gesture | Success boolean |
+| `input_text(text)` | Type text | Status message |
+| `press_key(keycode)` | Press Android key | Status message |
+| `back()` | Press back button | Status message |
+| `start_app(package, activity)` | Launch application | Status message |
+| `list_packages(include_system)` | List installed apps | Package list |
+| `install_app(path, reinstall, permissions)` | Install APK | Status message |
+| `get_state(serial)` | Get device state | State dictionary |
+| `take_screenshot()` | Capture screen | Format and image data |
+| `remember(info)` | Store information | Confirmation message |
+| `get_memory()` | Retrieve stored info | Memory list |
+| `complete(success, reason)` | Finish task | None |
+
+## Dive Deeper
+You can find the SDK Reference for AdbTools [here](../sdk/adb-tools)

droidrun-0.3.2/docs/v3/concepts/models.mdx

@@ -0,0 +1,29 @@
+---
+title: 'Supported Models'
+description: 'DroidRun is **LLM agnostic**, which means you can use every LLM provider there is. 
+
+Under the hood, DroidRun leverages [LlamaIndex LLM providers](https://docs.llamaindex.ai/en/stable/api_reference/llms/) to provide seamless integration with all major language model providers. This means you can easily switch between different providers or use multiple providers simultaneously depending on your needs.
+'
+---
+
+## Install LLM Provider
+```bash
+# Install the package for your preffered LLM Provider
+pip install llama-index-llms-[PROVIDER]
+```
+
+## Supported Providers
+
+DroidRun supports all major LLM providers through LlamaIndex, including but not limited to:
+
+- **OpenAI** (GPT-4o, GPT-o3, etc.)
+- **Anthropic** (Claude models)
+- **GoogleGenAI** (Gemini)
+- **Azure OpenAI Service**
+- **AWS Bedrock**
+- **Cohere**
+- **Hugging Face**
+- **Local models** (Ollama, vLLM, etc.)
+- And many more...
+
+This flexibility allows you to choose the best model for your specific use case, budget, and performance requirements while maintaining the same DroidRun interface across all providers.

{droidrun-0.3.1 → droidrun-0.3.2}/docs/v3/concepts/portal-app.mdx

@@ -1,11 +1,14 @@
 ---
-title: 'DroidRun Portal App'
-description: 'Understanding the DroidRun Portal App and its role in the DroidRun framework'
+title: 'Android Portal APK'
+description: 'The DroidRun Portal App is a critical component of the DroidRun framework that runs directly on your Android device. It acts as a bridge between the DroidRun framework running on your computer and the Android operating system.'
 ---
 
-The DroidRun Portal App is a critical component of the DroidRun framework that runs directly on your Android device. It acts as a bridge between the DroidRun framework running on your computer and the Android operating system.
+<img src="../images/portal_apk.png" alt="DroidRun Portal App" width="300" />
 
-## 🔍 What is the DroidRun Portal App?
+
+
+
+## What is the DroidRun Portal App?
 
 The DroidRun Portal App is an Android application that:
 
@@ -14,9 +17,9 @@ The DroidRun Portal App is an Android application that:
 3. Executes commands sent from the DroidRun framework
 4. Provides visual feedback about identified UI elements
 
-## 🔄 How It Works
+## How It Works
 
-The Portal App utilizes Android's Accessibility Services to:
+The Portal App utilizes [Android's Accessibility Services](https://developer.android.com/reference/android/accessibilityservice/AccessibilityService) to:
 
 - Monitor UI changes on your device
 - Identify interactive elements (buttons, text fields, etc.)
@@ -37,7 +40,7 @@ These visual indicators help you understand:
 - What information is being sent to the LLM agent
 
 
-## 🔒 Privacy and Security
+## Privacy and Security
 
 The DroidRun Portal App:
 
@@ -46,14 +49,6 @@ The DroidRun Portal App:
 - Only activates when being used by the DroidRun framework
 - Can be easily disabled through Android settings when not in use
 
-## 🚀 Installation
-
-The DroidRun Portal App is available from the [DroidRun Portal repository](https://github.com/droidrun/droidrun-portal). For installation instructions, see the [Quickstart](/quickstart) guide.
-
-## 🔧 Troubleshooting
-
-### Common Issues
+## Installation
 
-- **App Not Detecting UI Elements**: Ensure the Accessibility Service is enabled
-- **Highlighting Not Visible**: Check if visual debugging is enabled in the app settings
-- **Communication Errors**: Make sure ADB is properly configured and your device is connected
+The DroidRun Portal App is available from the [DroidRun Portal repository](https://github.com/droidrun/droidrun-portal). For installation instructions, see the [Quickstart](/v3/quickstart) guide.