droidrun 0.3.3__tar.gz → 0.3.4__tar.gz

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

@@ -24,4 +24,6 @@ patch_apis.py
 .arize-phoenix
 
 
-uv.lock
+uv.lock
+
+todo.txt

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: droidrun
-Version: 0.3.3
+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
@@ -46,7 +46,6 @@ 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'

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.3 → droidrun-0.3.4}/docs/docs.json

@@ -14,7 +14,7 @@
         "tab": "Framework",
         "versions": [
           {
-            "version": "0.3.2",
+            "version": "0.3.3",
             "groups": [
               {
                 "group": "Introduction",
@@ -49,8 +49,7 @@
                   "v3/sdk/droid-agent",
                   "v3/sdk/adb-tools",
                   "v3/sdk/ios-tools",
-                  "v3/sdk/base-tools",
-                  "v3/sdk/adb-utils"
+                  "v3/sdk/base-tools"
                 ]
               }
             ]

{droidrun-0.3.3 → 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.3 → 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.3 → 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.3 → 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.3 → 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

{droidrun-0.3.3 → droidrun-0.3.4}/docs/v3/sdk/adb-tools.mdx

@@ -19,7 +19,11 @@ Core UI interaction tools for Android device control.
 #### AdbTools.\_\_init\_\_
 
 ```python
-def __init__(serial: str) -> None
+def __init__(
+    serial: str | None = None,
+    use_tcp: bool = False,
+    tcp_port: int = 8080
+) -> None
 ```
 
 Initialize the AdbTools instance.
@@ -27,32 +31,53 @@ Initialize the AdbTools instance.
 **Arguments**:
 
 - `serial` - Device serial number
+- `use_tcp` - Whether to use TCP communication (default: False)
+- `tcp_port` - TCP port for communication (default: 8080)
 
-<a id="droidrun.tools.adb.AdbTools.create"></a>
+<a id="droidrun.tools.adb.AdbTools.setup_tcp_forward"></a>
 
-#### AdbTools.create
+#### AdbTools.setup\_tcp\_forward
 
 ```python
-async def create(cls: Type[Self], serial: str = None) -> Self
+def setup_tcp_forward() -> bool
 ```
 
-Create an AdbTools instance.
+Set up ADB TCP port forwarding for communication with the portal app.
 
-**Arguments**:
+**Returns**:
 
-- `serial` - Optional device serial number. If not provided, the first device found will be used.
-  
+- `bool` - True if forwarding was set up successfully, False otherwise
+
+<a id="droidrun.tools.adb.AdbTools.teardown_tcp_forward"></a>
+
+#### AdbTools.teardown\_tcp\_forward
+
+```python
+def teardown_tcp_forward() -> bool
+```
+
+Remove ADB TCP port forwarding.
 
 **Returns**:
 
-  AdbTools instance
+- `bool` - True if forwarding was removed successfully, False otherwise
+
+<a id="droidrun.tools.adb.AdbTools.__del__"></a>
+
+#### AdbTools.\_\_del\_\_
+
+```python
+def __del__()
+```
+
+Cleanup when the object is destroyed.
 
 <a id="droidrun.tools.adb.AdbTools.tap_by_index"></a>
 
 #### AdbTools.tap\_by\_index
 
 ```python
-async def tap_by_index(index: int, serial: Optional[str] = None) -> str
+def tap_by_index(index: int) -> str
 ```
 
 Tap on a UI element by its index.
@@ -74,7 +99,7 @@ to find the element with the given index and tap on its center coordinates.
 #### AdbTools.tap\_by\_coordinates
 
 ```python
-async def tap_by_coordinates(x: int, y: int) -> bool
+def tap_by_coordinates(x: int, y: int) -> bool
 ```
 
 Tap on the device screen at specific coordinates.
@@ -94,7 +119,7 @@ Tap on the device screen at specific coordinates.
 #### AdbTools.tap
 
 ```python
-async def tap(index: int) -> str
+def tap(index: int) -> str
 ```
 
 Tap on a UI element by its index.
@@ -116,12 +141,12 @@ to find the element with the given index and tap on its center coordinates.
 #### AdbTools.swipe
 
 ```python
-async def swipe(
+def swipe(
     start_x: int,
     start_y: int,
     end_x: int,
     end_y: int,
-    duration_ms: int = 300
+    duration_ms: float = 300
 ) -> bool
 ```
 
@@ -134,7 +159,35 @@ To perform a hold (long press), set the start and end coordinates to the same va
 - `start_y` - Starting Y coordinate
 - `end_x` - Ending X coordinate
 - `end_y` - Ending Y coordinate
-- `duration_ms` - Duration of swipe in milliseconds
+- `duration` - Duration of swipe in seconds
+
+**Returns**:
+
+  Bool indicating success or failure
+
+<a id="droidrun.tools.adb.AdbTools.drag"></a>
+
+#### AdbTools.drag
+
+```python
+def drag(
+    start_x: int,
+    start_y: int,
+    end_x: int,
+    end_y: int,
+    duration: float = 3
+) -> bool
+```
+
+Performs a straight-line drag and drop gesture on the device screen.
+
+**Arguments**:
+
+- `start_x` - Starting X coordinate
+- `start_y` - Starting Y coordinate
+- `end_x` - Ending X coordinate
+- `end_y` - Ending Y coordinate
+- `duration` - Duration of swipe in seconds
 
 **Returns**:
 
@@ -145,7 +198,7 @@ To perform a hold (long press), set the start and end coordinates to the same va
 #### AdbTools.input\_text
 
 ```python
-async def input_text(text: str, serial: Optional[str] = None) -> str
+def input_text(text: str) -> str
 ```
 
 Input text on the device.
@@ -165,7 +218,7 @@ Always make sure that the Focused Element is not None before inputting text.
 #### AdbTools.back
 
 ```python
-async def back() -> str
+def back() -> str
 ```
 
 Go back on the current view.
@@ -176,7 +229,7 @@ This presses the Android back button.
 #### AdbTools.press\_key
 
 ```python
-async def press_key(keycode: int) -> str
+def press_key(keycode: int) -> str
 ```
 
 Press a key on the Android device.
@@ -196,7 +249,7 @@ Common keycodes:
 #### AdbTools.start\_app
 
 ```python
-async def start_app(package: str, activity: str = "") -> str
+def start_app(package: str, activity: str | None = None) -> str
 ```
 
 Start an app on the device.
@@ -211,7 +264,7 @@ Start an app on the device.
 #### AdbTools.install\_app
 
 ```python
-async def install_app(
+def install_app(
     apk_path: str,
     reinstall: bool = False,
     grant_permissions: bool = True
@@ -231,7 +284,7 @@ Install an app on the device.
 #### AdbTools.take\_screenshot
 
 ```python
-async def take_screenshot() -> Tuple[str, bytes]
+def take_screenshot() -> Tuple[str, bytes]
 ```
 
 Take a screenshot of the device.
@@ -243,7 +296,7 @@ Also stores the screenshot in the screenshots list with timestamp for later GIF
 #### AdbTools.list\_packages
 
 ```python
-async def list_packages(include_system_apps: bool = False) -> List[str]
+def list_packages(include_system_apps: bool = False) -> List[str]
 ```
 
 List installed packages on the device.
@@ -277,7 +330,7 @@ Mark the task as finished.
 #### AdbTools.remember
 
 ```python
-async def remember(information: str) -> str
+def remember(information: str) -> str
 ```
 
 Store important information to remember for future context.
@@ -314,7 +367,7 @@ Retrieve all stored memory items.
 #### AdbTools.get\_state
 
 ```python
-async def get_state(serial: Optional[str] = None) -> Dict[str, Any]
+def get_state(serial: Optional[str] = None) -> Dict[str, Any]
 ```
 
 Get both the a11y tree and phone state in a single call using the combined /state endpoint.
@@ -328,3 +381,45 @@ Get both the a11y tree and phone state in a single call using the combined /stat
 
   Dictionary containing both 'a11y_tree' and 'phone_state' data
 
+<a id="droidrun.tools.adb.AdbTools.get_a11y_tree"></a>
+
+#### AdbTools.get\_a11y\_tree
+
+```python
+def get_a11y_tree() -> Dict[str, Any]
+```
+
+Get just the accessibility tree using the /a11y_tree endpoint.
+
+**Returns**:
+
+  Dictionary containing accessibility tree data
+
+<a id="droidrun.tools.adb.AdbTools.get_phone_state"></a>
+
+#### AdbTools.get\_phone\_state
+
+```python
+def get_phone_state() -> Dict[str, Any]
+```
+
+Get just the phone state using the /phone_state endpoint.
+
+**Returns**:
+
+  Dictionary containing phone state data
+
+<a id="droidrun.tools.adb.AdbTools.ping"></a>
+
+#### AdbTools.ping
+
+```python
+def ping() -> Dict[str, Any]
+```
+
+Test the TCP connection using the /ping endpoint.
+
+**Returns**:
+
+  Dictionary with ping result
+

{droidrun-0.3.3 → droidrun-0.3.4}/docs/v3/sdk/base-tools.mdx

@@ -13,12 +13,23 @@ class Tools(ABC)
 Abstract base class for all tools.
 This class provides a common interface for all tools to implement.
 
+<a id="droidrun.tools.tools.Tools.ui_action"></a>
+
+#### Tools.ui\_action
+
+```python
+def ui_action(func)
+```
+
+"
+Decorator to capture screenshots and UI states for actions that modify the UI.
+
 <a id="droidrun.tools.tools.Tools.get_state"></a>
 
 #### Tools.get\_state
 
 ```python
-async def get_state() -> Dict[str, Any]
+def get_state() -> Dict[str, Any]
 ```
 
 Get the current state of the tool.
@@ -28,7 +39,7 @@ Get the current state of the tool.
 #### Tools.tap\_by\_index
 
 ```python
-async def tap_by_index(index: int) -> bool
+def tap_by_index(index: int) -> str
 ```
 
 Tap the element at the given index.
@@ -38,7 +49,7 @@ Tap the element at the given index.
 #### Tools.swipe
 
 ```python
-async def swipe(
+def swipe(
     start_x: int,
     start_y: int,
     end_x: int,
@@ -49,12 +60,28 @@ async def swipe(
 
 Swipe from the given start coordinates to the given end coordinates.
 
+<a id="droidrun.tools.tools.Tools.drag"></a>
+
+#### Tools.drag
+
+```python
+def drag(
+    start_x: int,
+    start_y: int,
+    end_x: int,
+    end_y: int,
+    duration_ms: int = 3000
+) -> bool
+```
+
+Drag from the given start coordinates to the given end coordinates.
+
 <a id="droidrun.tools.tools.Tools.input_text"></a>
 
 #### Tools.input\_text
 
 ```python
-async def input_text(text: str) -> bool
+def input_text(text: str) -> str
 ```
 
 Input the given text into a focused input field.
@@ -64,7 +91,7 @@ Input the given text into a focused input field.
 #### Tools.back
 
 ```python
-async def back() -> bool
+def back() -> str
 ```
 
 Press the back button.
@@ -74,7 +101,7 @@ Press the back button.
 #### Tools.press\_key
 
 ```python
-async def press_key(keycode: int) -> bool
+def press_key(keycode: int) -> str
 ```
 
 Enter the given keycode.
@@ -84,7 +111,7 @@ Enter the given keycode.
 #### Tools.start\_app
 
 ```python
-async def start_app(package: str, activity: str = "") -> bool
+def start_app(package: str, activity: str = "") -> str
 ```
 
 Start the given app.
@@ -94,7 +121,7 @@ Start the given app.
 #### Tools.take\_screenshot
 
 ```python
-async def take_screenshot() -> Tuple[str, bytes]
+def take_screenshot() -> Tuple[str, bytes]
 ```
 
 Take a screenshot of the device.
@@ -104,7 +131,7 @@ Take a screenshot of the device.
 #### Tools.list\_packages
 
 ```python
-async def list_packages(include_system_apps: bool = False) -> List[str]
+def list_packages(include_system_apps: bool = False) -> List[str]
 ```
 
 List all packages on the device.
@@ -114,7 +141,7 @@ List all packages on the device.
 #### Tools.remember
 
 ```python
-async def remember(information: str) -> str
+def remember(information: str) -> str
 ```
 
 Remember the given information. This is used to store information in the tool's memory.
@@ -124,7 +151,7 @@ Remember the given information. This is used to store information in the tool's
 #### Tools.get\_memory
 
 ```python
-async def get_memory() -> List[str]
+def get_memory() -> List[str]
 ```
 
 Get the memory of the tool.
@@ -134,7 +161,7 @@ Get the memory of the tool.
 #### Tools.complete
 
 ```python
-def complete(success: bool, reason: str = "") -> bool
+def complete(success: bool, reason: str = "") -> None
 ```
 
 Complete the tool. This is used to indicate that the tool has completed its task.
@@ -144,7 +171,10 @@ Complete the tool. This is used to indicate that the tool has completed its task
 #### describe\_tools
 
 ```python
-def describe_tools(tools: Tools) -> Dict[str, Callable[..., Any]]
+def describe_tools(
+    tools: Tools,
+    exclude_tools: Optional[List[str]] = None
+) -> Dict[str, Callable[..., Any]]
 ```
 
 Describe the tools available for the given Tools instance.
@@ -152,6 +182,7 @@ Describe the tools available for the given Tools instance.
 **Arguments**:
 
 - `tools` - The Tools instance to describe.
+- `exclude_tools` - List of tool names to exclude from the description.
   
 
 **Returns**:

{droidrun-0.3.3 → droidrun-0.3.4}/docs/v3/sdk/droid-agent.mdx

@@ -33,7 +33,8 @@ def __init__(
     reflection: bool = False,
     enable_tracing: bool = False,
     debug: bool = False,
-    save_trajectories: bool = False,
+    save_trajectories: str = "none",
+    excluded_tools: List[str] = None,
     *args,
     **kwargs
 )
@@ -52,6 +53,10 @@ Initialize the DroidAgent wrapper.
 - `reflection` - Whether to reflect on steps the CodeActAgent did to give the PlannerAgent advice
 - `enable_tracing` - Whether to enable Arize Phoenix tracing
 - `debug` - Whether to enable verbose debug logging
+- `save_trajectories` - Trajectory saving level. Can be:
+  - "none" (no saving)
+  - "step" (save per step)
+  - "action" (save per action)
 - `**kwargs` - Additional keyword arguments to pass to the agents
 
 <a id="droidrun.agent.droid.droid_agent.DroidAgent.run"></a>
@@ -59,7 +64,7 @@ Initialize the DroidAgent wrapper.
 #### DroidAgent.run
 
 ```python
-def run() -> WorkflowHandler
+def run(*args, **kwargs) -> WorkflowHandler
 ```
 
 Run the DroidAgent workflow.