synapse-sdk 2025.10.1__py3-none-any.whl → 2025.10.3__py3-none-any.whl

synapse_sdk/plugins/README.md

@@ -46,7 +46,7 @@ The `Action` class (`synapse_sdk/plugins/categories/base.py`) provides the unifi
 ```python
 class Action:
     """Base class for all plugin actions.
-    
+
     Class Variables:
         name (str): Action identifier
         category (PluginCategory): Plugin category
@@ -55,7 +55,7 @@ class Action:
         params_model (BaseModel): Parameter validation model
         progress_categories (Dict): Progress tracking categories
         metrics_categories (Dict): Metrics collection categories
-    
+
     Instance Variables:
         params (Dict): Validated action parameters
         plugin_config (Dict): Plugin configuration
@@ -63,7 +63,7 @@ class Action:
         client: Backend API client
         run (Run): Execution instance
     """
-    
+
     # Class configuration
     name = None
     category = None
@@ -72,7 +72,7 @@ class Action:
     params_model = None
     progress_categories = None
     metrics_categories = None
-    
+
     def start(self):
         """Main action logic - implement in subclasses."""
         raise NotImplementedError
@@ -111,20 +111,20 @@ The `Run` class (`models.py`) manages action execution:
 ```python
 class Run(BaseModel):
     """Manages plugin execution lifecycle.
-    
+
     Key Methods:
         log_message(message, context): Log execution messages
         set_progress(current, total, category): Update progress
         set_metrics(metrics, category): Record metrics
         log(log_type, data): Structured logging
     """
-    
+
     def log_message(self, message: str, context: str = 'INFO'):
         """Log execution messages with context."""
-        
+
     def set_progress(self, current: int, total: int, category: str = None):
         """Update progress tracking."""
-        
+
     def set_metrics(self, metrics: dict, category: str):
         """Record execution metrics."""
 ```
@@ -165,18 +165,18 @@ class MyActionParams(BaseModel):
 @register_action
 class MyAction(Action):
     """Base implementation for my_category actions."""
-    
+
     name = 'my_action'
     category = PluginCategory.MY_CATEGORY
     method = RunMethod.JOB
     params_model = MyActionParams
-    
+
     progress_categories = {
         'preprocessing': {'proportion': 20},
         'processing': {'proportion': 60},
         'postprocessing': {'proportion': 20}
     }
-    
+
     metrics_categories = {
         'performance': {
             'throughput': 0,
@@ -184,30 +184,30 @@ class MyAction(Action):
             'accuracy': 0
         }
     }
-    
+
     def start(self):
         """Main execution logic."""
         self.run.log_message("Starting my action...")
-        
+
         # Access validated parameters
         input_path = self.params['input_path']
         output_path = self.params['output_path']
-        
+
         # Update progress
         self.run.set_progress(0, 100, 'preprocessing')
-        
+
         # Your implementation here
         result = self.process_data(input_path, output_path)
-        
+
         # Record metrics
         self.run.set_metrics({
             'throughput': result['throughput'],
             'items_processed': result['count']
         }, 'performance')
-        
+
         self.run.log_message("Action completed successfully")
         return result
-    
+
     def process_data(self, input_path, output_path):
         """Implement category-specific logic."""
         raise NotImplementedError("Subclasses must implement process_data")
@@ -221,7 +221,7 @@ from synapse_sdk.plugins.categories.my_category import MyAction as BaseMyAction
 
 class MyAction(BaseMyAction):
     """Custom implementation of my_action."""
-    
+
     def process_data(self, input_path, output_path):
         """Custom data processing logic."""
         # Plugin developer implements this
@@ -266,32 +266,29 @@ class UploadAction(Action):
     category = PluginCategory.UPLOAD
     method = RunMethod.JOB
     run_class = UploadRun
-    
+
     def start(self):
         # Comprehensive upload workflow
         storage_id = self.params.get('storage')
         path = self.params.get('path')
-        
+
         # Setup and validation
         storage = self.client.get_storage(storage_id)
         pathlib_cwd = get_pathlib(storage, path)
-        
+
         # Excel metadata processing
         excel_metadata = self._read_excel_metadata(pathlib_cwd)
-        
+
         # File organization and upload
         file_specification = self._analyze_collection()
         organized_files = self._organize_files(pathlib_cwd, file_specification, excel_metadata)
-        
-        # Async or sync upload based on configuration
-        if self.params.get('use_async_upload', False):
-            uploaded_files = self.run_async(self._upload_files_async(organized_files, 10))
-        else:
-            uploaded_files = self._upload_files(organized_files)
-        
+
+        # Upload files
+        uploaded_files = self._upload_files(organized_files)
+
         # Data unit generation
         generated_data_units = self._generate_data_units(uploaded_files, batch_size)
-        
+
         return {
             'uploaded_files_count': len(uploaded_files),
             'generated_data_units_count': len(generated_data_units)
@@ -302,6 +299,414 @@ class UploadAction(Action):
 
 For complex actions that require multiple components, follow the modular structure pattern established by the refactored upload action. This approach improves maintainability, testability, and code organization.
 
+## Complex Action Refactoring Patterns
+
+### Overview
+
+As plugin actions evolve and grow in complexity, they often become monolithic files with 900+ lines containing multiple responsibilities. The SYN-5398 UploadAction refactoring demonstrates how to break down complex actions using **Strategy** and **Facade** design patterns, transforming a 1,600+ line monolithic implementation into a maintainable, testable architecture.
+
+### When to Apply Complex Refactoring
+
+Consider refactoring when your action exhibits:
+
+- **Size**: 900+ lines in a single method or file
+- **Multiple Responsibilities**: Handling validation, file processing, uploads, metadata extraction in one method
+- **Conditional Complexity**: Multiple if/else branches for different processing strategies
+- **Testing Difficulty**: Hard to unit test individual components
+- **Maintenance Issues**: Changes require touching multiple unrelated sections
+
+### Strategy Pattern for Pluggable Behaviors
+
+The Strategy pattern allows you to define a family of algorithms, encapsulate each one, and make them interchangeable. This is ideal for actions that need different implementations of the same behavior.
+
+#### Core Strategy Types
+
+Based on the UploadAction refactoring, identify these key strategy categories:
+
+```python
+# 1. ValidationStrategy - Parameter and environment validation
+class ValidationStrategy(ABC):
+    @abstractmethod
+    def validate(self, context: ActionContext) -> ValidationResult:
+        """Validate parameters and environment."""
+        pass
+
+class UploadValidationStrategy(ValidationStrategy):
+    def validate(self, context: ActionContext) -> ValidationResult:
+        # Validate storage, collection, file paths
+        return ValidationResult(is_valid=True, errors=[])
+
+# 2. FileDiscoveryStrategy - Different file discovery methods
+class FileDiscoveryStrategy(ABC):
+    @abstractmethod
+    def discover_files(self, context: ActionContext) -> List[Path]:
+        """Discover files to process."""
+        pass
+
+class RecursiveFileDiscoveryStrategy(FileDiscoveryStrategy):
+    def discover_files(self, context: ActionContext) -> List[Path]:
+        # Recursive directory traversal
+        return list(context.base_path.rglob("*"))
+
+# 3. MetadataStrategy - Various metadata extraction approaches
+class MetadataStrategy(ABC):
+    @abstractmethod
+    def extract_metadata(self, files: List[Path], context: ActionContext) -> Dict:
+        """Extract metadata from files."""
+        pass
+
+class ExcelMetadataStrategy(MetadataStrategy):
+    def extract_metadata(self, files: List[Path], context: ActionContext) -> Dict:
+        # Excel-specific metadata extraction
+        return {"excel_sheets": [], "total_rows": 0}
+
+# 4. UploadStrategy - Different upload implementations
+class UploadStrategy(ABC):
+    @abstractmethod
+    def upload_files(self, files: List[Path], context: ActionContext) -> List[UploadResult]:
+        """Upload files using specific strategy."""
+        pass
+
+class StandardUploadStrategy(UploadStrategy):
+    def upload_files(self, files: List[Path], context: ActionContext) -> List[UploadResult]:
+        # Standard upload implementation
+        return [self._upload_single(f) for f in files]
+
+# 5. DataUnitStrategy - Different data unit generation methods
+class DataUnitStrategy(ABC):
+    @abstractmethod
+    def generate_data_units(self, uploaded_files: List[UploadResult], context: ActionContext) -> List[DataUnit]:
+        """Generate data units from uploaded files."""
+        pass
+
+class StandardDataUnitStrategy(DataUnitStrategy):
+    def generate_data_units(self, uploaded_files: List[UploadResult], context: ActionContext) -> List[DataUnit]:
+        # Standard data unit creation
+        return [DataUnit(file=file) for file in uploaded_files]
+```
+
+#### Strategy Factory Pattern
+
+Use a factory to create appropriate strategies based on configuration:
+
+```python
+class StrategyFactory:
+    """Factory for creating action strategies based on context."""
+
+    @staticmethod
+    def create_validation_strategy(context: ActionContext) -> ValidationStrategy:
+        if context.params.get('strict_validation', False):
+            return StrictValidationStrategy()
+        return StandardValidationStrategy()
+
+    @staticmethod
+    def create_upload_strategy(context: ActionContext) -> UploadStrategy:
+        return StandardUploadStrategy()
+
+    @staticmethod
+    def create_file_discovery_strategy(context: ActionContext) -> FileDiscoveryStrategy:
+        if context.params.get('is_recursive', False):
+            return RecursiveFileDiscoveryStrategy()
+        return FlatFileDiscoveryStrategy()
+```
+
+### Facade Pattern with Orchestrator
+
+The Facade pattern provides a simplified interface to a complex subsystem. The **Orchestrator** coordinates all strategies through a step-based workflow.
+
+#### Orchestrator Implementation
+
+```python
+class UploadOrchestrator:
+    """Facade that orchestrates the complete upload workflow."""
+
+    def __init__(self, context: ActionContext):
+        self.context = context
+        self.factory = StrategyFactory()
+        self.steps_completed = []
+
+        # Initialize strategies
+        self.validation_strategy = self.factory.create_validation_strategy(context)
+        self.file_discovery_strategy = self.factory.create_file_discovery_strategy(context)
+        self.metadata_strategy = self.factory.create_metadata_strategy(context)
+        self.upload_strategy = self.factory.create_upload_strategy(context)
+        self.data_unit_strategy = self.factory.create_data_unit_strategy(context)
+
+    def execute_workflow(self) -> UploadResult:
+        """Execute the complete upload workflow with rollback support."""
+        try:
+            # Step 1: Setup and validation
+            self._execute_step("setup_validation", self._setup_and_validate)
+
+            # Step 2: File discovery
+            files = self._execute_step("file_discovery", self._discover_files)
+
+            # Step 3: Excel metadata extraction
+            metadata = self._execute_step("metadata_extraction",
+                                              lambda: self._extract_metadata(files))
+
+            # Step 4: File organization
+            organized_files = self._execute_step("file_organization",
+                                                     lambda: self._organize_files(files, metadata))
+
+            # Step 5: File upload
+            uploaded_files = self._execute_step("file_upload",
+                                                    lambda: self._upload_files(organized_files))
+
+            # Step 6: Data unit generation
+            data_units = self._execute_step("data_unit_generation",
+                                                lambda: self._generate_data_units(uploaded_files))
+
+            # Step 7: Cleanup
+            self._execute_step("cleanup", self._cleanup_temp_files)
+
+            # Step 8: Result aggregation
+            return self._execute_step("result_aggregation",
+                                          lambda: self._aggregate_results(uploaded_files, data_units))
+
+        except Exception as e:
+            self._rollback_completed_steps()
+            raise UploadOrchestrationError(f"Workflow failed at step {len(self.steps_completed)}: {e}")
+
+    def _execute_step(self, step_name: str, step_func: callable):
+        """Execute a workflow step with error handling and progress tracking."""
+        self.context.logger.log_message_with_code(LogCode.STEP_STARTED, step_name)
+
+        try:
+            result = step_func()
+            self.steps_completed.append(step_name)
+            self.context.logger.log_message_with_code(LogCode.STEP_COMPLETED, step_name)
+            return result
+        except Exception as e:
+            self.context.logger.log_message_with_code(LogCode.STEP_FAILED, step_name, str(e))
+            raise
+
+    def _setup_and_validate(self):
+        """Step 1: Setup and validation using strategy."""
+        validation_result = self.validation_strategy.validate(self.context)
+        if not validation_result.is_valid:
+            raise ValidationError(f"Validation failed: {validation_result.errors}")
+
+    def _discover_files(self) -> List[Path]:
+        """Step 2: File discovery using strategy."""
+        return self.file_discovery_strategy.discover_files(self.context)
+
+    def _extract_metadata(self, files: List[Path]) -> Dict:
+        """Step 3: Metadata extraction using strategy."""
+        return self.metadata_strategy.extract_metadata(files, self.context)
+
+    def _upload_files(self, files: List[Path]) -> List[UploadResult]:
+        """Step 5: File upload using strategy."""
+        return self.upload_strategy.upload_files(files, self.context)
+
+    def _generate_data_units(self, uploaded_files: List[UploadResult]) -> List[DataUnit]:
+        """Step 6: Data unit generation using strategy."""
+        return self.data_unit_strategy.generate_data_units(uploaded_files, self.context)
+
+    def _rollback_completed_steps(self):
+        """Rollback completed steps in reverse order."""
+        for step in reversed(self.steps_completed):
+            try:
+                rollback_method = getattr(self, f"_rollback_{step}", None)
+                if rollback_method:
+                    rollback_method()
+            except Exception as e:
+                self.context.logger.log_message_with_code(LogCode.ROLLBACK_FAILED, step, str(e))
+```
+
+#### Transformed Action Implementation
+
+The main action becomes dramatically simplified:
+
+```python
+# Before: 900+ line monolithic start() method
+class UploadAction(Action):
+    def start(self):
+        # 900+ lines of mixed responsibilities...
+
+# After: Clean, orchestrated implementation (196 lines total)
+class UploadAction(Action):
+    """Upload action using Strategy and Facade patterns."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.context = ActionContext(
+            params=self.params,
+            client=self.client,
+            logger=self.run,
+            workspace=self.get_workspace_path()
+        )
+
+    def start(self) -> UploadResult:
+        """Main action execution using orchestrator facade."""
+        self.run.log_message_with_code(LogCode.UPLOAD_STARTED)
+
+        try:
+            # Create and execute orchestrator
+            orchestrator = UploadOrchestrator(self.context)
+            result = orchestrator.execute_workflow()
+
+            self.run.log_message_with_code(LogCode.UPLOAD_COMPLETED,
+                                         result.uploaded_files_count, result.data_units_count)
+            return result
+
+        except Exception as e:
+            self.run.log_message_with_code(LogCode.UPLOAD_FAILED, str(e))
+            raise ActionError(f"Upload action failed: {e}")
+```
+
+### Context Management
+
+Use a shared context object to pass state between strategies and orchestrator:
+
+```python
+@dataclass
+class ActionContext:
+    """Shared context for action execution."""
+    params: Dict[str, Any]
+    client: Any
+    logger: Any
+    workspace: Path
+    temp_files: List[Path] = field(default_factory=list)
+    metrics: Dict[str, Any] = field(default_factory=dict)
+
+    def add_temp_file(self, file_path: Path):
+        """Track temporary files for cleanup."""
+        self.temp_files.append(file_path)
+
+    def update_metrics(self, category: str, metrics: Dict[str, Any]):
+        """Update execution metrics."""
+        if category not in self.metrics:
+            self.metrics[category] = {}
+        self.metrics[category].update(metrics)
+```
+
+### Migration Guide for Complex Actions
+
+#### Step 1: Identify Strategy Boundaries
+
+Analyze your monolithic action to identify:
+
+1. **Different algorithms** for the same operation (validation methods, file processing approaches)
+2. **Configurable behaviors** that change based on parameters
+3. **Testable units** that can be isolated
+
+#### Step 2: Extract Strategies
+
+```python
+# Before: Mixed responsibilities in one method
+def start(self):
+    # validation logic (100 lines)
+    if self.params.get('strict_mode'):
+        # strict validation
+    else:
+        # standard validation
+
+    # file discovery logic (150 lines)
+    if self.params.get('recursive'):
+        # recursive discovery
+    else:
+        # flat discovery
+
+    # upload logic (200 lines)
+    # Direct upload implementation
+    uploaded_files = self._upload_files(organized_files)
+
+# After: Separated into strategies
+class StrictValidationStrategy(ValidationStrategy): ...
+class StandardValidationStrategy(ValidationStrategy): ...
+class RecursiveFileDiscoveryStrategy(FileDiscoveryStrategy): ...
+class StandardUploadStrategy(UploadStrategy): ...
+```
+
+#### Step 3: Create Orchestrator
+
+Design your workflow steps:
+
+1. Define clear step boundaries
+2. Implement rollback for each step
+3. Add progress tracking and logging
+4. Handle errors gracefully
+
+#### Step 4: Update Action Class
+
+Transform the main action to use the orchestrator:
+
+1. Create context object
+2. Initialize orchestrator
+3. Execute workflow
+4. Handle results and errors
+
+### Benefits and Metrics
+
+The SYN-5398 refactoring achieved:
+
+#### **Code Reduction**
+
+- Main action: 900+ lines → 196 lines (-78% reduction)
+- Total codebase: 1,600+ lines → 1,400+ lines (better organized)
+- Cyclomatic complexity: High → Low (single responsibility per class)
+
+#### **Improved Testability**
+
+- **89 passing tests** with individual strategy testing
+- **Isolated unit tests** for each strategy component
+- **Integration tests** for orchestrator workflow
+- **Rollback testing** for error scenarios
+
+#### **Better Maintainability**
+
+- **Single responsibility** per strategy class
+- **Clear separation** of concerns
+- **Reusable strategies** across different actions
+- **Easy to extend** with new strategy implementations
+
+#### **Enhanced Flexibility**
+
+- **Runtime strategy selection** based on parameters
+- **Pluggable algorithms** without changing core logic
+- **Configuration-driven** behavior changes
+- **A/B testing support** through strategy switching
+
+### Example: Converting a Complex Action
+
+```python
+# Before: Monolithic action (simplified example)
+class ComplexAction(Action):
+    def start(self):
+        # 50 lines of validation
+        if self.params.get('validation_type') == 'strict':
+            # strict validation logic
+        else:
+            # standard validation logic
+
+        # 100 lines of data processing
+        if self.params.get('processing_method') == 'batch':
+            # batch processing logic
+        else:
+            # stream processing logic
+
+        # 80 lines of output generation
+        if self.params.get('output_format') == 'json':
+            # JSON output logic
+        else:
+            # CSV output logic
+
+# After: Strategy-based action
+class ComplexAction(Action):
+    def start(self):
+        context = ActionContext(params=self.params, logger=self.run)
+        orchestrator = ComplexActionOrchestrator(context)
+        return orchestrator.execute_workflow()
+
+# Individual strategies (testable, reusable)
+class StrictValidationStrategy(ValidationStrategy): ...
+class BatchProcessingStrategy(ProcessingStrategy): ...
+class JSONOutputStrategy(OutputStrategy): ...
+```
+
+This pattern transformation makes complex actions maintainable, testable, and extensible while preserving all original functionality.
+
 ### Recommended File Structure
 
 ```
@@ -333,7 +738,7 @@ from .utils import ExcelSecurityConfig, PathAwareJSONEncoder
 
 __all__ = [
     'UploadAction',
-    'UploadRun', 
+    'UploadRun',
     'UploadParams',
     'UploadStatus',
     'LogCode',
@@ -359,27 +764,27 @@ from .run import UploadRun
 
 class UploadAction(Action):
     """Main upload action implementation."""
-    
+
     name = 'upload'
     category = PluginCategory.UPLOAD
     method = RunMethod.JOB
     run_class = UploadRun
     params_model = UploadParams
-    
+
     def start(self):
         """Main action logic."""
         # Validate parameters
         self.validate_params()
-        
+
         # Log start
         self.run.log_message_with_code(LogCode.UPLOAD_STARTED)
-        
+
         # Execute main logic
         result = self._process_upload()
-        
+
         # Log completion
         self.run.log_message_with_code(LogCode.UPLOAD_COMPLETED)
-        
+
         return result
 ```
 
@@ -394,7 +799,7 @@ from synapse_sdk.utils.pydantic.validators import non_blank
 
 class UploadParams(BaseModel):
     """Upload action parameters with validation."""
-    
+
     name: Annotated[str, AfterValidator(non_blank)]
     description: str | None = None
     path: str
@@ -403,8 +808,7 @@ class UploadParams(BaseModel):
     project: int | None = None
     is_recursive: bool = False
     max_file_size_mb: int = 50
-    use_async_upload: bool = True
-    
+
     @field_validator('storage', mode='before')
     @classmethod
     def check_storage_exists(cls, value: str, info) -> str:
@@ -467,19 +871,19 @@ from .enums import LogCode, LOG_MESSAGES
 
 class UploadRun(Run):
     """Specialized run management for upload actions."""
-    
+
     def log_message_with_code(self, code: LogCode, *args, level: Optional[Context] = None):
         """Type-safe logging with predefined messages."""
         if code not in LOG_MESSAGES:
             self.log_message(f'Unknown log code: {code}')
             return
-        
+
         log_config = LOG_MESSAGES[code]
         message = log_config['message'].format(*args) if args else log_config['message']
         log_level = level or log_config['level']
-        
+
         self.log_message(message, context=log_level.value)
-    
+
     def log_upload_event(self, code: LogCode, *args, level: Optional[Context] = None):
         """Log upload-specific events with metrics."""
         self.log_message_with_code(code, *args, level)
@@ -515,7 +919,7 @@ from pathlib import Path
 
 class PathAwareJSONEncoder(json.JSONEncoder):
     """JSON encoder that handles Path objects."""
-    
+
     def default(self, obj):
         if hasattr(obj, '__fspath__') or hasattr(obj, 'as_posix'):
             return str(obj)
@@ -525,7 +929,7 @@ class PathAwareJSONEncoder(json.JSONEncoder):
 
 class ExcelSecurityConfig:
     """Configuration for Excel file security limits."""
-    
+
     def __init__(self):
         self.MAX_FILE_SIZE_MB = int(os.getenv('EXCEL_MAX_FILE_SIZE_MB', '10'))
         self.MAX_ROWS = int(os.getenv('EXCEL_MAX_ROWS', '10000'))
@@ -548,7 +952,7 @@ class ExcelSecurityConfig:
 # Before: Single upload.py file (1362 lines)
 class UploadAction(Action):
     # All code in one file...
-    
+
 # After: Modular structure
 # action.py - Main logic (546 lines)
 # models.py - Parameter validation (98 lines)
@@ -591,11 +995,11 @@ class UploadRun(Run):
         if code not in LOG_MESSAGES:
             self.log_message(f'Unknown log code: {code}')
             return
-        
+
         log_config = LOG_MESSAGES[code]
         message = log_config['message'].format(*args) if args else log_config['message']
         log_level = level or log_config['level'] or Context.INFO
-        
+
         if log_level == Context.INFO.value:
             self.log_message(message, context=log_level.value)
         else:
@@ -678,7 +1082,7 @@ class MyAction(Action):
             'description': 'Evaluating results'
         }
     }
-    
+
     def start(self):
         # Update specific progress categories
         self.run.set_progress(50, 100, 'data_loading')
@@ -691,26 +1095,26 @@ class MyAction(Action):
 def get_runtime_env(self):
     """Customize execution environment."""
     env = super().get_runtime_env()
-    
+
     # Add custom packages
     env['pip']['packages'].extend([
         'custom-ml-library==2.0.0',
         'specialized-tool>=1.5.0'
     ])
-    
+
     # Set environment variables
     env['env_vars'].update({
         'CUDA_VISIBLE_DEVICES': '0,1',
         'OMP_NUM_THREADS': '8',
         'CUSTOM_CONFIG_PATH': '/app/config'
     })
-    
+
     # Add working directory files
     env['working_dir_files'] = {
         'config.yaml': 'path/to/local/config.yaml',
         'model_weights.pth': 'path/to/weights.pth'
     }
-    
+
     return env
 ```
 
@@ -722,27 +1126,27 @@ from typing import Literal, Optional, List
 
 class AdvancedParams(BaseModel):
     """Advanced parameter validation."""
-    
+
     # Enum-like validation
     model_type: Literal["cnn", "transformer", "resnet"]
-    
+
     # Range validation
     learning_rate: float = Field(gt=0, le=1, default=0.001)
     batch_size: int = Field(ge=1, le=1024, default=32)
-    
+
     # File path validation
     data_path: str
     output_path: Optional[str] = None
-    
+
     # Complex validation
     layers: List[int] = Field(min_items=1, max_items=10)
-    
+
     @validator('data_path')
     def validate_data_path(cls, v):
         if not os.path.exists(v):
             raise ValueError(f'Data path does not exist: {v}')
         return v
-    
+
     @validator('output_path')
     def validate_output_path(cls, v, values):
         if v is None:
@@ -750,7 +1154,7 @@ class AdvancedParams(BaseModel):
             data_path = values.get('data_path', '')
             return f"{data_path}_output"
         return v
-    
+
     @validator('layers')
     def validate_layers(cls, v):
         if len(v) < 2:
@@ -779,11 +1183,11 @@ class UploadAction(Action):
         files = self._discover_files()
         processed_files = self._process_files(files)
         return self._generate_output(processed_files)
-    
+
     def _validate_inputs(self):
         """Separate validation logic."""
         pass
-    
+
     def _discover_files(self):
         """Separate file discovery logic."""
         pass
@@ -796,11 +1200,11 @@ class LogCode(str, Enum):
 # Good: Type hints and documentation
 def process_batch(self, items: List[Dict[str, Any]], batch_size: int = 100) -> List[Dict[str, Any]]:
     """Process items in batches for memory efficiency.
-    
+
     Args:
         items: List of items to process
         batch_size: Number of items per batch
-        
+
     Returns:
         List of processed items
     """
@@ -809,16 +1213,13 @@ def process_batch(self, items: List[Dict[str, Any]], batch_size: int = 100) -> L
 ### 3. Performance Optimization
 
 ```python
-# Use async for I/O-bound operations
-async def _upload_files_async(self, files: List[Path], max_concurrent: int = 10):
-    semaphore = asyncio.Semaphore(max_concurrent)
-    
-    async def upload_single_file(file_path):
-        async with semaphore:
-            return await self._upload_file(file_path)
-    
-    tasks = [upload_single_file(f) for f in files]
-    return await asyncio.gather(*tasks, return_exceptions=True)
+# Use simple sequential processing for file uploads
+def _upload_files(self, files: List[Path]) -> List[UploadResult]:
+    results = []
+    for file_path in files:
+        result = self._upload_file(file_path)
+        results.append(result)
+    return results
 
 # Use generators for memory efficiency
 def _process_large_dataset(self, data_source):
@@ -826,7 +1227,7 @@ def _process_large_dataset(self, data_source):
     for chunk in self._chunk_data(data_source, chunk_size=1000):
         processed_chunk = self._process_chunk(chunk)
         yield processed_chunk
-        
+
         # Update progress
         self.run.set_progress(self.processed_count, self.total_count, 'processing')
 ```
@@ -858,11 +1259,11 @@ class MyAction(Action):
 def _validate_file_path(self, file_path: str) -> Path:
     """Validate and sanitize file paths."""
     path = Path(file_path).resolve()
-    
+
     # Prevent directory traversal
     if not str(path).startswith(str(self.workspace_root)):
         raise ActionError(f"File path outside workspace: {path}")
-    
+
     return path
 
 # Good: Sanitize user inputs
@@ -886,27 +1287,33 @@ def _validate_data_size(self, data: bytes) -> None:
 ### Core Classes
 
 #### Action
+
 Base class for all plugin actions.
 
 **Methods:**
+
 - `start()`: Main execution method (abstract)
 - `run_action()`: Execute action with error handling
 - `get_runtime_env()`: Get execution environment configuration
 - `validate_params()`: Validate action parameters
 
 #### Run
+
 Manages action execution lifecycle.
 
 **Methods:**
+
 - `log_message(message, context)`: Log execution messages
 - `set_progress(current, total, category)`: Update progress
 - `set_metrics(metrics, category)`: Record metrics
 - `log(log_type, data)`: Structured logging
 
 #### PluginRelease
+
 Manages plugin metadata and configuration.
 
 **Attributes:**
+
 - `code`: Plugin identifier
 - `name`: Human-readable name
 - `version`: Semantic version
@@ -930,4 +1337,4 @@ config = load_plugin_config("/path/to/plugin")
 is_valid = validate_plugin("/path/to/plugin")
 ```
 
-This README provides the foundation for developing and extending the Synapse SDK plugin system. For specific implementation examples, refer to the existing plugin categories and their respective documentation.
+This README provides the foundation for developing and extending the Synapse SDK plugin system. For specific implementation examples, refer to the existing plugin categories and their respective documentation.