droidrun 0.4.0.dev4__tar.gz → 0.4.0.dev5__tar.gz

{droidrun-0.4.0.dev4 → droidrun-0.4.0.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: droidrun
-Version: 0.4.0.dev4
+Version: 0.4.0.dev5
 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

{droidrun-0.4.0.dev4 → droidrun-0.4.0.dev5}/docs/docs.json

@@ -23,21 +23,12 @@
                   "v4/quickstart"
                 ]
               },
-              {
-                "group": "Concepts",
-                "pages": [
-                  "v4/concepts/architecture",
-                  "v4/concepts/workflow-architecture",
-                  "v4/concepts/event-streaming"
-                ]
-              },
               {
                 "group": "Guides",
                 "pages": [
                   "v4/guides/overview",
-                  "v4/guides/cli",
-                  "v4/guides/configuration",
                   "v4/guides/device-setup",
+                  "v4/guides/cli",
                   "v4/guides/custom-tools-credentials",
                   "v4/guides/custom-variables",
                   "v4/guides/app-cards",
@@ -45,13 +36,26 @@
                   "v4/guides/telemetry-tracing"
                 ]
               },
+              {
+                "group": "Concepts",
+                "pages": [
+                  "v4/concepts/overview",
+                  "v4/concepts/agent-architecture",
+                  "v4/concepts/scripter-agent",
+                  "v4/concepts/shared-state",
+                  "v4/concepts/events-and-workflows",
+                  "v4/concepts/prompts"
+                ]
+              },
               {
                 "group": "SDK Reference",
                 "pages": [
+                  "v4/sdk",
                   "v4/sdk/droid-agent",
                   "v4/sdk/adb-tools",
                   "v4/sdk/ios-tools",
-                  "v4/sdk/base-tools"
+                  "v4/sdk/base-tools",
+                  "v4/sdk/configuration"
                 ]
               }
             ]
@@ -85,15 +89,6 @@
                   "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"
-                ]
               }
             ]
           },

{droidrun-0.4.0.dev4 → droidrun-0.4.0.dev5}/docs/v1/concepts/portal-app.mdx

@@ -48,7 +48,7 @@ The DroidRun Portal App:
 
 ## 🚀 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.
+The DroidRun Portal App is available from the [DroidRun Portal repository](https://github.com/droidrun/droidrun-portal). For installation instructions, see the [Quickstart](/v1/quickstart) guide.
 
 ## 🔧 Troubleshooting
 

{droidrun-0.4.0.dev4 → droidrun-0.4.0.dev5}/docs/v1/quickstart.mdx

@@ -289,5 +289,5 @@ pip show droidrun
 
 Now that you've got DroidRun running, you can:
 
-- Learn about the [ReAct agent system](/concepts/agent)
-- Discover all [Android interactions](/concepts/android-control) 
+- Learn about the [ReAct agent system](/v1/concepts/agent)
+- Discover all [Android interactions](/v1/concepts/android-control) 

{droidrun-0.4.0.dev4 → droidrun-0.4.0.dev5}/docs/v2/concepts/portal-app.mdx

@@ -48,7 +48,7 @@ The DroidRun Portal App:
 
 ## 🚀 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.
+The DroidRun Portal App is available from the [DroidRun Portal repository](https://github.com/droidrun/droidrun-portal). For installation instructions, see the [Quickstart](/v2/quickstart) guide.
 
 ## 🔧 Troubleshooting
 

{droidrun-0.4.0.dev4 → droidrun-0.4.0.dev5}/docs/v3/concepts/android-tools.mdx

@@ -100,4 +100,4 @@ format, image_data = await tools.take_screenshot()
 | `complete(success, reason)` | Finish task | None |
 
 ## Dive Deeper
-You can find the SDK Reference for AdbTools [here](../sdk/adb-tools)
+SDK reference documentation is available in the v4 documentation.

droidrun-0.4.0.dev5/docs/v4/concepts/agent-architecture.mdx

@@ -0,0 +1,241 @@
+---
+title: 'Multi-Agent Architecture'
+description: 'Droidrun v4 hierarchical agent system with specialized roles for planning, execution, and computation.'
+---
+
+## What is Multi-Agent Architecture?
+
+Droidrun v4 uses a **hierarchical multi-agent system** where specialized agents work together:
+
+- **DroidAgent**: Main orchestrator coordinating all agents
+- **ManagerAgent**: Strategic planner creating task plans
+- **ExecutorAgent**: Tactical actor executing atomic actions
+- **CodeActAgent**: Direct code generator for simple tasks
+- **ScripterAgent**: Off-device Python executor for API calls, file operations, and computations
+
+**Location**: `droidrun/agent/droid/droid_agent.py`
+
+## How It Works
+
+```
+DroidAgent (orchestrator)
+├── Reasoning Mode: ManagerAgent → ExecutorAgent → ScripterAgent
+└── Direct Mode: CodeActAgent
+```
+
+All agents share `DroidAgentState` for coordination and communicate through events.
+
+## DroidAgent (Orchestrator)
+
+Entry point for all tasks. Routes to appropriate agents based on mode.
+
+```python
+from droidrun.agent.droid import DroidAgent
+from droidrun.config_manager import DroidrunConfig
+
+
+config = DroidrunConfig()
+
+# Reasoning mode (complex tasks)
+agent = DroidAgent(reasoning=True, config=config)
+
+# Direct mode (simple tasks)
+agent = DroidAgent(reasoning=False, config=config)
+
+result = agent.run("Send message to John")
+```
+
+## ManagerAgent (Planner)
+
+Creates strategic plans and breaks tasks into subgoals.
+
+**Location**: `droidrun/agent/manager/manager_agent.py:46`
+
+```python
+class ManagerPlan(BaseModel):
+    current_subgoal: str  # Next subgoal for Executor
+    reasoning: str        # Why this subgoal
+    should_finalize: bool # Task complete?
+    script_block: str | None  # Python for ScripterAgent
+    full_plan: List[str]  # Complete plan
+```
+
+**Configuration:**
+```yaml
+agent:
+  manager:
+    max_steps: 10
+    vision: true
+
+llm_profiles:
+  manager:
+    provider: Anthropic
+    model: claude-sonnet-4
+    temperature: 0.7
+```
+
+## ExecutorAgent (Actor)
+
+Executes atomic actions for each subgoal.
+
+**Location**: `droidrun/agent/executor/executor_agent.py`
+
+```python
+class ExecutorAction(BaseModel):
+    action: str        # "click", "type", "swipe", etc.
+    parameters: dict   # Action parameters
+    reasoning: str     # Why this action
+
+class ExecutorResult(BaseModel):
+    success: bool      # Action succeeded?
+    outcome: str       # What happened
+    error_message: str | None
+```
+
+**Configuration:**
+```yaml
+agent:
+  executor:
+    max_steps: 5
+    vision: true
+
+llm_profiles:
+  executor:
+    provider: OpenAI
+    model: gpt-4o
+    temperature: 0.3
+```
+
+## CodeActAgent (Direct Executor)
+
+Generates Python code using atomic actions (no planning overhead).
+
+**Location**: `droidrun/agent/codeact/codeact_agent.py`
+
+```python
+# Available functions in CodeAct
+click(index: int)
+long_press(index: int)
+type(text: str, index: int = None)
+swipe(coordinate: tuple, coordinate2: tuple)
+system_button(button: str)
+open_app(text: str)
+get_state() -> dict
+take_screenshot() -> str
+remember(information: str)
+complete(success: bool, reason: str)
+```
+
+**Configuration:**
+```yaml
+agent:
+  codeact:
+    max_steps: 15
+    vision: false
+    safe_execution:
+      enabled: true
+
+llm_profiles:
+  codeact:
+    provider: GoogleGenAI
+    model: models/gemini-2.0-flash-exp
+```
+
+## ScripterAgent (Python Executor)
+
+Executes off-device Python for API calls, file operations, data processing, and computations.
+
+**Location**: `droidrun/agent/scripter/`
+
+Triggered when Manager delegates tasks requiring off-device computation. ScripterAgent is a **ReAct agent** that iteratively generates and executes Python code, then returns a final message to Manager.
+
+```python
+# Manager delegates with context + task
+"""
+User needs weather in San Francisco for clothing decision.
+Task: Fetch current weather and report temperature + conditions
+API: https://api.weather.com/forecast?city=San Francisco
+"""
+
+# ScripterAgent (ReAct loop):
+# 1. Generates code
+import requests
+response = requests.get("https://api.weather.com/forecast",
+                       params={"city": "San Francisco"})
+print(response.json())
+
+# 2. Observes output: {'temp': 62, 'description': 'Partly cloudy'}
+
+# 3. Returns message to Manager:
+"The weather in San Francisco is 62°F with partly cloudy conditions."
+```
+
+**Configuration:**
+```yaml
+agent:
+  scripter:
+    max_steps: 10
+    safe_execution:
+      enabled: true
+      allowed_modules:
+        - datetime
+        - json
+        - requests
+```
+
+## Agent Coordination
+
+### Shared State
+
+All agents read/write `DroidAgentState`:
+
+```python
+state = DroidAgentState(
+    task="Book flight",
+    action_history=[],
+    visited_packages=[],
+    error_count=0,
+    scripter_results={},
+    manager_plan="",
+    executor_feedback="",
+    step_count=0
+)
+```
+
+### Event Flow (Reasoning Mode)
+
+```
+StartEvent
+  ↓
+ManagerInputEvent → run_manager()
+  ↓
+ManagerPlanEvent → handle_manager_plan()
+  ↓
+ExecutorInputEvent → run_executor()
+  ↓
+ExecutorResultEvent → handle_executor_result()
+  ↓
+[loop or finalize]
+  ↓
+FinalizeEvent → finalize()
+  ↓
+ResultEvent (StopEvent)
+```
+
+## Quick Reference
+
+| Agent | Role | Best For | Config Key |
+|-------|------|----------|------------|
+| DroidAgent | Orchestrator | Entry point | `agent.*` |
+| ManagerAgent | Planner | Strategy, recovery | `agent.manager.*` |
+| ExecutorAgent | Actor | Action execution | `agent.executor.*` |
+| CodeActAgent | Direct | Simple tasks | `agent.codeact.*` |
+| ScripterAgent | Python Executor | APIs, files, data | `agent.scripter.*` |
+
+## Related Topics
+
+- [Reasoning Mode](./reasoning-mode) - Manager → Executor workflow
+- [Direct Mode](./direct-mode) - CodeActAgent workflow
+- [ScripterAgent](./scripter-agent) - Off-device computation
+- [Shared State](./shared-state) - DroidAgentState coordination
+- [Configuration](./configuration) - Per-agent LLM profiles

droidrun-0.4.0.dev5/docs/v4/concepts/events-and-workflows.mdx

@@ -0,0 +1,165 @@
+---
+title: 'Event Streaming'
+description: 'How to consume real-time events from DroidAgent execution.'
+---
+
+## Overview
+
+Droidrun provides **real-time event streaming** that gives you visibility into agent execution as it happens. This allows you to build UIs, logging systems, or monitoring tools that react to agent actions in real-time.
+
+Under the hood, Droidrun uses [llama-index workflows](https://docs.llamaindex.ai/en/stable/understanding/workflows/) - an event-driven orchestration system that powers the agent architecture.
+
+## Basic Usage
+
+```python
+from droidrun.agent.droid import DroidAgent
+
+# Create and run agent
+agent = DroidAgent(goal="Open Gmail and check inbox", config=config)
+handler = agent.run()
+
+# Stream events in real-time
+async for event in handler.stream_events():
+    if isinstance(event, ManagerInternalPlanEvent):
+        print(f"📋 Plan: {event.plan}")
+        print(f"🎯 Current subgoal: {event.current_subgoal}")
+
+    elif isinstance(event, ExecutorInternalActionEvent):
+        print(f"⚡ Action: {event.description}")
+        print(f"💭 Thought: {event.thought}")
+
+    elif isinstance(event, ScreenshotEvent):
+        save_screenshot(event.screenshot, f"step_{event.step}.png")
+
+    elif isinstance(event, CodeGenerationEvent):
+        print(f"🐍 Generated code (step {event.step_number}):")
+        print(event.code)
+
+# Wait for final result
+result = await handler
+print(f"✅ Success: {result.success}")
+print(f"📝 Reason: {result.reason}")
+```
+
+## Event Types
+
+### Planning Events
+
+**ManagerInternalPlanEvent** - Emitted when Manager creates/updates a plan:
+```python
+class ManagerInternalPlanEvent(Event):
+    plan: str              # Full task plan with subgoals
+    current_subgoal: str   # Current subgoal being executed
+    thought: str           # Manager's reasoning
+    manager_answer: str    # Direct answer (if task is complete)
+```
+
+### Execution Events
+
+**ExecutorInternalActionEvent** - Emitted when Executor selects an action:
+```python
+class ExecutorInternalActionEvent(Event):
+    action_json: str    # JSON representation of selected action
+    thought: str        # Executor's reasoning
+    description: str    # Human-readable action description
+```
+
+**CodeGenerationEvent** - Emitted when CodeAct generates code:
+```python
+class CodeGenerationEvent(Event):
+    code: str          # Generated Python code
+    step_number: int   # Current step in execution
+```
+
+**CodeExecutionResultEvent** - Emitted after code execution:
+```python
+class CodeExecutionResultEvent(Event):
+    success: bool    # Whether execution succeeded
+    output: str      # Execution output or error message
+```
+
+### Visual Events
+
+**ScreenshotEvent** - Emitted when a screenshot is captured:
+```python
+class ScreenshotEvent(Event):
+    screenshot: bytes  # PNG image data
+    step: int         # Step number
+```
+
+**AccessibilityTreeEvent** - Emitted when UI tree is captured:
+```python
+class AccessibilityTreeEvent(Event):
+    tree: str         # Accessibility tree dump
+    step: int         # Step number
+```
+
+## Common Patterns
+
+### Building a Live UI
+
+```python
+async def run_with_ui(goal: str):
+    agent = DroidAgent(goal=goal, config=config)
+    handler = agent.run()
+
+    async for event in handler.stream_events():
+        if isinstance(event, ManagerInternalPlanEvent):
+            ui.update_plan(event.plan)
+            ui.update_current_step(event.current_subgoal)
+
+        elif isinstance(event, ExecutorInternalActionEvent):
+            ui.add_action_log(event.description, event.thought)
+
+        elif isinstance(event, ScreenshotEvent):
+            ui.update_screenshot(event.screenshot)
+
+    result = await handler
+    ui.show_completion(result.success, result.reason)
+```
+
+### Logging and Monitoring
+
+```python
+import logging
+
+logger = logging.getLogger("droidrun.monitor")
+
+async def monitor_execution(goal: str):
+    agent = DroidAgent(goal=goal, config=config)
+    handler = agent.run()
+
+    start_time = time.time()
+    action_count = 0
+
+    async for event in handler.stream_events():
+        if isinstance(event, ExecutorInternalActionEvent):
+            action_count += 1
+            logger.info(f"Action {action_count}: {event.description}")
+
+        elif isinstance(event, CodeExecutionResultEvent):
+            if not event.success:
+                logger.error(f"Code execution failed: {event.output}")
+
+    result = await handler
+    duration = time.time() - start_time
+
+    logger.info(f"Task completed in {duration:.2f}s with {action_count} actions")
+    logger.info(f"Result: {result.success} - {result.reason}")
+```
+
+## Notes
+
+- Events are **streamed in real-time** as the agent executes
+- Not all events are emitted in every execution (depends on mode and actions)
+- **Reasoning mode** emits `ManagerInternalPlanEvent` and `ExecutorInternalActionEvent`
+- **Direct mode** emits `CodeGenerationEvent` and `CodeExecutionResultEvent`
+- All events are **Pydantic models** with full type safety
+- The `handler` object is **async** - always use `await handler` to get the final result
+
+## Learn More
+
+- [LlamaIndex Workflows](https://docs.llamaindex.ai/en/stable/understanding/workflows/) - The underlying orchestration system
+- [Agent Architecture](./agent-architecture) - Multi-agent system overview
+- [Reasoning Mode](./reasoning-mode) - Manager/Executor workflow details
+- [Direct Mode](./direct-mode) - CodeAct workflow details

droidrun-0.4.0.dev5/docs/v4/concepts/overview.mdx

@@ -0,0 +1,107 @@
+---
+title: 'Architecture Overview'
+description: 'Understanding Droidrun v4 multi-agent system for device automation.'
+---
+
+## What is Droidrun?
+
+Droidrun uses a **multi-agent architecture** where specialized agents work together to complete tasks. Instead of one agent doing everything, different agents handle planning, execution, and computation.
+
+### Two Execution Modes
+
+- **Reasoning Mode** (`reasoning=True`): Manager plans, Executor acts. Best for complex tasks.
+- **Direct Mode** (`reasoning=False`): CodeActAgent executes immediately. Best for simple tasks.
+
+## Core Agents
+
+### DroidAgent (Orchestrator)
+Main coordinator that manages the workflow and routes between agents.
+
+**Location**: `droidrun/agent/droid/droid_agent.py:75`
+
+### ManagerAgent (Planner)
+Creates high-level plans and monitors progress. Only used in reasoning mode.
+
+**Location**: `droidrun/agent/manager/manager_agent.py:46`
+
+### ExecutorAgent (Actor)
+Executes specific actions for each subgoal. Only used in reasoning mode.
+
+**Location**: `droidrun/agent/executor/executor_agent.py:46`
+
+### CodeActAgent (Direct Executor)
+Generates and executes Python code directly. Used in direct mode.
+
+**Location**: `droidrun/agent/codeact/codeact_agent.py`
+
+### ScripterAgent (Off-Device)
+Handles Python computations without device interaction (API calls, calculations).
+
+**Location**: `droidrun/agent/scripter/`
+
+## Workflow Comparison
+
+### Reasoning Mode Flow
+```
+Goal → Manager (creates plan) → Executor (executes action) →
+Manager (checks result) → Executor (next action) → ...
+```
+
+### Direct Mode Flow
+```
+Goal → CodeActAgent (generates code) → Execute → Done
+```
+
+## Per-Agent Configuration
+
+Configure different LLMs for each agent:
+
+```yaml
+# config.yaml
+llm_profiles:
+  manager:
+    provider: Anthropic
+    model: claude-sonnet-4
+
+  executor:
+    provider: OpenAI
+    model: gpt-4o
+
+  codeact:
+    provider: GoogleGenAI
+    model: models/gemini-2.0-flash-exp
+
+agent:
+  reasoning: true
+  max_steps: 15
+```
+
+## When to Use Each Mode
+
+**Use Reasoning Mode for:**
+- Multi-step tasks (booking flights, configuring settings)
+- Tasks requiring planning and adaptation
+- Complex workflows across multiple apps
+
+**Use Direct Mode for:**
+- Simple actions (screenshots, sending messages)
+- Fast execution without planning overhead
+- Well-defined single-step tasks
+
+## Key Features
+
+### Shared State
+All agents share `DroidAgentState` for coordination:
+- Action history
+- Error tracking
+- Memory and context
+- Script results
+
+## Dive Deeper
+
+- [Agent Architecture](./agent-architecture) - Detailed design
+- [Reasoning Mode](./reasoning-mode) - Manager/Executor workflow
+- [Direct Mode](./direct-mode) - CodeAct workflow
+- [Configuration](./configuration) - Setup and LLM profiles
+- [Custom Tools](./custom-tools) - Extending functionality
+- [Migration Guide](./migration-guide) - Upgrading from v3