Release v2.3.21

README.md

@@ -112,6 +112,11 @@ PraisonAI is a production-ready Multi-AI Agents framework with self-reflection,
 | 🤖 Workflow with Agents | [Example](examples/python/workflows/workflow_with_agents.py) | [📖](https://docs.praison.ai/features/workflows) |
 | 🔄 Conditional Steps | [Example](examples/python/workflows/workflow_conditional.py) | [📖](https://docs.praison.ai/features/workflows) |
 | 🎭 Mixed Steps | [Example](examples/python/workflows/workflow_mixed_steps.py) | [📖](https://docs.praison.ai/features/workflows) |
+| 🔀 Agentic Routing | [Example](examples/python/workflows/workflow_routing.py) | [📖](https://docs.praison.ai/features/workflow-routing) |
+| ⚡ Parallel Execution | [Example](examples/python/workflows/workflow_parallel.py) | [📖](https://docs.praison.ai/features/workflow-parallel) |
+| 🔁 Loop over List | [Example](examples/python/workflows/workflow_loop_list.py) | [📖](https://docs.praison.ai/features/workflow-loop) |
+| 📄 Loop over CSV | [Example](examples/python/workflows/workflow_loop_csv.py) | [📖](https://docs.praison.ai/features/workflow-loop) |
+| 🔄 Evaluator-Optimizer | [Example](examples/python/workflows/workflow_repeat.py) | [📖](https://docs.praison.ai/features/workflow-repeat) |
 
 ## Supported Providers
 
@@ -456,6 +461,17 @@ result = asyncio.run(manager.aexecute("deploy", default_llm="gpt-4o-mini"))
 - **Branching**: Use `next_steps` and `branch_condition` for conditional routing
 - **Loops**: Use `loop_over` and `loop_var` to iterate over data
 
+### Choosing the Right Workflow System
+
+| Use Case | Recommended |
+|----------|-------------|
+| Simple function pipelines | `Workflow` class ⭐ |
+| Agent-only pipelines | `Workflow` class |
+| CSV batch processing | `process="workflow"` |
+| Complex task routing | `process="workflow"` |
+| Markdown templates | `WorkflowManager` |
+| Early stop / conditional | `Workflow` class |
+
 ### Simple Workflow (Recommended)
 
 The easiest way to create workflows - just pass functions as steps:
@@ -506,6 +522,48 @@ loop_step = WorkflowStep(
 )
 ```
 
+### Workflow Patterns (route, parallel, loop, repeat)
+
+```python
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+# Or use Pipeline (alias for Workflow)
+from praisonaiagents import Pipeline
+from praisonaiagents.workflows import route, parallel, loop, repeat
+
+# 1. ROUTING - Decision-based branching
+workflow = Workflow(steps=[
+    classify_request,  # Returns "approve" or "reject"
+    route({
+        "approve": [approve_handler],
+        "reject": [reject_handler],
+        "default": [fallback_handler]
+    })
+])
+
+# 2. PARALLEL - Concurrent execution
+workflow = Workflow(steps=[
+    parallel([research_market, research_competitors, research_customers]),
+    summarize_results  # Gets all parallel outputs
+])
+
+# 3. LOOP - Iterate over list or CSV
+workflow = Workflow(
+    steps=[loop(process_item, over="items")],
+    variables={"items": ["a", "b", "c"]}
+)
+# Or from CSV file:
+workflow = Workflow(steps=[loop(process_row, from_csv="data.csv")])
+
+# 4. REPEAT - Evaluator-Optimizer pattern
+workflow = Workflow(steps=[
+    repeat(
+        generator,
+        until=lambda ctx: "done" in ctx.previous_result,
+        max_iterations=5
+    )
+])
+```
+
 ### Task Callbacks & Variables (process="workflow")
 
 ```python

docker/Dockerfile

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     flask \
-    "praisonai>=2.3.19" \
+    "praisonai>=2.3.21" \
     "praisonai[api]" \
     gunicorn \
     markdown

docker/Dockerfile.chat

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=2.3.19" \
+    "praisonai>=2.3.21" \
     "praisonai[chat]" \
     "embedchain[github,youtube]"
 

docker/Dockerfile.dev

@@ -20,7 +20,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=2.3.19" \
+    "praisonai>=2.3.21" \
     "praisonai[ui]" \
     "praisonai[chat]" \
     "praisonai[realtime]" \

docker/Dockerfile.ui

@@ -16,7 +16,7 @@ RUN mkdir -p /root/.praison
 # Install Python packages (using latest versions)
 RUN pip install --no-cache-dir \
     praisonai_tools \
-    "praisonai>=2.3.19" \
+    "praisonai>=2.3.21" \
     "praisonai[ui]" \
     "praisonai[crewai]"
 

examples/python/workflows/workflow_loop_csv.py

@@ -0,0 +1,55 @@
+"""
+Workflow Loop with CSV Example
+
+Demonstrates iterating over a CSV file, processing each row.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import loop
+import tempfile
+import os
+
+# Create sample CSV file
+csv_content = """name,email,task
+Alice,[email protected],Write documentation
+Bob,[email protected],Review pull requests
+Charlie,[email protected],Fix critical bug
+Diana,[email protected],Deploy to production"""
+
+# Processor for each CSV row
+def process_task(ctx: WorkflowContext) -> StepResult:
+    """Process a single task from CSV."""
+    item = ctx.variables.get("item", {})
+    name = item.get("name", "Unknown")
+    task = item.get("task", "No task")
+    index = ctx.variables.get("loop_index", 0)
+    
+    return StepResult(
+        output=f"[{index+1}] {name}: {task} ✅",
+        variables={"last_processed": name}
+    )
+
+if __name__ == "__main__":
+    # Create temp CSV file
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.csv', delete=False) as f:
+        f.write(csv_content)
+        csv_path = f.name
+    
+    try:
+        print("=== Testing Loop with CSV ===\n")
+        print(f"CSV file: {csv_path}\n")
+        
+        # Create workflow
+        workflow = Workflow(
+            name="CSV Task Processor",
+            steps=[loop(process_task, from_csv=csv_path)]
+        )
+        
+        result = workflow.start("Process all tasks", verbose=True)
+        
+        print(f"\nAll outputs:\n{result['output']}")
+        print(f"\nProcessed {len(result['variables']['loop_outputs'])} items")
+        print(f"Last processed: {result['variables'].get('last_processed')}")
+        
+    finally:
+        os.unlink(csv_path)

examples/python/workflows/workflow_loop_list.py

@@ -0,0 +1,52 @@
+"""
+Workflow Loop with List Example
+
+Demonstrates iterating over a list of items, processing each one.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import loop
+
+# Sample data
+fruits = ["apple", "banana", "cherry", "date", "elderberry"]
+
+# Processor for each item
+def process_fruit(ctx: WorkflowContext) -> StepResult:
+    """Process a single fruit from the list."""
+    fruit = ctx.variables.get("item", "unknown")
+    index = ctx.variables.get("loop_index", 0)
+    
+    # Simulate processing
+    result = f"🍎 [{index + 1}] {fruit.upper()} - processed successfully"
+    
+    return StepResult(
+        output=result,
+        variables={"last_fruit": fruit}
+    )
+
+# Aggregator to summarize results
+def summarize(ctx: WorkflowContext) -> StepResult:
+    """Summarize all processed fruits."""
+    outputs = ctx.variables.get("loop_outputs", [])
+    summary = f"📊 Processed {len(outputs)} fruits:\n"
+    summary += "\n".join(f"  {o}" for o in outputs)
+    return StepResult(output=summary)
+
+# Create workflow
+workflow = Workflow(
+    name="Fruit Processor",
+    steps=[
+        loop(process_fruit, over="fruits"),
+        summarize
+    ],
+    variables={"fruits": fruits}
+)
+
+if __name__ == "__main__":
+    print("=== Testing Loop with List ===\n")
+    
+    result = workflow.start("Process all fruits", verbose=True)
+    
+    print(f"\nFinal Output:\n{result['output']}")
+    print(f"\nLoop outputs count: {len(result['variables']['loop_outputs'])}")
+    print(f"Last processed: {result['variables'].get('last_fruit')}")

examples/python/workflows/workflow_parallel.py

@@ -0,0 +1,53 @@
+"""
+Workflow Parallel Execution Example
+
+Demonstrates running multiple steps concurrently and
+combining their results.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import parallel
+import time
+
+# Parallel workers - each does independent work
+def research_market(ctx: WorkflowContext) -> StepResult:
+    """Research market trends."""
+    time.sleep(0.1)  # Simulate work
+    return StepResult(output="📊 Market: Growth expected 15% YoY")
+
+def research_competitors(ctx: WorkflowContext) -> StepResult:
+    """Research competitor analysis."""
+    time.sleep(0.1)  # Simulate work
+    return StepResult(output="🏢 Competitors: 3 major players identified")
+
+def research_customers(ctx: WorkflowContext) -> StepResult:
+    """Research customer feedback."""
+    time.sleep(0.1)  # Simulate work
+    return StepResult(output="👥 Customers: 85% satisfaction rate")
+
+# Aggregator - combines parallel results
+def summarize_research(ctx: WorkflowContext) -> StepResult:
+    """Summarize all research findings."""
+    outputs = ctx.variables.get("parallel_outputs", [])
+    summary = "📋 RESEARCH SUMMARY:\n" + "\n".join(f"  • {o}" for o in outputs)
+    return StepResult(output=summary)
+
+# Create workflow with parallel execution
+workflow = Workflow(
+    name="Parallel Research",
+    steps=[
+        parallel([research_market, research_competitors, research_customers]),
+        summarize_research
+    ]
+)
+
+if __name__ == "__main__":
+    print("=== Testing Parallel Workflow ===\n")
+    
+    start_time = time.time()
+    result = workflow.start("Analyze the business landscape", verbose=True)
+    elapsed = time.time() - start_time
+    
+    print(f"\nFinal Output:\n{result['output']}")
+    print(f"\nCompleted in {elapsed:.2f}s (parallel execution)")
+    print(f"Individual outputs: {len(result['variables']['parallel_outputs'])}")

examples/python/workflows/workflow_repeat.py

@@ -0,0 +1,69 @@
+"""
+Workflow Repeat (Evaluator-Optimizer) Example
+
+Demonstrates repeating a step until a condition is met.
+This is useful for iterative improvement patterns.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import repeat
+
+# Simulated content generator that improves each iteration
+class ContentGenerator:
+    def __init__(self):
+        self.iteration = 0
+        self.content = []
+    
+    def generate(self, ctx: WorkflowContext) -> StepResult:
+        """Generate content, adding more each iteration."""
+        self.iteration += 1
+        
+        # Add new content each iteration
+        new_items = [
+            f"Point {self.iteration}.1: Key insight about the topic",
+            f"Point {self.iteration}.2: Supporting evidence"
+        ]
+        self.content.extend(new_items)
+        
+        output = f"Iteration {self.iteration}: Generated {len(self.content)} points total"
+        
+        return StepResult(
+            output=output,
+            variables={
+                "total_points": len(self.content),
+                "content": self.content.copy()
+            }
+        )
+
+# Condition: stop when we have enough content
+def has_enough_content(ctx: WorkflowContext) -> bool:
+    """Check if we have generated enough content."""
+    total = ctx.variables.get("total_points", 0)
+    return total >= 6  # Stop when we have 6+ points
+
+# Create generator instance
+generator = ContentGenerator()
+
+# Create workflow with repeat pattern
+workflow = Workflow(
+    name="Content Generator",
+    steps=[
+        repeat(
+            generator.generate,
+            until=has_enough_content,
+            max_iterations=10
+        )
+    ]
+)
+
+if __name__ == "__main__":
+    print("=== Testing Repeat (Evaluator-Optimizer) Pattern ===\n")
+    
+    result = workflow.start("Generate comprehensive content", verbose=True)
+    
+    print(f"\nFinal output: {result['output']}")
+    print(f"Total iterations: {result['variables']['repeat_iterations']}")
+    print(f"Total points generated: {result['variables']['total_points']}")
+    print("\nGenerated content:")
+    for point in result['variables']['content']:
+        print(f"  • {point}")

examples/python/workflows/workflow_routing.py

@@ -0,0 +1,61 @@
+"""
+Workflow Routing Example
+
+Demonstrates decision-based routing where the workflow
+takes different paths based on the output of a decision step.
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents.workflows import route
+
+# Decision maker - determines which route to take
+def classify_request(ctx: WorkflowContext) -> StepResult:
+    """Classify the input and decide the route."""
+    input_lower = ctx.input.lower()
+    
+    if "urgent" in input_lower or "emergency" in input_lower:
+        return StepResult(output="priority: high")
+    elif "question" in input_lower or "help" in input_lower:
+        return StepResult(output="priority: support")
+    else:
+        return StepResult(output="priority: normal")
+
+# Route handlers
+def handle_high_priority(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output="🚨 HIGH PRIORITY: Escalating to senior team immediately!")
+
+def handle_support(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output="💬 SUPPORT: Routing to help desk for assistance.")
+
+def handle_normal(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output="📋 NORMAL: Added to standard processing queue.")
+
+# Create workflow with routing
+workflow = Workflow(
+    name="Request Router",
+    steps=[
+        classify_request,
+        route({
+            "high": [handle_high_priority],
+            "support": [handle_support],
+            "normal": [handle_normal],
+            "default": [handle_normal]
+        })
+    ]
+)
+
+if __name__ == "__main__":
+    # Test different inputs
+    print("=== Testing Routing Workflow ===\n")
+    
+    # Test 1: Urgent request
+    result = workflow.start("This is an URGENT matter!", verbose=True)
+    print(f"Result: {result['output']}\n")
+    
+    # Test 2: Support request
+    result = workflow.start("I have a question about my account", verbose=True)
+    print(f"Result: {result['output']}\n")
+    
+    # Test 3: Normal request
+    result = workflow.start("Please process my order", verbose=True)
+    print(f"Result: {result['output']}")

src/praisonai-agents/praisonaiagents/__init__.py

@@ -54,7 +54,13 @@ except ImportError:
     MCP = None
 from .session import Session
 from .memory.memory import Memory
-from .memory.workflows import Workflow, WorkflowStep, WorkflowContext, StepResult
+# Workflows - import from dedicated workflows module
+from .workflows import (
+    Workflow, WorkflowStep, WorkflowContext, StepResult,
+    Route, Parallel, Loop, Repeat,
+    route, parallel, loop, repeat,
+    Pipeline  # Alias for Workflow
+)
 from .guardrails import GuardrailResult, LLMGuardrail
 
 # Fast Context support (lazy loaded to avoid performance impact)

src/praisonai-agents/praisonaiagents/memory/__init__.py

@@ -48,30 +48,58 @@ def __getattr__(name):
     if name == "create_auto_memory":
         from .auto_memory import create_auto_memory
         return create_auto_memory
+    # Workflows - now in dedicated module, re-export for backward compatibility
     if name == "WorkflowManager":
-        from .workflows import WorkflowManager
+        from ..workflows import WorkflowManager
         return WorkflowManager
     if name == "Workflow":
-        from .workflows import Workflow
+        from ..workflows import Workflow
         return Workflow
     if name == "WorkflowStep":
-        from .workflows import WorkflowStep
+        from ..workflows import WorkflowStep
         return WorkflowStep
     if name == "WorkflowContext":
-        from .workflows import WorkflowContext
+        from ..workflows import WorkflowContext
         return WorkflowContext
     if name == "StepResult":
-        from .workflows import StepResult
+        from ..workflows import StepResult
         return StepResult
+    if name == "Pipeline":
+        from ..workflows import Pipeline
+        return Pipeline
+    if name == "Route":
+        from ..workflows import Route
+        return Route
+    if name == "Parallel":
+        from ..workflows import Parallel
+        return Parallel
+    if name == "Loop":
+        from ..workflows import Loop
+        return Loop
+    if name == "Repeat":
+        from ..workflows import Repeat
+        return Repeat
+    if name == "route":
+        from ..workflows import route
+        return route
+    if name == "parallel":
+        from ..workflows import parallel
+        return parallel
+    if name == "loop":
+        from ..workflows import loop
+        return loop
+    if name == "repeat":
+        from ..workflows import repeat
+        return repeat
     # Backward compatibility aliases
     if name == "StepInput":
-        from .workflows import WorkflowContext
+        from ..workflows import WorkflowContext
         return WorkflowContext
     if name == "StepOutput":
-        from .workflows import StepResult
+        from ..workflows import StepResult
         return StepResult
     if name == "create_workflow_manager":
-        from .workflows import create_workflow_manager
+        from ..workflows.workflows import create_workflow_manager
         return create_workflow_manager
     if name == "HooksManager":
         from .hooks import HooksManager
@@ -98,13 +126,23 @@ __all__ = [
     "AutoMemory",
     "AutoMemoryExtractor",
     "create_auto_memory",
-    # Workflows
+    # Workflows (re-exported from praisonaiagents.workflows for backward compatibility)
     "WorkflowManager",
     "Workflow",
+    "Pipeline",
     "WorkflowStep",
     "WorkflowContext",
     "StepResult",
     "create_workflow_manager",
+    # Workflow patterns
+    "Route",
+    "Parallel",
+    "Loop",
+    "Repeat",
+    "route",
+    "parallel",
+    "loop",
+    "repeat",
     # Hooks
     "HooksManager",
     "HookResult",

src/praisonai-agents/praisonaiagents/memory/workflows.py

@@ -49,6 +49,137 @@ StepInput = WorkflowContext
 StepOutput = StepResult
 
 
+# =============================================================================
+# Workflow Pattern Helpers
+# =============================================================================
+
+@dataclass
+class Route:
+    """
+    Decision-based branching. Routes to different steps based on previous output.
+    
+    Usage:
+        workflow = Workflow(steps=[
+            decision_maker,
+            route({
+                "approve": [approve_step],
+                "reject": [reject_step],
+                "default": [fallback_step]
+            })
+        ])
+    """
+    routes: Dict[str, List] = field(default_factory=dict)
+    default: Optional[List] = None
+    
+    def __init__(self, routes: Dict[str, List], default: Optional[List] = None):
+        self.routes = routes
+        self.default = default or routes.get("default", [])
+
+
+@dataclass  
+class Parallel:
+    """
+    Execute multiple steps concurrently and combine results.
+    
+    Usage:
+        workflow = Workflow(steps=[
+            parallel([agent1, agent2, agent3]),
+            aggregator
+        ])
+    """
+    steps: List = field(default_factory=list)
+    
+    def __init__(self, steps: List):
+        self.steps = steps
+
+
+@dataclass
+class Loop:
+    """
+    Iterate over a list or CSV file, executing step for each item.
+    
+    Usage:
+        # Loop over list variable
+        workflow = Workflow(
+            steps=[loop(processor, over="items")],
+            variables={"items": ["a", "b", "c"]}
+        )
+        
+        # Loop over CSV file
+        workflow = Workflow(steps=[
+            loop(processor, from_csv="data.csv")
+        ])
+    """
+    step: Any = None
+    over: Optional[str] = None  # Variable name containing list
+    from_csv: Optional[str] = None  # CSV file path
+    from_file: Optional[str] = None  # Text file path (one item per line)
+    var_name: str = "item"  # Variable name for current item
+    
+    def __init__(
+        self, 
+        step: Any, 
+        over: Optional[str] = None,
+        from_csv: Optional[str] = None,
+        from_file: Optional[str] = None,
+        var_name: str = "item"
+    ):
+        self.step = step
+        self.over = over
+        self.from_csv = from_csv
+        self.from_file = from_file
+        self.var_name = var_name
+
+
+@dataclass
+class Repeat:
+    """
+    Repeat a step until a condition is met (evaluator-optimizer pattern).
+    
+    Usage:
+        workflow = Workflow(steps=[
+            repeat(
+                generator,
+                until=lambda ctx: "done" in ctx.previous_result.lower(),
+                max_iterations=5
+            )
+        ])
+    """
+    step: Any = None
+    until: Optional[Callable[[WorkflowContext], bool]] = None
+    max_iterations: int = 10
+    
+    def __init__(
+        self,
+        step: Any,
+        until: Optional[Callable[[WorkflowContext], bool]] = None,
+        max_iterations: int = 10
+    ):
+        self.step = step
+        self.until = until
+        self.max_iterations = max_iterations
+
+
+# Convenience functions for cleaner API
+def route(routes: Dict[str, List], default: Optional[List] = None) -> Route:
+    """Create a routing decision point."""
+    return Route(routes=routes, default=default)
+
+def parallel(steps: List) -> Parallel:
+    """Execute steps in parallel."""
+    return Parallel(steps=steps)
+
+def loop(step: Any, over: Optional[str] = None, from_csv: Optional[str] = None, 
+         from_file: Optional[str] = None, var_name: str = "item") -> Loop:
+    """Loop over items executing step for each."""
+    return Loop(step=step, over=over, from_csv=from_csv, from_file=from_file, var_name=var_name)
+
+def repeat(step: Any, until: Optional[Callable[[WorkflowContext], bool]] = None,
+           max_iterations: int = 10) -> Repeat:
+    """Repeat step until condition is met."""
+    return Repeat(step=step, until=until, max_iterations=max_iterations)
+
+
 @dataclass
 class WorkflowStep:
     """A single step in a workflow."""
@@ -173,9 +304,6 @@ class Workflow:
         Returns:
             Dict with 'output' (final result) and 'steps' (all step results)
         """
-        # Normalize steps - convert Agents/functions to WorkflowStep
-        normalized_steps = self._normalize_steps()
-        
         # Use default LLM if not specified
         model = llm or self.default_llm or "gpt-4o-mini"
         
@@ -185,7 +313,59 @@ class Workflow:
         results = []
         previous_output = None
         
-        for i, step in enumerate(normalized_steps):
+        # Process steps (may include Route, Parallel, Loop, Repeat)
+        i = 0
+        while i < len(self.steps):
+            step = self.steps[i]
+            
+            # Handle special pattern types
+            if isinstance(step, Route):
+                # Decision-based routing
+                route_result = self._execute_route(
+                    step, previous_output, input, all_variables, model, verbose
+                )
+                results.extend(route_result["steps"])
+                previous_output = route_result["output"]
+                all_variables.update(route_result.get("variables", {}))
+                i += 1
+                continue
+                
+            elif isinstance(step, Parallel):
+                # Parallel execution
+                parallel_result = self._execute_parallel(
+                    step, previous_output, input, all_variables, model, verbose
+                )
+                results.extend(parallel_result["steps"])
+                previous_output = parallel_result["output"]
+                all_variables.update(parallel_result.get("variables", {}))
+                i += 1
+                continue
+                
+            elif isinstance(step, Loop):
+                # Loop over items
+                loop_result = self._execute_loop(
+                    step, previous_output, input, all_variables, model, verbose
+                )
+                results.extend(loop_result["steps"])
+                previous_output = loop_result["output"]
+                all_variables.update(loop_result.get("variables", {}))
+                i += 1
+                continue
+                
+            elif isinstance(step, Repeat):
+                # Repeat until condition
+                repeat_result = self._execute_repeat(
+                    step, previous_output, input, all_variables, model, verbose
+                )
+                results.extend(repeat_result["steps"])
+                previous_output = repeat_result["output"]
+                all_variables.update(repeat_result.get("variables", {}))
+                i += 1
+                continue
+            
+            # Normalize single step
+            step = self._normalize_single_step(step, i)
+            
             # Create context for handlers
             context = WorkflowContext(
                 input=input,
@@ -200,6 +380,7 @@ class Workflow:
                     if not step.should_run(context):
                         if verbose:
                             print(f"⏭️ Skipped: {step.name}")
+                        i += 1
                         continue
                 except Exception as e:
                     logger.error(f"should_run failed for {step.name}: {e}")
@@ -270,6 +451,8 @@ class Workflow:
             # Store output in variables
             var_name = step.output_variable or f"{step.name}_output"
             all_variables[var_name] = output
+            
+            i += 1
         
         return {
             "output": previous_output,
@@ -306,11 +489,300 @@ class Workflow:
         
         return normalized
     
+    def _normalize_single_step(self, step: Any, index: int) -> 'WorkflowStep':
+        """Normalize a single step to WorkflowStep."""
+        if isinstance(step, WorkflowStep):
+            return step
+        elif callable(step):
+            return WorkflowStep(
+                name=getattr(step, '__name__', f'step_{index+1}'),
+                handler=step
+            )
+        elif hasattr(step, 'chat'):
+            return WorkflowStep(
+                name=getattr(step, 'name', f'agent_{index+1}'),
+                agent=step,
+                action="{{input}}"
+            )
+        else:
+            return WorkflowStep(
+                name=f'step_{index+1}',
+                action=str(step)
+            )
+    
+    def _execute_single_step_internal(
+        self, 
+        step: Any, 
+        previous_output: Optional[str],
+        input: str,
+        all_variables: Dict[str, Any],
+        model: str,
+        verbose: bool,
+        index: int = 0
+    ) -> Dict[str, Any]:
+        """Execute a single step and return result."""
+        normalized = self._normalize_single_step(step, index)
+        
+        context = WorkflowContext(
+            input=input,
+            previous_result=str(previous_output) if previous_output else None,
+            current_step=normalized.name,
+            variables=all_variables.copy()
+        )
+        
+        output = None
+        stop = False
+        
+        if normalized.handler:
+            try:
+                result = normalized.handler(context)
+                if isinstance(result, StepResult):
+                    output = result.output
+                    stop = result.stop_workflow
+                    if result.variables:
+                        all_variables.update(result.variables)
+                else:
+                    output = str(result)
+            except Exception as e:
+                output = f"Error: {e}"
+        elif normalized.agent:
+            try:
+                output = normalized.agent.chat(normalized.action or input)
+            except Exception as e:
+                output = f"Error: {e}"
+        elif normalized.action:
+            try:
+                from ..agent.agent import Agent
+                config = normalized.agent_config or self.default_agent_config or {}
+                temp_agent = Agent(
+                    name=config.get("name", normalized.name),
+                    role=config.get("role", "Assistant"),
+                    goal=config.get("goal", "Complete the task"),
+                    llm=config.get("llm", model),
+                    verbose=verbose
+                )
+                action = normalized.action
+                for key, value in all_variables.items():
+                    action = action.replace(f"{{{{{key}}}}}", str(value))
+                if previous_output:
+                    action = action.replace("{{previous_output}}", str(previous_output))
+                output = temp_agent.chat(action)
+            except Exception as e:
+                output = f"Error: {e}"
+        
+        if verbose:
+            print(f"✅ {normalized.name}: {str(output)[:100]}...")
+        
+        return {
+            "step": normalized.name,
+            "output": output,
+            "stop": stop,
+            "variables": all_variables
+        }
+    
+    def _execute_route(
+        self,
+        route_step: Route,
+        previous_output: Optional[str],
+        input: str,
+        all_variables: Dict[str, Any],
+        model: str,
+        verbose: bool
+    ) -> Dict[str, Any]:
+        """Execute routing based on previous output."""
+        results = []
+        output = previous_output
+        
+        # Find matching route
+        matched_route = None
+        prev_lower = str(previous_output).lower() if previous_output else ""
+        
+        for key in route_step.routes:
+            if key.lower() in prev_lower or key == "default":
+                if key != "default":
+                    matched_route = route_step.routes[key]
+                    break
+        
+        if matched_route is None:
+            matched_route = route_step.default or []
+        
+        if verbose:
+            route_name = next((k for k in route_step.routes if route_step.routes[k] == matched_route), "default")
+            print(f"🔀 Routing to: {route_name}")
+        
+        # Execute matched route steps
+        for idx, step in enumerate(matched_route):
+            step_result = self._execute_single_step_internal(
+                step, output, input, all_variables, model, verbose, idx
+            )
+            results.append({"step": step_result["step"], "output": step_result["output"]})
+            output = step_result["output"]
+            all_variables.update(step_result.get("variables", {}))
+            
+            if step_result.get("stop"):
+                break
+        
+        return {"steps": results, "output": output, "variables": all_variables}
+    
+    def _execute_parallel(
+        self,
+        parallel_step: Parallel,
+        previous_output: Optional[str],
+        input: str,
+        all_variables: Dict[str, Any],
+        model: str,
+        verbose: bool
+    ) -> Dict[str, Any]:
+        """Execute steps in parallel (simulated with sequential for now)."""
+        import concurrent.futures
+        
+        results = []
+        outputs = []
+        
+        if verbose:
+            print(f"⚡ Running {len(parallel_step.steps)} steps in parallel...")
+        
+        # Use ThreadPoolExecutor for parallel execution
+        with concurrent.futures.ThreadPoolExecutor(max_workers=len(parallel_step.steps)) as executor:
+            futures = []
+            for idx, step in enumerate(parallel_step.steps):
+                future = executor.submit(
+                    self._execute_single_step_internal,
+                    step, previous_output, input, all_variables.copy(), model, False, idx
+                )
+                futures.append((idx, future))
+            
+            for idx, future in futures:
+                try:
+                    step_result = future.result()
+                    results.append({"step": step_result["step"], "output": step_result["output"]})
+                    outputs.append(step_result["output"])
+                except Exception as e:
+                    results.append({"step": f"parallel_{idx}", "output": f"Error: {e}"})
+                    outputs.append(f"Error: {e}")
+        
+        # Combine outputs
+        combined_output = "\n---\n".join(str(o) for o in outputs)
+        all_variables["parallel_outputs"] = outputs
+        
+        if verbose:
+            print(f"✅ Parallel complete: {len(outputs)} results")
+        
+        return {"steps": results, "output": combined_output, "variables": all_variables}
+    
+    def _execute_loop(
+        self,
+        loop_step: Loop,
+        previous_output: Optional[str],
+        input: str,
+        all_variables: Dict[str, Any],
+        model: str,
+        verbose: bool
+    ) -> Dict[str, Any]:
+        """Execute step for each item in loop."""
+        import csv
+        
+        results = []
+        outputs = []
+        items = []
+        
+        # Get items from variable, CSV, or file
+        if loop_step.over:
+            items = all_variables.get(loop_step.over, [])
+            if isinstance(items, str):
+                items = [items]
+        elif loop_step.from_csv:
+            try:
+                with open(loop_step.from_csv, 'r', encoding='utf-8') as f:
+                    reader = csv.DictReader(f)
+                    items = list(reader)
+            except Exception as e:
+                logger.error(f"Failed to read CSV {loop_step.from_csv}: {e}")
+                items = []
+        elif loop_step.from_file:
+            try:
+                with open(loop_step.from_file, 'r', encoding='utf-8') as f:
+                    items = [line.strip() for line in f if line.strip()]
+            except Exception as e:
+                logger.error(f"Failed to read file {loop_step.from_file}: {e}")
+                items = []
+        
+        if verbose:
+            print(f"🔁 Looping over {len(items)} items...")
+        
+        for idx, item in enumerate(items):
+            # Add current item to variables
+            loop_vars = all_variables.copy()
+            loop_vars[loop_step.var_name] = item
+            loop_vars["loop_index"] = idx
+            
+            step_result = self._execute_single_step_internal(
+                loop_step.step, previous_output, input, loop_vars, model, verbose, idx
+            )
+            results.append({"step": f"{step_result['step']}_{idx}", "output": step_result["output"]})
+            outputs.append(step_result["output"])
+            previous_output = step_result["output"]
+        
+        all_variables["loop_outputs"] = outputs
+        combined_output = "\n".join(str(o) for o in outputs) if outputs else ""
+        
+        return {"steps": results, "output": combined_output, "variables": all_variables}
+    
+    def _execute_repeat(
+        self,
+        repeat_step: Repeat,
+        previous_output: Optional[str],
+        input: str,
+        all_variables: Dict[str, Any],
+        model: str,
+        verbose: bool
+    ) -> Dict[str, Any]:
+        """Repeat step until condition is met."""
+        results = []
+        output = previous_output
+        
+        if verbose:
+            print(f"🔄 Repeating up to {repeat_step.max_iterations} times...")
+        
+        for iteration in range(repeat_step.max_iterations):
+            step_result = self._execute_single_step_internal(
+                repeat_step.step, output, input, all_variables, model, verbose, iteration
+            )
+            results.append({"step": f"{step_result['step']}_{iteration}", "output": step_result["output"]})
+            output = step_result["output"]
+            all_variables.update(step_result.get("variables", {}))
+            
+            # Check until condition
+            if repeat_step.until:
+                context = WorkflowContext(
+                    input=input,
+                    previous_result=str(output) if output else None,
+                    current_step=f"repeat_{iteration}",
+                    variables=all_variables.copy()
+                )
+                try:
+                    if repeat_step.until(context):
+                        if verbose:
+                            print(f"✅ Repeat condition met at iteration {iteration + 1}")
+                        break
+                except Exception as e:
+                    logger.error(f"Repeat until condition failed: {e}")
+            
+            if step_result.get("stop"):
+                break
+        
+        all_variables["repeat_iterations"] = iteration + 1
+        return {"steps": results, "output": output, "variables": all_variables}
+    
     def start(self, input: str = "", **kwargs) -> Dict[str, Any]:
         """Alias for run() for consistency with PraisonAIAgents."""
         return self.run(input, **kwargs)
 
 
+# Alias: Pipeline = Workflow (they are the same concept)
+Pipeline = Workflow
+
+
 class WorkflowManager:
     """
     Manages workflow discovery, loading, and execution.

src/praisonai-agents/praisonaiagents/workflows/__init__.py

@@ -0,0 +1,55 @@
+"""
+Workflows module for PraisonAI Agents.
+
+Provides workflow/pipeline patterns for orchestrating agents and functions.
+"""
+
+from .workflows import (
+    # Core classes
+    Workflow,
+    Pipeline,  # Alias for Workflow
+    WorkflowStep,
+    WorkflowContext,
+    StepResult,
+    WorkflowManager,
+    
+    # Pattern helpers
+    Route,
+    Parallel,
+    Loop,
+    Repeat,
+    
+    # Convenience functions
+    route,
+    parallel,
+    loop,
+    repeat,
+    
+    # Backward compatibility aliases
+    StepInput,
+    StepOutput,
+)
+
+__all__ = [
+    # Core
+    "Workflow",
+    "Pipeline",
+    "WorkflowStep",
+    "WorkflowContext",
+    "StepResult",
+    "WorkflowManager",
+    
+    # Patterns
+    "Route",
+    "Parallel",
+    "Loop",
+    "Repeat",
+    "route",
+    "parallel",
+    "loop",
+    "repeat",
+    
+    # Aliases
+    "StepInput",
+    "StepOutput",
+]

src/praisonai-agents/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "praisonaiagents"
-version = "0.0.197"
+version = "0.0.199"
 description = "Praison AI agents for completing complex tasks with Self Reflection Agents"
 requires-python = ">=3.10"
 authors = [

src/praisonai-agents/tests/test_workflow_patterns.py

@@ -0,0 +1,544 @@
+"""
+Unit tests for Workflow Patterns: route, parallel, loop, repeat
+
+Test-Driven Development tests for all workflow pattern features.
+"""
+
+import pytest
+import tempfile
+import os
+from praisonaiagents import Workflow, WorkflowContext, StepResult, Pipeline
+from praisonaiagents.workflows import (
+    route, parallel, loop, repeat,
+    Route, Parallel, Loop, Repeat,
+    WorkflowStep, WorkflowManager
+)
+
+
+# =============================================================================
+# Test Fixtures
+# =============================================================================
+
+@pytest.fixture
+def simple_step():
+    """A simple step that returns its input."""
+    def step(ctx: WorkflowContext) -> StepResult:
+        return StepResult(output=f"Processed: {ctx.input}")
+    return step
+
+
+@pytest.fixture
+def csv_file():
+    """Create a temporary CSV file for testing."""
+    content = """name,email,task
+Alice,[email protected],Write docs
+Bob,[email protected],Review code
+Charlie,[email protected],Test features"""
+    
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.csv', delete=False) as f:
+        f.write(content)
+        path = f.name
+    
+    yield path
+    
+    # Cleanup
+    os.unlink(path)
+
+
+# =============================================================================
+# Test: Basic Workflow
+# =============================================================================
+
+class TestBasicWorkflow:
+    """Test basic workflow functionality."""
+    
+    def test_sequential_steps(self):
+        """Test sequential step execution."""
+        def step1(ctx): return StepResult(output="Step 1")
+        def step2(ctx): return StepResult(output="Step 2")
+        def step3(ctx): return StepResult(output="Step 3")
+        
+        workflow = Workflow(steps=[step1, step2, step3])
+        result = workflow.start("test")
+        
+        assert result["output"] == "Step 3"
+        assert len(result["steps"]) == 3
+    
+    def test_context_passing(self):
+        """Test that context is passed between steps."""
+        def step1(ctx): 
+            return StepResult(output="Hello", variables={"greeting": "Hello"})
+        
+        def step2(ctx):
+            greeting = ctx.variables.get("greeting", "")
+            prev = ctx.previous_result
+            return StepResult(output=f"{greeting} from step2, prev={prev}")
+        
+        workflow = Workflow(steps=[step1, step2])
+        result = workflow.start("test")
+        
+        assert "Hello" in result["output"]
+        assert "prev=Hello" in result["output"]
+    
+    def test_early_stop(self):
+        """Test early workflow termination."""
+        def stopper(ctx): 
+            return StepResult(output="Stopped", stop_workflow=True)
+        def never_runs(ctx): 
+            return StepResult(output="Should not run")
+        
+        workflow = Workflow(steps=[stopper, never_runs])
+        result = workflow.start("test")
+        
+        assert result["output"] == "Stopped"
+        assert len(result["steps"]) == 1
+    
+    def test_should_run_condition(self):
+        """Test conditional step execution with should_run."""
+        def always(ctx): return StepResult(output="Always")
+        def conditional(ctx): return StepResult(output="Conditional")
+        def is_special(ctx): return "special" in ctx.input.lower()
+        
+        workflow = Workflow(steps=[
+            WorkflowStep(name="always", handler=always),
+            WorkflowStep(name="conditional", handler=conditional, should_run=is_special)
+        ])
+        
+        # Without "special" - conditional should be skipped
+        result = workflow.start("normal input")
+        assert len([s for s in result["steps"] if s["output"]]) == 1
+        
+        # With "special" - both should run
+        result = workflow.start("special input")
+        assert len([s for s in result["steps"] if s["output"]]) == 2
+
+
+# =============================================================================
+# Test: Route Pattern
+# =============================================================================
+
+class TestRoutePattern:
+    """Test decision-based routing."""
+    
+    def test_route_creation(self):
+        """Test Route class creation."""
+        r = route({"a": ["step_a"], "b": ["step_b"]})
+        assert isinstance(r, Route)
+        assert "a" in r.routes
+        assert "b" in r.routes
+    
+    def test_route_with_default(self):
+        """Test Route with default fallback."""
+        r = route({"a": ["step_a"]}, default=["fallback"])
+        assert r.default == ["fallback"]
+    
+    def test_route_matching(self):
+        """Test route matching based on output."""
+        def classifier(ctx): 
+            return StepResult(output="approve this request")
+        def approve(ctx): 
+            return StepResult(output="Approved!")
+        def reject(ctx): 
+            return StepResult(output="Rejected!")
+        
+        workflow = Workflow(steps=[
+            classifier,
+            route({
+                "approve": [approve],
+                "reject": [reject]
+            })
+        ])
+        
+        result = workflow.start("test")
+        assert "Approved" in result["output"]
+    
+    def test_route_default_fallback(self):
+        """Test route falls back to default when no match."""
+        def classifier(ctx): 
+            return StepResult(output="unknown category")
+        def fallback(ctx): 
+            return StepResult(output="Fallback executed")
+        
+        workflow = Workflow(steps=[
+            classifier,
+            route({
+                "approve": [lambda ctx: StepResult(output="Approved")],
+                "default": [fallback]
+            })
+        ])
+        
+        result = workflow.start("test")
+        assert "Fallback" in result["output"]
+    
+    def test_route_multi_step(self):
+        """Test route with multiple steps in a branch."""
+        def classifier(ctx): 
+            return StepResult(output="process")
+        def step1(ctx): 
+            return StepResult(output="Step1", variables={"step1": True})
+        def step2(ctx): 
+            return StepResult(output="Step2")
+        
+        workflow = Workflow(steps=[
+            classifier,
+            route({"process": [step1, step2]})
+        ])
+        
+        result = workflow.start("test")
+        assert result["output"] == "Step2"
+        assert result["variables"].get("step1") == True
+
+
+# =============================================================================
+# Test: Parallel Pattern
+# =============================================================================
+
+class TestParallelPattern:
+    """Test concurrent execution."""
+    
+    def test_parallel_creation(self):
+        """Test Parallel class creation."""
+        p = parallel(["step1", "step2", "step3"])
+        assert isinstance(p, Parallel)
+        assert len(p.steps) == 3
+    
+    def test_parallel_execution(self):
+        """Test parallel step execution."""
+        def task_a(ctx): return StepResult(output="Result A")
+        def task_b(ctx): return StepResult(output="Result B")
+        def task_c(ctx): return StepResult(output="Result C")
+        
+        workflow = Workflow(steps=[
+            parallel([task_a, task_b, task_c])
+        ])
+        
+        result = workflow.start("test")
+        
+        # All outputs should be in combined result
+        assert "Result A" in result["output"]
+        assert "Result B" in result["output"]
+        assert "Result C" in result["output"]
+        
+        # parallel_outputs variable should have all results
+        assert len(result["variables"]["parallel_outputs"]) == 3
+    
+    def test_parallel_with_aggregator(self):
+        """Test parallel followed by aggregator."""
+        def task_a(ctx): return StepResult(output="A")
+        def task_b(ctx): return StepResult(output="B")
+        
+        def aggregator(ctx):
+            outputs = ctx.variables.get("parallel_outputs", [])
+            return StepResult(output=f"Combined: {len(outputs)} results")
+        
+        workflow = Workflow(steps=[
+            parallel([task_a, task_b]),
+            aggregator
+        ])
+        
+        result = workflow.start("test")
+        assert "Combined: 2 results" in result["output"]
+
+
+# =============================================================================
+# Test: Loop Pattern
+# =============================================================================
+
+class TestLoopPattern:
+    """Test iteration over data."""
+    
+    def test_loop_creation(self):
+        """Test Loop class creation."""
+        l = loop("step", over="items")
+        assert isinstance(l, Loop)
+        assert l.over == "items"
+        assert l.var_name == "item"
+    
+    def test_loop_over_list(self):
+        """Test loop over list variable."""
+        def processor(ctx):
+            item = ctx.variables.get("item", "unknown")
+            return StepResult(output=f"Processed: {item}")
+        
+        workflow = Workflow(
+            steps=[loop(processor, over="items")],
+            variables={"items": ["apple", "banana", "cherry"]}
+        )
+        
+        result = workflow.start("test")
+        
+        assert len(result["variables"]["loop_outputs"]) == 3
+        assert "Processed: apple" in result["output"]
+        assert "Processed: cherry" in result["output"]
+    
+    def test_loop_with_index(self):
+        """Test loop provides index variable."""
+        def processor(ctx):
+            item = ctx.variables.get("item")
+            index = ctx.variables.get("loop_index")
+            return StepResult(output=f"[{index}] {item}")
+        
+        workflow = Workflow(
+            steps=[loop(processor, over="items")],
+            variables={"items": ["a", "b", "c"]}
+        )
+        
+        result = workflow.start("test")
+        
+        assert "[0] a" in result["output"]
+        assert "[1] b" in result["output"]
+        assert "[2] c" in result["output"]
+    
+    def test_loop_custom_var_name(self):
+        """Test loop with custom variable name."""
+        def processor(ctx):
+            fruit = ctx.variables.get("fruit", "unknown")
+            return StepResult(output=f"Fruit: {fruit}")
+        
+        workflow = Workflow(
+            steps=[loop(processor, over="fruits", var_name="fruit")],
+            variables={"fruits": ["apple", "banana"]}
+        )
+        
+        result = workflow.start("test")
+        assert "Fruit: apple" in result["output"]
+    
+    def test_loop_from_csv(self, csv_file):
+        """Test loop over CSV file."""
+        def processor(ctx):
+            row = ctx.variables.get("item", {})
+            name = row.get("name", "unknown")
+            return StepResult(output=f"Name: {name}")
+        
+        workflow = Workflow(steps=[
+            loop(processor, from_csv=csv_file)
+        ])
+        
+        result = workflow.start("test")
+        
+        assert len(result["variables"]["loop_outputs"]) == 3
+        assert "Name: Alice" in result["output"]
+        assert "Name: Bob" in result["output"]
+        assert "Name: Charlie" in result["output"]
+    
+    def test_loop_empty_list(self):
+        """Test loop with empty list."""
+        def processor(ctx):
+            return StepResult(output="Should not run")
+        
+        workflow = Workflow(
+            steps=[loop(processor, over="items")],
+            variables={"items": []}
+        )
+        
+        result = workflow.start("test")
+        assert len(result["variables"]["loop_outputs"]) == 0
+
+
+# =============================================================================
+# Test: Repeat Pattern
+# =============================================================================
+
+class TestRepeatPattern:
+    """Test evaluator-optimizer pattern."""
+    
+    def test_repeat_creation(self):
+        """Test Repeat class creation."""
+        r = repeat("step", until=lambda ctx: True, max_iterations=5)
+        assert isinstance(r, Repeat)
+        assert r.max_iterations == 5
+    
+    def test_repeat_until_condition(self):
+        """Test repeat stops when condition is met."""
+        counter = [0]
+        
+        def generator(ctx):
+            counter[0] += 1
+            return StepResult(
+                output=f"Count: {counter[0]}",
+                variables={"count": counter[0]}
+            )
+        
+        def is_done(ctx):
+            return ctx.variables.get("count", 0) >= 3
+        
+        workflow = Workflow(steps=[
+            repeat(generator, until=is_done, max_iterations=10)
+        ])
+        
+        result = workflow.start("test")
+        
+        assert result["variables"]["repeat_iterations"] == 3
+        assert counter[0] == 3
+    
+    def test_repeat_max_iterations(self):
+        """Test repeat respects max_iterations."""
+        counter = [0]
+        
+        def generator(ctx):
+            counter[0] += 1
+            return StepResult(output=f"Count: {counter[0]}")
+        
+        # Never-true condition
+        def never_done(ctx):
+            return False
+        
+        workflow = Workflow(steps=[
+            repeat(generator, until=never_done, max_iterations=5)
+        ])
+        
+        result = workflow.start("test")
+        
+        assert result["variables"]["repeat_iterations"] == 5
+        assert counter[0] == 5
+    
+    def test_repeat_without_condition(self):
+        """Test repeat without until condition runs max_iterations times."""
+        counter = [0]
+        
+        def generator(ctx):
+            counter[0] += 1
+            return StepResult(output=f"Count: {counter[0]}")
+        
+        workflow = Workflow(steps=[
+            repeat(generator, max_iterations=3)
+        ])
+        
+        result = workflow.start("test")
+        
+        assert counter[0] == 3
+    
+    def test_repeat_with_early_stop(self):
+        """Test repeat stops on stop_workflow=True."""
+        counter = [0]
+        
+        def generator(ctx):
+            counter[0] += 1
+            if counter[0] >= 2:
+                return StepResult(output="Stopping", stop_workflow=True)
+            return StepResult(output=f"Count: {counter[0]}")
+        
+        workflow = Workflow(steps=[
+            repeat(generator, max_iterations=10)
+        ])
+        
+        result = workflow.start("test")
+        
+        assert counter[0] == 2
+
+
+# =============================================================================
+# Test: Pipeline Alias
+# =============================================================================
+
+class TestPipelineAlias:
+    """Test Pipeline is an alias for Workflow."""
+    
+    def test_pipeline_is_workflow(self):
+        """Test Pipeline is the same class as Workflow."""
+        assert Pipeline is Workflow
+    
+    def test_pipeline_works(self):
+        """Test Pipeline can be used like Workflow."""
+        def step1(ctx): return StepResult(output="Pipeline works!")
+        
+        pipeline = Pipeline(steps=[step1])
+        result = pipeline.start("test")
+        
+        assert result["output"] == "Pipeline works!"
+
+
+# =============================================================================
+# Test: Backward Compatibility
+# =============================================================================
+
+class TestBackwardCompatibility:
+    """Test backward compatibility with old import paths."""
+    
+    def test_import_from_memory_workflows(self):
+        """Test imports from praisonaiagents.memory.workflows still work."""
+        from praisonaiagents.memory.workflows import (
+            Workflow, WorkflowStep, WorkflowContext, StepResult,
+            route, parallel, loop, repeat
+        )
+        
+        assert Workflow is not None
+        assert route is not None
+    
+    def test_import_from_memory_module(self):
+        """Test imports from praisonaiagents.memory still work."""
+        from praisonaiagents.memory import Workflow, Pipeline, route, parallel
+        
+        assert Workflow is not None
+        assert Pipeline is Workflow
+    
+    def test_step_input_output_aliases(self):
+        """Test StepInput/StepOutput backward compatibility aliases."""
+        from praisonaiagents.workflows import StepInput, StepOutput
+        
+        # These should be aliases for WorkflowContext and StepResult
+        assert StepInput is WorkflowContext
+        assert StepOutput is StepResult
+
+
+# =============================================================================
+# Test: Combined Patterns
+# =============================================================================
+
+class TestCombinedPatterns:
+    """Test combining multiple patterns."""
+    
+    def test_parallel_then_route(self):
+        """Test parallel followed by routing."""
+        def task_a(ctx): return StepResult(output="success from A")
+        def task_b(ctx): return StepResult(output="success from B")
+        
+        def classifier(ctx):
+            outputs = ctx.variables.get("parallel_outputs", [])
+            if all("success" in o for o in outputs):
+                return StepResult(output="all success")
+            return StepResult(output="some failed")
+        
+        def success_handler(ctx): return StepResult(output="All tasks succeeded!")
+        def failure_handler(ctx): return StepResult(output="Some tasks failed!")
+        
+        workflow = Workflow(steps=[
+            parallel([task_a, task_b]),
+            classifier,
+            route({
+                "success": [success_handler],
+                "failed": [failure_handler]
+            })
+        ])
+        
+        result = workflow.start("test")
+        assert "succeeded" in result["output"]
+    
+    def test_loop_with_aggregation(self):
+        """Test loop followed by aggregation step."""
+        def processor(ctx):
+            item = ctx.variables.get("item")
+            return StepResult(output=f"Processed: {item}")
+        
+        def aggregator(ctx):
+            outputs = ctx.variables.get("loop_outputs", [])
+            return StepResult(output=f"Total: {len(outputs)} items processed")
+        
+        workflow = Workflow(
+            steps=[
+                loop(processor, over="items"),
+                aggregator
+            ],
+            variables={"items": ["a", "b", "c", "d"]}
+        )
+        
+        result = workflow.start("test")
+        assert "Total: 4 items processed" in result["output"]
+
+
+# =============================================================================
+# Run Tests
+# =============================================================================
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

src/praisonai-agents/uv.lock

@@ -2422,7 +2422,7 @@ wheels = [
 
 [[package]]
 name = "praisonaiagents"
-version = "0.0.197"
+version = "0.0.199"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },

src/praisonai/README.md

@@ -112,6 +112,11 @@ PraisonAI is a production-ready Multi-AI Agents framework with self-reflection,
 | 🤖 Workflow with Agents | [Example](examples/python/workflows/workflow_with_agents.py) | [📖](https://docs.praison.ai/features/workflows) |
 | 🔄 Conditional Steps | [Example](examples/python/workflows/workflow_conditional.py) | [📖](https://docs.praison.ai/features/workflows) |
 | 🎭 Mixed Steps | [Example](examples/python/workflows/workflow_mixed_steps.py) | [📖](https://docs.praison.ai/features/workflows) |
+| 🔀 Agentic Routing | [Example](examples/python/workflows/workflow_routing.py) | [📖](https://docs.praison.ai/features/workflow-routing) |
+| ⚡ Parallel Execution | [Example](examples/python/workflows/workflow_parallel.py) | [📖](https://docs.praison.ai/features/workflow-parallel) |
+| 🔁 Loop over List | [Example](examples/python/workflows/workflow_loop_list.py) | [📖](https://docs.praison.ai/features/workflow-loop) |
+| 📄 Loop over CSV | [Example](examples/python/workflows/workflow_loop_csv.py) | [📖](https://docs.praison.ai/features/workflow-loop) |
+| 🔄 Evaluator-Optimizer | [Example](examples/python/workflows/workflow_repeat.py) | [📖](https://docs.praison.ai/features/workflow-repeat) |
 
 ## Supported Providers
 
@@ -456,6 +461,17 @@ result = asyncio.run(manager.aexecute("deploy", default_llm="gpt-4o-mini"))
 - **Branching**: Use `next_steps` and `branch_condition` for conditional routing
 - **Loops**: Use `loop_over` and `loop_var` to iterate over data
 
+### Choosing the Right Workflow System
+
+| Use Case | Recommended |
+|----------|-------------|
+| Simple function pipelines | `Workflow` class ⭐ |
+| Agent-only pipelines | `Workflow` class |
+| CSV batch processing | `process="workflow"` |
+| Complex task routing | `process="workflow"` |
+| Markdown templates | `WorkflowManager` |
+| Early stop / conditional | `Workflow` class |
+
 ### Simple Workflow (Recommended)
 
 The easiest way to create workflows - just pass functions as steps:
@@ -506,6 +522,48 @@ loop_step = WorkflowStep(
 )
 ```
 
+### Workflow Patterns (route, parallel, loop, repeat)
+
+```python
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+# Or use Pipeline (alias for Workflow)
+from praisonaiagents import Pipeline
+from praisonaiagents.workflows import route, parallel, loop, repeat
+
+# 1. ROUTING - Decision-based branching
+workflow = Workflow(steps=[
+    classify_request,  # Returns "approve" or "reject"
+    route({
+        "approve": [approve_handler],
+        "reject": [reject_handler],
+        "default": [fallback_handler]
+    })
+])
+
+# 2. PARALLEL - Concurrent execution
+workflow = Workflow(steps=[
+    parallel([research_market, research_competitors, research_customers]),
+    summarize_results  # Gets all parallel outputs
+])
+
+# 3. LOOP - Iterate over list or CSV
+workflow = Workflow(
+    steps=[loop(process_item, over="items")],
+    variables={"items": ["a", "b", "c"]}
+)
+# Or from CSV file:
+workflow = Workflow(steps=[loop(process_row, from_csv="data.csv")])
+
+# 4. REPEAT - Evaluator-Optimizer pattern
+workflow = Workflow(steps=[
+    repeat(
+        generator,
+        until=lambda ctx: "done" in ctx.previous_result,
+        max_iterations=5
+    )
+])
+```
+
 ### Task Callbacks & Variables (process="workflow")
 
 ```python

src/praisonai/praisonai.rb

@@ -3,8 +3,8 @@ class Praisonai < Formula
   
     desc "AI tools for various AI applications"
     homepage "https://github.com/MervinPraison/PraisonAI"
-    url "https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.3.19.tar.gz"
-    sha256 `curl -sL https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.3.19.tar.gz | shasum -a 256`.split.first
+    url "https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.3.21.tar.gz"
+    sha256 `curl -sL https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.3.21.tar.gz | shasum -a 256`.split.first
     license "MIT"
   
     depends_on "[email protected]"

src/praisonai/praisonai/deploy.py

@@ -57,7 +57,7 @@ class CloudDeployer:
             file.write("FROM python:3.11-slim\n")
             file.write("WORKDIR /app\n")
             file.write("COPY . .\n")
-            file.write("RUN pip install flask praisonai==2.3.19 gunicorn markdown\n")
+            file.write("RUN pip install flask praisonai==2.3.21 gunicorn markdown\n")
             file.write("EXPOSE 8080\n")
             file.write('CMD ["gunicorn", "-b", "0.0.0.0:8080", "api:app"]\n')
             

src/praisonai/praisonai/version.py

@@ -1 +1 @@
-__version__ = "2.3.19"
+__version__ = "2.3.21"

src/praisonai/pyproject.toml

@@ -12,7 +12,7 @@ dependencies = [
     "rich>=13.7",
     "markdown>=3.5",
     "pyparsing>=3.0.0",
-    "praisonaiagents>=0.0.197",
+    "praisonaiagents>=0.0.199",
     "python-dotenv>=0.19.0",
     "instructor>=1.3.3",
     "PyYAML>=6.0",

src/praisonai/uv.lock

@@ -4197,7 +4197,7 @@ requires-dist = [
     { name = "praisonai-tools", marker = "extra == 'autogen'", specifier = ">=0.0.22" },
     { name = "praisonai-tools", marker = "extra == 'autogen-v4'", specifier = ">=0.0.22" },
     { name = "praisonai-tools", marker = "extra == 'crewai'", specifier = ">=0.0.22" },
-    { name = "praisonaiagents", specifier = ">=0.0.197" },
+    { name = "praisonaiagents", specifier = ">=0.0.199" },
     { name = "pyautogen", marker = "extra == 'autogen'", specifier = "==0.2.29" },
     { name = "pydantic", marker = "extra == 'chat'", specifier = "<=2.10.1" },
     { name = "pydantic", marker = "extra == 'code'", specifier = "<=2.10.1" },
@@ -4252,7 +4252,7 @@ wheels = [
 
 [[package]]
 name = "praisonaiagents"
-version = "0.0.197"
+version = "0.0.199"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "aiohttp" },
@@ -4261,9 +4261,9 @@ dependencies = [
     { name = "pydantic" },
     { name = "rich" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/c6/00/342eae9c9b8bc25e812ad761ad91c0ad18adc533eaa2aa3c7c31a85cd7f8/praisonaiagents-0.0.197.tar.gz", hash = "sha256:9504dcfc861907201a10335ea7b74bfe2c6d189cc4f97951b782cd6ac46c8ee0", size = 520740, upload-time = "2025-12-16T23:26:31.078Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/8b/5f/fffbe2473e579edc0bc00022179a896e847128056b6b51905fc497b3cb7d/praisonaiagents-0.0.199.tar.gz", hash = "sha256:276a224350d1a975bdb69f5f07898a60ac9fce0b2d45edbab14e8b755a66853c", size = 538316, upload-time = "2025-12-17T00:01:47.411Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/ee/5d/2aaa57e97d84b12dc75b66e083839eb3f9d3ef8d7721a9d8e4e7d2513ded/praisonaiagents-0.0.197-py3-none-any.whl", hash = "sha256:701b60a02d9e7147909a1311572e092846ef8247b7251b67b31dbcd581eec1d7", size = 497086, upload-time = "2025-12-16T23:26:29.208Z" },
+    { url = "https://files.pythonhosted.org/packages/c9/25/489052a4ed1c8a65a08ae48fabe94b1a399cd82ed2e9c47264a1f82d066c/praisonaiagents-0.0.199-py3-none-any.whl", hash = "sha256:5bc887e097d2e444d63b755d356c537ed30e5f519c2e21adc819160ff4ed5697", size = 515315, upload-time = "2025-12-17T00:01:45.602Z" },
 ]
 
 [[package]]