droidrun 0.1.0__tar.gz → 0.3.0__tar.gz

droidrun-0.3.0/.gitignore

@@ -0,0 +1,22 @@
+dist/
+# Python bytecode files
+__pycache__/
+*.py[cod]
+*$py.class
+trajectories/
+*.class
+
+test.py
+test.ipynb
+*.log
+
+messages_log.json
+
+.idea
+.vscode
+.vscode-test
+.vscode-test-*
+.idea/*
+.vscode/*
+patch_apis.py
+.*

droidrun-0.3.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to the DroidRun project will be documented in this file.
+
+## [0.2.0] - 2025-05-21
+
+### Added
+- **New LLM Providers**
+  - Added support for Ollama (local LLM models)
+  - Added support for DeepSeek models
+  - Case-sensitive provider names: OpenAI, Anthropic, Gemini, Ollama, DeepSeek
+
+- **Planning System**
+  - Added DroidAgent with planning capabilities for complex tasks
+  - Introduced task decomposition for multi-step operations
+
+- **LlamaIndex Integration**
+  - Replaced custom LLM wrapper with LlamaIndex integration
+  - Added direct support for LlamaIndex LLM classes
+
+- **Tracing and Debugging**
+  - Added integration with Arize Phoenix for execution tracing
+  - Added token usage analysis
+  - Added execution time metrics
+
+- **CLI Enhancements**
+  - Added `--reasoning` flag to enable planning capabilities
+  - Added `--tracing` flag for execution tracing with Phoenix
+
+- **Documentation**
+  - Added comprehensive documentation for new features
+  - Created dedicated pages for planning and tracing
+  - Updated all examples to reflect new API patterns
+
+### Changed
+- **Agent Architecture**
+  - Replaced ReActAgent with the new DroidAgent system
+  - Refactored agent initialization to use tools_instance and tool_list
+  - Changed API from `task` parameter to `goal` parameter
+
+### Deprecated
+- Old agent initialization pattern with `device_serial` parameter
+- Direct LLM provider initialization (replaced by LlamaIndex)
+- Non-case-sensitive provider names
+
+### Removed
+- ReActAgent class (replaced by DroidAgent)
+- LLMReasoner class (replaced by LlamaIndex)
+- Some previously documented tools that were not fully implemented
+
+### Fixed
+- Various UI interaction issues
+- Improved error handling in device connections
+- More reliable Android element detection

droidrun-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,118 @@
+# Contributing to DroidRun
+
+Thank you for your interest in contributing to DroidRun! This document provides guidelines and instructions for contributing to the project.
+
+## Getting Started
+
+1. Fork the repository on GitHub
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/droidrun.git
+   cd droidrun
+   ```
+3. Set up your development environment as described below
+
+## Development Setup
+
+1. Create and activate a virtual environment:
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+   ```
+
+2. Install development dependencies:
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+## Making Contributions
+
+1. Create a new branch for your feature:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes following our coding standards:
+   - Use type hints for Python functions
+   - Follow PEP 8 style guidelines
+   - Write descriptive commit messages
+   - Update documentation as needed
+
+3. Commit your changes:
+   ```bash
+   git add .
+   git commit -m "feat: add your feature description"
+   ```
+
+4. Push to your fork:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+5. Open a Pull Request
+
+## Documentation
+
+- Update the README.md if you change functionality
+- Add docstrings to new functions and classes
+- Update the documentation in the `docs/` directory
+
+## Community
+
+- Join our [Discord server](https://discord.gg/ZZbKEZZkwK) for discussions
+- Follow us on [Twitter/X](https://x.com/droid_run)
+- Check our [Documentation](https://docs.droidrun.ai)
+- Report bugs and request features through [GitHub Issues](https://github.com/droidrun/droidrun/issues)
+
+## Security Checks
+
+To ensure the security of the codebase, we have integrated security checks using `bandit` and `safety`. These tools help identify potential security issues in the code and dependencies.
+
+### Running Security Checks
+
+Before submitting any code, please run the following security checks:
+
+1. **Bandit**: A tool to find common security issues in Python code.
+   ```bash
+   bandit -r droidrun
+   ```
+
+2. **Safety**: A tool to check your installed dependencies for known security vulnerabilities.
+   ```bash
+   safety check
+   ```
+
+You can also run both checks using the provided script:
+```bash
+python -m droidrun.tools.security_check
+```
+
+## Pull Request Process
+
+1. Update documentation for any modified functionality
+2. Update the changelog if applicable
+3. Get at least one code review from a maintainer
+4. Once approved, a maintainer will merge your PR
+
+## Release Process
+
+Releases are handled by the maintainers. Version numbers follow [Semantic Versioning](https://semver.org/).
+
+## Questions?
+
+If you have questions about contributing:
+1. Check existing GitHub issues
+2. Ask in our Discord server
+3. Open a new GitHub issue for complex questions
+
+Thank you for contributing to DroidRun! 🚀
+
+## Language
+
+English is the preferred language for all contributions, including:
+- Code comments
+- Documentation
+- Commit messages
+- Pull requests
+- Issue reports
+- Community discussions

droidrun-0.3.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: droidrun
+Version: 0.3.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: arize-phoenix
+Requires-Dist: click>=8.1.0
+Requires-Dist: llama-index
+Requires-Dist: llama-index-callbacks-arize-phoenix
+Requires-Dist: llama-index-llms-anthropic
+Requires-Dist: llama-index-llms-deepseek
+Requires-Dist: llama-index-llms-gemini
+Requires-Dist: llama-index-llms-ollama
+Requires-Dist: llama-index-llms-openai
+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: bandit>=1.7.0; 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'
+Requires-Dist: safety>=2.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./static/droidrun-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="./static/droidrun.png">
+  <img src="./static/droidrun.png"  width="full">
+</picture>
+
+[![GitHub stars](https://img.shields.io/github/stars/droidrun/droidrun?style=social)](https://github.com/droidrun/droidrun/stargazers)
+[![Discord](https://img.shields.io/discord/1360219330318696488?color=7289DA&label=Discord&logo=discord&logoColor=white)](https://discord.gg/ZZbKEZZkwK)
+[![Documentation](https://img.shields.io/badge/Documentation-📕-blue)](https://docs.droidrun.ai)
+[![Benchmark](https://img.shields.io/badge/Benchmark-🏅-teal)](https://droidrun.ai/benchmark)
+[![Twitter Follow](https://img.shields.io/twitter/follow/droid_run?style=social)](https://x.com/droid_run)
+
+
+
+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)
+
+- 🤖 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
+- 💻 Easy to use CLI with enhanced debugging features
+- 🐍 Extendable Python API for custom automations
+- 📸 Screenshot analysis for visual understanding of the device
+- 🫆 Execution tracing with Arize Phoenix
+
+## 📦 Installation
+
+```bash
+pip install droidrun
+```
+
+## 🚀 Quickstart
+Read on how to get droidrun up and running within seconds in [our docs](https://docs.droidrun.ai/v3/quickstart)!
+
+
+## 🎬 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)
+
+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
+
+- Automated UI testing of mobile applications
+- Creating guided workflows for non-technical users
+- Automating repetitive tasks on mobile devices
+- 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.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details. 
+
+## Security Checks
+
+To ensure the security of the codebase, we have integrated security checks using `bandit` and `safety`. These tools help identify potential security issues in the code and dependencies.
+
+### Running Security Checks
+
+Before submitting any code, please run the following security checks:
+
+1. **Bandit**: A tool to find common security issues in Python code.
+   ```bash
+   bandit -r droidrun
+   ```
+
+2. **Safety**: A tool to check your installed dependencies for known security vulnerabilities.
+   ```bash
+   safety scan
+   ```

droidrun-0.3.0/README.md

@@ -0,0 +1,97 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./static/droidrun-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="./static/droidrun.png">
+  <img src="./static/droidrun.png"  width="full">
+</picture>
+
+[![GitHub stars](https://img.shields.io/github/stars/droidrun/droidrun?style=social)](https://github.com/droidrun/droidrun/stargazers)
+[![Discord](https://img.shields.io/discord/1360219330318696488?color=7289DA&label=Discord&logo=discord&logoColor=white)](https://discord.gg/ZZbKEZZkwK)
+[![Documentation](https://img.shields.io/badge/Documentation-📕-blue)](https://docs.droidrun.ai)
+[![Benchmark](https://img.shields.io/badge/Benchmark-🏅-teal)](https://droidrun.ai/benchmark)
+[![Twitter Follow](https://img.shields.io/twitter/follow/droid_run?style=social)](https://x.com/droid_run)
+
+
+
+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)
+
+- 🤖 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
+- 💻 Easy to use CLI with enhanced debugging features
+- 🐍 Extendable Python API for custom automations
+- 📸 Screenshot analysis for visual understanding of the device
+- 🫆 Execution tracing with Arize Phoenix
+
+## 📦 Installation
+
+```bash
+pip install droidrun
+```
+
+## 🚀 Quickstart
+Read on how to get droidrun up and running within seconds in [our docs](https://docs.droidrun.ai/v3/quickstart)!
+
+
+## 🎬 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)
+
+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
+
+- Automated UI testing of mobile applications
+- Creating guided workflows for non-technical users
+- Automating repetitive tasks on mobile devices
+- 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.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details. 
+
+## Security Checks
+
+To ensure the security of the codebase, we have integrated security checks using `bandit` and `safety`. These tools help identify potential security issues in the code and dependencies.
+
+### Running Security Checks
+
+Before submitting any code, please run the following security checks:
+
+1. **Bandit**: A tool to find common security issues in Python code.
+   ```bash
+   bandit -r droidrun
+   ```
+
+2. **Safety**: A tool to check your installed dependencies for known security vulnerabilities.
+   ```bash
+   safety scan
+   ```

droidrun-0.3.0/codeact.html

@@ -0,0 +1,155 @@
+<html>
+    <head>
+        <meta charset="utf-8">
+        
+            <script src="lib/bindings/utils.js"></script>
+            <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/vis-network/9.1.2/dist/dist/vis-network.min.css" integrity="sha512-WgxfT5LWjfszlPHXRmBWHkV2eceiWTOBvrKCNbdgDYTHrT2AeLCGbF4sZlZw3UMN3WtL0tGUoIAKsu8mllg/XA==" crossorigin="anonymous" referrerpolicy="no-referrer" />
+            <script src="https://cdnjs.cloudflare.com/ajax/libs/vis-network/9.1.2/dist/vis-network.min.js" integrity="sha512-LnvoEWDFrqGHlHmDD2101OrLcbsfkrzoSpvtSQtxK3RMnRV0eOkhhBN2dXHKRrUU8p2DGRTk35n4O8nWSVe1mQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script>
+            
+        
+<center>
+<h1></h1>
+</center>
+
+<!-- <link rel="stylesheet" href="../node_modules/vis/dist/vis.min.css" type="text/css" />
+<script type="text/javascript" src="../node_modules/vis/dist/vis.js"> </script>-->
+        <link
+          href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.0-beta3/dist/css/bootstrap.min.css"
+          rel="stylesheet"
+          integrity="sha384-eOJMYsd53ii+scO/bJGFsiCZc+5NDVN2yr8+0RDqr0Ql0h+rP48ckxlpbzKgwra6"
+          crossorigin="anonymous"
+        />
+        <script
+          src="https://cdn.jsdelivr.net/npm/bootstrap@5.0.0-beta3/dist/js/bootstrap.bundle.min.js"
+          integrity="sha384-JEW9xMcG8R+pH31jmWH6WWP0WintQrMb4s7ZOdauHnUtxwoG2vI5DkLtS3qm9Ekf"
+          crossorigin="anonymous"
+        ></script>
+
+
+        <center>
+          <h1></h1>
+        </center>
+        <style type="text/css">
+
+             #mynetwork {
+                 width: 100%;
+                 height: 750px;
+                 background-color: #ffffff;
+                 border: 1px solid lightgray;
+                 position: relative;
+                 float: left;
+             }
+
+             
+
+             
+
+             
+        </style>
+    </head>
+
+
+    <body>
+        <div class="card" style="width: 100%">
+            
+            
+            <div id="mynetwork" class="card-body"></div>
+        </div>
+
+        
+        
+
+        <script type="text/javascript">
+
+              // initialize global variables.
+              var edges;
+              var nodes;
+              var allNodes;
+              var allEdges;
+              var nodeColors;
+              var originalNodes;
+              var network;
+              var container;
+              var options, data;
+              var filter = {
+                  item : '',
+                  property : '',
+                  value : []
+              };
+
+              
+
+              
+
+              // This method is responsible for drawing the graph, returns the drawn network
+              function drawGraph() {
+                  var container = document.getElementById('mynetwork');
+
+                  
+
+                  // parsing and collecting nodes and edges from the python
+                  nodes = new vis.DataSet([{"color": "#ADD8E6", "id": "_done", "label": "_done", "shape": "box"}, {"color": "#FFA07A", "id": "StopEvent", "label": "StopEvent", "shape": "ellipse"}, {"color": "#ADD8E6", "id": "execute_code", "label": "execute_code", "shape": "box"}, {"color": "#90EE90", "id": "TaskExecutionEvent", "label": "TaskExecutionEvent", "shape": "ellipse"}, {"color": "#90EE90", "id": "TaskExecutionResultEvent", "label": "TaskExecutionResultEvent", "shape": "ellipse"}, {"color": "#90EE90", "id": "TaskEndEvent", "label": "TaskEndEvent", "shape": "ellipse"}, {"color": "#ADD8E6", "id": "finalize", "label": "finalize", "shape": "box"}, {"color": "#ADD8E6", "id": "handle_execution_result", "label": "handle_execution_result", "shape": "box"}, {"color": "#90EE90", "id": "TaskInputEvent", "label": "TaskInputEvent", "shape": "ellipse"}, {"color": "#ADD8E6", "id": "handle_llm_input", "label": "handle_llm_input", "shape": "box"}, {"color": "#90EE90", "id": "TaskThinkingEvent", "label": "TaskThinkingEvent", "shape": "ellipse"}, {"color": "#ADD8E6", "id": "handle_llm_output", "label": "handle_llm_output", "shape": "box"}, {"color": "#ADD8E6", "id": "prepare_chat", "label": "prepare_chat", "shape": "box"}, {"color": "#E27AFF", "id": "StartEvent", "label": "StartEvent", "shape": "ellipse"}]);
+                  edges = new vis.DataSet([{"arrows": "to", "from": "StopEvent", "to": "_done"}, {"arrows": "to", "from": "execute_code", "to": "TaskExecutionResultEvent"}, {"arrows": "to", "from": "execute_code", "to": "TaskEndEvent"}, {"arrows": "to", "from": "TaskExecutionEvent", "to": "execute_code"}, {"arrows": "to", "from": "finalize", "to": "StopEvent"}, {"arrows": "to", "from": "TaskEndEvent", "to": "finalize"}, {"arrows": "to", "from": "handle_execution_result", "to": "TaskInputEvent"}, {"arrows": "to", "from": "TaskExecutionResultEvent", "to": "handle_execution_result"}, {"arrows": "to", "from": "handle_llm_input", "to": "TaskThinkingEvent"}, {"arrows": "to", "from": "handle_llm_input", "to": "TaskEndEvent"}, {"arrows": "to", "from": "TaskInputEvent", "to": "handle_llm_input"}, {"arrows": "to", "from": "handle_llm_output", "to": "TaskExecutionEvent"}, {"arrows": "to", "from": "handle_llm_output", "to": "TaskInputEvent"}, {"arrows": "to", "from": "TaskThinkingEvent", "to": "handle_llm_output"}, {"arrows": "to", "from": "prepare_chat", "to": "TaskInputEvent"}, {"arrows": "to", "from": "StartEvent", "to": "prepare_chat"}]);
+
+                  nodeColors = {};
+                  allNodes = nodes.get({ returnType: "Object" });
+                  for (nodeId in allNodes) {
+                    nodeColors[nodeId] = allNodes[nodeId].color;
+                  }
+                  allEdges = edges.get({ returnType: "Object" });
+                  // adding nodes and edges to the graph
+                  data = {nodes: nodes, edges: edges};
+
+                  var options = {
+    "configure": {
+        "enabled": false
+    },
+    "edges": {
+        "color": {
+            "inherit": true
+        },
+        "smooth": {
+            "enabled": true,
+            "type": "dynamic"
+        }
+    },
+    "interaction": {
+        "dragNodes": true,
+        "hideEdgesOnDrag": false,
+        "hideNodesOnDrag": false
+    },
+    "physics": {
+        "enabled": true,
+        "stabilization": {
+            "enabled": true,
+            "fit": true,
+            "iterations": 1000,
+            "onlyDynamicEdges": false,
+            "updateInterval": 50
+        }
+    }
+};
+
+                  
+
+
+                  
+
+                  network = new vis.Network(container, data, options);
+
+                  
+
+                  
+
+                  
+
+
+                  
+
+                  return network;
+
+              }
+              drawGraph();
+        </script>
+    </body>
+</html>