droidrun 0.3.2__tar.gz → 0.3.4__tar.gz

droidrun-0.3.4/.github/workflows/bounty.yml

@@ -0,0 +1,134 @@
+name: "Project V2: Status ← issue label"
+
+on:
+  issues:
+    types: [labeled]
+
+env:
+  ORG: droidrun
+  PROJECT_NUMBER: 2
+  PROJECT_TOKEN: ${{ secrets.BOUNTY_SECRET }}
+
+jobs:
+  update_status:
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Fetch project & field metadata
+        id: metadata
+        env:
+          GH_TOKEN: ${{ env.PROJECT_TOKEN }}
+        run: |
+          # 1) Query projectV2 ID and the Status field + its options
+          gh api graphql -f query='
+            query($org:String!,$num:Int!){
+              organization(login:$org){
+                projectV2(number:$num){
+                  id
+                  fields(first:20){
+                    nodes{
+                      ... on ProjectV2SingleSelectField{
+                        id
+                        name
+                        options { id name }
+                      }
+                    }
+                  }
+                }
+              }
+            }' \
+            -f org="${ORG}" -F num=${PROJECT_NUMBER} \
+            --jq '
+              .data.organization.projectV2 as $p |
+              ($p.id) as $projId |
+              ($p.fields.nodes[] | select(.name=="Status")) as $f |
+              {
+                projectId: $projId,
+                statusFieldId: $f.id,
+                options: ($f.options | map({(.name): .id}) | add)
+              }
+            ' > meta.json
+
+          # expose to GH env
+          echo "PROJECT_ID=$(jq -r .projectId meta.json)" >> $GITHUB_ENV
+          echo "STATUS_FIELD_ID=$(jq -r .statusFieldId meta.json)" >> $GITHUB_ENV
+          # options is an object like {"Eligible":"ID1","Bounty Posted":"ID2",...}
+          echo "STATUS_OPTIONS=$(jq -c .options meta.json)" >> $GITHUB_ENV
+
+      - name: Determine target option ID
+        id: pick
+        run: |
+          LABEL="${{ github.event.label.name }}"
+          # map label→ field option name
+          case "$LABEL" in
+            eligible)      OPT_NAME="📝 Eligible"      ;;
+            bounty-official) OPT_NAME="💰 Bounty" ;;
+            claimed)       OPT_NAME="🛠️ In Progress"   ;;
+            *) echo "No matching status for $LABEL"; exit 0 ;;
+          esac
+
+          # extract from JSON map
+          OPT_ID=$(echo "$STATUS_OPTIONS" | jq -r --arg name "$OPT_NAME" '.[$name]')
+          echo "OPTION_ID=$OPT_ID" >> $GITHUB_ENV
+
+      - name: Ensure issue is in the project
+        id: add_if_missing
+        env:
+          GH_TOKEN: ${{ env.PROJECT_TOKEN }}
+        run: |
+          ISSUE_NODE_ID=$(gh api graphql -f query='
+          query($owner:String!,$repo:String!,$number:Int!){
+            repository(owner:$owner, name:$repo){
+              issue(number:$number){
+                id
+                projectItems(first:1){
+                  nodes{ id }
+                }
+              }
+            }
+          }' \
+          -f owner="droidrun" \
+          -f repo="droidrun" \
+          -F number=104 \
+          --jq '.data.repository.issue as $i |
+          { issueId: $i.id,
+            itemId: ($i.projectItems.nodes[0]?.id // "") }' )
+
+          # Save to file
+          echo "$ISSUE_NODE_ID" > issue.json
+          ISSUE_ID=$(jq -r .issueId issue.json)
+          ITEM_ID=$(jq -r .itemId issue.json)
+
+          if [ -z "$ITEM_ID" ]; then
+            ITEM_ID=$(gh api graphql -f query='
+              mutation($proj:ID!,$content:ID!){
+                addProjectV2ItemById(input:{projectId:$proj, contentId:$content}){
+                  item { id }
+                }
+              }' \
+              -f proj="${PROJECT_ID}" -f content="$ISSUE_ID" \
+              --jq '.data.addProjectV2ItemById.item.id')
+          fi
+          echo "ITEM_ID=$ITEM_ID" >> $GITHUB_ENV
+
+      - name: Update Status field
+        env:
+          GH_TOKEN: ${{ env.PROJECT_TOKEN }}
+        run: |
+          gh api graphql -f query='
+          mutation($proj:ID!,$item:ID!,$field:ID!,$opt:String!){
+            updateProjectV2ItemFieldValue(input:{
+              projectId: $proj,
+              itemId: $item,
+              fieldId: $field,
+              value: {
+                singleSelectOptionId: $opt
+              }
+            }) {
+              projectV2Item { id }
+            }
+          }' \
+          -f proj="${PROJECT_ID}" \
+          -f item="${ITEM_ID}" \
+          -f field="${STATUS_FIELD_ID}" \
+          -f opt="${OPTION_ID}"

{droidrun-0.3.2 → droidrun-0.3.4}/.github/workflows/publish.yml

@@ -53,6 +53,7 @@ jobs:
 
   publish-to-testpypi:
     name: Publish Python 🐍 distribution 📦 to TestPyPI
+    if: startsWith(github.ref, 'refs/tags/')
     needs:
     - build
     runs-on: ubuntu-latest
@@ -73,4 +74,4 @@ jobs:
     - name: Publish distribution 📦 to TestPyPI
       uses: pypa/gh-action-pypi-publish@release/v1
       with:
-        repository-url: https://test.pypi.org/legacy/
+        repository-url: https://test.pypi.org/legacy/

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

@@ -22,3 +22,8 @@ messages_log.json
 patch_apis.py
 .git
 .arize-phoenix
+
+
+uv.lock
+
+todo.txt

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: droidrun
-Version: 0.3.2
+Version: 0.3.4
 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
@@ -25,9 +25,11 @@ Classifier: Topic :: Software Development :: Testing
 Classifier: Topic :: Software Development :: Testing :: Acceptance
 Classifier: Topic :: System :: Emulators
 Classifier: Topic :: Utilities
-Requires-Python: >=3.10
+Requires-Python: >=3.11
+Requires-Dist: adbutils==2.10.0
 Requires-Dist: aiofiles>=23.0.0
 Requires-Dist: anthropic>=0.7.0
+Requires-Dist: apkutils==2.0.0
 Requires-Dist: arize-phoenix
 Requires-Dist: click>=8.1.0
 Requires-Dist: llama-index
@@ -64,6 +66,12 @@ Description-Content-Type: text/markdown
 [![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)
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=983810&theme=dark&period=daily&t=1753948032207">
+  <source media="(prefers-color-scheme: light)" srcset="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=983810&theme=neutral&period=daily&t=1753948125523">
+  <a href="https://www.producthunt.com/products/droidrun-framework-for-mobile-agent?embed=true&utm_source=badge-top-post-badge&utm_medium=badge&utm_source=badge-droidrun" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=983810&theme=neutral&period=daily&t=1753948125523" alt="Droidrun - Give&#0032;AI&#0032;native&#0032;control&#0032;of&#0032;physical&#0032;&#0038;&#0032;virtual&#0032;phones&#0046; | Product Hunt" style="width: 200px; height: 54px;" width="200" height="54" /></a>
+</picture>
+
 
 
 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)
@@ -91,17 +99,21 @@ Read on how to get droidrun up and running within seconds in [our docs](https://
 
 ## 🎬 Demo Videos
 
-1. **Group Chat Summarization**: Let DroidRun summarize an escalated group chat for you.   
+1. **Accommodation booking**: Let Droidrun search for an apartment for you
+
+   [![Droidrun Accommodation Booking Demo](https://img.youtube.com/vi/VUpCyq1PSXw/0.jpg)](https://youtu.be/VUpCyq1PSXw)
+
+<br>
 
-   [![Group Chat Summarizer](https://img.youtube.com/vi/ofEnSUHHxX8/0.jpg)](https://www.youtube.com/watch?v=ofEnSUHHxX8)
+2. **Trend Hunter**: Let Droidrun hunt down trending posts
 
-2. **Travel Search Assistant**: Wittness DroidRun looking for the cheapest stay and share it with a colleague on telegram.    
+   [![Droidrun Trend Hunter Demo](https://img.youtube.com/vi/7V8S2f8PnkQ/0.jpg)](https://youtu.be/7V8S2f8PnkQ)
 
-   [![Travel Search Assistant](https://img.youtube.com/vi/QgtRaLS3NBM/0.jpg)](https://www.youtube.com/watch?v=QgtRaLS3NBM)
+<br>
 
-3. **Automate TikTok Shopping**: See how DroidRun looks for a stanley cup on TikTok Shop and send the product details via email.    
+3. **Streak Saver**: Let Droidrun save your streak on your favorite language learning app
 
-    [![TikTok Shopping Assistant](https://img.youtube.com/vi/ol3bivBAmn4/0.jpg)](https://www.youtube.com/watch?v=ol3bivBAmn4)
+   [![Droidrun Streak Saver Demo](https://img.youtube.com/vi/B5q2B467HKw/0.jpg)](https://youtu.be/B5q2B467HKw)
 
 
 ## 💡 Example Use Cases

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

@@ -10,6 +10,12 @@
 [![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)
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=983810&theme=dark&period=daily&t=1753948032207">
+  <source media="(prefers-color-scheme: light)" srcset="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=983810&theme=neutral&period=daily&t=1753948125523">
+  <a href="https://www.producthunt.com/products/droidrun-framework-for-mobile-agent?embed=true&utm_source=badge-top-post-badge&utm_medium=badge&utm_source=badge-droidrun" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=983810&theme=neutral&period=daily&t=1753948125523" alt="Droidrun - Give&#0032;AI&#0032;native&#0032;control&#0032;of&#0032;physical&#0032;&#0038;&#0032;virtual&#0032;phones&#0046; | Product Hunt" style="width: 200px; height: 54px;" width="200" height="54" /></a>
+</picture>
+
 
 
 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)
@@ -37,17 +43,21 @@ Read on how to get droidrun up and running within seconds in [our docs](https://
 
 ## 🎬 Demo Videos
 
-1. **Group Chat Summarization**: Let DroidRun summarize an escalated group chat for you.   
+1. **Accommodation booking**: Let Droidrun search for an apartment for you
+
+   [![Droidrun Accommodation Booking Demo](https://img.youtube.com/vi/VUpCyq1PSXw/0.jpg)](https://youtu.be/VUpCyq1PSXw)
+
+<br>
 
-   [![Group Chat Summarizer](https://img.youtube.com/vi/ofEnSUHHxX8/0.jpg)](https://www.youtube.com/watch?v=ofEnSUHHxX8)
+2. **Trend Hunter**: Let Droidrun hunt down trending posts
 
-2. **Travel Search Assistant**: Wittness DroidRun looking for the cheapest stay and share it with a colleague on telegram.    
+   [![Droidrun Trend Hunter Demo](https://img.youtube.com/vi/7V8S2f8PnkQ/0.jpg)](https://youtu.be/7V8S2f8PnkQ)
 
-   [![Travel Search Assistant](https://img.youtube.com/vi/QgtRaLS3NBM/0.jpg)](https://www.youtube.com/watch?v=QgtRaLS3NBM)
+<br>
 
-3. **Automate TikTok Shopping**: See how DroidRun looks for a stanley cup on TikTok Shop and send the product details via email.    
+3. **Streak Saver**: Let Droidrun save your streak on your favorite language learning app
 
-    [![TikTok Shopping Assistant](https://img.youtube.com/vi/ol3bivBAmn4/0.jpg)](https://www.youtube.com/watch?v=ol3bivBAmn4)
+   [![Droidrun Streak Saver Demo](https://img.youtube.com/vi/B5q2B467HKw/0.jpg)](https://youtu.be/B5q2B467HKw)
 
 
 ## 💡 Example Use Cases

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

@@ -0,0 +1,4 @@
+md5 0b688f460703d59bd84fe71387e626d5 v3/sdk/droid-agent.mdx
+md5 47f362d52ba26155d647efec628294cf v3/sdk/base-tools.mdx
+md5 2e83b80e94101d983ed52ac5ae91314f v3/sdk/adb-tools.mdx
+md5 7d779482901cc5eb62288ac9c8d85199 v3/sdk/ios-tools.mdx

droidrun-0.3.4/docs/docs.json

@@ -0,0 +1,146 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "DroidRun",
+  "colors": {
+    "primary": "#0D9373",
+    "light": "#07C983",
+    "dark": "#0D9373"
+  },
+  "favicon": "/favicon.png",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Framework",
+        "versions": [
+          {
+            "version": "0.3.3",
+            "groups": [
+              {
+                "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/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"
+                ]
+              }
+            ]
+          },
+          {
+            "version": "0.2.0",
+            "groups": [
+              {
+                "group": "Getting Started",
+                "pages": [
+                  "v2/overview",
+                  "v2/quickstart"
+                ]
+              },
+              {
+                "group": "Core Concepts",
+                "pages": [
+                  "v2/concepts/agent",
+                  "v2/concepts/planning",
+                  "v2/concepts/android-control",
+                  "v2/concepts/portal-app",
+                  "v2/concepts/tracing"
+                ]
+              }
+            ]
+          },
+          {
+            "version": "0.1.0",
+            "groups": [
+              {
+                "group": "Getting Started",
+                "pages": [
+                  "v1/overview",
+                  "v1/quickstart"
+                ]
+              },
+              {
+                "group": "Core Concepts",
+                "pages": [
+                  "v1/concepts/agent",
+                  "v1/concepts/android-control",
+                  "v1/concepts/portal-app"
+                ]
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Cloud API",
+        "versions": [
+          {
+            "version": "0.1.0",
+            "openapi": "https://api.droidrun.ai/v1/openapi.json"
+          }
+        ]
+      }
+    ]
+  },
+  "logo": {
+    "light": "/logo/light.svg",
+    "dark": "/logo/dark.svg"
+  },
+  "navbar": {
+    "links": [
+      {
+        "label": "GitHub",
+        "href": "https://github.com/droidrun/droidrun"
+      },
+      {
+        "label": "Benchmark",
+        "href": "https://droidrun.ai/benchmark"
+      }
+    ],
+    "primary": {
+      "type": "button",
+      "label": "Join Discord",
+      "href": "https://discord.gg/gdekvkJFvn"
+    }
+  },
+  "footer": {
+    "socials": {
+      "github": "https://github.com/droidrun/droidrun",
+      "x": "https://x.com/droid_run",
+      "discord": "https://discord.gg/gdekvkJFvn",
+      "website": "https://droidrun.ai"
+    }
+  },
+  "errors": {
+    "404": {
+      "redirect": false
+    }
+  }
+}

{droidrun-0.3.2 → droidrun-0.3.4}/docs/v3/concepts/agent.mdx

@@ -21,7 +21,7 @@ def __init__(
     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)
+    save_trajectories: str = "none",            # Trajectory saving level: "none" (no saving), "step" (save per step), "action" (save per action)
     *args,
     **kwargs
 )
@@ -92,6 +92,7 @@ agent = DroidAgent(
     reflection=True
 )
 ```
+<Warning>Reflection is based on screenshots. Use it alongside an LLM model with vision capabilities (e.g., GPT-4o, Gemini-2.5-Flash etc.).</Warning>
 **Flow:** Goal → Planning → Execution → Reflection → Re-planning (if needed) → Result
 
 **Best Practice:**

{droidrun-0.3.2 → droidrun-0.3.4}/docs/v3/concepts/android-tools.mdx

@@ -37,12 +37,12 @@ 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()
+tools.get_state()  # Cache elements first
+tools.tap_by_index(2)  # Tap element
+tools.swipe(500, 200, 500, 800, 400)  # Swipe down
+tools.input_text("Hello, World!")
+tools.press_key(66)  # Enter key
+tools.back()
 ```
 
 ## App Management Tools

{droidrun-0.3.2 → droidrun-0.3.4}/docs/v3/concepts/models.mdx

@@ -1,6 +1,6 @@
 ---
 title: 'Supported Models'
-description: 'DroidRun is **LLM agnostic**, which means you can use every LLM provider there is. 
+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.
 '
@@ -8,7 +8,7 @@ Under the hood, DroidRun leverages [LlamaIndex LLM providers](https://docs.llama
 
 ## Install LLM Provider
 ```bash
-# Install the package for your preffered LLM Provider
+# Install the package for your preferred LLM Provider
 pip install llama-index-llms-[PROVIDER]
 ```
 
@@ -19,6 +19,8 @@ DroidRun supports all major LLM providers through LlamaIndex, including but not
 - **OpenAI** (GPT-4o, GPT-o3, etc.)
 - **Anthropic** (Claude models)
 - **GoogleGenAI** (Gemini)
+- **OpenAILike** (OpenAI-compatible APIs such as OpenRouter, Azure OpenAI, local LM Studio)
+- **DeepSeek** (DeepSeek LLM integrations)
 - **Azure OpenAI Service**
 - **AWS Bedrock**
 - **Cohere**

{droidrun-0.3.2 → droidrun-0.3.4}/docs/v3/guides/gemini.mdx

@@ -46,7 +46,7 @@ from droidrun import DroidAgent, AdbTools
 
 async def main():
     # load adb tools for the first connected device
-    tools = await AdbTools.create()
+    tools = AdbTools()
 
     # Set up the Gemini LLM
     llm = GoogleGenAI(

{droidrun-0.3.2 → droidrun-0.3.4}/docs/v3/guides/ollama.mdx

@@ -61,12 +61,14 @@ from droidrun import DroidAgent, AdbTools
 
 async def main():
     # load adb tools for the first connected device
-    tools = await AdbTools.create()
+    tools = AdbTools()
 
     # Set up the Ollama LLM with a modern model
     llm = Ollama(
-        model="qwen2.5vl",  # or "gemma3", "deepseek", "llama4", etc.
-        base_url="http://localhost:11434"  # default Ollama endpoint
+        model="qwen2.5vl",                  # or "gemma3", "deepseek", "llama4", etc.
+        base_url="http://localhost:11434",  # default Ollama endpoint
+        context_window=8192,                # limit the max context window to prevent running out of memory. 
+        request_timeout=120.0               # increase the request timeout
     )
 
     # Create the DroidAgent
@@ -74,7 +76,7 @@ async def main():
         goal="Open Settings and check battery level",
         llm=llm,
         tools=tools,
-        vision=True,         # Optional: enable vision. use vision=False for deepseek models
+        vision=False,         # Optional: enable vision. use vision=True only in conjunction with a vision model
         reasoning=True,       # Optional: enable planning/reasoning. Read more about the agent configuration in Core-Concepts/Agent
     )
 
@@ -88,6 +90,8 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+<Note>Limiting the llm's context_window reduces memory usage, but degrades the agent's performance too. For the best results try extending it as much as possible.</Note>
+
 ## 4. Troubleshooting
 
 - **Ollama not running:** Make sure `ollama serve` is running and accessible at `http://localhost:11434`.

{droidrun-0.3.2 → droidrun-0.3.4}/docs/v3/guides/openailike.mdx

@@ -50,7 +50,7 @@ from droidrun import DroidAgent, AdbTools
 
 async def main():
     # Load adb tools for the first connected device
-    tools = await AdbTools.create()
+    tools = AdbTools()
 
     # Set up the OpenAI-like LLM (uses env vars for API key and base by default)
     llm = OpenAILike(

{droidrun-0.3.2 → droidrun-0.3.4}/docs/v3/quickstart.mdx

@@ -59,7 +59,7 @@ from llama_index.llms.google_genai import GoogleGenAI
 
 async def main():
     # Load tools
-    tools = await AdbTools.create()
+    tools = AdbTools()
     # set up google gemini llm
     llm = GoogleGenAI(
         api_key="YOUR_GEMINI_API_KEY",  # Replace with your Gemini API key