Plan execute pattern on UI

flo_ai/docs/plan_execution_guide.md

@@ -0,0 +1,123 @@
+# Plan Execution Framework Guide
+
+The Flo AI framework provides built-in support for plan-and-execute workflows, making it easy to create multi-step, coordinated agent workflows.
+
+## Quick Start
+
+### 1. Basic Software Development Workflow
+
+```python
+import asyncio
+from flo_ai.llm import OpenAI
+from flo_ai.arium.memory import PlanAwareMemory
+from flo_ai.arium.llm_router import create_plan_execute_router
+from flo_ai.arium import AriumBuilder
+from flo_ai.models.plan_agents import create_software_development_agents
+
+async def main():
+    # Setup (3 lines!)
+    llm = OpenAI(model='gpt-4o', api_key='your-key')
+    memory = PlanAwareMemory()
+    agents = create_software_development_agents(memory, llm)
+
+    # Create router
+    router = create_plan_execute_router(
+        planner_agent='planner',
+        executor_agent='developer',
+        reviewer_agent='reviewer',
+        additional_agents={'tester': 'Tests implementations'},
+        llm=llm,
+    )
+
+    # Build workflow
+    agent_list = list(agents.values())
+    arium = (
+        AriumBuilder()
+        .with_memory(memory)
+        .add_agents(agent_list)
+        .start_with(agents['planner'])
+        .add_edge(agents['planner'], agent_list, router)
+        .add_edge(agents['developer'], agent_list, router)
+        .add_edge(agents['tester'], agent_list, router)
+        .add_edge(agents['reviewer'], agent_list, router)
+        .end_with(agents['reviewer'])
+        .build()
+    )
+
+    # Execute
+    result = await arium.run(['Create a user authentication API'])
+
+asyncio.run(main())
+```
+
+### 2. Custom Plan Workflow
+
+```python
+from flo_ai.models.plan_agents import PlannerAgent, ExecutorAgent
+
+# Create custom agents
+planner = PlannerAgent(memory, llm, name='planner')
+researcher = ExecutorAgent(memory, llm, name='researcher')
+analyst = ExecutorAgent(memory, llm, name='analyst')
+writer = ExecutorAgent(memory, llm, name='writer')
+
+# Use the same pattern as above with your custom agents
+```
+
+## Key Components
+
+### Plan Agents
+
+- **`PlannerAgent`**: Creates execution plans automatically
+- **`ExecutorAgent`**: Executes plan steps and tracks progress
+- **`create_software_development_agents()`**: Pre-configured dev team
+
+### Plan Tools
+
+- **`PlanTool`**: Parses and stores execution plans (from `flo_ai.tool.plan_tool`)
+- **`StepTool`**: Marks steps as completed (from `flo_ai.tool.plan_tool`)
+- **`PlanStatusTool`**: Checks plan progress (from `flo_ai.tool.plan_tool`)
+
+### Memory
+
+- **`PlanAwareMemory`**: Stores both conversations and execution plans
+
+### Router
+
+- **`create_plan_execute_router()`**: Intelligent routing for plan workflows
+
+## How It Works
+
+1. **Planning Phase**: Router sends task to planner agent
+2. **Plan Storage**: Planner creates and stores ExecutionPlan in memory
+3. **Execution Phase**: Router routes to appropriate agents based on plan steps
+4. **Progress Tracking**: Agents mark steps as completed using tools
+5. **Completion**: Router detects when all steps are done
+
+## Plan Format
+
+Plans are created in this standard format:
+
+```
+EXECUTION PLAN: [Title]
+DESCRIPTION: [Description]
+
+STEPS:
+1. step_1: [Task description] → agent_name
+2. step_2: [Task description] → agent_name (depends on: step_1)
+3. step_3: [Task description] → agent_name (depends on: step_1, step_2)
+```
+
+## Benefits
+
+- **Minimal Code**: Pre-built components handle all the complexity
+- **Automatic Plan Management**: Plans are created, stored, and tracked automatically
+- **Flexible**: Create custom agents for any domain
+- **Robust**: Built-in error handling and progress tracking
+- **Reusable**: Tools and agents work across different workflows
+
+## Examples
+
+See the `examples/` directory for:
+- `fixed_plan_execute_demo.py` - Basic software development workflow
+- `custom_plan_execute_demo.py` - Custom research workflow

flo_ai/examples/custom_plan_execute_demo.py

@@ -0,0 +1,127 @@
+"""
+Custom Plan-Execute Demo - Creating Your Own Plan Workflows
+
+This demo shows how to create custom plan-execute workflows
+using the framework's plan execution components.
+"""
+
+import asyncio
+import os
+from flo_ai.llm import OpenAI
+from flo_ai.arium.memory import PlanAwareMemory
+from flo_ai.arium.llm_router import create_plan_execute_router
+from flo_ai.arium import AriumBuilder
+from flo_ai.models.plan_agents import PlannerAgent, ExecutorAgent
+
+
+async def main():
+    """Custom plan-execute workflow example"""
+    print('🎯 Custom Plan-Execute Demo')
+    print('=' * 35)
+
+    # Check API key
+    api_key = os.getenv('OPENAI_API_KEY')
+    if not api_key:
+        print('❌ OPENAI_API_KEY environment variable not set')
+        return
+
+    # Setup
+    llm = OpenAI(model='gpt-4o', api_key=api_key)
+    memory = PlanAwareMemory()
+
+    # Create custom agents for research workflow
+    planner = PlannerAgent(
+        memory=memory,
+        llm=llm,
+        name='planner',
+        system_prompt="""You are a research project planner. Create plans for research tasks.
+
+EXECUTION PLAN: [Title]
+DESCRIPTION: [Description]
+
+STEPS:
+1. step_1: [Research task] → researcher
+2. step_2: [Analysis task] → analyst (depends on: step_1)
+3. step_3: [Writing task] → writer (depends on: step_2)
+
+Use agents: researcher, analyst, writer
+IMPORTANT: After generating the plan, use store_execution_plan to save it.""",
+    )
+
+    researcher = ExecutorAgent(
+        memory=memory,
+        llm=llm,
+        name='researcher',
+        system_prompt="""You are a researcher who gathers information and data.
+Check plan status first, then execute research steps thoroughly.""",
+    )
+
+    analyst = ExecutorAgent(
+        memory=memory,
+        llm=llm,
+        name='analyst',
+        system_prompt="""You are an analyst who processes and analyzes research data.
+Check plan status first, then execute analysis steps thoroughly.""",
+    )
+
+    writer = ExecutorAgent(
+        memory=memory,
+        llm=llm,
+        name='writer',
+        system_prompt="""You are a writer who creates reports and summaries.
+Check plan status first, then execute writing steps thoroughly.""",
+    )
+
+    agents = [planner, researcher, analyst, writer]
+
+    # Create router
+    router = create_plan_execute_router(
+        planner_agent='planner',
+        executor_agent='researcher',
+        reviewer_agent='writer',
+        additional_agents={'analyst': 'Analyzes research data and findings'},
+        llm=llm,
+    )
+
+    # Build workflow
+    arium = (
+        AriumBuilder()
+        .with_memory(memory)
+        .add_agents(agents)
+        .start_with(planner)
+        .add_edge(planner, agents, router)
+        .add_edge(researcher, agents, router)
+        .add_edge(analyst, agents, router)
+        .add_edge(writer, agents, router)
+        .end_with(writer)
+        .build()
+    )
+
+    # Execute task
+    task = 'Research the impact of AI on software development productivity'
+    print(f'📋 Task: {task}')
+    print('🔄 Executing custom research workflow...\n')
+
+    try:
+        result = await arium.run([task])
+
+        print('\n' + '=' * 40)
+        print('🎉 CUSTOM WORKFLOW COMPLETED!')
+        print('=' * 40)
+
+        if result:
+            final_result = result[-1] if isinstance(result, list) else result
+            print(f'\n📄 Final Result:\n{final_result}')
+
+        # Show plan status
+        current_plan = memory.get_current_plan()
+        if current_plan:
+            print(f'\n📊 Plan: {current_plan.title}')
+            print(f'✅ Completed: {current_plan.is_completed()}')
+
+    except Exception as e:
+        print(f'❌ Error: {e}')
+
+
+if __name__ == '__main__':
+    asyncio.run(main())