Release v2.3.28

- Bump PraisonAI version to 2.3.28 across Dockerfiles and deployment scripts.
- Update praisonaiagents version to 0.1.7 in pyproject.toml.
- Enhance README with a structured Table of Contents and improved section headers for better navigation.
- Remove outdated README.md from praisonai-agents and link to the main README.

.github/workflows/docker-publish.yml

@@ -1,45 +1,54 @@
-name: Daily Publish Docker
+name: Publish Docker
 
 on:
-  push:
-    branches:
-      - main
-  schedule:
-    - cron: '0 0 * * *'
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Docker image tag (default: latest)'
+        required: false
+        default: 'latest'
 
 jobs:
-  check-and-build:
+  build-and-push:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
     
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v2
-
-      - name: Check last commit time
-        id: check_commit
-        run: |
-          last_commit_time=$(git log -1 --format=%ct)
-          current_time=$(date +%s)
-          time_diff=$((current_time - last_commit_time))
-          if [ $time_diff -ge 120 ] && [ $time_diff -lt 240 ]; then
-            echo "should_run=true" >> $GITHUB_OUTPUT
-          else
-            echo "should_run=false" >> $GITHUB_OUTPUT
-          fi
+        uses: actions/checkout@v4
 
       - name: Set up Docker Buildx
-        if: steps.check_commit.outputs.should_run == 'true'
-        uses: docker/setup-buildx-action@v1
+        uses: docker/setup-buildx-action@v3
 
-      - name: Log in to the GitHub Container Registry
-        if: steps.check_commit.outputs.should_run == 'true'
-        run: echo ${{ secrets.GH_TOKEN }} | docker login ghcr.io -u USERNAME --password-stdin
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/mervinpraison/praisonai
+          tags: |
+            type=raw,value=latest,enable=${{ github.event_name == 'release' }}
+            type=semver,pattern={{version}},enable=${{ github.event_name == 'release' }}
+            type=semver,pattern={{major}}.{{minor}},enable=${{ github.event_name == 'release' }}
+            type=raw,value=${{ github.event.inputs.tag || 'latest' }},enable=${{ github.event_name == 'workflow_dispatch' }}
 
       - name: Build and push Docker image
-        if: steps.check_commit.outputs.should_run == 'true'
-        uses: docker/build-push-action@v2
+        uses: docker/build-push-action@v5
         with:
           context: .
           file: ./docker/Dockerfile
           push: true
-          tags: ghcr.io/mervinpraison/praisonai:latest
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

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.28" \
     "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.28" \
     "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.28" \
     "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.28" \
     "praisonai[ui]" \
     "praisonai[crewai]"
 

examples/cookbooks/yaml/aws_bedrock_agents.yaml

@@ -1,10 +1,10 @@
 framework: crewai
 topic: "Technology Research and Content Creation using AWS Bedrock"
 
-roles:
+agents:  # Canonical: use 'agents' instead of 'roles'
   research_specialist:
     role: "Research Specialist"
-    backstory: |
+    instructions:  # Canonical |
       You are an experienced technology researcher with deep expertise in analyzing 
       emerging technologies and market trends. You excel at gathering comprehensive 
       information from various sources and synthesizing it into actionable insights.
@@ -35,7 +35,7 @@ roles:
 
   content_creator:
     role: "Technical Content Creator"
-    backstory: |
+    instructions:  # Canonical |
       You are a skilled technical writer and content creator who specializes in 
       translating complex technology concepts into engaging, accessible content 
       for various audiences including developers, business leaders, and end users.
@@ -64,7 +64,7 @@ roles:
 
   quality_reviewer:
     role: "Content Quality Reviewer"
-    backstory: |
+    instructions:  # Canonical |
       You are a meticulous editor and quality assurance specialist with extensive 
       experience in technical content review. You ensure accuracy, clarity, and 
       consistency while maintaining the intended tone and message.

examples/cookbooks/yaml/secondary_market_research_agents.yaml

@@ -8,10 +8,10 @@ variables:
   industry: "Electric Vehicles"
   research_focus: "comprehensive market analysis"
 
-roles:
+agents:  # Canonical: use 'agents' instead of 'roles'
   market_overview_specialist:
     role: "Market Overview Specialist" 
-    backstory: |
+    instructions:  # Canonical |
       You are a seasoned market research analyst with 10+ years of experience 
       in analyzing market dynamics, trends, and growth patterns across various 
       industries. You excel at synthesizing complex market data into clear, 
@@ -64,7 +64,7 @@ roles:
 
   competitive_intelligence_analyst:
     role: "Competitive Intelligence Analyst"
-    backstory: |
+    instructions:  # Canonical |
       You are a competitive intelligence expert specializing in analyzing 
       competitive landscapes, market positioning, and strategic intelligence. 
       You have deep expertise in competitor analysis, market share assessment, 
@@ -119,7 +119,7 @@ roles:
 
   financial_performance_analyst:
     role: "Financial Performance Analyst"
-    backstory: |
+    instructions:  # Canonical |
       You are a financial analyst with expertise in corporate finance, 
       financial statement analysis, and industry benchmarking. You specialize 
       in analyzing financial performance metrics, trends, and comparative 
@@ -173,7 +173,7 @@ roles:
 
   growth_opportunities_researcher:
     role: "Growth Opportunities Researcher"
-    backstory: |
+    instructions:  # Canonical |
       You are a strategic business analyst specializing in identifying growth 
       opportunities, market expansion strategies, and emerging business models. 
       You excel at spotting trends, gaps, and untapped potential in markets 
@@ -228,7 +228,7 @@ roles:
 
   risk_assessment_specialist:
     role: "Risk Assessment Specialist"
-    backstory: |
+    instructions:  # Canonical |
       You are a risk management expert with extensive experience in identifying, 
       analyzing, and assessing business risks across various industries. You 
       specialize in market risks, competitive threats, regulatory challenges, 
@@ -287,7 +287,7 @@ roles:
 
   research_report_synthesizer:
     role: "Research Report Synthesizer"
-    backstory: |
+    instructions:  # Canonical |
       You are an expert business report writer and analyst with extensive 
       experience in synthesizing complex research findings into clear, 
       actionable business intelligence reports. You excel at creating 

examples/python/tools/e2b/agents.yaml

@@ -1,8 +1,8 @@
 framework: praisonai
 topic: crawl and extract all data from each url from this page https://news.ycombinator.com/
-roles:
+agents:  # Canonical: use 'agents' instead of 'roles'
   web_scraper:
-    backstory: An expert in data extraction from websites, adept at navigating and
+    instructions:  # Canonical An expert in data extraction from websites, adept at navigating and
       retrieving detailed information.
     goal: Extract URLs from the source page
     role: Web Scraper
@@ -15,7 +15,7 @@ roles:
     tools:
     - 'code_interpret'
   url_data_extractor:
-    backstory: Specializes in crawling websites to gather comprehensive data, ensuring
+    instructions:  # Canonical Specializes in crawling websites to gather comprehensive data, ensuring
       nothing is missed from each link.
     goal: Crawl each URL for data extraction
     role: URL Data Extractor
@@ -29,7 +29,7 @@ roles:
     tools:
     - 'code_interpret'
   data_organizer:
-    backstory: Known for keen attention to detail, capable of structuring vast amounts
+    instructions:  # Canonical Known for keen attention to detail, capable of structuring vast amounts
       of information into usable formats efficiently.
     goal: Organize extracted data into a structured format
     role: Data Organizer

examples/python/workflows/simple_workflow.py

@@ -1,36 +1,38 @@
 """
-Simple Workflow Example
+Simple Agentic Workflow Example
 
-The easiest way to create and run workflows in PraisonAI.
-Just pass functions or agents as steps - no complex configuration needed!
+Demonstrates using Agent instances directly as workflow steps.
+Each agent processes the input and passes output to the next agent.
 """
 
-from praisonaiagents import Workflow, WorkflowContext, StepResult
+from praisonaiagents import Agent, Workflow
 
-# Define simple handler functions
-def validate(ctx: WorkflowContext) -> StepResult:
-    """Validate the input data."""
-    if not ctx.input:
-        return StepResult(output="No input provided", stop_workflow=True)
-    return StepResult(output=f"Validated: {ctx.input}")
+# Create agents with specific roles
+researcher = Agent(
+    name="Researcher",
+    role="Research Analyst",
+    goal="Research and provide information about topics",
+    instructions="You are a research analyst. Provide concise, factual information."
+)
 
-def process(ctx: WorkflowContext) -> StepResult:
-    """Process the validated data."""
-    return StepResult(output=f"Processed: {ctx.previous_result}")
+writer = Agent(
+    name="Writer", 
+    role="Content Writer",
+    goal="Write engaging content based on research",
+    instructions="You are a content writer. Write clear, engaging content based on the research provided."
+)
 
-def format_output(ctx: WorkflowContext) -> StepResult:
-    """Format the final output."""
-    return StepResult(output=f"✅ Final: {ctx.previous_result}")
-
-# Create workflow - just list your functions!
+# Create workflow with agents as steps
 workflow = Workflow(
-    name="Simple Pipeline",
-    steps=[validate, process, format_output]
+    name="Simple Agentic Pipeline",
+    steps=[researcher, writer]
 )
 
 if __name__ == "__main__":
-    # Run the workflow - PraisonAI style uses .start()
-    result = workflow.start("Hello, World!", verbose=True)
+    # Run workflow - agents process sequentially
+    result = workflow.start(
+        "What are the key benefits of AI agents?",
+        verbose=True
+    )
     
-    print(f"\nFinal output: {result['output']}")
-    print(f"Steps completed: {len(result['steps'])}")
+    print(f"\nFinal output:\n{result['output']}")

examples/python/workflows/simple_workflow_non_agentic.py

@@ -0,0 +1,36 @@
+"""
+Simple Workflow Example
+
+The easiest way to create and run workflows in PraisonAI.
+Just pass functions or agents as steps - no complex configuration needed!
+"""
+
+from praisonaiagents import Workflow, WorkflowContext, StepResult
+
+# Define simple handler functions
+def validate(ctx: WorkflowContext) -> StepResult:
+    """Validate the input data."""
+    if not ctx.input:
+        return StepResult(output="No input provided", stop_workflow=True)
+    return StepResult(output=f"Validated: {ctx.input}")
+
+def process(ctx: WorkflowContext) -> StepResult:
+    """Process the validated data."""
+    return StepResult(output=f"Processed: {ctx.previous_result}")
+
+def format_output(ctx: WorkflowContext) -> StepResult:
+    """Format the final output."""
+    return StepResult(output=f"✅ Final: {ctx.previous_result}")
+
+# Create workflow - just list your functions!
+workflow = Workflow(
+    name="Simple Pipeline",
+    steps=[validate, process, format_output]
+)
+
+if __name__ == "__main__":
+    # Run the workflow - PraisonAI style uses .start()
+    result = workflow.start("Hello, World!", verbose=True)
+    
+    print(f"\nFinal output: {result['output']}")
+    print(f"Steps completed: {len(result['steps'])}")

examples/python/workflows/workflow_conditional.py

@@ -1,68 +1,83 @@
 """
-Workflow Conditional Execution Example
+Agentic Conditional Workflow Example
 
-Demonstrates using should_run to conditionally execute steps
+Demonstrates using should_run to conditionally execute agent steps
 based on input or previous results.
 """
 
-from praisonaiagents import Workflow, WorkflowStep, WorkflowContext, StepResult
+from praisonaiagents import Agent, Workflow, WorkflowStep
 
-# Condition functions - return True to run the step, False to skip
-def is_sensitive_content(ctx: WorkflowContext) -> bool:
-    """Only run compliance check for sensitive topics."""
-    sensitive_keywords = ["legal", "medical", "financial", "security"]
-    return any(keyword in ctx.input.lower() for keyword in sensitive_keywords)
+# Condition functions
+def is_technical(ctx) -> bool:
+    """Only run technical review for technical content."""
+    keywords = ["code", "programming", "algorithm", "database", "api"]
+    return any(keyword in ctx.input.lower() for keyword in keywords)
 
-def needs_translation(ctx: WorkflowContext) -> bool:
-    """Only translate if content is not in English."""
-    return ctx.variables.get("language", "en") != "en"
+def needs_creative(ctx) -> bool:
+    """Only run creative enhancement for creative content."""
+    keywords = ["story", "poem", "creative", "write", "narrative"]
+    return any(keyword in ctx.input.lower() for keyword in keywords)
 
-# Handler functions
-def process_content(ctx: WorkflowContext) -> StepResult:
-    return StepResult(output=f"Processed: {ctx.input}")
+# Create agents
+analyzer = Agent(
+    name="Analyzer",
+    role="Content Analyzer",
+    goal="Analyze and process content",
+    instructions="Analyze the given content and provide insights."
+)
 
-def compliance_check(ctx: WorkflowContext) -> StepResult:
-    return StepResult(output=f"✅ Compliance verified for: {ctx.previous_result}")
+tech_reviewer = Agent(
+    name="TechReviewer",
+    role="Technical Reviewer",
+    goal="Review technical content",
+    instructions="Review the technical aspects and provide technical feedback."
+)
 
-def translate(ctx: WorkflowContext) -> StepResult:
-    lang = ctx.variables.get("language", "unknown")
-    return StepResult(output=f"🌐 Translated to {lang}: {ctx.previous_result}")
+creative_enhancer = Agent(
+    name="CreativeEnhancer",
+    role="Creative Enhancer",
+    goal="Enhance creative content",
+    instructions="Enhance the creative aspects and make it more engaging."
+)
 
-def finalize(ctx: WorkflowContext) -> StepResult:
-    return StepResult(output=f"📄 Final: {ctx.previous_result}")
+finalizer = Agent(
+    name="Finalizer",
+    role="Content Finalizer",
+    goal="Finalize the content",
+    instructions="Provide the final polished version of the content."
+)
 
 # Create workflow with conditional steps
 workflow = Workflow(
-    name="Conditional Pipeline",
+    name="Conditional Agentic Pipeline",
     steps=[
-        WorkflowStep(name="process", handler=process_content),
+        analyzer,  # Always runs
         WorkflowStep(
-            name="compliance",
-            handler=compliance_check,
-            should_run=is_sensitive_content  # Only runs for sensitive content
+            name="tech_review",
+            agent=tech_reviewer,
+            should_run=is_technical  # Only runs for technical content
         ),
         WorkflowStep(
-            name="translate",
-            handler=translate,
-            should_run=needs_translation  # Only runs if language != "en"
+            name="creative_enhance",
+            agent=creative_enhancer,
+            should_run=needs_creative  # Only runs for creative content
         ),
-        WorkflowStep(name="finalize", handler=finalize)
+        finalizer  # Always runs
     ]
 )
 
 if __name__ == "__main__":
-    # Test 1: Normal content (skips compliance)
-    print("=== Test 1: Normal content ===")
-    result = workflow.start("Hello world", verbose=True)
-    print(f"Output: {result['output']}\n")
+    # Test 1: Technical content
+    print("=== Test 1: Technical Content ===")
+    result = workflow.start("Review this Python code for best practices", verbose=True)
+    print(f"Output: {result['output'][:200]}...\n")
     
-    # Test 2: Sensitive content (runs compliance)
-    print("=== Test 2: Legal content ===")
-    result = workflow.start("Review this legal document", verbose=True)
-    print(f"Output: {result['output']}\n")
+    # Test 2: Creative content
+    print("=== Test 2: Creative Content ===")
+    result = workflow.start("Write a short story about a robot", verbose=True)
+    print(f"Output: {result['output'][:200]}...\n")
     
-    # Test 3: Non-English content (runs translation)
-    print("=== Test 3: Non-English content ===")
-    workflow.variables = {"language": "es"}
-    result = workflow.start("Hola mundo", verbose=True)
-    print(f"Output: {result['output']}")
+    # Test 3: General content (neither technical nor creative)
+    print("=== Test 3: General Content ===")
+    result = workflow.start("What is the weather like today?", verbose=True)
+    print(f"Output: {result['output'][:200]}...")

examples/python/workflows/workflow_conditional_non_agentic.py

@@ -0,0 +1,68 @@
+"""
+Workflow Conditional Execution Example
+
+Demonstrates using should_run to conditionally execute steps
+based on input or previous results.
+"""
+
+from praisonaiagents import Workflow, WorkflowStep, WorkflowContext, StepResult
+
+# Condition functions - return True to run the step, False to skip
+def is_sensitive_content(ctx: WorkflowContext) -> bool:
+    """Only run compliance check for sensitive topics."""
+    sensitive_keywords = ["legal", "medical", "financial", "security"]
+    return any(keyword in ctx.input.lower() for keyword in sensitive_keywords)
+
+def needs_translation(ctx: WorkflowContext) -> bool:
+    """Only translate if content is not in English."""
+    return ctx.variables.get("language", "en") != "en"
+
+# Handler functions
+def process_content(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output=f"Processed: {ctx.input}")
+
+def compliance_check(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output=f"✅ Compliance verified for: {ctx.previous_result}")
+
+def translate(ctx: WorkflowContext) -> StepResult:
+    lang = ctx.variables.get("language", "unknown")
+    return StepResult(output=f"🌐 Translated to {lang}: {ctx.previous_result}")
+
+def finalize(ctx: WorkflowContext) -> StepResult:
+    return StepResult(output=f"📄 Final: {ctx.previous_result}")
+
+# Create workflow with conditional steps
+workflow = Workflow(
+    name="Conditional Pipeline",
+    steps=[
+        WorkflowStep(name="process", handler=process_content),
+        WorkflowStep(
+            name="compliance",
+            handler=compliance_check,
+            should_run=is_sensitive_content  # Only runs for sensitive content
+        ),
+        WorkflowStep(
+            name="translate",
+            handler=translate,
+            should_run=needs_translation  # Only runs if language != "en"
+        ),
+        WorkflowStep(name="finalize", handler=finalize)
+    ]
+)
+
+if __name__ == "__main__":
+    # Test 1: Normal content (skips compliance)
+    print("=== Test 1: Normal content ===")
+    result = workflow.start("Hello world", verbose=True)
+    print(f"Output: {result['output']}\n")
+    
+    # Test 2: Sensitive content (runs compliance)
+    print("=== Test 2: Legal content ===")
+    result = workflow.start("Review this legal document", verbose=True)
+    print(f"Output: {result['output']}\n")
+    
+    # Test 3: Non-English content (runs translation)
+    print("=== Test 3: Non-English content ===")
+    workflow.variables = {"language": "es"}
+    result = workflow.start("Hola mundo", verbose=True)
+    print(f"Output: {result['output']}")

examples/python/workflows/workflow_loop_csv.py

@@ -0,0 +1,59 @@
+"""
+Agentic Loop with CSV Workflow Example
+
+Demonstrates iterating over a CSV file with an agent processing each row.
+"""
+
+from praisonaiagents import Agent, Workflow
+from praisonaiagents.workflows import loop
+import tempfile
+import os
+
+# Create sample CSV file content
+csv_content = """topic,description
+AI Ethics,Ethical considerations in artificial intelligence
+Machine Learning,Algorithms that learn from data
+Neural Networks,Computing systems inspired by biological neural networks
+Natural Language Processing,AI understanding human language"""
+
+# Create processor agent
+processor = Agent(
+    name="TopicProcessor",
+    role="Topic Analyst",
+    goal="Analyze and explain topics",
+    instructions="Provide a brief, insightful analysis of the given topic."
+)
+
+# Create summarizer agent
+summarizer = Agent(
+    name="Summarizer",
+    role="Results Summarizer",
+    goal="Summarize all processed results",
+    instructions="Create a comprehensive summary of all the analyzed topics."
+)
+
+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 Agentic Loop with CSV ===\n")
+        print(f"Processing CSV: {csv_path}\n")
+        
+        # Create workflow with loop over CSV
+        workflow = Workflow(
+            name="CSV Topic Processor",
+            steps=[
+                loop(processor, from_csv=csv_path),
+                summarizer
+            ]
+        )
+        
+        result = workflow.start("Analyze these AI topics", verbose=True)
+        
+        print(f"\nFinal Summary:\n{result['output']}")
+        
+    finally:
+        os.unlink(csv_path)

examples/python/workflows/workflow_loop_csv_non_agentic.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,56 @@
+"""
+Agentic Parallel Workflow Example
+
+Demonstrates running multiple agents concurrently and
+combining their results with an aggregator agent.
+"""
+
+from praisonaiagents import Agent, Workflow
+from praisonaiagents.workflows import parallel
+
+# Create parallel research agents
+market_researcher = Agent(
+    name="MarketResearcher",
+    role="Market Research Analyst",
+    goal="Research market trends and opportunities",
+    instructions="Analyze market trends. Provide concise market insights."
+)
+
+competitor_researcher = Agent(
+    name="CompetitorResearcher", 
+    role="Competitive Intelligence Analyst",
+    goal="Research competitor strategies",
+    instructions="Analyze competitors. Provide key competitive insights."
+)
+
+customer_researcher = Agent(
+    name="CustomerResearcher",
+    role="Customer Research Analyst", 
+    goal="Research customer needs and behaviors",
+    instructions="Analyze customer segments. Provide customer insights."
+)
+
+# Create aggregator agent
+aggregator = Agent(
+    name="Aggregator",
+    role="Research Synthesizer",
+    goal="Synthesize research findings",
+    instructions="Combine all research findings into a comprehensive summary."
+)
+
+# Create workflow with parallel execution
+workflow = Workflow(
+    name="Parallel Research Pipeline",
+    steps=[
+        parallel([market_researcher, competitor_researcher, customer_researcher]),
+        aggregator
+    ]
+)
+
+if __name__ == "__main__":
+    print("=== Testing Agentic Parallel Workflow ===\n")
+    
+    # Run workflow - all researchers work in parallel, then aggregator summarizes
+    result = workflow.start("Research the AI industry", verbose=True)
+    
+    print(f"\nFinal Summary:\n{result['output']}")

examples/python/workflows/workflow_parallel_non_agentic.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,53 @@
+"""
+Agentic Evaluator-Optimizer (Repeat) Workflow Example
+
+Demonstrates the evaluator-optimizer pattern where an agent
+generates content and another evaluates it, repeating until approved.
+"""
+
+from praisonaiagents import Agent, Workflow
+from praisonaiagents.workflows import repeat
+
+# Create generator agent
+generator = Agent(
+    name="Generator",
+    role="Content Generator",
+    goal="Generate high-quality content",
+    instructions="Generate content based on the topic. Improve based on feedback if provided."
+)
+
+# Create evaluator agent  
+evaluator = Agent(
+    name="Evaluator",
+    role="Content Evaluator",
+    goal="Evaluate and provide feedback on content",
+    instructions="Evaluate the content quality. If good, respond with 'APPROVED'. Otherwise provide specific feedback for improvement."
+)
+
+# Evaluation function to check if content is approved
+def is_approved(ctx) -> bool:
+    return "approved" in ctx.previous_result.lower()
+
+# Create workflow with evaluator-optimizer pattern
+workflow = Workflow(
+    name="Evaluator-Optimizer Pipeline",
+    steps=[
+        generator,  # First, generate content
+        repeat(
+            evaluator,  # Evaluate and provide feedback
+            until=is_approved,
+            max_iterations=3
+        )
+    ]
+)
+
+if __name__ == "__main__":
+    print("=== Testing Agentic Evaluator-Optimizer Workflow ===\n")
+    
+    # Run optimization workflow
+    result = workflow.start(
+        "Write a compelling product description for an AI assistant",
+        verbose=True
+    )
+    
+    print(f"\nFinal Result:\n{result['output']}")

examples/python/workflows/workflow_repeat_non_agentic.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,65 @@
+"""
+Agentic Routing Workflow Example
+
+Demonstrates decision-based routing where an agent classifier
+routes to specialized handler agents based on the request type.
+"""
+
+from praisonaiagents import Agent, Workflow
+from praisonaiagents.workflows import route
+
+# Create classifier agent
+classifier = Agent(
+    name="Classifier",
+    role="Request Classifier",
+    goal="Classify incoming requests",
+    instructions="Classify the request. Respond with ONLY 'technical', 'creative', or 'general'."
+)
+
+# Create specialized handler agents
+tech_agent = Agent(
+    name="TechExpert",
+    role="Technical Expert",
+    goal="Handle technical questions",
+    instructions="You are a technical expert. Provide detailed technical answers."
+)
+
+creative_agent = Agent(
+    name="CreativeWriter",
+    role="Creative Writer", 
+    goal="Handle creative requests",
+    instructions="You are a creative writer. Write engaging, creative content."
+)
+
+general_agent = Agent(
+    name="GeneralAssistant",
+    role="General Assistant",
+    goal="Handle general requests",
+    instructions="You are a helpful assistant. Provide clear, helpful responses."
+)
+
+# Create workflow with routing
+workflow = Workflow(
+    name="Agentic Router",
+    steps=[
+        classifier,
+        route({
+            "technical": [tech_agent],
+            "creative": [creative_agent],
+            "default": [general_agent]
+        })
+    ]
+)
+
+if __name__ == "__main__":
+    print("=== Testing Agentic Routing Workflow ===\n")
+    
+    # Test 1: Technical question
+    print("--- Technical Request ---")
+    result = workflow.start("How does machine learning work?", verbose=True)
+    print(f"Result: {result['output'][:200]}...\n")
+    
+    # Test 2: Creative request
+    print("--- Creative Request ---")
+    result = workflow.start("Write a poem about the ocean", verbose=True)
+    print(f"Result: {result['output'][:200]}...")

examples/python/workflows/workflow_routing_non_agentic.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']}")

examples/yaml/agents_workflow.yaml

@@ -0,0 +1,117 @@
+# Extended agents.yaml with Workflow Patterns
+# This file demonstrates the extended agents.yaml format that supports
+# advanced workflow patterns while maintaining backward compatibility.
+#
+# Usage: praisonai agents_workflow.yaml
+#
+# Key differences from standard agents.yaml:
+# - process: workflow (triggers workflow mode)
+# - workflow: section for planning, reasoning, memory
+# - steps: section for workflow patterns (route, parallel, loop, repeat)
+
+framework: praisonai
+process: workflow
+topic: "Research AI trends and create a comprehensive report"
+
+# Workflow configuration (new)
+workflow:
+  planning: true
+  reasoning: true
+  verbose: true
+  memory_config:
+    provider: chroma
+    persist: true
+
+# Variables for template substitution
+variables:
+  topic: AI trends
+  topics:
+    - Machine Learning
+    - Neural Networks
+    - Natural Language Processing
+
+# Agent definitions using familiar 'roles' format
+agents:  # Canonical: use 'agents' instead of 'roles'
+  classifier:
+    role: Request Classifier
+    instructions:  # Canonical |
+      You are an expert at classifying requests into categories.
+      Respond with ONLY one word: 'technical', 'creative', or 'research'.
+    goal: Classify incoming requests accurately
+    
+  researcher:
+    role: Research Analyst
+    instructions:  # Canonical |
+      You are a skilled research analyst with expertise in technology trends.
+      You provide concise, factual research findings with citations.
+    goal: Research topics thoroughly and provide insights
+    tools:
+      - tavily_search
+    llm:
+      model: gpt-4o-mini
+      
+  tech_expert:
+    role: Technical Expert
+    instructions:  # Canonical |
+      You are a technical expert with deep knowledge in AI and ML.
+      You provide detailed technical explanations.
+    goal: Handle technical questions with expertise
+    
+  creative_writer:
+    role: Creative Writer
+    instructions:  # Canonical |
+      You are a creative writer who can make complex topics engaging.
+      You write in a clear, accessible style.
+    goal: Create engaging content from research
+    
+  market_analyst:
+    role: Market Analyst
+    instructions:  # Canonical |
+      You analyze market trends and competitive landscapes.
+      You provide actionable business insights.
+    goal: Analyze market trends and opportunities
+    
+  aggregator:
+    role: Synthesizer
+    instructions:  # Canonical |
+      You combine findings from multiple sources into coherent reports.
+      You identify patterns and key insights.
+    goal: Synthesize all findings into comprehensive reports
+
+# Workflow steps with patterns (new)
+steps:
+  # Step 1: Classify the request
+  - agent: classifier
+    action: "Classify this request: {{topic}}"
+    
+  # Step 2: Route to appropriate handler based on classification
+  - name: routing
+    route:
+      technical: [tech_expert]
+      creative: [creative_writer]
+      default: [researcher]
+      
+  # Step 3: Parallel research on multiple aspects
+  - name: parallel_research
+    parallel:
+      - agent: researcher
+        action: "Research technology trends for {{topic}}"
+      - agent: market_analyst
+        action: "Analyze market opportunities for {{topic}}"
+        
+  # Step 4: Loop over specific topics
+  - agent: researcher
+    action: "Deep dive into {{item}}"
+    loop:
+      over: topics
+      
+  # Step 5: Aggregate all findings
+  - agent: aggregator
+    action: "Synthesize all research findings into a comprehensive report"
+    repeat:
+      until: "comprehensive"
+      max_iterations: 2
+
+# Optional callbacks
+callbacks:
+  on_step_complete: log_step

examples/yaml/workflows/complete_workflow.yaml

@@ -0,0 +1,116 @@
+# Complete Workflow Example
+# Demonstrates all workflow patterns in a single comprehensive workflow
+
+name: Complete Research Workflow
+description: A comprehensive workflow demonstrating all patterns - route, parallel, loop, repeat
+framework: praisonai
+
+workflow:
+  planning: true
+  reasoning: true
+  verbose: true
+  memory_config:
+    provider: chroma
+    persist: true
+
+variables:
+  topic: AI trends
+  topics:
+    - Machine Learning
+    - Neural Networks
+    - Natural Language Processing
+
+agents:
+  classifier:
+    name: Classifier
+    role: Request Classifier
+    goal: Classify incoming requests
+    instructions: |
+      Classify the request. Respond with ONLY one word:
+      - 'technical' for technical questions
+      - 'creative' for creative requests
+      - 'research' for research tasks
+
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research topics thoroughly
+    instructions: "You are a research analyst. Provide concise, factual research findings."
+
+  tech_expert:
+    name: TechExpert
+    role: Technical Expert
+    goal: Handle technical questions
+    instructions: "You are a technical expert. Provide detailed technical answers."
+
+  creative_writer:
+    name: CreativeWriter
+    role: Creative Writer
+    goal: Handle creative requests
+    instructions: "You are a creative writer. Write engaging, creative content."
+
+  market_analyst:
+    name: MarketAnalyst
+    role: Market Analyst
+    goal: Analyze market trends
+    instructions: "You are a market analyst. Provide market insights."
+
+  competitor_analyst:
+    name: CompetitorAnalyst
+    role: Competitor Analyst
+    goal: Analyze competitors
+    instructions: "You are a competitor analyst. Provide competitive insights."
+
+  aggregator:
+    name: Aggregator
+    role: Synthesizer
+    goal: Combine and synthesize findings
+    instructions: "You are a synthesizer. Combine all findings into a comprehensive report."
+
+  evaluator:
+    name: Evaluator
+    role: Quality Evaluator
+    goal: Evaluate content quality
+    instructions: |
+      Evaluate the content. If it's comprehensive and well-structured, respond with "APPROVED".
+      Otherwise, provide specific feedback for improvement.
+
+steps:
+  # Step 1: Classify the request
+  - agent: classifier
+    action: "Classify: {{input}}"
+    
+  # Step 2: Route to appropriate handler
+  - name: routing
+    route:
+      technical: [tech_expert]
+      creative: [creative_writer]
+      default: [researcher]
+      
+  # Step 3: Parallel research
+  - name: parallel_research
+    parallel:
+      - agent: market_analyst
+        action: "Analyze market for {{topic}}"
+      - agent: competitor_analyst
+        action: "Analyze competitors for {{topic}}"
+        
+  # Step 4: Loop over topics
+  - agent: researcher
+    action: "Research {{item}}"
+    loop:
+      over: topics
+      
+  # Step 5: Aggregate findings
+  - agent: aggregator
+    action: "Synthesize all findings into a comprehensive report"
+    
+  # Step 6: Evaluator-optimizer
+  - agent: evaluator
+    action: "Evaluate the report quality"
+    repeat:
+      until: "approved"
+      max_iterations: 2
+
+callbacks:
+  on_step_complete: log_step

examples/yaml/workflows/evaluator_optimizer_workflow.yaml

@@ -0,0 +1,43 @@
+# Evaluator-Optimizer Workflow
+# Demonstrates the repeat() pattern for iterative improvement
+
+name: Evaluator Optimizer Workflow
+description: A generator creates content, an evaluator reviews it repeatedly until quality standards are met
+
+workflow:
+  verbose: true
+
+agents:
+  generator:
+    name: Generator
+    role: Content Generator
+    goal: Generate high-quality content
+    instructions: |
+      You are a content generator. Generate content based on the request.
+      If feedback is provided, improve your content based on that feedback.
+      Always strive for clarity, accuracy, and engagement.
+
+  evaluator:
+    name: Evaluator
+    role: Content Evaluator
+    goal: Evaluate content quality and provide feedback
+    instructions: |
+      You are a content evaluator. Review the content provided.
+      
+      If the content is high quality (clear, accurate, engaging), respond with:
+      "APPROVED: [brief reason]"
+      
+      If the content needs improvement, respond with:
+      "NEEDS IMPROVEMENT: [specific feedback for improvement]"
+      
+      Be constructive and specific in your feedback.
+
+steps:
+  - agent: generator
+    action: "Generate content for: {{input}}"
+    
+  - agent: evaluator
+    action: "Evaluate this content and provide feedback: {{previous_output}}"
+    repeat:
+      until: "approved"
+      max_iterations: 3

examples/yaml/workflows/example_usage.py

@@ -0,0 +1,152 @@
+"""
+Example usage of YAML Workflow Parser.
+
+This script demonstrates how to load and execute YAML workflow files.
+"""
+
+import os
+from pathlib import Path
+
+# Ensure OPENAI_API_KEY is set
+if not os.getenv("OPENAI_API_KEY"):
+    print("Please set OPENAI_API_KEY environment variable")
+    print("export OPENAI_API_KEY='your-api-key'")
+    exit(1)
+
+from praisonaiagents.workflows import YAMLWorkflowParser, WorkflowManager
+
+
+def example_1_parse_and_run():
+    """Example 1: Parse YAML and run workflow directly."""
+    print("=" * 60)
+    print("Example 1: Parse YAML and run workflow")
+    print("=" * 60)
+    
+    yaml_content = """
+name: Quick Research
+description: A quick research workflow
+
+agents:
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research topics
+    instructions: "Provide brief, factual information."
+
+steps:
+  - agent: researcher
+    action: "Research: {{input}}"
+"""
+    
+    parser = YAMLWorkflowParser()
+    workflow = parser.parse_string(yaml_content)
+    
+    print(f"Workflow Name: {workflow.name}")
+    print(f"Steps: {len(workflow.steps)}")
+    
+    # Run the workflow
+    result = workflow.start("What is Python?")
+    print(f"Result: {result['output'][:200]}...")
+    print()
+
+
+def example_2_load_yaml_file():
+    """Example 2: Load workflow from YAML file using WorkflowManager."""
+    print("=" * 60)
+    print("Example 2: Load YAML file with WorkflowManager")
+    print("=" * 60)
+    
+    # Get the directory of this script
+    script_dir = Path(__file__).parent
+    yaml_file = script_dir / "simple_workflow.yaml"
+    
+    if not yaml_file.exists():
+        print(f"YAML file not found: {yaml_file}")
+        return
+    
+    manager = WorkflowManager()
+    workflow = manager.load_yaml(yaml_file)
+    
+    print(f"Loaded workflow: {workflow.name}")
+    print(f"Steps: {len(workflow.steps)}")
+    
+    # Run the workflow
+    result = workflow.start("Benefits of renewable energy")
+    print(f"Result: {result['output'][:200]}...")
+    print()
+
+
+def example_3_execute_yaml_directly():
+    """Example 3: Execute YAML file directly with WorkflowManager."""
+    print("=" * 60)
+    print("Example 3: Execute YAML directly")
+    print("=" * 60)
+    
+    script_dir = Path(__file__).parent
+    yaml_file = script_dir / "simple_workflow.yaml"
+    
+    if not yaml_file.exists():
+        print(f"YAML file not found: {yaml_file}")
+        return
+    
+    manager = WorkflowManager()
+    result = manager.execute_yaml(
+        yaml_file,
+        input_data="The future of AI",
+        verbose=True
+    )
+    
+    print(f"Status: {result['status']}")
+    print(f"Result: {result['output'][:200]}...")
+    print()
+
+
+def example_4_with_variables():
+    """Example 4: YAML workflow with variables."""
+    print("=" * 60)
+    print("Example 4: Workflow with variables")
+    print("=" * 60)
+    
+    yaml_content = """
+name: Variable Workflow
+variables:
+  topic: Machine Learning
+  style: concise
+
+agents:
+  writer:
+    name: Writer
+    role: Content Writer
+    goal: Write content
+    instructions: "Write {{style}} content about the topic."
+
+steps:
+  - agent: writer
+    action: "Write about {{topic}}"
+"""
+    
+    parser = YAMLWorkflowParser()
+    workflow = parser.parse_string(yaml_content)
+    
+    print(f"Variables: {workflow.variables}")
+    
+    # Run with default variables
+    result = workflow.start("")
+    print(f"Result: {result['output'][:200]}...")
+    print()
+
+
+if __name__ == "__main__":
+    print("YAML Workflow Examples")
+    print("=" * 60)
+    print()
+    
+    # Run examples
+    example_1_parse_and_run()
+    example_2_load_yaml_file()
+    example_3_execute_yaml_directly()
+    example_4_with_variables()
+    
+    print("=" * 60)
+    print("All examples completed!")
+    print("=" * 60)

examples/yaml/workflows/loop_workflow.yaml

@@ -0,0 +1,42 @@
+# Loop Workflow
+# Demonstrates the loop() pattern for iterating over items
+
+name: Repetitive Processing Workflow
+description: An agent processes multiple items in a loop, then a summarizer combines results
+
+workflow:
+  verbose: true
+
+variables:
+  topics:
+    - Artificial Intelligence
+    - Machine Learning
+    - Neural Networks
+    - Natural Language Processing
+
+agents:
+  processor:
+    name: Processor
+    role: Topic Processor
+    goal: Process and analyze each topic thoroughly
+    instructions: |
+      You are a topic processor. For each topic given, provide:
+      1. A brief definition
+      2. Key concepts
+      3. Real-world applications
+      Keep your response concise but informative.
+
+  summarizer:
+    name: Summarizer
+    role: Results Summarizer
+    goal: Summarize all processed results into a final report
+    instructions: "You are a summarizer. Combine all the processed topics into a cohesive final report."
+
+steps:
+  - agent: processor
+    action: "Analyze this topic: {{item}}"
+    loop:
+      over: topics
+      
+  - agent: summarizer
+    action: "Create a comprehensive summary of all the analyzed topics"

examples/yaml/workflows/parallel_workflow.yaml

@@ -0,0 +1,46 @@
+# Parallel Workflow
+# Demonstrates the parallel() pattern for concurrent execution
+
+name: Parallel Research Workflow
+description: Multiple agents research different aspects concurrently, then an aggregator combines results
+
+workflow:
+  verbose: true
+
+agents:
+  market_researcher:
+    name: MarketResearcher
+    role: Market Research Analyst
+    goal: Research market trends and opportunities
+    instructions: "You are a market research analyst. Analyze market trends and provide concise insights."
+
+  competitor_researcher:
+    name: CompetitorResearcher
+    role: Competitive Intelligence Analyst
+    goal: Research competitor strategies and positioning
+    instructions: "You are a competitive intelligence analyst. Analyze competitors and provide key insights."
+
+  customer_researcher:
+    name: CustomerResearcher
+    role: Customer Research Analyst
+    goal: Research customer needs and behaviors
+    instructions: "You are a customer research analyst. Analyze customer segments and provide insights."
+
+  aggregator:
+    name: Aggregator
+    role: Research Synthesizer
+    goal: Synthesize all research findings into a comprehensive summary
+    instructions: "You are a research synthesizer. Combine all research findings into a clear, comprehensive summary."
+
+steps:
+  - name: parallel_research
+    parallel:
+      - agent: market_researcher
+        action: "Research market trends for: {{input}}"
+      - agent: competitor_researcher
+        action: "Research competitors for: {{input}}"
+      - agent: customer_researcher
+        action: "Research customer needs for: {{input}}"
+        
+  - agent: aggregator
+    action: "Synthesize all the research findings into a comprehensive report"

examples/yaml/workflows/routing_workflow.yaml

@@ -0,0 +1,49 @@
+# Routing Workflow
+# Demonstrates the route() pattern for decision-based branching
+
+name: Agentic Routing Workflow
+description: A classifier agent routes requests to specialized handler agents
+
+workflow:
+  verbose: true
+
+agents:
+  classifier:
+    name: Classifier
+    role: Request Classifier
+    goal: Classify incoming requests by type
+    instructions: |
+      You are a request classifier. Analyze the request and respond with ONLY one word:
+      - 'technical' for technical/coding questions
+      - 'creative' for creative writing requests
+      - 'general' for everything else
+      
+      Respond with ONLY the classification word, nothing else.
+
+  tech_expert:
+    name: TechExpert
+    role: Technical Expert
+    goal: Answer technical questions with expertise
+    instructions: "You are a technical expert. Provide detailed, accurate technical answers."
+
+  creative_writer:
+    name: CreativeWriter
+    role: Creative Writer
+    goal: Create engaging creative content
+    instructions: "You are a creative writer. Write engaging, imaginative content."
+
+  general_assistant:
+    name: GeneralAssistant
+    role: General Assistant
+    goal: Help with general requests
+    instructions: "You are a helpful assistant. Provide clear, helpful responses."
+
+steps:
+  - agent: classifier
+    action: "Classify this request: {{input}}"
+    
+  - name: routing
+    route:
+      technical: [tech_expert]
+      creative: [creative_writer]
+      default: [general_assistant]

examples/yaml/workflows/simple_workflow.yaml

@@ -0,0 +1,28 @@
+# Simple Sequential Workflow
+# Demonstrates basic agent-to-agent workflow
+
+name: Simple Research Workflow
+description: A simple workflow where a researcher gathers info and a writer summarizes it
+
+workflow:
+  verbose: true
+
+agents:
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research and gather information about topics
+    instructions: "You are a research analyst. Provide concise, factual information about the given topic."
+
+  writer:
+    name: Writer
+    role: Content Writer
+    goal: Write clear and engaging summaries
+    instructions: "You are a content writer. Take the research provided and write a clear, engaging summary."
+
+steps:
+  - agent: researcher
+    action: "Research the following topic: {{input}}"
+    
+  - agent: writer
+    action: "Write a summary based on this research: {{previous_output}}"

src/praisonai-agents/README.md

@@ -0,0 +1 @@
+../../README.md

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/process/process.py

@@ -826,7 +826,34 @@ Provide a JSON with the structure:
         logging.info("Hierarchical task execution finished")
 
     def workflow(self):
-        """Synchronous version of workflow method"""
+        """Synchronous version of workflow method.
+        
+        DEPRECATED: This method is deprecated. Use the Workflow class instead:
+        
+        ```python
+        from praisonaiagents import Workflow, StepResult
+        from praisonaiagents.workflows import route, parallel, loop, repeat
+        
+        workflow = Workflow(steps=[step1, step2])
+        result = workflow.start("input")
+        ```
+        
+        The Workflow class provides a simpler API with more features:
+        - route() for decision-based branching
+        - parallel() for concurrent execution
+        - loop() for iteration over lists/CSV
+        - repeat() for evaluator-optimizer patterns
+        - Callbacks (on_step_start, on_step_complete, etc.)
+        - Guardrails with validation feedback
+        - Status tracking
+        """
+        import warnings
+        warnings.warn(
+            "process='workflow' is deprecated. Use the Workflow class instead: "
+            "from praisonaiagents import Workflow; workflow = Workflow(steps=[...]); workflow.start()",
+            DeprecationWarning,
+            stacklevel=2
+        )
         current_iter = 0  # Track how many times we've looped
         # Build workflow relationships first
         for task in self.tasks.values():

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

@@ -0,0 +1,60 @@
+"""
+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,
+)
+
+from .yaml_parser import YAMLWorkflowParser
+
+__all__ = [
+    # Core
+    "Workflow",
+    "Pipeline",
+    "WorkflowStep",
+    "WorkflowContext",
+    "StepResult",
+    "WorkflowManager",
+    
+    # YAML Parser
+    "YAMLWorkflowParser",
+    
+    # Patterns
+    "Route",
+    "Parallel",
+    "Loop",
+    "Repeat",
+    "route",
+    "parallel",
+    "loop",
+    "repeat",
+    
+    # Aliases
+    "StepInput",
+    "StepOutput",
+]

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

@@ -0,0 +1,739 @@
+"""
+YAML Workflow Parser for PraisonAI Agents.
+
+Parses YAML workflow files into Workflow objects with support for:
+- Agent definitions with planning, reasoning, tools
+- Workflow patterns: route(), parallel(), loop(), repeat()
+- Variables and template substitution
+- Callbacks and guardrails
+- Memory configuration
+"""
+
+import yaml
+from typing import Any, Callable, Dict, List, Optional, Union
+from pathlib import Path
+
+from ..agent.agent import Agent
+from .workflows import Workflow, WorkflowStep, route, parallel, loop, repeat
+
+
+class YAMLWorkflowParser:
+    """
+    Parser for YAML workflow files.
+    
+    Converts YAML workflow definitions into Workflow objects that can be executed.
+    
+    Example YAML format:
+    ```yaml
+    name: My Workflow
+    description: A multi-agent workflow
+    
+    workflow:
+      planning: true
+      reasoning: true
+      verbose: true
+      memory_config:
+        provider: chroma
+        persist: true
+    
+    variables:
+      topic: AI trends
+    
+    agents:
+      researcher:
+        name: Researcher
+        role: Research Analyst
+        goal: Research topics
+        instructions: "Provide research findings"
+        tools:
+          - tavily_search
+    
+    steps:
+      - agent: researcher
+        action: "Research {{topic}}"
+      - name: routing
+        route:
+          technical: [tech_agent]
+          default: [general_agent]
+    
+    callbacks:
+      on_step_complete: log_step
+    ```
+    """
+    
+    def __init__(self, tool_registry: Optional[Dict[str, Callable]] = None):
+        """
+        Initialize the YAML workflow parser.
+        
+        Args:
+            tool_registry: Optional dictionary mapping tool names to callable functions
+        """
+        self.tool_registry = tool_registry or {}
+        self._agents: Dict[str, Agent] = {}
+        self._callbacks: Dict[str, Callable] = {}
+    
+    def parse_file(self, file_path: Union[str, Path]) -> Workflow:
+        """
+        Parse a YAML workflow file.
+        
+        Args:
+            file_path: Path to the YAML file
+            
+        Returns:
+            Workflow object ready for execution
+        """
+        file_path = Path(file_path)
+        if not file_path.exists():
+            raise FileNotFoundError(f"Workflow file not found: {file_path}")
+        
+        with open(file_path, 'r') as f:
+            yaml_content = f.read()
+        
+        return self.parse_string(yaml_content)
+    
+    def parse_string(self, yaml_content: str) -> Workflow:
+        """
+        Parse a YAML workflow string.
+        
+        Args:
+            yaml_content: YAML content as string
+            
+        Returns:
+            Workflow object ready for execution
+        """
+        data = yaml.safe_load(yaml_content)
+        # Normalize to canonical format (accept both old and new field names)
+        normalized_data = self._normalize_yaml_config(data)
+        return self._parse_workflow_data(normalized_data)
+    
+    def _normalize_yaml_config(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Normalize YAML config to canonical format.
+        
+        Accepts both old (agents.yaml) and new (workflow.yaml) field names.
+        This implements "Accept liberally, suggest canonically" principle.
+        
+        Canonical names (preferred):
+        - agents (not roles)
+        - instructions (not backstory)  
+        - action (not description)
+        - steps (not tasks)
+        - name (not topic)
+        
+        Args:
+            data: Raw parsed YAML data
+            
+        Returns:
+            Normalized data with canonical field names
+        """
+        if not data:
+            return data
+            
+        normalized = data.copy()
+        
+        # 1. Normalize workflow name: topic -> name
+        if 'topic' in normalized and 'name' not in normalized:
+            normalized['name'] = normalized.get('topic', 'Unnamed Workflow')
+        
+        # 2. Normalize container: roles -> agents
+        # Note: _convert_roles_to_agents handles backstory -> instructions
+        if 'roles' in normalized and 'agents' not in normalized:
+            normalized['agents'] = self._convert_roles_to_agents(normalized['roles'])
+            # Extract steps from tasks nested in roles if no steps defined
+            if 'steps' not in normalized:
+                normalized['steps'] = self._extract_steps_from_roles(normalized['roles'])
+        
+        # 3. Normalize agent fields: backstory -> instructions (for agents section)
+        if 'agents' in normalized:
+            for agent_id, agent_config in normalized['agents'].items():
+                if isinstance(agent_config, dict):
+                    # backstory -> instructions
+                    if 'backstory' in agent_config and 'instructions' not in agent_config:
+                        agent_config['instructions'] = agent_config['backstory']
+        
+        # 4. Normalize step fields: description -> action
+        if 'steps' in normalized:
+            for step in normalized['steps']:
+                if isinstance(step, dict):
+                    # description -> action
+                    if 'description' in step and 'action' not in step:
+                        step['action'] = step['description']
+                    
+                    # Handle parallel steps
+                    if 'parallel' in step:
+                        for parallel_step in step['parallel']:
+                            if isinstance(parallel_step, dict):
+                                if 'description' in parallel_step and 'action' not in parallel_step:
+                                    parallel_step['action'] = parallel_step['description']
+        
+        return normalized
+    
+    def _extract_steps_from_roles(self, roles: Dict[str, Dict]) -> List[Dict]:
+        """
+        Extract steps from tasks nested within roles (agents.yaml format).
+        
+        Args:
+            roles: The roles section from agents.yaml
+            
+        Returns:
+            List of step definitions
+        """
+        steps = []
+        for role_id, role_config in roles.items():
+            if 'tasks' in role_config:
+                for task_id, task_config in role_config['tasks'].items():
+                    step = {
+                        'name': task_id,
+                        'agent': role_id,
+                    }
+                    # description -> action
+                    if 'description' in task_config:
+                        step['action'] = task_config['description']
+                    elif 'action' in task_config:
+                        step['action'] = task_config['action']
+                    
+                    # Copy other task fields
+                    for field in ['expected_output', 'context', 'output_file', 
+                                  'output_json', 'create_directory', 'callback',
+                                  'async_execution', 'guardrail', 'max_retries']:
+                        if field in task_config:
+                            step[field] = task_config[field]
+                    
+                    steps.append(step)
+        return steps
+    
+    def _parse_workflow_data(self, data: Dict[str, Any]) -> Workflow:
+        """
+        Parse workflow data dictionary into a Workflow object.
+        
+        Args:
+            data: Parsed YAML data dictionary
+            
+        Returns:
+            Workflow object
+        """
+        # Extract workflow metadata
+        name = data.get('name', 'Unnamed Workflow')
+        description = data.get('description', '')
+        
+        # Extract framework and process (for feature parity with agents.yaml)
+        framework = data.get('framework', 'praisonai')
+        process = data.get('process', 'sequential')
+        manager_llm = data.get('manager_llm')
+        
+        # Parse workflow configuration
+        workflow_config = data.get('workflow', {})
+        planning = workflow_config.get('planning', False)
+        planning_llm = workflow_config.get('planning_llm')
+        reasoning = workflow_config.get('reasoning', False)
+        verbose = workflow_config.get('verbose', False)
+        memory_config = workflow_config.get('memory_config')
+        
+        # Parse variables
+        variables = data.get('variables', {})
+        
+        # Parse agents - support both 'agents' and 'roles' keys for backward compatibility
+        agents_data = data.get('agents', {})
+        if not agents_data and 'roles' in data:
+            # Convert roles format to agents format
+            agents_data = self._convert_roles_to_agents(data['roles'])
+        self._agents = self._parse_agents(agents_data)
+        
+        # Parse callbacks
+        callbacks_data = data.get('callbacks', {})
+        self._parse_callbacks(callbacks_data)
+        
+        # Parse steps
+        steps_data = data.get('steps', [])
+        steps = self._parse_steps(steps_data)
+        
+        # Create workflow
+        workflow = Workflow(
+            name=name,
+            steps=steps,
+            variables=variables,
+            planning=planning,
+            planning_llm=planning_llm,
+            reasoning=reasoning,
+            verbose=verbose,
+            memory_config=memory_config,
+            on_workflow_start=self._callbacks.get('on_workflow_start'),
+            on_step_complete=self._callbacks.get('on_step_complete'),
+            on_workflow_complete=self._callbacks.get('on_workflow_complete'),
+        )
+        
+        # Store additional attributes for feature parity with agents.yaml
+        workflow.description = description
+        workflow.framework = framework
+        workflow.process = process
+        workflow.manager_llm = manager_llm
+        
+        return workflow
+    
+    def _convert_roles_to_agents(self, roles: Dict[str, Dict]) -> Dict[str, Dict]:
+        """
+        Convert agents.yaml 'roles' format to workflow 'agents' format.
+        
+        This enables backward compatibility with the existing agents.yaml format.
+        
+        Mapping:
+        - backstory -> instructions
+        - role -> role
+        - goal -> goal
+        - tools -> tools
+        - llm -> llm
+        - tasks -> (used to auto-generate steps if no steps defined)
+        
+        Args:
+            roles: The roles section from agents.yaml
+            
+        Returns:
+            Converted agents dictionary in workflow format
+        """
+        agents = {}
+        for role_id, role_config in roles.items():
+            agent = {
+                'name': role_config.get('role', role_id),
+                'role': role_config.get('role', role_id),
+                'goal': role_config.get('goal', ''),
+                'instructions': role_config.get('backstory', ''),
+            }
+            
+            # Copy optional fields
+            if 'llm' in role_config:
+                llm_config = role_config['llm']
+                if isinstance(llm_config, dict):
+                    agent['llm'] = llm_config.get('model', 'gpt-4o-mini')
+                else:
+                    agent['llm'] = llm_config
+            
+            if 'tools' in role_config:
+                agent['tools'] = [t for t in role_config['tools'] if t]
+            
+            if 'verbose' in role_config:
+                agent['verbose'] = role_config['verbose']
+            
+            if 'max_iter' in role_config:
+                agent['max_iter'] = role_config['max_iter']
+            
+            if 'planning' in role_config:
+                agent['planning'] = role_config['planning']
+            
+            if 'reasoning' in role_config:
+                agent['reasoning'] = role_config['reasoning']
+            
+            agents[role_id] = agent
+        
+        return agents
+    
+    def _parse_agents(self, agents_data: Dict[str, Dict]) -> Dict[str, Agent]:
+        """
+        Parse agent definitions from YAML.
+        
+        Args:
+            agents_data: Dictionary of agent definitions
+            
+        Returns:
+            Dictionary mapping agent names to Agent objects
+        """
+        agents = {}
+        
+        for agent_id, agent_config in agents_data.items():
+            agent = self._create_agent(agent_id, agent_config)
+            agents[agent_id] = agent
+        
+        return agents
+    
+    def _create_agent(self, agent_id: str, config: Dict[str, Any]) -> Agent:
+        """
+        Create an Agent from configuration.
+        
+        Args:
+            agent_id: Identifier for the agent
+            config: Agent configuration dictionary
+            
+        Returns:
+            Agent object
+        """
+        # Extract agent parameters
+        name = config.get('name', agent_id)
+        role = config.get('role', 'Assistant')
+        goal = config.get('goal', '')
+        instructions = config.get('instructions', '')
+        backstory = config.get('backstory', '')
+        
+        # LLM configuration
+        llm = config.get('llm')
+        
+        # Tools
+        tools_config = config.get('tools', [])
+        tools = self._resolve_tools(tools_config)
+        
+        # Advanced parameters (feature parity with agents.yaml)
+        planning = config.get('planning', False)
+        reasoning = config.get('reasoning', False)
+        verbose = config.get('verbose', False)
+        allow_delegation = config.get('allow_delegation', False)
+        max_iter = config.get('max_iter')
+        cache = config.get('cache', True)
+        
+        # Additional agents.yaml fields
+        function_calling_llm = config.get('function_calling_llm')
+        max_rpm = config.get('max_rpm')
+        max_execution_time = config.get('max_execution_time')
+        reflect_llm = config.get('reflect_llm')
+        min_reflect = config.get('min_reflect')
+        max_reflect = config.get('max_reflect')
+        system_template = config.get('system_template')
+        prompt_template = config.get('prompt_template')
+        response_template = config.get('response_template')
+        
+        # Create agent
+        agent = Agent(
+            name=name,
+            role=role,
+            goal=goal,
+            instructions=instructions,
+            backstory=backstory,
+            llm=llm,
+            tools=tools if tools else None,
+            verbose=verbose,
+        )
+        
+        # Store additional attributes for later use
+        agent._yaml_planning = planning
+        agent._yaml_reasoning = reasoning
+        agent._yaml_allow_delegation = allow_delegation
+        agent._yaml_max_iter = max_iter
+        agent._yaml_cache = cache
+        
+        # Store additional agents.yaml fields for feature parity
+        agent._yaml_function_calling_llm = function_calling_llm
+        agent._yaml_max_rpm = max_rpm
+        agent._yaml_max_execution_time = max_execution_time
+        agent._yaml_reflect_llm = reflect_llm
+        agent._yaml_min_reflect = min_reflect
+        agent._yaml_max_reflect = max_reflect
+        agent._yaml_system_template = system_template
+        agent._yaml_prompt_template = prompt_template
+        agent._yaml_response_template = response_template
+        
+        return agent
+    
+    def _resolve_tools(self, tools_config: List[str]) -> List[Callable]:
+        """
+        Resolve tool names to callable functions.
+        
+        Args:
+            tools_config: List of tool names
+            
+        Returns:
+            List of callable tool functions
+        """
+        tools = []
+        for tool_name in tools_config:
+            if tool_name in self.tool_registry:
+                tools.append(self.tool_registry[tool_name])
+            # If tool not in registry, skip it (will be resolved later or is a string reference)
+        return tools
+    
+    def _parse_callbacks(self, callbacks_data: Dict[str, str]) -> None:
+        """
+        Parse callback definitions.
+        
+        Args:
+            callbacks_data: Dictionary of callback name to function name
+        """
+        # For now, store callback names - they can be resolved later
+        # In a full implementation, these would be resolved to actual functions
+        for callback_name, func_name in callbacks_data.items():
+            # Store as None for now - actual resolution happens at runtime
+            self._callbacks[callback_name] = None
+    
+    def _parse_steps(self, steps_data: List[Dict]) -> List:
+        """
+        Parse workflow steps from YAML.
+        
+        Args:
+            steps_data: List of step definitions
+            
+        Returns:
+            List of workflow steps (Agent, WorkflowStep, or pattern objects)
+        """
+        steps = []
+        
+        for step_data in steps_data:
+            step = self._parse_single_step(step_data)
+            if step is not None:
+                steps.append(step)
+        
+        return steps
+    
+    def _parse_single_step(self, step_data: Dict) -> Any:
+        """
+        Parse a single step definition.
+        
+        Args:
+            step_data: Step definition dictionary
+            
+        Returns:
+            Step object (Agent, WorkflowStep, or pattern)
+        """
+        # Check for pattern types
+        if 'route' in step_data:
+            return self._parse_route_step(step_data)
+        elif 'parallel' in step_data:
+            return self._parse_parallel_step(step_data)
+        elif 'loop' in step_data:
+            return self._parse_loop_step(step_data)
+        elif 'repeat' in step_data:
+            return self._parse_repeat_step(step_data)
+        elif 'agent' in step_data:
+            return self._parse_agent_step(step_data)
+        else:
+            # Generic step
+            return self._parse_generic_step(step_data)
+    
+    def _parse_agent_step(self, step_data: Dict) -> Agent:
+        """
+        Parse an agent step.
+        
+        Args:
+            step_data: Step definition with 'agent' key
+            
+        Returns:
+            Agent object
+        """
+        agent_id = step_data['agent']
+        
+        if agent_id in self._agents:
+            agent = self._agents[agent_id]
+            
+            # Store step name if provided
+            step_name = step_data.get('name')
+            if step_name:
+                agent._yaml_step_name = step_name
+            
+            # If there's an action, we need to handle it
+            action = step_data.get('action')
+            if action:
+                # Store action as task for the agent
+                agent._yaml_action = action
+            
+            # Handle guardrail
+            guardrail = step_data.get('guardrail')
+            if guardrail:
+                agent._yaml_guardrail = guardrail
+            
+            # Handle max_retries
+            max_retries = step_data.get('max_retries')
+            if max_retries:
+                agent._yaml_max_retries = max_retries
+            
+            # Handle expected_output (feature parity with agents.yaml tasks)
+            expected_output = step_data.get('expected_output')
+            if expected_output:
+                agent._yaml_expected_output = expected_output
+            
+            # Handle context/dependencies (feature parity with agents.yaml tasks)
+            context = step_data.get('context')
+            if context:
+                agent._yaml_context = context
+            
+            # Handle output_file
+            output_file = step_data.get('output_file')
+            if output_file:
+                agent._yaml_output_file = output_file
+            
+            # Handle output_json (structured output)
+            output_json = step_data.get('output_json')
+            if output_json:
+                agent._yaml_output_json = output_json
+            
+            # Handle output_pydantic
+            output_pydantic = step_data.get('output_pydantic')
+            if output_pydantic:
+                agent._yaml_output_pydantic = output_pydantic
+            
+            # Handle create_directory
+            create_directory = step_data.get('create_directory')
+            if create_directory is not None:
+                agent._yaml_create_directory = create_directory
+            
+            # Handle callback
+            callback = step_data.get('callback')
+            if callback:
+                agent._yaml_callback = callback
+            
+            # Handle async_execution
+            async_execution = step_data.get('async_execution')
+            if async_execution is not None:
+                agent._yaml_async_execution = async_execution
+            
+            return agent
+        else:
+            raise ValueError(f"Agent '{agent_id}' not defined in agents section")
+    
+    def _parse_route_step(self, step_data: Dict) -> Dict:
+        """
+        Parse a route pattern step.
+        
+        Args:
+            step_data: Step definition with 'route' key
+            
+        Returns:
+            Route pattern object
+        """
+        route_config = step_data['route']
+        
+        # Build routes dictionary with resolved agents
+        routes = {}
+        for route_key, agent_ids in route_config.items():
+            if isinstance(agent_ids, list):
+                routes[route_key] = [self._agents[aid] for aid in agent_ids if aid in self._agents]
+            else:
+                if agent_ids in self._agents:
+                    routes[route_key] = [self._agents[agent_ids]]
+        
+        return route(routes)
+    
+    def _parse_parallel_step(self, step_data: Dict) -> Dict:
+        """
+        Parse a parallel pattern step.
+        
+        Args:
+            step_data: Step definition with 'parallel' key
+            
+        Returns:
+            Parallel pattern object
+        """
+        parallel_config = step_data['parallel']
+        
+        # Build list of parallel steps
+        parallel_steps = []
+        for item in parallel_config:
+            if 'agent' in item:
+                agent_id = item['agent']
+                if agent_id in self._agents:
+                    agent = self._agents[agent_id]
+                    # Store action if present
+                    if 'action' in item:
+                        agent._yaml_action = item['action']
+                    parallel_steps.append(agent)
+        
+        return parallel(parallel_steps)
+    
+    def _parse_loop_step(self, step_data: Dict) -> Dict:
+        """
+        Parse a loop pattern step.
+        
+        Args:
+            step_data: Step definition with 'loop' key
+            
+        Returns:
+            Loop pattern object
+        """
+        loop_config = step_data['loop']
+        agent_id = step_data.get('agent')
+        
+        if agent_id and agent_id in self._agents:
+            agent = self._agents[agent_id]
+            
+            # Store action if present
+            if 'action' in step_data:
+                agent._yaml_action = step_data['action']
+            
+            # Get loop parameters
+            over = loop_config.get('over')
+            from_csv = loop_config.get('from_csv')
+            
+            return loop(agent, over=over, from_csv=from_csv)
+        
+        raise ValueError("Loop step requires an agent")
+    
+    def _parse_repeat_step(self, step_data: Dict) -> Dict:
+        """
+        Parse a repeat pattern step.
+        
+        Args:
+            step_data: Step definition with 'repeat' key
+            
+        Returns:
+            Repeat pattern object
+        """
+        repeat_config = step_data['repeat']
+        agent_id = step_data.get('agent')
+        
+        if agent_id and agent_id in self._agents:
+            agent = self._agents[agent_id]
+            
+            # Store action if present
+            if 'action' in step_data:
+                agent._yaml_action = step_data['action']
+            
+            # Get repeat parameters
+            until = repeat_config.get('until')
+            max_iterations = repeat_config.get('max_iterations', 5)
+            
+            # Create condition function from 'until' string
+            if isinstance(until, str):
+                condition = self._create_condition_from_string(until)
+            else:
+                condition = until
+            
+            return repeat(agent, until=condition, max_iterations=max_iterations)
+        
+        raise ValueError("Repeat step requires an agent")
+    
+    def _create_condition_from_string(self, condition_str: str) -> Callable:
+        """
+        Create a condition function from a string.
+        
+        Args:
+            condition_str: Condition string (e.g., "approved", "comprehensive")
+            
+        Returns:
+            Callable condition function
+        """
+        def condition(ctx) -> bool:
+            result = str(ctx.previous_result).lower()
+            return condition_str.lower() in result
+        return condition
+    
+    def _parse_generic_step(self, step_data: Dict) -> WorkflowStep:
+        """
+        Parse a generic workflow step.
+        
+        Args:
+            step_data: Step definition dictionary
+            
+        Returns:
+            WorkflowStep object
+        """
+        name = step_data.get('name', 'step')
+        action = step_data.get('action', '')
+        
+        return WorkflowStep(
+            name=name,
+            action=action,
+        )
+    
+    def register_tool(self, name: str, tool: Callable) -> None:
+        """
+        Register a tool for use in workflows.
+        
+        Args:
+            name: Tool name as referenced in YAML
+            tool: Callable tool function
+        """
+        self.tool_registry[name] = tool
+    
+    def register_callback(self, name: str, callback: Callable) -> None:
+        """
+        Register a callback function.
+        
+        Args:
+            name: Callback name as referenced in YAML
+            callback: Callable callback function
+        """
+        self._callbacks[name] = callback

src/praisonai-agents/pyproject.toml

@@ -4,8 +4,9 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "praisonaiagents"
-version = "0.0.197"
+version = "0.1.7"
 description = "Praison AI agents for completing complex tasks with Self Reflection Agents"
+readme = "README.md"
 requires-python = ">=3.10"
 authors = [
     { name="Mervin Praison" }

src/praisonai-agents/tests/test_file_memory.py

@@ -493,17 +493,22 @@ class TestAgentIntegration:
     
     def test_agent_store_memory(self):
         """Test Agent store_memory method."""
+        import uuid
         from praisonaiagents import Agent
         
+        # Use unique user_id to avoid stale data from previous test runs
+        unique_user_id = f"test_user_{uuid.uuid4().hex[:8]}"
+        
         agent = Agent(
             name="Test Agent",
-            memory=True
+            memory=True,
+            user_id=unique_user_id
         )
         
         agent.store_memory("User prefers dark mode", memory_type="short_term")
         
         items = agent._memory_instance.get_short_term()
-        assert len(items) == 1
+        assert len(items) == 1, f"Expected 1 item, got {len(items)} items"
         assert items[0].content == "User prefers dark mode"
     
     def test_agent_get_memory_context(self):
@@ -658,10 +663,12 @@ class TestMultiAgentMemorySharing:
     
     def test_agents_share_memory_with_same_user_id(self):
         """Test that agents with same user_id share memory."""
+        import uuid
         from praisonaiagents import Agent
         
         with tempfile.TemporaryDirectory() as tmpdir:
-            user_id = "shared_user"
+            # Use unique user_id to avoid stale data from previous test runs
+            user_id = f"shared_user_{uuid.uuid4().hex[:8]}"
             base_path = f"{tmpdir}/memory"
             
             # Agent 1 stores memories
@@ -676,9 +683,9 @@ class TestMultiAgentMemorySharing:
             agent1._memory_instance.add_entity("Alice", "person", {"role": "developer"})
             
             # Verify Agent1 stored memories
-            assert len(agent1._memory_instance.get_short_term()) == 1
-            assert len(agent1._memory_instance.get_long_term()) == 1
-            assert len(agent1._memory_instance.get_all_entities()) == 1
+            assert len(agent1._memory_instance.get_short_term()) == 1, f"Expected 1 short_term, got {len(agent1._memory_instance.get_short_term())}"
+            assert len(agent1._memory_instance.get_long_term()) == 1, f"Expected 1 long_term, got {len(agent1._memory_instance.get_long_term())}"
+            assert len(agent1._memory_instance.get_all_entities()) == 1, f"Expected 1 entity, got {len(agent1._memory_instance.get_all_entities())}"
             
             # Agent 2 with same user_id should load memories
             agent2 = Agent(

src/praisonai-agents/tests/test_fix_comprehensive.py

@@ -6,6 +6,8 @@ The agent should:
 3. Return the final result (200)
 """
 
+import pytest
+import os
 from praisonaiagents import Agent
 
 def get_stock_price(company_name: str) -> str:
@@ -35,41 +37,60 @@ def multiply(a: int, b: int) -> int:
     print(f"[Tool Called] multiply({a}, {b})")
     return a * b
 
-# Test with Gemini
-print("=" * 60)
-print("Testing with Gemini model")
-print("=" * 60)
 
-agent_gemini = Agent(
-    instructions="You are a helpful assistant. You can use the tools provided to you to help the user. When asked to multiply a stock price, first get the stock price, then multiply it.",
-    llm="gemini/gemini-2.5-pro",
-    tools=[get_stock_price, multiply],
-    verbose=True
+@pytest.mark.skipif(
+    not os.environ.get("OPENAI_API_KEY"),
+    reason="OPENAI_API_KEY not set - skipping integration test"
 )
+def test_sequential_tool_calling_gpt():
+    """Test sequential tool calling with GPT model"""
+    print("=" * 60)
+    print("Testing with GPT model")
+    print("=" * 60)
 
-result_gemini = agent_gemini.start("what is the stock price of Google? multiply the Google stock price with 2")
-print(f"\nFinal Result (Gemini): {result_gemini}")
+    agent_gpt = Agent(
+        instructions="You are a helpful assistant. When asked to multiply a stock price, first get the stock price, then multiply it.",
+        llm="gpt-4o-mini",
+        tools=[get_stock_price, multiply],
+        verbose=True
+    )
 
-# Test with GPT-4
-print("\n" + "=" * 60)
-print("Testing with GPT-4 model")
-print("=" * 60)
+    result = agent_gpt.start("what is the stock price of Google? multiply the Google stock price with 2")
+    print(f"\nFinal Result (GPT): {result}")
+    
+    # Verify result
+    assert result, "GPT returned empty result"
+    print(f"GPT result contains '200': {'200' in str(result)}")
 
-agent_gpt4 = Agent(
-    instructions="You are a helpful assistant. You can use the tools provided to you to help the user. When asked to multiply a stock price, first get the stock price, then multiply it.",
-    llm="gpt-5-nano",
-    tools=[get_stock_price, multiply],
-    verbose=True
+
+@pytest.mark.skipif(
+    not os.environ.get("GOOGLE_API_KEY"),
+    reason="GOOGLE_API_KEY not set - skipping integration test"
 )
+def test_sequential_tool_calling_gemini():
+    """Test sequential tool calling with Gemini model"""
+    print("=" * 60)
+    print("Testing with Gemini model")
+    print("=" * 60)
 
-result_gpt4 = agent_gpt4.start("what is the stock price of Google? multiply the Google stock price with 2")
-print(f"\nFinal Result (GPT-4): {result_gpt4}")
+    agent_gemini = Agent(
+        instructions="You are a helpful assistant. When asked to multiply a stock price, first get the stock price, then multiply it.",
+        llm="gemini/gemini-2.0-flash",
+        tools=[get_stock_price, multiply],
+        verbose=True
+    )
 
-# Verify results
-print("\n" + "=" * 60)
-print("Test Results Summary")
-print("=" * 60)
-print(f"Gemini result contains '200': {'200' in str(result_gemini) if result_gemini else False}")
-print(f"GPT-4 result contains '200': {'200' in str(result_gpt4) if result_gpt4 else False}")
-print(f"Gemini returned empty: {not result_gemini or result_gemini == ''}")
-print(f"GPT-4 returned empty: {not result_gpt4 or result_gpt4 == ''}")
+    result = agent_gemini.start("what is the stock price of Google? multiply the Google stock price with 2")
+    print(f"\nFinal Result (Gemini): {result}")
+    
+    # Verify result
+    assert result, "Gemini returned empty result"
+    print(f"Gemini result contains '200': {'200' in str(result)}")
+
+
+if __name__ == "__main__":
+    # Run tests manually
+    if os.environ.get("OPENAI_API_KEY"):
+        test_sequential_tool_calling_gpt()
+    if os.environ.get("GOOGLE_API_KEY"):
+        test_sequential_tool_calling_gemini()

src/praisonai-agents/tests/test_llm_self_reflection_direct.py

@@ -2,7 +2,23 @@
 """Test LLM class directly to verify self-reflection fix"""
 
 from praisonaiagents.llm import LLM
-from praisonaiagents.tools import calculator
+
+# Define calculator tool locally to avoid import issues
+def calculator(expression: str) -> str:
+    """
+    Evaluate a mathematical expression.
+    
+    Args:
+        expression: A mathematical expression to evaluate (e.g., "2 + 2", "15 * 23")
+    
+    Returns:
+        The result of the calculation as a string
+    """
+    try:
+        result = eval(expression)
+        return str(result)
+    except Exception as e:
+        return f"Error: {str(e)}"
 
 def test_llm_direct():
     """Test LLM class directly with self-reflection and tools"""

src/praisonai-agents/tests/test_ollama_async_fix.py

@@ -5,7 +5,9 @@ Test script to verify Ollama empty response fix for both sync and async methods.
 
 import asyncio
 import logging
-from praisonaiagents import Agent, Task, PraisonAIAgents, TaskOutput
+import os
+import pytest
+from praisonaiagents import Agent, Task, PraisonAIAgents
 from typing import Dict, Any
 
 # Enable debug logging
@@ -25,8 +27,8 @@ def search_tool(query: str) -> Dict[str, Any]:
     logging.debug(f"[TEST] Search tool returning: {results}")
     return results
 
-# Test with both sync and async workflows
-async def test_model_async(model_name: str):
+# Helper async function to test a model
+async def _test_model_async_helper(model_name: str):
     print(f"\n{'='*60}")
     print(f"Testing ASYNC with model: {model_name}")
     print('='*60)
@@ -78,7 +80,7 @@ async def test_model_async(model_name: str):
         traceback.print_exc()
         return False
 
-def test_model_sync(model_name: str):
+def _test_model_sync_helper(model_name: str):
     print(f"\n{'='*60}")
     print(f"Testing SYNC with model: {model_name}")
     print('='*60)
@@ -130,18 +132,60 @@ def test_model_sync(model_name: str):
         traceback.print_exc()
         return False
 
+@pytest.mark.skipif(
+    not os.environ.get("OPENAI_API_KEY"),
+    reason="OPENAI_API_KEY not set - skipping integration test"
+)
+@pytest.mark.asyncio
+async def test_ollama_async_openai():
+    """Test async with OpenAI model as baseline."""
+    result = await _test_model_async_helper("gpt-4o-mini")
+    assert result, "OpenAI async model test failed"
+
+
+@pytest.mark.skipif(
+    not os.environ.get("OPENAI_API_KEY"),
+    reason="OPENAI_API_KEY not set - skipping integration test"
+)
+def test_ollama_sync_openai():
+    """Test sync with OpenAI model as baseline."""
+    result = _test_model_sync_helper("gpt-4o-mini")
+    assert result, "OpenAI sync model test failed"
+
+
+@pytest.mark.skipif(
+    not os.environ.get("OLLAMA_HOST", "").strip(),
+    reason="OLLAMA_HOST not set - skipping Ollama integration test"
+)
+@pytest.mark.asyncio
+async def test_ollama_async_ollama():
+    """Test async with Ollama model."""
+    result = await _test_model_async_helper("ollama/llama3.2")
+    assert result, "Ollama async model test failed"
+
+
+@pytest.mark.skipif(
+    not os.environ.get("OLLAMA_HOST", "").strip(),
+    reason="OLLAMA_HOST not set - skipping Ollama integration test"
+)
+def test_ollama_sync_ollama():
+    """Test sync with Ollama model."""
+    result = _test_model_sync_helper("ollama/llama3.2")
+    assert result, "Ollama sync model test failed"
+
+
 async def main():
     print("Testing Ollama empty response fix for both sync and async...")
     
     # Test sync methods
     print("\n1. Testing SYNC methods:")
-    openai_sync_success = test_model_sync("openai/gpt-5-nano")
-    ollama_sync_success = test_model_sync("ollama/llama3.2")
+    openai_sync_success = _test_model_sync_helper("gpt-4o-mini")
+    ollama_sync_success = _test_model_sync_helper("ollama/llama3.2")
     
     # Test async methods
     print("\n2. Testing ASYNC methods:")
-    openai_async_success = await test_model_async("openai/gpt-5-nano")
-    ollama_async_success = await test_model_async("ollama/llama3.2")
+    openai_async_success = await _test_model_async_helper("gpt-4o-mini")
+    ollama_async_success = await _test_model_async_helper("ollama/llama3.2")
     
     # Summary
     print(f"\n{'='*60}")

src/praisonai-agents/tests/test_ollama_fix.py

@@ -4,7 +4,9 @@ Test script to verify Ollama empty response fix.
 """
 
 import logging
-from praisonaiagents import Agent, Task, PraisonAIAgents, TaskOutput
+import os
+import pytest
+from praisonaiagents import Agent, Task, PraisonAIAgents
 from typing import Dict, Any
 
 # Enable debug logging
@@ -24,8 +26,8 @@ def search_tool(query: str) -> Dict[str, Any]:
     logging.debug(f"[TEST] Search tool returning: {results}")
     return results
 
-# Test with both OpenAI and Ollama models
-def test_model(model_name: str):
+# Helper function to test a model
+def _test_model_helper(model_name: str):
     print(f"\n{'='*60}")
     print(f"Testing with model: {model_name}")
     print('='*60)
@@ -77,16 +79,36 @@ def test_model(model_name: str):
         traceback.print_exc()
         return False
 
+@pytest.mark.skipif(
+    not os.environ.get("OPENAI_API_KEY"),
+    reason="OPENAI_API_KEY not set - skipping integration test"
+)
+def test_ollama_fix_openai():
+    """Test with OpenAI model as baseline."""
+    result = _test_model_helper("gpt-4o-mini")
+    assert result, "OpenAI model test failed"
+
+
+@pytest.mark.skipif(
+    not os.environ.get("OLLAMA_HOST", "").strip(),
+    reason="OLLAMA_HOST not set - skipping Ollama integration test"
+)
+def test_ollama_fix_ollama():
+    """Test with Ollama model."""
+    result = _test_model_helper("ollama/llama3.2")
+    assert result, "Ollama model test failed"
+
+
 if __name__ == "__main__":
     print("Testing Ollama empty response fix...")
     
     # Test with OpenAI first (as baseline)
     print("\n1. Testing with OpenAI (baseline):")
-    openai_success = test_model("openai/gpt-5-nano")
+    openai_success = _test_model_helper("gpt-4o-mini")
     
     # Test with Ollama
     print("\n2. Testing with Ollama:")
-    ollama_success = test_model("ollama/llama3.2")
+    ollama_success = _test_model_helper("ollama/llama3.2")
     
     # Summary
     print(f"\n{'='*60}")

src/praisonai-agents/tests/test_ollama_sequential_fix.py

@@ -53,11 +53,14 @@ def test_ollama_argument_validation():
     print("\n2. Testing mixed arguments (the main issue):")
     mixed_args = {"a": "get_stock_price", "company_name": "Google", "b": "2"}
     filtered_args = llm._validate_and_filter_ollama_arguments("multiply", mixed_args, tools)
-    expected_filtered = {"a": "get_stock_price", "b": "2"}  # Should remove 'company_name'
+    # Note: The method may coerce "2" to int 2 based on type hints - both are acceptable
+    expected_filtered_str = {"a": "get_stock_price", "b": "2"}  # String version
+    expected_filtered_int = {"a": "get_stock_price", "b": 2}    # Int version (coerced)
     print(f"Original: {mixed_args}")
     print(f"Filtered: {filtered_args}")
-    print(f"Expected: {expected_filtered}")
-    assert filtered_args == expected_filtered, f"Expected {expected_filtered}, got {filtered_args}"
+    print(f"Expected: {expected_filtered_str} or {expected_filtered_int}")
+    assert filtered_args == expected_filtered_str or filtered_args == expected_filtered_int, \
+        f"Expected {expected_filtered_str} or {expected_filtered_int}, got {filtered_args}"
     print("✅ Mixed arguments filtering test passed")
     
     # Test case 3: All invalid arguments

src/praisonai-agents/tests/test_planning.py

@@ -704,7 +704,8 @@ class TestPlanningAgent:
         planner = PlanningAgent()
         
         mock_llm = MagicMock()
-        mock_llm.achat = AsyncMock(return_value=json.dumps({
+        # Mock get_response_async which is the method actually called
+        mock_llm.get_response_async = AsyncMock(return_value=json.dumps({
             "name": "Test Plan",
             "description": "A test plan",
             "steps": [
@@ -733,7 +734,8 @@ class TestPlanningAgent:
         planner = PlanningAgent()
         
         mock_llm = MagicMock()
-        mock_llm.achat = AsyncMock(return_value=json.dumps({
+        # Mock get_response_async which is the method actually called
+        mock_llm.get_response_async = AsyncMock(return_value=json.dumps({
             "name": "Refined Plan",
             "description": "Updated plan",
             "steps": [
@@ -765,7 +767,8 @@ class TestPlanningAgent:
         planner = PlanningAgent()
         
         mock_llm = MagicMock()
-        mock_llm.achat = AsyncMock(return_value="Analysis: Python project with FastAPI")
+        # Mock get_response_async which is the method actually called
+        mock_llm.get_response_async = AsyncMock(return_value="Analysis: Python project with FastAPI")
         
         planner._llm = mock_llm
         

src/praisonai-agents/tests/test_self_reflection_comprehensive.py

@@ -2,7 +2,29 @@
 """Comprehensive test script to verify self-reflection works with tools after the fix"""
 
 from praisonaiagents import Agent, Task, PraisonAIAgents
-from praisonaiagents.tools import duckduckgo_search
+
+# Define duckduckgo_search tool locally to avoid import issues
+def duckduckgo_search(query: str) -> str:
+    """
+    Search the web using DuckDuckGo.
+    
+    Args:
+        query: The search query string
+    
+    Returns:
+        Search results as a string
+    """
+    try:
+        from duckduckgo_search import DDGS
+        with DDGS() as ddgs:
+            results = list(ddgs.text(query, max_results=3))
+            if results:
+                return "\n".join([f"- {r.get('title', '')}: {r.get('body', '')}" for r in results])
+            return "No results found"
+    except ImportError:
+        return f"Mock search results for: {query}"
+    except Exception as e:
+        return f"Search error: {str(e)}"
 
 def test_self_reflection_with_tools():
     """Test self-reflection with tools - should work after the fix"""

src/praisonai-agents/tests/test_self_reflection_fix_simple.py

@@ -2,7 +2,23 @@
 """Simple test to verify the self-reflection fix works"""
 
 from praisonaiagents import Agent
-from praisonaiagents.tools import calculator
+
+# Define calculator tool locally to avoid import issues
+def calculator(expression: str) -> str:
+    """
+    Evaluate a mathematical expression.
+    
+    Args:
+        expression: A mathematical expression to evaluate (e.g., "2 + 2", "25 * 17")
+    
+    Returns:
+        The result of the calculation as a string
+    """
+    try:
+        result = eval(expression)
+        return str(result)
+    except Exception as e:
+        return f"Error: {str(e)}"
 
 def test_self_reflection_fix():
     """Test that self-reflection works with tools after the fix"""

src/praisonai-agents/tests/test_self_reflection_fix_verification.py

@@ -2,7 +2,23 @@
 """Test to verify the self-reflection fix works with tools"""
 
 from praisonaiagents import Agent, Task, PraisonAIAgents
-from praisonaiagents.tools import calculator
+
+# Define calculator tool locally to avoid import issues
+def calculator(expression: str) -> str:
+    """
+    Evaluate a mathematical expression.
+    
+    Args:
+        expression: A mathematical expression to evaluate (e.g., "123 * 456")
+    
+    Returns:
+        The result of the calculation as a string
+    """
+    try:
+        result = eval(expression)
+        return str(result)
+    except Exception as e:
+        return f"Error: {str(e)}"
 
 def test_self_reflection_fix_verification():
     """Test that self-reflection now works with tools"""

src/praisonai-agents/tests/test_workflow_agents.py

@@ -319,7 +319,14 @@ class TestExecuteWithAgents:
         result = manager.execute("test_workflow")
         
         assert not result["success"]
-        assert "No executor available" in result.get("error", "")
+        # Error can be at top level or in results array
+        error_found = "No executor available" in result.get("error", "")
+        if not error_found and "results" in result:
+            error_found = any(
+                "No executor available" in r.get("error", "") 
+                for r in result.get("results", [])
+            )
+        assert error_found, f"Expected 'No executor available' error, got: {result}"
 
 
 class TestWorkflowLevelDefaults:

src/praisonai-agents/uv.lock

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

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.28.tar.gz"
+    sha256 `curl -sL https://github.com/MervinPraison/PraisonAI/archive/refs/tags/v2.3.28.tar.gz | shasum -a 256`.split.first
     license "MIT"
   
     depends_on "[email protected]"

src/praisonai/praisonai/agents_generator.py

@@ -318,7 +318,16 @@ class AgentsGenerator:
                 print(f"File not found: {self.agent_file}")
                 return
 
-        topic = config['topic']
+        # Check if this is a workflow-mode YAML (process: workflow or has steps section)
+        process_type = config.get('process', 'sequential')
+        has_steps = 'steps' in config
+        has_workflow_config = 'workflow' in config
+        
+        if process_type == 'workflow' or (has_steps and has_workflow_config):
+            # Route to YAMLWorkflowParser for advanced workflow patterns
+            return self._run_yaml_workflow(config)
+
+        topic = config.get('topic', '')
         tools_dict = {}
         
         # Only try to use praisonai_tools if it's available and needed
@@ -406,6 +415,53 @@ class AgentsGenerator:
                 agentops.init(os.environ.get("AGENTOPS_API_KEY"), default_tags=["crewai"])
             return self._run_crewai(config, topic, tools_dict)
 
+    def _run_yaml_workflow(self, config):
+        """
+        Run a YAML workflow using the YAMLWorkflowParser.
+        
+        This method handles agents.yaml files that have:
+        - process: workflow
+        - steps section with workflow patterns (route, parallel, loop, repeat)
+        
+        Args:
+            config (dict): The parsed YAML configuration
+            
+        Returns:
+            str: Result of the workflow execution
+        """
+        if not PRAISONAI_AVAILABLE:
+            raise ImportError("PraisonAI is not installed. Please install it with 'pip install praisonaiagents'")
+        
+        try:
+            from praisonaiagents.workflows import YAMLWorkflowParser
+        except ImportError:
+            raise ImportError("YAMLWorkflowParser not available. Please update praisonaiagents.")
+        
+        # Ensure name is present (YAMLWorkflowParser handles roles->agents conversion)
+        if 'name' not in config:
+            config['name'] = config.get('topic', 'Workflow')
+        
+        # Convert config back to YAML string for parser
+        # Note: YAMLWorkflowParser handles 'roles' to 'agents' conversion internally
+        import yaml as yaml_module
+        yaml_content = yaml_module.dump(config, default_flow_style=False)
+        
+        # Parse and execute
+        parser = YAMLWorkflowParser()
+        workflow = parser.parse_string(yaml_content)
+        
+        # Get input from topic or variables
+        input_data = config.get('topic', '')
+        
+        # Execute workflow
+        self.logger.info(f"Running workflow: {workflow.name}")
+        result = workflow.start(input_data)
+        
+        if result.get("status") == "completed":
+            return result.get("output", "Workflow completed successfully")
+        else:
+            return f"Workflow failed: {result.get('error', 'Unknown error')}"
+
     def _run_autogen(self, config, topic, tools_dict):
         """
         Run agents using the AutoGen framework.

src/praisonai/praisonai/auto.py

@@ -335,4 +335,225 @@ The final role you create should satisfy the provided task: """ + self.topic + "
 
     
 # generator = AutoGenerator(framework="crewai", topic="Create a movie script about Cat in Mars")
-# print(generator.generate())
+# print(generator.generate())
+
+
+# =============================================================================
+# Workflow Auto-Generation (Feature Parity)
+# =============================================================================
+
+class WorkflowStepDetails(BaseModel):
+    """Details for a workflow step."""
+    agent: str
+    action: str
+    expected_output: Optional[str] = None
+
+class WorkflowRouteDetails(BaseModel):
+    """Details for a route step."""
+    name: str
+    route: Dict[str, List[str]]
+
+class WorkflowParallelDetails(BaseModel):
+    """Details for a parallel step."""
+    name: str
+    parallel: List[WorkflowStepDetails]
+
+class WorkflowAgentDetails(BaseModel):
+    """Details for a workflow agent."""
+    name: str
+    role: str
+    goal: str
+    instructions: str
+    tools: Optional[List[str]] = None
+
+class WorkflowStructure(BaseModel):
+    """Structure for auto-generated workflow."""
+    name: str
+    description: str
+    agents: Dict[str, WorkflowAgentDetails]
+    steps: List[Dict]  # Can be agent steps, route, parallel, etc.
+
+
+class WorkflowAutoGenerator:
+    """
+    Auto-generates workflow.yaml files from a topic description.
+    
+    Uses lazy loading to avoid performance impact when not used.
+    
+    Usage:
+        generator = WorkflowAutoGenerator(topic="Research AI trends and write a report")
+        path = generator.generate()
+    """
+    
+    def __init__(self, topic: str = "Research and write about AI", 
+                 workflow_file: str = "workflow.yaml",
+                 config_list: Optional[List[Dict]] = None):
+        """
+        Initialize the WorkflowAutoGenerator.
+        
+        Args:
+            topic: The task/topic for the workflow
+            workflow_file: Output file name
+            config_list: Optional LLM configuration
+        """
+        # Support multiple environment variable patterns
+        model_name = os.environ.get("MODEL_NAME") or os.environ.get("OPENAI_MODEL_NAME", "gpt-4o-mini")
+        base_url = (
+            os.environ.get("OPENAI_BASE_URL") or 
+            os.environ.get("OPENAI_API_BASE") or
+            os.environ.get("OLLAMA_API_BASE", "https://api.openai.com/v1")
+        )
+        
+        self.config_list = config_list or [
+            {
+                'model': model_name,
+                'base_url': base_url,
+                'api_key': os.environ.get("OPENAI_API_KEY")
+            }
+        ]
+        self.topic = topic
+        self.workflow_file = workflow_file
+        self._client = None  # Lazy loading
+    
+    @property
+    def client(self):
+        """Lazy load the OpenAI client to avoid performance impact."""
+        if self._client is None:
+            self._client = instructor.patch(
+                OpenAI(
+                    base_url=self.config_list[0]['base_url'],
+                    api_key=self.config_list[0]['api_key'],
+                ),
+                mode=instructor.Mode.JSON,
+            )
+        return self._client
+    
+    def generate(self, pattern: str = "sequential") -> str:
+        """
+        Generate a workflow YAML file.
+        
+        Args:
+            pattern: Workflow pattern - "sequential", "routing", "parallel", "loop"
+            
+        Returns:
+            Path to the generated workflow file
+        """
+        response = self.client.chat.completions.create(
+            model=self.config_list[0]['model'],
+            response_model=WorkflowStructure,
+            max_retries=5,
+            messages=[
+                {"role": "system", "content": "You are a helpful assistant that designs workflow structures."},
+                {"role": "user", "content": self._get_prompt(pattern)}
+            ]
+        )
+        
+        json_data = json.loads(response.model_dump_json())
+        return self._save_workflow(json_data, pattern)
+    
+    def _get_prompt(self, pattern: str) -> str:
+        """Generate the prompt based on the workflow pattern."""
+        base_prompt = f"""Generate a workflow structure for: "{self.topic}"
+
+The workflow should use the "{pattern}" pattern.
+Create 2-4 agents with clear roles and instructions.
+Each step should have a clear action.
+
+"""
+        
+        if pattern == "routing":
+            base_prompt += """
+Include a classifier agent that routes to different specialized agents.
+The route step should have at least 2 routes plus a default.
+
+Example structure:
+{
+  "name": "Routing Workflow",
+  "description": "Routes requests to specialized agents",
+  "agents": {
+    "classifier": {"name": "Classifier", "role": "Request Classifier", "goal": "Classify requests", "instructions": "Respond with ONLY: technical, creative, or general"},
+    "tech_agent": {"name": "TechExpert", "role": "Technical Expert", "goal": "Handle technical questions", "instructions": "Provide technical answers"}
+  },
+  "steps": [
+    {"agent": "classifier", "action": "Classify: {{input}}"},
+    {"name": "routing", "route": {"technical": ["tech_agent"], "default": ["tech_agent"]}}
+  ]
+}
+"""
+        elif pattern == "parallel":
+            base_prompt += """
+Include multiple agents that work in parallel, then an aggregator.
+
+Example structure:
+{
+  "name": "Parallel Workflow",
+  "description": "Multiple agents work concurrently",
+  "agents": {
+    "researcher1": {"name": "Researcher1", "role": "Market Analyst", "goal": "Research market", "instructions": "Provide market insights"},
+    "researcher2": {"name": "Researcher2", "role": "Competitor Analyst", "goal": "Research competitors", "instructions": "Provide competitor insights"},
+    "aggregator": {"name": "Aggregator", "role": "Synthesizer", "goal": "Combine findings", "instructions": "Synthesize all research"}
+  },
+  "steps": [
+    {"name": "parallel_research", "parallel": [
+      {"agent": "researcher1", "action": "Research market for {{input}}"},
+      {"agent": "researcher2", "action": "Research competitors for {{input}}"}
+    ]},
+    {"agent": "aggregator", "action": "Combine all findings"}
+  ]
+}
+"""
+        else:  # sequential
+            base_prompt += """
+Create a sequential workflow where agents work one after another.
+
+Example structure:
+{
+  "name": "Sequential Workflow",
+  "description": "Agents work in sequence",
+  "agents": {
+    "researcher": {"name": "Researcher", "role": "Research Analyst", "goal": "Research topics", "instructions": "Provide research findings"},
+    "writer": {"name": "Writer", "role": "Content Writer", "goal": "Write content", "instructions": "Write clear content"}
+  },
+  "steps": [
+    {"agent": "researcher", "action": "Research: {{input}}"},
+    {"agent": "writer", "action": "Write based on: {{previous_output}}"}
+  ]
+}
+"""
+        
+        base_prompt += f"\nGenerate a workflow for: {self.topic}"
+        return base_prompt
+    
+    def _save_workflow(self, data: Dict, pattern: str) -> str:
+        """Save the workflow to a YAML file."""
+        # Build the workflow YAML structure
+        workflow_yaml = {
+            'name': data.get('name', 'Auto-Generated Workflow'),
+            'description': data.get('description', ''),
+            'framework': 'praisonai',
+            'workflow': {
+                'verbose': True,
+                'planning': False,
+                'reasoning': False
+            },
+            'agents': {},
+            'steps': data.get('steps', [])
+        }
+        
+        # Convert agents
+        for agent_id, agent_data in data.get('agents', {}).items():
+            workflow_yaml['agents'][agent_id] = {
+                'name': agent_data.get('name', agent_id),
+                'role': agent_data.get('role', 'Assistant'),
+                'goal': agent_data.get('goal', ''),
+                'instructions': agent_data.get('instructions', '')
+            }
+            if agent_data.get('tools'):
+                workflow_yaml['agents'][agent_id]['tools'] = agent_data['tools']
+        
+        # Write to file
+        full_path = os.path.abspath(self.workflow_file)
+        with open(full_path, 'w') as f:
+            yaml.dump(workflow_yaml, f, default_flow_style=False, sort_keys=False)
+        
+        return full_path

src/praisonai/praisonai/cli/features/__init__.py

@@ -19,6 +19,7 @@ Features:
 - todo: Todo list management
 - router: Smart model selection
 - flow_display: Visual workflow tracking
+- workflow: YAML workflow management
 """
 
 # Type hints available for IDE support
@@ -39,6 +40,7 @@ __all__ = [
     'TodoHandler',
     'RouterHandler',
     'FlowDisplayHandler',
+    'WorkflowHandler',
 ]
 
 def __getattr__(name):
@@ -85,4 +87,7 @@ def __getattr__(name):
     elif name == 'FlowDisplayHandler':
         from .flow_display import FlowDisplayHandler
         return FlowDisplayHandler
+    elif name == 'WorkflowHandler':
+        from .workflow import WorkflowHandler
+        return WorkflowHandler
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/praisonai/praisonai/cli/features/workflow.py

@@ -0,0 +1,653 @@
+"""
+Workflow Handler for CLI.
+
+Provides YAML workflow management commands.
+Usage: praisonai workflow run research.yaml
+       praisonai workflow validate research.yaml
+       praisonai workflow list
+       praisonai workflow create --template routing
+"""
+
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from .base import CommandHandler
+
+
+class WorkflowHandler(CommandHandler):
+    """
+    Handler for workflow command.
+    
+    Manages YAML workflow files - run, validate, list, and create from templates.
+    
+    Example:
+        praisonai workflow run research.yaml --var topic="AI"
+        praisonai workflow validate research.yaml
+        praisonai workflow list
+        praisonai workflow create --template routing --output my_workflow.yaml
+    """
+    
+    # Workflow templates
+    TEMPLATES = {
+        "simple": """# Simple Sequential Workflow
+name: Simple Workflow
+description: A simple sequential workflow
+
+workflow:
+  verbose: true
+
+agents:
+  researcher:
+    name: Researcher
+    role: Research Analyst
+    goal: Research topics
+    instructions: "Provide concise, factual information."
+
+  writer:
+    name: Writer
+    role: Content Writer
+    goal: Write content
+    instructions: "Write clear, engaging content."
+
+steps:
+  - agent: researcher
+    action: "Research: {{input}}"
+    
+  - agent: writer
+    action: "Write summary based on: {{previous_output}}"
+""",
+        "routing": """# Routing Workflow
+name: Routing Workflow
+description: Classifier routes to specialized agents
+
+workflow:
+  verbose: true
+
+agents:
+  classifier:
+    name: Classifier
+    role: Request Classifier
+    goal: Classify requests
+    instructions: "Respond with ONLY 'technical', 'creative', or 'general'."
+
+  tech_agent:
+    name: TechExpert
+    role: Technical Expert
+    goal: Handle technical questions
+    instructions: "Provide technical answers."
+
+  creative_agent:
+    name: Creative
+    role: Creative Writer
+    goal: Handle creative requests
+    instructions: "Write creative content."
+
+  general_agent:
+    name: General
+    role: General Assistant
+    goal: Handle general requests
+    instructions: "Provide helpful responses."
+
+steps:
+  - agent: classifier
+    action: "Classify: {{input}}"
+    
+  - name: routing
+    route:
+      technical: [tech_agent]
+      creative: [creative_agent]
+      default: [general_agent]
+""",
+        "parallel": """# Parallel Workflow
+name: Parallel Research Workflow
+description: Multiple agents work concurrently
+
+workflow:
+  verbose: true
+
+agents:
+  researcher1:
+    name: MarketResearcher
+    role: Market Analyst
+    goal: Research market trends
+    instructions: "Provide market insights."
+
+  researcher2:
+    name: CompetitorResearcher
+    role: Competitor Analyst
+    goal: Research competitors
+    instructions: "Provide competitor insights."
+
+  aggregator:
+    name: Aggregator
+    role: Synthesizer
+    goal: Combine findings
+    instructions: "Synthesize all research."
+
+steps:
+  - name: parallel_research
+    parallel:
+      - agent: researcher1
+        action: "Research market for: {{input}}"
+      - agent: researcher2
+        action: "Research competitors for: {{input}}"
+        
+  - agent: aggregator
+    action: "Combine all findings"
+""",
+        "loop": """# Loop Workflow
+name: Loop Processing Workflow
+description: Process multiple items in a loop
+
+workflow:
+  verbose: true
+
+variables:
+  items:
+    - Item 1
+    - Item 2
+    - Item 3
+
+agents:
+  processor:
+    name: Processor
+    role: Item Processor
+    goal: Process each item
+    instructions: "Process the given item thoroughly."
+
+  summarizer:
+    name: Summarizer
+    role: Summarizer
+    goal: Summarize results
+    instructions: "Summarize all processed items."
+
+steps:
+  - agent: processor
+    action: "Process: {{item}}"
+    loop:
+      over: items
+      
+  - agent: summarizer
+    action: "Summarize all processed items"
+""",
+        "evaluator-optimizer": """# Evaluator-Optimizer Workflow
+name: Evaluator Optimizer Workflow
+description: Generate and improve until approved
+
+workflow:
+  verbose: true
+
+agents:
+  generator:
+    name: Generator
+    role: Content Generator
+    goal: Generate content
+    instructions: "Generate content. Improve based on feedback if provided."
+
+  evaluator:
+    name: Evaluator
+    role: Evaluator
+    goal: Evaluate content
+    instructions: "If good, respond 'APPROVED'. Otherwise provide feedback."
+
+steps:
+  - agent: generator
+    action: "Generate content for: {{input}}"
+    
+  - agent: evaluator
+    action: "Evaluate: {{previous_output}}"
+    repeat:
+      until: "approved"
+      max_iterations: 3
+"""
+    }
+    
+    def __init__(self, verbose: bool = False):
+        super().__init__(verbose)
+        self._manager = None
+        self._parser = None
+    
+    @property
+    def feature_name(self) -> str:
+        return "workflow"
+    
+    def get_actions(self) -> List[str]:
+        return ["run", "validate", "list", "create", "auto", "help"]
+    
+    def get_help_text(self) -> str:
+        return """
+Workflow Commands:
+  praisonai workflow run <file.yaml>           - Run a YAML workflow
+  praisonai workflow run <file.yaml> --var key=value  - Run with variables
+  praisonai workflow validate <file.yaml>      - Validate a YAML workflow
+  praisonai workflow list                      - List workflows in .praison/workflows/
+  praisonai workflow create --template <name>  - Create from template
+  praisonai workflow auto "topic" --pattern <pattern>  - Auto-generate workflow
+  
+Templates: simple, routing, parallel, loop, evaluator-optimizer
+Patterns: sequential, routing, parallel
+
+Example:
+  praisonai workflow run research.yaml --var topic="AI trends"
+  praisonai workflow create --template routing --output my_workflow.yaml
+  praisonai workflow auto "Research AI trends" --pattern parallel
+"""
+    
+    def _get_manager(self):
+        """Get WorkflowManager lazily."""
+        if self._manager is None:
+            try:
+                from praisonaiagents.workflows import WorkflowManager
+                self._manager = WorkflowManager()
+            except ImportError:
+                self.print_status(
+                    "Workflows require praisonaiagents. Install with: pip install praisonaiagents",
+                    "error"
+                )
+                return None
+        return self._manager
+    
+    def _get_parser(self):
+        """Get YAMLWorkflowParser lazily."""
+        if self._parser is None:
+            try:
+                from praisonaiagents.workflows import YAMLWorkflowParser
+                self._parser = YAMLWorkflowParser()
+            except ImportError:
+                self.print_status(
+                    "Workflows require praisonaiagents. Install with: pip install praisonaiagents",
+                    "error"
+                )
+                return None
+        return self._parser
+    
+    def _parse_variables(self, args: List[str]) -> Dict[str, Any]:
+        """Parse --var key=value arguments."""
+        variables = {}
+        i = 0
+        while i < len(args):
+            if args[i] == "--var" and i + 1 < len(args):
+                var_str = args[i + 1]
+                if "=" in var_str:
+                    key, value = var_str.split("=", 1)
+                    variables[key.strip()] = value.strip()
+                i += 2
+            else:
+                i += 1
+        return variables
+    
+    def _get_file_from_args(self, args: List[str]) -> Optional[str]:
+        """Get the file path from arguments."""
+        for arg in args:
+            if arg.endswith(('.yaml', '.yml')) and not arg.startswith('--'):
+                return arg
+        return None
+    
+    def action_run(self, args: List[str], **kwargs) -> Any:
+        """
+        Run a YAML workflow file.
+        
+        Args:
+            args: [file.yaml, --var, key=value, ...]
+            
+        Returns:
+            Workflow execution result
+        """
+        file_path = self._get_file_from_args(args)
+        if not file_path:
+            self.print_status("Usage: praisonai workflow run <file.yaml>", "error")
+            return None
+        
+        if not os.path.exists(file_path):
+            self.print_status(f"File not found: {file_path}", "error")
+            return None
+        
+        manager = self._get_manager()
+        if not manager:
+            return None
+        
+        # Parse variables
+        variables = self._parse_variables(args)
+        
+        # Get input if provided
+        input_data = kwargs.get('input', '')
+        
+        # Check for --verbose flag
+        verbose = '--verbose' in args or '-v' in args
+        
+        self.print_status(f"Running workflow: {file_path}", "info")
+        if variables:
+            self.print_status(f"Variables: {variables}", "info")
+        
+        try:
+            result = manager.execute_yaml(
+                file_path,
+                input_data=input_data,
+                variables=variables,
+                verbose=verbose
+            )
+            
+            self.print_status("Workflow completed!", "success")
+            
+            # Print output
+            if result.get('output'):
+                from rich import print as rprint
+                rprint("\n[bold]Output:[/bold]")
+                rprint(result['output'])
+            
+            return result
+            
+        except Exception as e:
+            self.print_status(f"Workflow failed: {e}", "error")
+            return None
+    
+    def action_validate(self, args: List[str], **kwargs) -> bool:
+        """
+        Validate a YAML workflow file.
+        
+        Args:
+            args: [file.yaml]
+            
+        Returns:
+            True if valid, False otherwise
+        """
+        file_path = self._get_file_from_args(args)
+        if not file_path:
+            self.print_status("Usage: praisonai workflow validate <file.yaml>", "error")
+            return False
+        
+        if not os.path.exists(file_path):
+            self.print_status(f"File not found: {file_path}", "error")
+            return False
+        
+        parser = self._get_parser()
+        if not parser:
+            return False
+        
+        self.print_status(f"Validating: {file_path}", "info")
+        
+        try:
+            # Load raw YAML to check for non-canonical names
+            import yaml
+            with open(file_path, 'r') as f:
+                raw_data = yaml.safe_load(f)
+            
+            # Check for non-canonical names and suggest canonical ones
+            suggestions = self._get_canonical_suggestions(raw_data)
+            
+            workflow = parser.parse_file(file_path)
+            
+            # Print validation results
+            from rich import print as rprint
+            from rich.table import Table
+            
+            table = Table(title="Workflow Validation")
+            table.add_column("Property", style="cyan")
+            table.add_column("Value", style="green")
+            
+            table.add_row("Name", workflow.name)
+            table.add_row("Description", getattr(workflow, 'description', 'N/A'))
+            table.add_row("Steps", str(len(workflow.steps)))
+            table.add_row("Variables", str(len(workflow.variables)))
+            table.add_row("Planning", str(workflow.planning))
+            table.add_row("Reasoning", str(workflow.reasoning))
+            
+            rprint(table)
+            self.print_status("✓ Workflow is valid!", "success")
+            
+            # Show suggestions for canonical names
+            if suggestions:
+                rprint()
+                rprint("[yellow]💡 Suggestions for canonical field names:[/yellow]")
+                for suggestion in suggestions:
+                    rprint(f"   [dim]•[/dim] {suggestion}")
+                rprint()
+                rprint("[dim]Note: Both old and new names work, but canonical names are recommended.[/dim]")
+            
+            return True
+            
+        except Exception as e:
+            self.print_status(f"✗ Validation failed: {e}", "error")
+            return False
+    
+    def _get_canonical_suggestions(self, data: Dict) -> List[str]:
+        """
+        Check for non-canonical field names and return suggestions.
+        
+        Canonical names (A-I-G-S mnemonic):
+        - Agents (not roles)
+        - Instructions (not backstory)
+        - Goal (same)
+        - Steps (not tasks)
+        
+        Also:
+        - name (not topic)
+        - action (not description)
+        
+        Args:
+            data: Raw YAML data
+            
+        Returns:
+            List of suggestion strings
+        """
+        suggestions = []
+        
+        if not data:
+            return suggestions
+        
+        # Check top-level keys
+        if 'roles' in data:
+            suggestions.append("Use 'agents' instead of 'roles'")
+        
+        if 'topic' in data and 'name' not in data:
+            suggestions.append("Use 'name' instead of 'topic'")
+        
+        # Check agent fields
+        agents_data = data.get('agents', data.get('roles', {}))
+        for agent_id, agent_config in agents_data.items():
+            if isinstance(agent_config, dict):
+                if 'backstory' in agent_config:
+                    suggestions.append(f"Agent '{agent_id}': Use 'instructions' instead of 'backstory'")
+                
+                # Check nested tasks
+                if 'tasks' in agent_config:
+                    suggestions.append(f"Agent '{agent_id}': Use 'steps' at top level instead of nested 'tasks'")
+        
+        # Check step fields
+        steps_data = data.get('steps', [])
+        for i, step in enumerate(steps_data):
+            if isinstance(step, dict):
+                if 'description' in step and 'action' not in step:
+                    step_name = step.get('name', f'step {i+1}')
+                    suggestions.append(f"Step '{step_name}': Use 'action' instead of 'description'")
+                
+                # Check parallel steps
+                if 'parallel' in step:
+                    for j, parallel_step in enumerate(step['parallel']):
+                        if isinstance(parallel_step, dict):
+                            if 'description' in parallel_step and 'action' not in parallel_step:
+                                suggestions.append(f"Parallel step {j+1}: Use 'action' instead of 'description'")
+        
+        return suggestions
+    
+    def action_list(self, args: List[str], **kwargs) -> List[str]:
+        """
+        List available workflows in .praison/workflows/ directory.
+        
+        Returns:
+            List of workflow file names
+        """
+        workflows_dir = Path(".praison/workflows")
+        
+        if not workflows_dir.exists():
+            self.print_status("No .praison/workflows/ directory found", "warning")
+            self.print_status("Create one with: mkdir -p .praison/workflows", "info")
+            return []
+        
+        # Find all YAML files
+        yaml_files = list(workflows_dir.glob("*.yaml")) + list(workflows_dir.glob("*.yml"))
+        
+        if not yaml_files:
+            self.print_status("No workflow files found in .praison/workflows/", "warning")
+            return []
+        
+        from rich import print as rprint
+        from rich.table import Table
+        
+        table = Table(title="Available Workflows")
+        table.add_column("File", style="cyan")
+        table.add_column("Name", style="green")
+        table.add_column("Steps", style="yellow")
+        
+        parser = self._get_parser()
+        workflow_names = []
+        
+        for yaml_file in yaml_files:
+            try:
+                if parser:
+                    workflow = parser.parse_file(yaml_file)
+                    table.add_row(
+                        yaml_file.name,
+                        workflow.name,
+                        str(len(workflow.steps))
+                    )
+                else:
+                    table.add_row(yaml_file.name, "N/A", "N/A")
+                workflow_names.append(yaml_file.name)
+            except Exception as e:
+                table.add_row(yaml_file.name, f"Error: {e}", "N/A")
+        
+        rprint(table)
+        return workflow_names
+    
+    def action_create(self, args: List[str], **kwargs) -> Optional[str]:
+        """
+        Create a workflow from a template.
+        
+        Args:
+            args: [--template, <name>, --output, <file.yaml>]
+            
+        Returns:
+            Path to created file
+        """
+        # Parse arguments
+        template_name = None
+        output_file = None
+        
+        i = 0
+        while i < len(args):
+            if args[i] == "--template" and i + 1 < len(args):
+                template_name = args[i + 1]
+                i += 2
+            elif args[i] == "--output" and i + 1 < len(args):
+                output_file = args[i + 1]
+                i += 2
+            else:
+                i += 1
+        
+        if not template_name:
+            self.print_status("Usage: praisonai workflow create --template <name>", "error")
+            self.print_status(f"Available templates: {', '.join(self.TEMPLATES.keys())}", "info")
+            return None
+        
+        if template_name not in self.TEMPLATES:
+            self.print_status(f"Unknown template: {template_name}", "error")
+            self.print_status(f"Available templates: {', '.join(self.TEMPLATES.keys())}", "info")
+            return None
+        
+        # Default output file
+        if not output_file:
+            output_file = f"{template_name}_workflow.yaml"
+        
+        # Check if file exists
+        if os.path.exists(output_file):
+            self.print_status(f"File already exists: {output_file}", "error")
+            return None
+        
+        # Write template
+        template_content = self.TEMPLATES[template_name]
+        
+        with open(output_file, 'w') as f:
+            f.write(template_content)
+        
+        self.print_status(f"✓ Created workflow: {output_file}", "success")
+        self.print_status(f"Run with: praisonai workflow run {output_file}", "info")
+        
+        return output_file
+    
+    def action_auto(self, args: List[str], **kwargs) -> Optional[str]:
+        """
+        Auto-generate a workflow from a topic description.
+        
+        Args:
+            args: ["topic description", --pattern, <pattern>, --output, <file.yaml>]
+            
+        Returns:
+            Path to created file
+        """
+        # Parse arguments
+        topic = None
+        pattern = "sequential"
+        output_file = None
+        
+        i = 0
+        while i < len(args):
+            if args[i] == "--pattern" and i + 1 < len(args):
+                pattern = args[i + 1]
+                i += 2
+            elif args[i] == "--output" and i + 1 < len(args):
+                output_file = args[i + 1]
+                i += 2
+            elif not args[i].startswith("--") and topic is None:
+                topic = args[i]
+                i += 1
+            else:
+                i += 1
+        
+        if not topic:
+            self.print_status('Usage: praisonai workflow auto "topic" --pattern <pattern>', "error")
+            self.print_status("Patterns: sequential, routing, parallel", "info")
+            return None
+        
+        # Validate pattern
+        valid_patterns = ["sequential", "routing", "parallel", "loop"]
+        if pattern not in valid_patterns:
+            self.print_status(f"Unknown pattern: {pattern}", "error")
+            self.print_status(f"Valid patterns: {', '.join(valid_patterns)}", "info")
+            return None
+        
+        # Default output file
+        if not output_file:
+            # Create safe filename from topic
+            safe_name = "".join(c if c.isalnum() else "_" for c in topic[:30]).lower()
+            output_file = f"{safe_name}_workflow.yaml"
+        
+        # Check if file exists
+        if os.path.exists(output_file):
+            self.print_status(f"File already exists: {output_file}", "error")
+            return None
+        
+        self.print_status(f"Generating {pattern} workflow for: {topic}", "info")
+        
+        try:
+            # Lazy import to avoid performance impact
+            from praisonai.auto import WorkflowAutoGenerator
+            
+            generator = WorkflowAutoGenerator(
+                topic=topic,
+                workflow_file=output_file
+            )
+            
+            result_path = generator.generate(pattern=pattern)
+            
+            self.print_status(f"✓ Created workflow: {result_path}", "success")
+            self.print_status(f"Run with: praisonai workflow run {output_file}", "info")
+            
+            return result_path
+            
+        except ImportError:
+            self.print_status("Auto-generation requires instructor: pip install instructor", "error")
+            return None
+        except Exception as e:
+            self.print_status(f"Generation failed: {e}", "error")
+            return None

src/praisonai/praisonai/cli/main.py

@@ -1485,6 +1485,12 @@ class PraisonAI:
                     return
                 workflow_name = action_args[0]
                 
+                # Check if it's a YAML file
+                if workflow_name.endswith(('.yaml', '.yml')) and os.path.exists(workflow_name):
+                    # Use new YAML workflow parser
+                    self._run_yaml_workflow(workflow_name, action_args, variables, args)
+                    return
+                
                 # Use global flags (--llm, --tools, --planning, --memory, --save, --verbose)
                 workflow_llm = getattr(args, 'llm', None) if args else None
                 workflow_tools_str = getattr(args, 'tools', None) if args else None
@@ -1607,22 +1613,55 @@ class PraisonAI:
                 print(f"[green]✅ Workflow created: {workflow_name}[/green]")
                 print(f"[cyan]Edit the workflow in .praison/workflows/{workflow_name}.md[/cyan]")
                 
+            elif action == 'validate':
+                # Validate a YAML workflow file
+                if not action_args:
+                    print("[red]ERROR: YAML file required. Usage: praisonai workflow validate <file.yaml>[/red]")
+                    return
+                yaml_file = action_args[0]
+                if not yaml_file.endswith(('.yaml', '.yml')):
+                    print("[red]ERROR: File must be a YAML file (.yaml or .yml)[/red]")
+                    return
+                self._validate_yaml_workflow(yaml_file)
+                
+            elif action == 'template':
+                # Create from template
+                template_name = action_args[0] if action_args else None
+                output_file = None
+                for i, arg in enumerate(action_args):
+                    if arg == '--output' and i + 1 < len(action_args):
+                        output_file = action_args[i + 1]
+                self._create_workflow_from_template(template_name, output_file)
+            
+            elif action == 'auto':
+                # Auto-generate workflow from topic
+                self._auto_generate_workflow(action_args)
+                
             elif action == 'help' or action == '--help':
                 print("[bold]Workflow Commands:[/bold]")
                 print("  praisonai workflow list                  - List available workflows")
                 print("  praisonai workflow run <name>            - Execute a workflow")
+                print("  praisonai workflow run <file.yaml>       - Execute a YAML workflow")
                 print("  praisonai workflow show <name>           - Show workflow details")
                 print("  praisonai workflow create <name>         - Create a new workflow")
+                print("  praisonai workflow validate <file.yaml>  - Validate a YAML workflow")
+                print("  praisonai workflow template <name>       - Create from template")
+                print('  praisonai workflow auto "topic"          - Auto-generate workflow')
+                print("\n[bold]Templates:[/bold]")
+                print("  simple, routing, parallel, loop, evaluator-optimizer")
                 print("\n[bold]Options (uses global flags):[/bold]")
                 print("  --workflow-var key=value                 - Set workflow variable (can be repeated)")
+                print("  --var key=value                          - Set variable for YAML workflows")
                 print("  --llm <model>                            - LLM model (e.g., openai/gpt-4o-mini)")
                 print("  --tools <tools>                          - Tools (comma-separated, e.g., tavily)")
                 print("  --planning                               - Enable planning mode")
                 print("  --memory                                 - Enable memory")
                 print("  --verbose                                - Enable verbose output")
                 print("  --save                                   - Save output to file")
-                print("\n[bold]Example:[/bold]")
+                print("\n[bold]Examples:[/bold]")
                 print("  praisonai workflow run 'Research Blog' --tools tavily --save")
+                print("  praisonai workflow run research.yaml --var topic='AI trends'")
+                print("  praisonai workflow template routing --output my_workflow.yaml")
             else:
                 print(f"[red]Unknown workflow action: {action}[/red]")
                 print("Use 'praisonai workflow help' for available commands")
@@ -1633,6 +1672,325 @@ class PraisonAI:
         except Exception as e:
             print(f"[red]ERROR: Workflow command failed: {e}[/red]")
 
+    def _run_yaml_workflow(self, yaml_file: str, action_args: list, variables: dict = None, args=None):
+        """
+        Run a YAML workflow file using the new YAMLWorkflowParser.
+        
+        Args:
+            yaml_file: Path to the YAML workflow file
+            action_args: Additional arguments
+            variables: Workflow variables
+            args: Parsed command line arguments
+        """
+        try:
+            from praisonaiagents.workflows import WorkflowManager
+            from rich import print
+            from rich.table import Table
+            from rich.console import Console
+            
+            console = Console()
+            manager = WorkflowManager()
+            
+            # Parse --var arguments from action_args
+            parsed_vars = variables or {}
+            i = 0
+            while i < len(action_args):
+                if action_args[i] == "--var" and i + 1 < len(action_args):
+                    var_str = action_args[i + 1]
+                    if "=" in var_str:
+                        key, value = var_str.split("=", 1)
+                        parsed_vars[key.strip()] = value.strip()
+                    i += 2
+                else:
+                    i += 1
+            
+            # Get verbose flag
+            verbose = '--verbose' in action_args or '-v' in action_args or (getattr(args, 'verbose', False) if args else False)
+            
+            print(f"[bold cyan]Running YAML workflow: {yaml_file}[/bold cyan]")
+            if parsed_vars:
+                print(f"[cyan]Variables: {parsed_vars}[/cyan]")
+            
+            # Load and execute the YAML workflow
+            workflow = manager.load_yaml(yaml_file)
+            
+            # Show workflow info
+            table = Table(title=f"Workflow: {workflow.name}")
+            table.add_column("Property", style="cyan")
+            table.add_column("Value", style="green")
+            table.add_row("Steps", str(len(workflow.steps)))
+            table.add_row("Planning", str(workflow.planning))
+            table.add_row("Reasoning", str(workflow.reasoning))
+            console.print(table)
+            
+            # Merge variables
+            if parsed_vars:
+                workflow.variables.update(parsed_vars)
+            
+            # Set verbose
+            if verbose:
+                workflow.verbose = True
+            
+            # Execute
+            print("\n[bold]Executing workflow...[/bold]\n")
+            result = workflow.start("")
+            
+            if result.get("status") == "completed":
+                print("\n[green]✅ Workflow completed successfully![/green]")
+                
+                # Show output
+                if result.get("output"):
+                    print("\n[bold]Output:[/bold]")
+                    output = result["output"]
+                    if len(output) > 2000:
+                        print(output[:2000] + "...")
+                    else:
+                        print(output)
+            else:
+                print(f"\n[red]❌ Workflow failed: {result.get('error', 'Unknown error')}[/red]")
+                
+        except FileNotFoundError:
+            print(f"[red]ERROR: YAML file not found: {yaml_file}[/red]")
+        except Exception as e:
+            print(f"[red]ERROR: YAML workflow failed: {e}[/red]")
+            import traceback
+            traceback.print_exc()
+
+    def _validate_yaml_workflow(self, yaml_file: str):
+        """
+        Validate a YAML workflow file.
+        
+        Args:
+            yaml_file: Path to the YAML workflow file
+        """
+        try:
+            from praisonaiagents.workflows import YAMLWorkflowParser
+            from rich import print
+            from rich.table import Table
+            from rich.console import Console
+            import yaml
+            
+            console = Console()
+            
+            if not os.path.exists(yaml_file):
+                print(f"[red]ERROR: File not found: {yaml_file}[/red]")
+                return
+            
+            print(f"[cyan]Validating: {yaml_file}[/cyan]")
+            
+            # Load raw YAML to check for non-canonical names
+            with open(yaml_file, 'r') as f:
+                raw_data = yaml.safe_load(f)
+            
+            # Check for non-canonical names and suggest canonical ones
+            suggestions = self._get_canonical_suggestions(raw_data)
+            
+            parser = YAMLWorkflowParser()
+            workflow = parser.parse_file(yaml_file)
+            
+            # Show validation results
+            table = Table(title="Workflow Validation")
+            table.add_column("Property", style="cyan")
+            table.add_column("Value", style="green")
+            
+            table.add_row("Name", workflow.name)
+            table.add_row("Description", getattr(workflow, 'description', 'N/A'))
+            table.add_row("Steps", str(len(workflow.steps)))
+            table.add_row("Variables", str(len(workflow.variables)))
+            table.add_row("Planning", str(workflow.planning))
+            table.add_row("Reasoning", str(workflow.reasoning))
+            
+            console.print(table)
+            print("[green]✓ Workflow is valid![/green]")
+            
+            # Show suggestions for canonical names
+            if suggestions:
+                print()
+                print("[yellow]💡 Suggestions for canonical field names:[/yellow]")
+                for suggestion in suggestions:
+                    print(f"   [dim]•[/dim] {suggestion}")
+                print()
+                print("[dim]Note: Both old and new names work, but canonical names are recommended.[/dim]")
+            
+        except Exception as e:
+            print(f"[red]✗ Validation failed: {e}[/red]")
+    
+    def _get_canonical_suggestions(self, data: dict) -> list:
+        """
+        Check for non-canonical field names and return suggestions.
+        
+        Canonical names (A-I-G-S mnemonic):
+        - Agents (not roles)
+        - Instructions (not backstory)
+        - Goal (same)
+        - Steps (not tasks)
+        
+        Also:
+        - name (not topic)
+        - action (not description)
+        
+        Args:
+            data: Raw YAML data
+            
+        Returns:
+            List of suggestion strings
+        """
+        suggestions = []
+        
+        if not data:
+            return suggestions
+        
+        # Check top-level keys
+        if 'roles' in data:
+            suggestions.append("Use 'agents' instead of 'roles'")
+        
+        if 'topic' in data and 'name' not in data:
+            suggestions.append("Use 'name' instead of 'topic'")
+        
+        # Check agent fields
+        agents_data = data.get('agents', data.get('roles', {}))
+        for agent_id, agent_config in agents_data.items():
+            if isinstance(agent_config, dict):
+                if 'backstory' in agent_config:
+                    suggestions.append(f"Agent '{agent_id}': Use 'instructions' instead of 'backstory'")
+                
+                # Check nested tasks
+                if 'tasks' in agent_config:
+                    suggestions.append(f"Agent '{agent_id}': Use 'steps' at top level instead of nested 'tasks'")
+        
+        # Check step fields
+        steps_data = data.get('steps', [])
+        for i, step in enumerate(steps_data):
+            if isinstance(step, dict):
+                if 'description' in step and 'action' not in step:
+                    step_name = step.get('name', f'step {i+1}')
+                    suggestions.append(f"Step '{step_name}': Use 'action' instead of 'description'")
+                
+                # Check parallel steps
+                if 'parallel' in step:
+                    for j, parallel_step in enumerate(step['parallel']):
+                        if isinstance(parallel_step, dict):
+                            if 'description' in parallel_step and 'action' not in parallel_step:
+                                suggestions.append(f"Parallel step {j+1}: Use 'action' instead of 'description'")
+        
+        return suggestions
+
+    def _create_workflow_from_template(self, template_name: str = None, output_file: str = None):
+        """
+        Create a workflow from a template.
+        
+        Uses templates from WorkflowHandler to avoid duplication.
+        
+        Args:
+            template_name: Name of the template
+            output_file: Output file path
+        """
+        from rich import print
+        
+        # Use templates from WorkflowHandler to avoid duplication
+        try:
+            from .features.workflow import WorkflowHandler
+            templates = WorkflowHandler.TEMPLATES
+        except ImportError:
+            print("[red]ERROR: WorkflowHandler not available.[/red]")
+            return
+        
+        if not template_name:
+            print("[red]ERROR: Template name required.[/red]")
+            print(f"[cyan]Available templates: {', '.join(templates.keys())}[/cyan]")
+            return
+        
+        if template_name not in templates:
+            print(f"[red]ERROR: Unknown template: {template_name}[/red]")
+            print(f"[cyan]Available templates: {', '.join(templates.keys())}[/cyan]")
+            return
+        
+        # Default output file
+        if not output_file:
+            output_file = f"{template_name}_workflow.yaml"
+        
+        # Check if file exists
+        if os.path.exists(output_file):
+            print(f"[red]ERROR: File already exists: {output_file}[/red]")
+            return
+        
+        # Write template
+        with open(output_file, 'w') as f:
+            f.write(templates[template_name])
+        
+        print(f"[green]✓ Created workflow: {output_file}[/green]")
+        print(f"[cyan]Run with: praisonai workflow run {output_file}[/cyan]")
+
+    def _auto_generate_workflow(self, action_args: list):
+        """
+        Auto-generate a workflow from a topic description.
+        
+        Args:
+            action_args: ["topic description", --pattern, <pattern>, --output, <file.yaml>]
+        """
+        from rich import print
+        
+        # Parse arguments
+        topic = None
+        pattern = "sequential"
+        output_file = None
+        
+        i = 0
+        while i < len(action_args):
+            if action_args[i] == "--pattern" and i + 1 < len(action_args):
+                pattern = action_args[i + 1]
+                i += 2
+            elif action_args[i] == "--output" and i + 1 < len(action_args):
+                output_file = action_args[i + 1]
+                i += 2
+            elif not action_args[i].startswith("--") and topic is None:
+                topic = action_args[i]
+                i += 1
+            else:
+                i += 1
+        
+        if not topic:
+            print('[red]Usage: praisonai workflow auto "topic" --pattern <pattern>[/red]')
+            print("[cyan]Patterns: sequential, routing, parallel[/cyan]")
+            return
+        
+        # Validate pattern
+        valid_patterns = ["sequential", "routing", "parallel", "loop"]
+        if pattern not in valid_patterns:
+            print(f"[red]Unknown pattern: {pattern}[/red]")
+            print(f"[cyan]Valid patterns: {', '.join(valid_patterns)}[/cyan]")
+            return
+        
+        # Default output file
+        if not output_file:
+            safe_name = "".join(c if c.isalnum() else "_" for c in topic[:30]).lower()
+            output_file = f"{safe_name}_workflow.yaml"
+        
+        # Check if file exists
+        if os.path.exists(output_file):
+            print(f"[red]ERROR: File already exists: {output_file}[/red]")
+            return
+        
+        print(f"[cyan]Generating {pattern} workflow for: {topic}[/cyan]")
+        
+        try:
+            from praisonai.auto import WorkflowAutoGenerator
+            
+            generator = WorkflowAutoGenerator(
+                topic=topic,
+                workflow_file=output_file
+            )
+            
+            result_path = generator.generate(pattern=pattern)
+            
+            print(f"[green]✓ Created workflow: {result_path}[/green]")
+            print(f"[cyan]Run with: praisonai workflow run {output_file}[/cyan]")
+            
+        except ImportError:
+            print("[red]Auto-generation requires instructor: pip install instructor[/red]")
+        except Exception as e:
+            print(f"[red]Generation failed: {e}[/red]")
+
     def handle_hooks_command(self, action: str):
         """
         Handle hooks subcommand actions.

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.28 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.28"

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.1.7",
     "python-dotenv>=0.19.0",
     "instructor>=1.3.3",
     "PyYAML>=6.0",

src/praisonai/tests/test_runner.py

@@ -224,7 +224,7 @@ def run_tests(pattern=None, verbose=False, coverage=False):
         # Run only fast, non-integration tests
         cmd.extend(["tests/unit/", "-m", "not slow"])
     elif pattern == "all":
-        cmd.append("tests/")
+        cmd.extend(["tests/", "-m", "not real"])  # Exclude real tests that require API keys
     elif pattern == "frameworks":
         # Run both AutoGen and CrewAI integration tests (mock)
         cmd.extend(["tests/integration/autogen/", "tests/integration/crewai/"])

src/praisonai/tests/unit/test_cli_features.py

@@ -270,9 +270,10 @@ class TestSessionHandler:
         from praisonai.cli.features.session import SessionHandler
         handler = SessionHandler()
         actions = handler.get_actions()
-        assert "start" in actions
         assert "list" in actions
+        assert "show" in actions
         assert "resume" in actions
+        assert "delete" in actions
 
 
 class TestToolsHandler:

src/praisonai/tests/unit/test_workflow_cli.py

@@ -0,0 +1,112 @@
+"""
+Unit tests for Workflow CLI commands.
+
+Tests the WorkflowHandler CLI feature for YAML workflow management.
+"""
+
+import os
+import tempfile
+
+
+class TestWorkflowHandler:
+    """Tests for WorkflowHandler CLI feature."""
+    
+    def test_workflow_handler_import(self):
+        """Test that WorkflowHandler can be imported."""
+        from praisonai.cli.features import WorkflowHandler
+        assert WorkflowHandler is not None
+    
+    def test_workflow_handler_initialization(self):
+        """Test WorkflowHandler initialization."""
+        from praisonai.cli.features.workflow import WorkflowHandler
+        handler = WorkflowHandler(verbose=True)
+        assert handler.feature_name == "workflow"
+    
+    def test_workflow_get_actions(self):
+        """Test getting available actions."""
+        from praisonai.cli.features.workflow import WorkflowHandler
+        handler = WorkflowHandler()
+        actions = handler.get_actions()
+        assert "run" in actions
+        assert "validate" in actions
+        assert "list" in actions
+        assert "create" in actions
+    
+    def test_workflow_templates_exist(self):
+        """Test that workflow templates are defined."""
+        from praisonai.cli.features.workflow import WorkflowHandler
+        handler = WorkflowHandler()
+        assert "simple" in handler.TEMPLATES
+        assert "routing" in handler.TEMPLATES
+        assert "parallel" in handler.TEMPLATES
+        assert "loop" in handler.TEMPLATES
+        assert "evaluator-optimizer" in handler.TEMPLATES
+    
+    def test_workflow_create_template(self):
+        """Test creating a workflow from template."""
+        from praisonai.cli.features.workflow import WorkflowHandler
+        handler = WorkflowHandler()
+        
+        with tempfile.TemporaryDirectory() as tmpdir:
+            output_file = os.path.join(tmpdir, "test_workflow.yaml")
+            result = handler.action_create(
+                ["--template", "simple", "--output", output_file]
+            )
+            
+            assert result == output_file
+            assert os.path.exists(output_file)
+            
+            # Check content
+            with open(output_file, 'r') as f:
+                content = f.read()
+            assert "name: Simple Workflow" in content
+            assert "agents:" in content
+            assert "steps:" in content
+    
+    def test_workflow_validate(self):
+        """Test validating a YAML workflow."""
+        from praisonai.cli.features.workflow import WorkflowHandler
+        handler = WorkflowHandler()
+        
+        yaml_content = """
+name: Test Workflow
+agents:
+  agent1:
+    name: Agent1
+    role: Worker
+    goal: Work
+    instructions: "Do work"
+
+steps:
+  - agent: agent1
+    action: "Work"
+"""
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.yaml', delete=False) as f:
+            f.write(yaml_content)
+            temp_path = f.name
+        
+        try:
+            result = handler.action_validate([temp_path])
+            assert result == True
+        finally:
+            os.unlink(temp_path)
+    
+    def test_workflow_validate_invalid_file(self):
+        """Test validating a non-existent file."""
+        from praisonai.cli.features.workflow import WorkflowHandler
+        handler = WorkflowHandler()
+        
+        result = handler.action_validate(["nonexistent.yaml"])
+        assert result == False
+    
+    def test_workflow_help_text(self):
+        """Test help text contains expected commands."""
+        from praisonai.cli.features.workflow import WorkflowHandler
+        handler = WorkflowHandler()
+        help_text = handler.get_help_text()
+        
+        assert "run" in help_text
+        assert "validate" in help_text
+        assert "list" in help_text
+        assert "create" in help_text
+        assert "template" in help_text

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.1.7" },
     { 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.1.7"
 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/07/19/d59400d701c3433c1b0c08024f34d9e17d63bb6257c0f56e39c9715f66a8/praisonaiagents-0.1.7.tar.gz", hash = "sha256:42ac442ff80bdbcca0f25987d8ac722e4ce9480a650acecde1c6fc7fa124acdf", size = 615505, upload-time = "2025-12-17T13:15:11.644Z" }
 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/b1/cb/cdd00ec34abb60925133ed8643432f93f45f4c679ccd3f599d01a26fc354/praisonaiagents-0.1.7-py3-none-any.whl", hash = "sha256:b07ecc2b088f9bcbd4dab352685f35142b422d002581aaa8b992a8f7033d6d13", size = 545981, upload-time = "2025-12-17T13:15:09.434Z" },
 ]
 
 [[package]]