""" WHOOSH API - Workflow Management Endpoints This module provides comprehensive API endpoints for managing multi-agent workflows in the WHOOSH distributed orchestration platform. It handles workflow creation, execution, monitoring, and lifecycle management. Key Features: - Multi-step workflow creation and validation - Agent coordination and task orchestration - Real-time execution monitoring and control - Workflow templates and reusability - Performance analytics and optimization """ from fastapi import APIRouter, Depends, HTTPException, Query, status from typing import List, Dict, Any, Optional from ..core.auth_deps import get_current_user_context from ..models.responses import ( WorkflowListResponse, WorkflowCreationResponse, WorkflowExecutionResponse, WorkflowCreationRequest, WorkflowExecutionRequest, WorkflowModel, ErrorResponse ) from ..core.error_handlers import ( coordinator_unavailable_error, validation_error, WHOOSHAPIException ) import uuid from datetime import datetime router = APIRouter() @router.get( "/workflows", response_model=WorkflowListResponse, status_code=status.HTTP_200_OK, summary="List all workflows", description=""" Retrieve a comprehensive list of all workflows in the WHOOSH system. This endpoint provides access to workflow definitions, templates, and metadata for building complex multi-agent orchestration pipelines. **Workflow Information Includes:** - Workflow definition and step configuration - Execution statistics and success rates - Creation and modification timestamps - User ownership and permissions - Performance metrics and analytics **Workflow Types:** - **Code Review Pipelines**: Automated code analysis and testing - **Deployment Workflows**: CI/CD and deployment automation - **Data Processing**: ETL and data transformation pipelines - **Testing Suites**: Comprehensive testing and quality assurance - **Documentation**: Automated documentation generation - **Security Audits**: Security scanning and vulnerability assessment **Use Cases:** - Browse available workflow templates - Monitor workflow performance and usage - Manage workflow lifecycle and versioning - Analyze workflow efficiency and optimization opportunities - Create workflow libraries and reusable components """, responses={ 200: {"description": "Workflow list retrieved successfully"}, 500: {"model": ErrorResponse, "description": "Failed to retrieve workflows"} } ) async def get_workflows( status_filter: Optional[str] = Query(None, alias="status", description="Filter by workflow status"), created_by: Optional[str] = Query(None, description="Filter by workflow creator"), limit: int = Query(50, description="Maximum number of workflows to return", ge=1, le=1000), current_user: Dict[str, Any] = Depends(get_current_user_context) ) -> WorkflowListResponse: """ Get a list of all workflows with optional filtering. Args: status_filter: Optional status filter for workflows created_by: Optional filter by workflow creator limit: Maximum number of workflows to return current_user: Current authenticated user context Returns: WorkflowListResponse: List of workflows with metadata Raises: HTTPException: If workflow retrieval fails """ try: # For now, return placeholder workflows until full workflow engine is implemented sample_workflows = [ WorkflowModel( id="workflow-code-review", name="Code Review Pipeline", description="Automated code review and testing workflow", status="active", steps=[ { "name": "Static Analysis", "type": "code_analysis", "agent_specialty": "kernel_dev", "context": {"analysis_type": "security", "rules": "strict"} }, { "name": "Unit Testing", "type": "testing", "agent_specialty": "tester", "context": {"test_suite": "unit", "coverage_threshold": 80} } ], created_at=datetime.utcnow(), created_by="system", execution_count=25, success_rate=92.5 ), WorkflowModel( id="workflow-deployment", name="Deployment Pipeline", description="CI/CD deployment workflow with testing and validation", status="active", steps=[ { "name": "Build", "type": "build", "agent_specialty": "general_ai", "context": {"target": "production", "optimize": True} }, { "name": "Integration Tests", "type": "testing", "agent_specialty": "tester", "context": {"test_suite": "integration", "environment": "staging"} }, { "name": "Deploy", "type": "deployment", "agent_specialty": "general_ai", "context": {"environment": "production", "strategy": "rolling"} } ], created_at=datetime.utcnow(), created_by="system", execution_count=15, success_rate=88.7 ) ] # Apply filters filtered_workflows = sample_workflows if status_filter: filtered_workflows = [w for w in filtered_workflows if w.status == status_filter] if created_by: filtered_workflows = [w for w in filtered_workflows if w.created_by == created_by] # Apply limit filtered_workflows = filtered_workflows[:limit] return WorkflowListResponse( workflows=filtered_workflows, total=len(filtered_workflows), message=f"Retrieved {len(filtered_workflows)} workflows" ) except Exception as e: raise HTTPException( status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"Failed to retrieve workflows: {str(e)}" ) @router.post( "/workflows", response_model=WorkflowCreationResponse, status_code=status.HTTP_201_CREATED, summary="Create a new workflow", description=""" Create a new multi-agent workflow for task orchestration and automation. This endpoint allows you to define complex workflows that coordinate multiple agents to perform sophisticated development and operational tasks. **Workflow Creation Process:** 1. **Validation**: Validate workflow structure and step definitions 2. **Agent Verification**: Verify required agent specializations are available 3. **Dependency Analysis**: Analyze step dependencies and execution order 4. **Resource Planning**: Estimate resource requirements and execution time 5. **Storage**: Persist workflow definition for future execution **Workflow Step Types:** - `code_analysis`: Static code analysis and review - `testing`: Test execution and validation - `build`: Compilation and build processes - `deployment`: Application deployment and configuration - `documentation`: Documentation generation and updates - `security_scan`: Security analysis and vulnerability assessment - `performance_test`: Performance testing and benchmarking - `data_processing`: Data transformation and analysis **Advanced Features:** - **Conditional Execution**: Steps can have conditions and branching logic - **Parallel Execution**: Steps can run in parallel for improved performance - **Error Handling**: Define retry policies and error recovery procedures - **Variable Substitution**: Use variables and templates for flexible workflows - **Agent Selection**: Specify agent requirements and selection criteria - **Timeout Management**: Configure timeouts for individual steps and overall workflow **Best Practices:** - Keep steps focused and atomic for better reliability - Use meaningful names and descriptions for clarity - Include appropriate error handling and retry logic - Optimize step ordering for performance and dependencies - Test workflows thoroughly before production use """, responses={ 201: {"description": "Workflow created successfully"}, 400: {"model": ErrorResponse, "description": "Invalid workflow configuration"}, 422: {"model": ErrorResponse, "description": "Workflow validation failed"}, 500: {"model": ErrorResponse, "description": "Workflow creation failed"} } ) async def create_workflow( workflow_data: WorkflowCreationRequest, current_user: Dict[str, Any] = Depends(get_current_user_context) ) -> WorkflowCreationResponse: """ Create a new workflow with validation and optimization. Args: workflow_data: Workflow configuration and step definitions current_user: Current authenticated user context Returns: WorkflowCreationResponse: Workflow creation confirmation with validation results Raises: HTTPException: If workflow creation fails due to validation or system issues """ try: # Validate workflow structure if not workflow_data.steps: raise validation_error("steps", "Workflow must have at least one step") # Validate step configuration for i, step in enumerate(workflow_data.steps): if not step.get("name"): raise validation_error(f"steps[{i}].name", "Step name is required") if not step.get("type"): raise validation_error(f"steps[{i}].type", "Step type is required") # Generate workflow ID workflow_id = f"workflow-{uuid.uuid4().hex[:8]}" # Perform workflow validation validation_results = { "valid": True, "warnings": [], "step_count": len(workflow_data.steps), "estimated_agents_required": len(set(step.get("agent_specialty", "general_ai") for step in workflow_data.steps)), "estimated_duration": workflow_data.timeout or 3600 } # Check for potential issues if len(workflow_data.steps) > 10: validation_results["warnings"].append("Workflow has many steps - consider breaking into smaller workflows") if workflow_data.timeout and workflow_data.timeout > 7200: # 2 hours validation_results["warnings"].append("Long timeout specified - ensure workflow is optimized") # TODO: Store workflow in database when workflow engine is fully implemented # For now, we simulate successful creation return WorkflowCreationResponse( workflow_id=workflow_id, validation_results=validation_results, message=f"Workflow '{workflow_data.name}' created successfully with {len(workflow_data.steps)} steps" ) except HTTPException: raise except Exception as e: raise HTTPException( status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"Failed to create workflow: {str(e)}" ) @router.get( "/workflows/{workflow_id}", response_model=WorkflowModel, status_code=status.HTTP_200_OK, summary="Get specific workflow details", description=""" Retrieve comprehensive details about a specific workflow by its ID. This endpoint provides complete information about a workflow including: - Workflow definition and step configuration - Execution history and performance metrics - Success rates and failure analysis - Resource utilization and optimization recommendations **Detailed Information Includes:** - Complete step definitions with agent requirements - Execution statistics and performance trends - Variable definitions and configuration options - Dependencies and prerequisite information - User permissions and ownership details - Audit trail and modification history **Use Cases:** - Review workflow configuration before execution - Analyze workflow performance and success rates - Debug workflow issues and failures - Copy or modify existing workflows - Generate workflow documentation and reports """, responses={ 200: {"description": "Workflow details retrieved successfully"}, 404: {"model": ErrorResponse, "description": "Workflow not found"}, 500: {"model": ErrorResponse, "description": "Failed to retrieve workflow details"} } ) async def get_workflow( workflow_id: str, current_user: Dict[str, Any] = Depends(get_current_user_context) ) -> WorkflowModel: """ Get detailed information about a specific workflow. Args: workflow_id: Unique identifier of the workflow to retrieve current_user: Current authenticated user context Returns: WorkflowModel: Comprehensive workflow details and configuration Raises: HTTPException: If workflow not found or retrieval fails """ try: # For now, return a sample workflow until full implementation if workflow_id == "workflow-code-review": return WorkflowModel( id=workflow_id, name="Code Review Pipeline", description="Automated code review and testing workflow", status="active", steps=[ { "name": "Static Analysis", "type": "code_analysis", "agent_specialty": "kernel_dev", "context": {"analysis_type": "security", "rules": "strict"}, "timeout": 600, "retry_policy": {"max_attempts": 3, "backoff": "exponential"} }, { "name": "Unit Testing", "type": "testing", "agent_specialty": "tester", "context": {"test_suite": "unit", "coverage_threshold": 80}, "timeout": 1200, "depends_on": ["Static Analysis"] } ], created_at=datetime.utcnow(), created_by="system", execution_count=25, success_rate=92.5 ) # Return 404 for unknown workflows raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Workflow with ID '{workflow_id}' not found" ) except HTTPException: raise except Exception as e: raise HTTPException( status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"Failed to retrieve workflow: {str(e)}" ) @router.post( "/workflows/{workflow_id}/execute", response_model=WorkflowExecutionResponse, status_code=status.HTTP_202_ACCEPTED, summary="Execute a workflow", description=""" Execute a workflow with optional input parameters and configuration overrides. This endpoint starts a new execution of the specified workflow, coordinating multiple agents to complete the defined sequence of tasks. **Execution Process:** 1. **Validation**: Validate input parameters and workflow readiness 2. **Resource Allocation**: Reserve required agents and resources 3. **Step Orchestration**: Execute workflow steps in correct order 4. **Progress Monitoring**: Track execution progress and status 5. **Result Collection**: Collect and aggregate step results 6. **Cleanup**: Release resources and generate execution report **Execution Features:** - **Parallel Processing**: Execute independent steps simultaneously - **Error Recovery**: Automatic retry and error handling - **Progress Tracking**: Real-time execution status and progress - **Resource Management**: Efficient agent allocation and scheduling - **Result Aggregation**: Collect and combine step outputs - **Audit Logging**: Complete execution audit trail **Input Parameters:** - Workflow variables and configuration overrides - Environment-specific settings and credentials - Resource constraints and preferences - Execution priority and scheduling options **Monitoring:** - Use the executions endpoints to monitor progress - Real-time status updates via WebSocket connections - Step-by-step progress tracking and logging - Performance metrics and resource utilization """, responses={ 202: {"description": "Workflow execution started successfully"}, 404: {"model": ErrorResponse, "description": "Workflow not found"}, 409: {"model": ErrorResponse, "description": "Workflow cannot be executed (insufficient resources, etc.)"}, 500: {"model": ErrorResponse, "description": "Workflow execution failed to start"} } ) async def execute_workflow( workflow_id: str, execution_data: WorkflowExecutionRequest, current_user: Dict[str, Any] = Depends(get_current_user_context) ) -> WorkflowExecutionResponse: """ Execute a workflow with the specified inputs and configuration. Args: workflow_id: Unique identifier of the workflow to execute execution_data: Execution parameters and configuration current_user: Current authenticated user context Returns: WorkflowExecutionResponse: Execution confirmation with tracking details Raises: HTTPException: If workflow not found or execution fails to start """ try: # Verify workflow exists (placeholder check) if workflow_id not in ["workflow-code-review", "workflow-deployment"]: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Workflow with ID '{workflow_id}' not found" ) # Generate execution ID execution_id = f"exec-{uuid.uuid4().hex[:8]}" # Estimate execution duration based on workflow and inputs estimated_duration = execution_data.timeout_override or 3600 # TODO: Start actual workflow execution when workflow engine is implemented # For now, simulate successful execution start return WorkflowExecutionResponse( execution_id=execution_id, workflow_id=workflow_id, estimated_duration=estimated_duration, message=f"Workflow execution '{execution_id}' started with priority {execution_data.priority}" ) except HTTPException: raise except Exception as e: raise HTTPException( status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"Failed to execute workflow: {str(e)}" ) @router.delete( "/workflows/{workflow_id}", status_code=status.HTTP_204_NO_CONTENT, summary="Delete a workflow", description=""" Delete a workflow from the system. This endpoint permanently removes a workflow definition and all associated metadata. This action cannot be undone. **Deletion Process:** 1. **Validation**: Verify workflow exists and user has permissions 2. **Active Check**: Ensure no active executions are running 3. **Cleanup**: Remove workflow definition and associated data 4. **Audit**: Log deletion event for audit trail **Safety Measures:** - Cannot delete workflows with active executions - Requires appropriate user permissions - Maintains execution history for completed runs - Generates audit log entry for deletion **Use Cases:** - Remove obsolete or unused workflows - Clean up test or experimental workflows - Maintain workflow library organization - Comply with data retention policies """, responses={ 204: {"description": "Workflow deleted successfully"}, 404: {"model": ErrorResponse, "description": "Workflow not found"}, 409: {"model": ErrorResponse, "description": "Workflow has active executions"}, 403: {"model": ErrorResponse, "description": "Insufficient permissions"}, 500: {"model": ErrorResponse, "description": "Workflow deletion failed"} } ) async def delete_workflow( workflow_id: str, current_user: Dict[str, Any] = Depends(get_current_user_context) ): """ Delete a workflow permanently. Args: workflow_id: Unique identifier of the workflow to delete current_user: Current authenticated user context Raises: HTTPException: If workflow not found, has active executions, or deletion fails """ try: # Verify workflow exists if workflow_id not in ["workflow-code-review", "workflow-deployment"]: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Workflow with ID '{workflow_id}' not found" ) # TODO: Check for active executions when execution engine is implemented # TODO: Verify user permissions for deletion # TODO: Perform actual deletion when database is implemented # For now, simulate successful deletion except HTTPException: raise except Exception as e: raise HTTPException( status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"Failed to delete workflow: {str(e)}" )