droidrun 0.4.0.dev5__tar.gz → 0.4.0.dev7__tar.gz

{droidrun-0.4.0.dev5 → droidrun-0.4.0.dev7}/.gitignore

@@ -36,4 +36,6 @@ credentials.yaml
 !.github/
 
 backend/
-frontend/
+frontend/
+
+reddit_python_posts.json

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: droidrun
-Version: 0.4.0.dev5
+Version: 0.4.0.dev7
 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.dev5 → droidrun-0.4.0.dev7}/docs/v4/guides/structured-output.mdx

@@ -142,7 +142,7 @@ llm_profiles:
 
 **Programmatically:**
 ```python
-from droidrun.llm_utils import load_llm
+from droidrun import load_llm
 
 config = DroidrunConfig()
 

{droidrun-0.4.0.dev5 → droidrun-0.4.0.dev7}/docs/v4/overview.mdx

@@ -51,24 +51,28 @@ Droidrun v4 introduces a hierarchical multi-agent system with specialized agents
 Monitor and debug agent execution in real-time with Droidrun's comprehensive event system:
 
 ```python
+import asyncio
 from droidrun import DroidAgent, ResultEvent
 from droidrun.agent.droid.events import ManagerPlanEvent, ExecutorResultEvent
 from droidrun.config_manager.config_manager import DroidrunConfig
 
-# Create config with defaults
-config = DroidrunConfig()
+async def main():
+    # Create config with defaults
+    config = DroidrunConfig()
+
+    agent = DroidAgent(goal="Open Settings and enable WiFi", config=config)
+    handler = agent.run()
 
-agent = DroidAgent(goal="Open Settings and enable WiFi", config=config)
-handler = agent.run()
+    # Stream events in real-time
+    async for event in handler.stream_events():
+        if isinstance(event, ManagerPlanEvent):
+            print(f"Plan: {event.plan}")
+        elif isinstance(event, ExecutorResultEvent):
+            print(f"Action: {event.action}")
 
-# Stream events in real-time
-async for event in handler.stream_events():
-    if isinstance(event, ManagerPlanEvent):
-        print(f"Plan: {event.plan}")
-    elif isinstance(event, ExecutorResultEvent):
-        print(f"Action: {event.action}")
+    result: ResultEvent = await handler
 
-result: ResultEvent = await handler
+asyncio.run(main())
 ```
 
 Events provide rich metadata for:
@@ -125,6 +129,7 @@ llm_profiles:
 Extract type-safe, validated data from device interactions using Pydantic models:
 
 ```python
+import asyncio
 from pydantic import BaseModel, Field
 from droidrun import DroidAgent, ResultEvent
 from droidrun.config_manager.config_manager import DroidrunConfig
@@ -135,21 +140,24 @@ class ContactInfo(BaseModel):
     phone: str = Field(description="Phone number")
     email: str = Field(description="Email address")
 
-# Create config with defaults
-config = DroidrunConfig()
+async def main():
+    # Create config with defaults
+    config = DroidrunConfig()
 
-agent = DroidAgent(
-    goal="Find John Smith's contact and extract details",
-    config=config,
-    output_model=ContactInfo  # Automatic structured extraction
-)
+    agent = DroidAgent(
+        goal="Find John Smith's contact and extract details",
+        config=config,
+        output_model=ContactInfo  # Automatic structured extraction
+    )
+
+    handler = agent.run()
+    result: ResultEvent = await handler
 
-handler = agent.run()
-result: ResultEvent = await handler
+    if result.success and result.structured_output:
+        contact: ContactInfo = result.structured_output
+        print(f"Phone: {contact.phone}")
 
-if result.success and result.structured_output:
-    contact: ContactInfo = result.structured_output
-    print(f"Phone: {contact.phone}")
+asyncio.run(main())
 ```
 
 <Card title="Structured Output Guide" icon="table" href="/v4/guides/structured-output">

{droidrun-0.4.0.dev5 → droidrun-0.4.0.dev7}/droidrun/agent/codeact/codeact_agent.py

@@ -18,7 +18,6 @@ from llama_index.core.memory import Memory
 from llama_index.core.workflow import Context, StartEvent, StopEvent, Workflow, step
 
 from droidrun.agent.codeact.events import (
-    EpisodicMemoryEvent,
     TaskEndEvent,
     TaskExecutionEvent,
     TaskExecutionResultEvent,
@@ -27,7 +26,6 @@ from droidrun.agent.codeact.events import (
 )
 from droidrun.agent.common.constants import LLM_HISTORY_LIMIT
 from droidrun.agent.common.events import RecordUIStateEvent, ScreenshotEvent
-from droidrun.agent.context.episodic_memory import EpisodicMemory, EpisodicMemoryStep
 from droidrun.agent.usage import get_usage_from_response
 from droidrun.agent.utils import chat_utils
 from droidrun.agent.utils.device_state_formatter import format_device_state
@@ -43,7 +41,7 @@ from droidrun.config_manager.prompt_loader import PromptLoader
 from droidrun.tools import Tools
 
 if TYPE_CHECKING:
-    from droidrun.agent.droid.droid_agent import DroidAgentState
+    from droidrun.agent.droid import DroidAgentState
 
 logger = logging.getLogger("droidrun")
 
@@ -85,7 +83,6 @@ class CodeActAgent(Workflow):
         self.prompt_resolver = prompt_resolver or PromptResolver()
 
         self.chat_memory = None
-        self.episodic_memory = EpisodicMemory()
         self.remembered_info = None
 
         self.goal = None
@@ -459,10 +456,6 @@ Now, describe the next step you will take to address the original goal: {goal}""
         self.tools.finished = False
         await ctx.store.set("chat_memory", self.chat_memory)
 
-        # Add final state observation to episodic memory
-        if self.vision:
-            await self._add_final_state_observation(ctx)
-
         result = {}
         result.update(
             {
@@ -472,10 +465,6 @@ Now, describe the next step you will take to address the original goal: {goal}""
             }
         )
 
-        ctx.write_event_to_stream(
-            EpisodicMemoryEvent(episodic_memory=self.episodic_memory)
-        )
-
         return StopEvent(result)
 
     async def _get_llm_response(
@@ -500,26 +489,6 @@ Now, describe the next step you will take to address the original goal: {goal}""
                     ]
                 filtered_chat_history.append(filtered_msg)
 
-            # Convert chat history and response to JSON strings
-            chat_history_str = json.dumps(
-                [
-                    {"role": msg.role, "content": msg.content}
-                    for msg in filtered_chat_history
-                ]
-            )
-            response_str = json.dumps(
-                {"role": response.message.role, "content": response.message.content}
-            )
-
-            step = EpisodicMemoryStep(
-                chat_history=chat_history_str,
-                response=response_str,
-                timestamp=time.time(),
-                screenshot=(await ctx.store.get("screenshot", None)),
-            )
-
-            self.episodic_memory.steps.append(step)
-
             assert hasattr(
                 response, "message"
             ), f"LLM response does not have a message attribute.\nResponse: {response}"
@@ -577,48 +546,3 @@ Now, describe the next step you will take to address the original goal: {goal}""
             preserved_head = []
 
         return preserved_head + tail
-
-    async def _add_final_state_observation(self, ctx: Context) -> None:
-        """Add the current UI state and screenshot as the final observation step."""
-        try:
-            # Get current screenshot and UI state
-            screenshot = None
-
-            try:
-                _, screenshot_bytes = self.tools.take_screenshot()
-                screenshot = screenshot_bytes
-            except Exception as e:
-                logger.warning(f"Failed to capture final screenshot: {e}")
-
-            try:
-                state = self.tools.get_state()
-                a11y_tree = state.get("a11y_tree", "")
-                phone_state = state.get("phone_state", "")  # noqa: F841
-            except Exception as e:
-                raise Exception(f"Failed to capture final UI state: {e}") from e
-
-            # Create final observation chat history and response
-            final_chat_history = [
-                {
-                    "role": "system",
-                    "content": "Final state observation after task completion",
-                }
-            ]
-            final_response = {
-                "role": "user",
-                "content": f"Final State Observation:\nUI State: {a11y_tree}\nScreenshot: {'Available' if screenshot else 'Not available'}",
-            }
-
-            # Create final episodic memory step
-            final_step = EpisodicMemoryStep(
-                chat_history=json.dumps(final_chat_history),
-                response=json.dumps(final_response),
-                timestamp=time.time(),
-                screenshot=screenshot,
-            )
-
-            self.episodic_memory.steps.append(final_step)
-            logger.info("Added final state observation to episodic memory")
-
-        except Exception as e:
-            logger.error(f"Failed to add final state observation: {e}")

{droidrun-0.4.0.dev5 → droidrun-0.4.0.dev7}/droidrun/agent/codeact/events.py

@@ -3,7 +3,6 @@ from typing import Optional
 from llama_index.core.llms import ChatMessage
 from llama_index.core.workflow import Event
 
-from droidrun.agent.context.episodic_memory import EpisodicMemory
 from droidrun.agent.usage import UsageResult
 
 
@@ -30,7 +29,3 @@ class TaskExecutionResultEvent(Event):
 class TaskEndEvent(Event):
     success: bool
     reason: str
-
-
-class EpisodicMemoryEvent(Event):
-    episodic_memory: EpisodicMemory

{droidrun-0.4.0.dev5 → droidrun-0.4.0.dev7}/droidrun/agent/droid/__init__.py

@@ -4,7 +4,7 @@ Droidrun Agent Module.
 This module provides a ReAct agent for automating Android devices using reasoning and acting.
 """
 
-from droidrun.agent.codeact.codeact_agent import CodeActAgent
 from droidrun.agent.droid.droid_agent import DroidAgent
+from droidrun.agent.droid.state import DroidAgentState
 
-__all__ = ["CodeActAgent", "DroidAgent"]
+__all__ = ["DroidAgent", "DroidAgentState"]

{droidrun-0.4.0.dev5 → droidrun-0.4.0.dev7}/droidrun/agent/droid/droid_agent.py

@@ -18,13 +18,10 @@ from llama_index.core.workflow import Context, StartEvent, StopEvent, Workflow,
 from workflows.events import Event
 from workflows.handler import WorkflowHandler
 from droidrun.agent.codeact import CodeActAgent
-from droidrun.agent.codeact.events import EpisodicMemoryEvent
 from droidrun.agent.common.events import MacroEvent, RecordUIStateEvent, ScreenshotEvent
-from droidrun.agent.context.task_manager import Task, TaskManager
 from droidrun.agent.droid.events import (
     CodeActExecuteEvent,
     CodeActResultEvent,
-    DroidAgentState,
     ExecutorInputEvent,
     ExecutorResultEvent,
     FinalizeEvent,
@@ -34,6 +31,7 @@ from droidrun.agent.droid.events import (
     ScripterExecutorInputEvent,
     ScripterExecutorResultEvent,
 )
+from droidrun.agent.droid.state import DroidAgentState
 from droidrun.agent.executor import ExecutorAgent
 from droidrun.agent.manager import ManagerAgent
 from droidrun.agent.scripter import ScripterAgent
@@ -269,9 +267,6 @@ class DroidAgent(Workflow):
             self.structured_output_llm = llms
 
         self.trajectory = Trajectory(goal=self.shared_state.instruction)
-        self.task_manager = TaskManager()
-        self.task_iter = None
-        self.current_episodic_memory = None
 
         self.atomic_tools = ATOMIC_ACTION_SIGNATURES.copy()
 
@@ -378,14 +373,13 @@ class DroidAgent(Workflow):
         Execute a single task using the CodeActAgent.
 
         Args:
-            task: Task dictionary with description and status
+            instruction: task of what the agent shall do
 
         Returns:
             Tuple of (success, reason)
         """
-        task: Task = ev.task
 
-        logger.info(f"🔧 Executing task: {task.description}")
+        logger.info(f"🔧 Executing task: {ev.instruction}")
 
         try:
             codeact_agent = CodeActAgent(
@@ -403,7 +397,7 @@ class DroidAgent(Workflow):
             )
 
             handler = codeact_agent.run(
-                input=task.description,
+                input=ev.instruction,
                 remembered_info=self.tools_instance.memory,
             )
 
@@ -413,17 +407,21 @@ class DroidAgent(Workflow):
             result = await handler
 
             if "success" in result and result["success"]:
-                return CodeActResultEvent(
+                event = CodeActResultEvent(
                     success=True,
                     reason=result["reason"],
-                    task=task,
+                    instruction=ev.instruction,
                 )
+                ctx.write_event_to_stream(event)
+                return event
             else:
-                return CodeActResultEvent(
+                event = CodeActResultEvent(
                     success=False,
                     reason=result["reason"],
-                    task=task,
+                    instruction=ev.instruction,
                 )
+                ctx.write_event_to_stream(event)
+                return event
 
         except Exception as e:
             logger.error(f"Error during task execution: {e}")
@@ -431,26 +429,32 @@ class DroidAgent(Workflow):
                 import traceback
 
                 logger.error(traceback.format_exc())
-            return CodeActResultEvent(
-                success=False, reason=f"Error: {str(e)}", task=task
+            event = CodeActResultEvent(
+                success=False, reason=f"Error: {str(e)}", instruction=ev.instruction
             )
+            ctx.write_event_to_stream(event)
+            return event
 
     @step
     async def handle_codeact_execute(
         self, ctx: Context, ev: CodeActResultEvent
     ) -> FinalizeEvent:
         try:
-            return FinalizeEvent(success=ev.success, reason=ev.reason)
+            event = FinalizeEvent(success=ev.success, reason=ev.reason)
+            ctx.write_event_to_stream(event)
+            return event
         except Exception as e:
             logger.error(f"❌ Error during DroidAgent execution: {e}")
             if self.config.logging.debug:
                 import traceback
 
                 logger.error(traceback.format_exc())
-            return FinalizeEvent(
+            event = FinalizeEvent(
                 success=False,
                 reason=str(e),
             )
+            ctx.write_event_to_stream(event)
+            return event
 
     @step
     async def start_handler(
@@ -480,15 +484,14 @@ class DroidAgent(Workflow):
             logger.info(
                 f"🔄 Direct execution mode - executing goal: {self.shared_state.instruction}"
             )
-            task = Task(
-                description=self.shared_state.instruction,
-                status=self.task_manager.STATUS_PENDING,
-                agent_type="Default",
-            )
-            return CodeActExecuteEvent(task=task)
+            event = CodeActExecuteEvent(instruction=self.shared_state.instruction)
+            ctx.write_event_to_stream(event)
+            return event
 
         logger.info("🧠 Reasoning mode - initializing Manager/Executor workflow")
-        return ManagerInputEvent()
+        event = ManagerInputEvent()
+        ctx.write_event_to_stream(event)
+        return event
 
     # ========================================================================
     # Manager/Executor Workflow Steps
@@ -506,10 +509,12 @@ class DroidAgent(Workflow):
         """
         if self.shared_state.step_number >= self.config.agent.max_steps:
             logger.warning(f"⚠️ Reached maximum steps ({self.config.agent.max_steps})")
-            return FinalizeEvent(
+            event = FinalizeEvent(
                 success=False,
                 reason=f"Reached maximum steps ({self.config.agent.max_steps})",
             )
+            ctx.write_event_to_stream(event)
+            return event
 
         logger.info(
             f"📋 Running Manager for planning... (step {self.shared_state.step_number}/{self.config.agent.max_steps})"
@@ -525,12 +530,15 @@ class DroidAgent(Workflow):
         result = await handler
 
         # Manager already updated shared_state, just return event with results
-        return ManagerPlanEvent(
+        event = ManagerPlanEvent(
             plan=result["plan"],
             current_subgoal=result["current_subgoal"],
             thought=result["thought"],
             manager_answer=result.get("manager_answer", ""),
+            success=result.get("success"),
         )
+        ctx.write_event_to_stream(event)
+        return event
 
     @step
     async def handle_manager_plan(
@@ -543,10 +551,16 @@ class DroidAgent(Workflow):
         """
         # Check for answer-type termination
         if ev.manager_answer.strip():
-            logger.info(f"💬 Manager provided answer: {ev.manager_answer}")
+            # Use success field from manager, default to True if not set for backward compatibility
+            success = ev.success if ev.success is not None else True
+            logger.info(
+                f"💬 Manager provided answer (success={success}): {ev.manager_answer}"
+            )
             self.shared_state.progress_status = f"Answer: {ev.manager_answer}"
 
-            return FinalizeEvent(success=True, reason=ev.manager_answer)
+            event = FinalizeEvent(success=success, reason=ev.manager_answer)
+            ctx.write_event_to_stream(event)
+            return event
 
         # Check for <script> tag in current_subgoal, then extract from full plan
         if "<script>" in ev.current_subgoal:
@@ -558,7 +572,9 @@ class DroidAgent(Workflow):
                 # Extract content between first <script> and first </script> in plan
                 task = ev.plan[start_idx + len("<script>") : end_idx].strip()
                 logger.info(f"🐍 Routing to ScripterAgent: {task[:80]}...")
-                return ScripterExecutorInputEvent(task=task)
+                event = ScripterExecutorInputEvent(task=task)
+                ctx.write_event_to_stream(event)
+                return event
             else:
                 # <script> found in subgoal but not properly closed in plan - log warning
                 logger.warning(
@@ -567,7 +583,9 @@ class DroidAgent(Workflow):
 
         # Continue to Executor with current subgoal
         logger.info(f"▶️  Proceeding to Executor with subgoal: {ev.current_subgoal}")
-        return ExecutorInputEvent(current_subgoal=ev.current_subgoal)
+        event = ExecutorInputEvent(current_subgoal=ev.current_subgoal)
+        ctx.write_event_to_stream(event)
+        return event
 
     @step
     async def run_executor(
@@ -599,12 +617,14 @@ class DroidAgent(Workflow):
         self.shared_state.last_action_thought = result.get("thought", "")
         self.shared_state.action_pool.append(result["action_json"])
 
-        return ExecutorResultEvent(
+        event = ExecutorResultEvent(
             action=result["action"],
             outcome=result["outcome"],
             error=result["error"],
             summary=result["summary"],
         )
+        ctx.write_event_to_stream(event)
+        return event
 
     @step
     async def handle_executor_result(
@@ -635,7 +655,9 @@ class DroidAgent(Workflow):
             f"🔄 Step {self.shared_state.step_number}/{self.config.agent.max_steps} complete, looping to Manager"
         )
 
-        return ManagerInputEvent()
+        event = ManagerInputEvent()
+        ctx.write_event_to_stream(event)
+        return event
 
     # ========================================================================
     # Script Executor Workflow Steps
@@ -682,12 +704,14 @@ class DroidAgent(Workflow):
 
         logger.info(f"🐍 ScripterAgent finished: {result['message'][:2000]}...")
 
-        return ScripterExecutorResultEvent(
+        event = ScripterExecutorResultEvent(
             task=ev.task,
             message=result["message"],
             success=result["success"],
             code_executions=result.get("code_executions", 0),
         )
+        ctx.write_event_to_stream(event)
+        return event
 
     @step
     async def handle_scripter_result(
@@ -710,7 +734,9 @@ class DroidAgent(Workflow):
         )
 
         # Loop back to Manager (script result in shared_state)
-        return ManagerInputEvent()
+        event = ManagerInputEvent()
+        ctx.write_event_to_stream(event)
+        return event
 
     # ========================================================================
     # End Manager/Executor/Script Workflow Steps
@@ -751,7 +777,7 @@ class DroidAgent(Workflow):
                     timeout=self.timeout,
                 )
 
-                handler = await structured_agent.run()
+                handler = structured_agent.run()
 
                 # Stream nested events
                 async for nested_ev in handler.stream_events():
@@ -782,10 +808,6 @@ class DroidAgent(Workflow):
         return result
 
     def handle_stream_event(self, ev: Event, ctx: Context):
-        if isinstance(ev, EpisodicMemoryEvent):
-            self.current_episodic_memory = ev.episodic_memory
-            return
-
         if not isinstance(ev, StopEvent):
             ctx.write_event_to_stream(ev)
 

droidrun-0.4.0.dev7/droidrun/agent/droid/events.py

@@ -0,0 +1,124 @@
+"""
+DroidAgent coordination events.
+
+These events are used for WORKFLOW COORDINATION between DroidAgent and its child agents.
+They carry minimal data needed for routing workflow steps.
+
+For internal events with full debugging metadata, see:
+- manager/events.py (ManagerInternalPlanEvent)
+- executor/events.py (ExecutorInternalActionEvent, ExecutorInternalResultEvent)
+"""
+
+from typing import Dict
+
+from llama_index.core.workflow import Event, StopEvent
+from pydantic import BaseModel
+
+
+class CodeActExecuteEvent(Event):
+    instruction: str
+
+
+class CodeActResultEvent(Event):
+    success: bool
+    reason: str
+    instruction: str
+
+
+class FinalizeEvent(Event):
+    success: bool
+    reason: str
+
+
+class ResultEvent(StopEvent):
+    """
+    DroidAgent final result event.
+
+    Returned by DroidAgent.run() with attributes:
+    - success: Whether the task completed successfully
+    - reason: Explanation of the result or error message
+    - steps: Number of steps taken
+    - structured_output: Extracted structured data (if output_model was provided)
+    """
+
+    success: bool
+    reason: str
+    steps: int
+    structured_output: BaseModel | None
+
+
+class TaskRunnerEvent(Event):
+    pass
+
+
+# ============================================================================
+# Manager/Executor coordination events
+# ============================================================================
+
+
+class ManagerInputEvent(Event):
+    """Trigger Manager workflow for planning"""
+
+    pass
+
+
+class ManagerPlanEvent(Event):
+    """
+    Coordination event from ManagerAgent to DroidAgent.
+
+    Used for workflow step routing only (NOT streamed to frontend).
+    For internal events with memory_update metadata, see ManagerInternalPlanEvent.
+    """
+
+    plan: str
+    current_subgoal: str
+    thought: str
+    manager_answer: str = ""
+    success: bool | None = (
+        None  # True/False if task complete, None if still in progress
+    )
+
+
+class ExecutorInputEvent(Event):
+    """Trigger Executor workflow for action execution"""
+
+    current_subgoal: str
+
+
+class ExecutorResultEvent(Event):
+    """
+    Coordination event from ExecutorAgent to DroidAgent.
+
+    Used for workflow step routing only (NOT streamed to frontend).
+    For internal events with thought/action_json metadata, see ExecutorInternalResultEvent.
+    """
+
+    action: Dict
+    outcome: bool
+    error: str
+    summary: str
+    full_response: str = ""
+
+
+# ============================================================================
+# Script executor coordination events
+# ============================================================================
+
+
+class ScripterExecutorInputEvent(Event):
+    """Trigger ScripterAgent workflow for off-device operations"""
+
+    task: str
+
+
+class ScripterExecutorResultEvent(Event):
+    """
+    Coordination event from ScripterAgent to DroidAgent.
+
+    Used for workflow step routing only (NOT streamed to frontend).
+    """
+
+    task: str
+    message: str  # Response from response() function
+    success: bool
+    code_executions: int