droidrun 0.3.1__tar.gz → 0.3.3__tar.gz

droidrun-0.3.3/.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.1 → droidrun-0.3.3}/.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.1 → droidrun-0.3.3}/.gitignore

@@ -1,4 +1,5 @@
 dist/
+build/
 # Python bytecode files
 __pycache__/
 *.py[cod]
@@ -21,3 +22,6 @@ messages_log.json
 patch_apis.py
 .git
 .arize-phoenix
+
+
+uv.lock

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: droidrun
-Version: 0.3.1
+Version: 0.3.3
 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
@@ -40,9 +42,11 @@ 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
+Requires-Dist: typing-extensions
 Provides-Extra: dev
 Requires-Dist: bandit>=1.7.0; extra == 'dev'
 Requires-Dist: black>=23.0.0; extra == 'dev'
@@ -63,10 +67,18 @@ 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)
 
+## 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 +94,28 @@ 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. **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>
+
+2. **Trend Hunter**: Let Droidrun hunt down trending posts
+
+   [![Droidrun Trend Hunter Demo](https://img.youtube.com/vi/7V8S2f8PnkQ/0.jpg)](https://youtu.be/7V8S2f8PnkQ)
+
+<br>
+
+3. **Streak Saver**: Let Droidrun save your streak on your favorite language learning app
+
+   [![Droidrun Streak Saver Demo](https://img.youtube.com/vi/B5q2B467HKw/0.jpg)](https://youtu.be/B5q2B467HKw)
 
-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 +125,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.3}/README.md

@@ -10,10 +10,18 @@
 [![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)
 
+## 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 +37,28 @@ 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. **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>
+
+2. **Trend Hunter**: Let Droidrun hunt down trending posts
+
+   [![Droidrun Trend Hunter Demo](https://img.youtube.com/vi/7V8S2f8PnkQ/0.jpg)](https://youtu.be/7V8S2f8PnkQ)
+
+<br>
+
+3. **Streak Saver**: Let Droidrun save your streak on your favorite language learning app
+
+   [![Droidrun Streak Saver Demo](https://img.youtube.com/vi/B5q2B467HKw/0.jpg)](https://youtu.be/B5q2B467HKw)
 
-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 +68,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.3/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.3/docs/docs.json

@@ -0,0 +1,147 @@
+{
+  "$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.2",
+            "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",
+                  "v3/sdk/adb-utils"
+                ]
+              }
+            ]
+          },
+          {
+            "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.3/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
+