# 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()`

```python
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()`

```python
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()`

```python
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()`

```python
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)

```python
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

```python
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**
```python
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**
```python
{
    '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

```python
# 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.