gateway/notes/WORKFLOW_ARCHITECTURE.md

Workflow Architecture Documentation

Overview

The workflow system has been refactored into a clear, structured approach with 5 distinct phases. This eliminates redundancies and provides better error handling, quality assessment, and maintainability.

Architecture Principles

1. Clear Phase Separation

Each workflow phase has a specific responsibility and clear inputs/outputs.

2. Unified Data Model

Standardized on TaskAction objects throughout the system.

3. Consistent Prompt Generation

All AI interactions use dedicated prompt generation functions.

4. Quality Assessment

Each task is reviewed before proceeding to the next.

Workflow Phases

Phase 1: High-Level Task Planning

Function: planHighLevelTasks() Purpose: Analyze user request and create a structured task plan Input: User input, available documents Output: Task plan with multiple task steps Prompt Function: _createTaskPlanningPrompt()

task_plan = await chatManager.planHighLevelTasks(userInput, workflow)

Phase 2: Task Definition and Action Generation

Function: defineTaskActions() Purpose: Define specific actions for each task step Input: Task step, workflow context, previous results Output: List of TaskAction objects Prompt Function: _createActionDefinitionPrompt()

task_actions = await chatManager.defineTaskActions(task_step, workflow, previous_results)

Phase 3: Action Execution

Function: executeTaskActions() Purpose: Execute all actions for a task step Input: List of TaskAction objects Output: List of action results Prompt Function: _createActionExecutionPrompt()

action_results = await chatManager.executeTaskActions(task_actions, workflow)

Phase 4: Task Review and Quality Assessment

Function: reviewTaskCompletion() Purpose: Review task completion and decide next steps Input: Task step, actions, results Output: Review result with quality metrics Prompt Function: _createResultReviewPrompt()

review_result = await chatManager.reviewTaskCompletion(task_step, task_actions, action_results, workflow)

Phase 5: Task Handover and State Management

Function: prepareTaskHandover() Purpose: Prepare results for next task or workflow completion Input: Task step, actions, review result Output: Handover data for next iteration Prompt Function: None (data processing only)

handover_data = await chatManager.prepareTaskHandover(task_step, task_actions, review_result, workflow)

Unified Workflow Execution

Main Entry Point

Function: executeUnifiedWorkflow() Purpose: Orchestrate all phases in sequence Input: User input, workflow Output: Complete workflow results

workflow_result = await chatManager.executeUnifiedWorkflow(userInput.prompt, workflow)

Workflow Flow

1. planHighLevelTasks() → Task Plan
2. For each task step:
   ├── defineTaskActions() → Task Actions
   ├── executeTaskActions() → Action Results
   ├── reviewTaskCompletion() → Review Result
   └── prepareTaskHandover() → Handover Data
3. Return workflow summary

Prompt Generation Functions

Function	Used In	Purpose
_createTaskPlanningPrompt()	planHighLevelTasks()	Generate high-level task plan
_createActionDefinitionPrompt()	defineTaskActions()	Generate specific actions for task
_createActionExecutionPrompt()	executeTaskActions()	Execute individual actions
_createResultReviewPrompt()	reviewTaskCompletion()	Review task completion

Data Models

TaskAction Object

class TaskAction:
    id: str
    execMethod: str
    execAction: str
    execParameters: Dict[str, Any]
    execResultLabel: Optional[str]
    status: TaskStatus
    error: Optional[str]
    result: Optional[str]
    # ... other fields

Workflow Result Structure

{
    'status': 'completed' | 'partial' | 'failed',
    'successful_tasks': int,
    'total_tasks': int,
    'workflow_results': List[Dict],
    'final_results': List[str]
}

Error Handling

Phase-Level Error Handling

Each phase has its own error handling:

• Planning: Fallback to basic task plan
• Definition: Skip task if no actions defined
• Execution: Stop on first action failure
• Review: Default to success to avoid blocking
• Handover: Provide empty results on error

Circuit Breaker Pattern

AI calls use circuit breaker pattern to prevent cascading failures.

Quality Metrics

Task Quality Assessment

• Success rate of actions
• Completion of expected outputs
• Meeting of success criteria
• Confidence scores

Workflow Quality Metrics

• Overall success rate
• Task completion percentage
• Error patterns and suggestions

Benefits of Refactored Architecture

1. Clear Separation of Concerns

Each phase has a single responsibility and clear interfaces.

2. Better Error Handling

Granular error handling at each phase with appropriate fallbacks.

3. Quality Assessment

Built-in review and quality metrics for each task.

4. Maintainability

Consistent patterns and unified data models.

5. Extensibility

Easy to add new phases or modify existing ones.

6. Debugging

Clear logging and error reporting at each phase.

Migration Path

Legacy Methods

All legacy methods are preserved for backward compatibility:

• createInitialTask()
• createNextTask()
• executeTask()
• executeAction()

New Unified Approach

Use executeUnifiedWorkflow() for new implementations.

Usage Example

# Initialize chat manager
await chatManager.initialize(workflow)

# Execute unified workflow
workflow_result = await chatManager.executeUnifiedWorkflow(userInput.prompt, workflow)

# Process results
if workflow_result['status'] == 'completed':
    print(f"Workflow completed: {workflow_result['successful_tasks']}/{workflow_result['total_tasks']} tasks")
else:
    print(f"Workflow failed: {workflow_result['error']}")

Future Enhancements

1. Retry Logic

Add exponential backoff retry for failed tasks.

2. Alternative Approaches

When primary method fails, try alternative approaches.

3. Parallel Execution

Execute independent tasks in parallel.

4. Progress Tracking

Real-time progress updates during workflow execution.

5. Rollback Mechanisms

Undo failed operations and restore previous state.