226 lines
No EOL
6.5 KiB
Markdown
226 lines
No EOL
6.5 KiB
Markdown
# 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. |