synapse-sdk 1.0.0b21__py3-none-any.whl → 1.0.0b23__py3-none-any.whl

synapse_sdk/plugins/README.md

@@ -0,0 +1,934 @@
+# Synapse SDK Plugin System - Developer Reference
+
+This document provides comprehensive guidance for developers working on the Synapse SDK plugin system architecture, internal APIs, and core infrastructure.
+
+## Overview
+
+The Synapse SDK plugin system is a modular framework that enables distributed execution of ML operations across different categories and execution methods. The system is built around the concept of **actions** - discrete operations that can be packaged, distributed, and executed in various environments.
+
+### Architecture
+
+```
+synapse_sdk/plugins/
+├── categories/           # Plugin category implementations
+│   ├── base.py          # Action base class
+│   ├── decorators.py    # Registration decorators
+│   ├── registry.py      # Action registry
+│   ├── neural_net/      # Neural network actions
+│   ├── export/          # Data export actions
+│   ├── upload/          # File upload actions
+│   ├── smart_tool/      # AI-powered tools
+│   ├── pre_annotation/  # Pre-processing actions
+│   ├── post_annotation/ # Post-processing actions
+│   └── data_validation/ # Validation actions
+├── templates/           # Cookiecutter templates
+├── utils/              # Utility functions
+├── models.py           # Core plugin models
+├── enums.py            # Plugin enums
+└── exceptions.py       # Plugin exceptions
+```
+
+### Key Features
+
+- **🔌 Modular Architecture**: Self-contained plugins with isolated dependencies
+- **⚡ Multiple Execution Methods**: Jobs, Tasks, and REST API endpoints
+- **📦 Distributed Execution**: Ray-based scalable computing
+- **🛠️ Template System**: Cookiecutter-based scaffolding
+- **📊 Progress Tracking**: Built-in logging, metrics, and progress monitoring
+- **🔄 Dynamic Loading**: Runtime plugin discovery and registration
+
+## Core Components
+
+### Action Base Class
+
+The `Action` class (`synapse_sdk/plugins/categories/base.py`) provides the unified interface for all plugin actions:
+
+```python
+class Action:
+    """Base class for all plugin actions.
+    
+    Class Variables:
+        name (str): Action identifier
+        category (PluginCategory): Plugin category
+        method (RunMethod): Execution method
+        run_class (Run): Run management class
+        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
+        plugin_release (PluginRelease): Plugin metadata
+        client: Backend API client
+        run (Run): Execution instance
+    """
+    
+    # Class configuration
+    name = None
+    category = None
+    method = None
+    run_class = Run
+    params_model = None
+    progress_categories = None
+    metrics_categories = None
+    
+    def start(self):
+        """Main action logic - implement in subclasses."""
+        raise NotImplementedError
+```
+
+### Plugin Categories
+
+The system supports seven main categories defined in `enums.py`:
+
+```python
+class PluginCategory(Enum):
+    NEURAL_NET = 'neural_net'          # ML training and inference
+    EXPORT = 'export'                  # Data export operations
+    UPLOAD = 'upload'                  # File upload functionality
+    SMART_TOOL = 'smart_tool'          # AI-powered automation
+    POST_ANNOTATION = 'post_annotation' # Post-processing
+    PRE_ANNOTATION = 'pre_annotation'   # Pre-processing
+    DATA_VALIDATION = 'data_validation' # Quality checks
+```
+
+### Execution Methods
+
+Three execution methods are supported:
+
+```python
+class RunMethod(Enum):
+    JOB = 'job'        # Long-running distributed tasks
+    TASK = 'task'      # Simple operations
+    RESTAPI = 'restapi' # HTTP endpoints
+```
+
+### Run Management
+
+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."""
+```
+
+## Creating Plugin Categories
+
+### 1. Define Category Structure
+
+Create a new category directory:
+
+```
+synapse_sdk/plugins/categories/my_category/
+├── __init__.py
+├── actions/
+│   ├── __init__.py
+│   └── my_action.py
+└── templates/
+    └── plugin/
+        ├── __init__.py
+        └── my_action.py
+```
+
+### 2. Implement Base Action
+
+```python
+# synapse_sdk/plugins/categories/my_category/actions/my_action.py
+from synapse_sdk.plugins.categories.base import Action
+from synapse_sdk.plugins.categories.decorators import register_action
+from synapse_sdk.plugins.enums import PluginCategory, RunMethod
+from pydantic import BaseModel
+
+class MyActionParams(BaseModel):
+    """Parameter model for validation."""
+    input_path: str
+    output_path: str
+    config: dict = {}
+
+@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,
+            'latency': 0,
+            '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")
+```
+
+### 3. Create Template
+
+```python
+# synapse_sdk/plugins/categories/my_category/templates/plugin/my_action.py
+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
+        return {"status": "success", "items_processed": 100}
+```
+
+### 4. Register Category
+
+Update `enums.py`:
+
+```python
+class PluginCategory(Enum):
+    # ... existing categories
+    MY_CATEGORY = 'my_category'
+```
+
+## Action Implementation Examples
+
+### Upload Action Architecture
+
+The upload action demonstrates modular action architecture:
+
+```
+# Structure after SYN-5306 refactoring
+synapse_sdk/plugins/categories/upload/actions/upload/
+├── __init__.py      # Public API exports
+├── action.py        # Main UploadAction class
+├── run.py          # UploadRun execution management
+├── models.py       # UploadParams validation
+├── enums.py        # LogCode and LOG_MESSAGES
+├── exceptions.py   # Custom exceptions
+└── utils.py        # Utility classes
+```
+
+**Key Implementation Details:**
+
+```python
+# upload/action.py
+@register_action
+class UploadAction(Action):
+    name = 'upload'
+    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)
+        
+        # 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)
+        }
+```
+
+## Plugin Action Structure Guidelines
+
+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.
+
+### Recommended File Structure
+
+```
+synapse_sdk/plugins/categories/{category}/actions/{action}/
+├── __init__.py          # Public API exports
+├── action.py            # Main action implementation
+├── run.py               # Execution and logging management
+├── models.py            # Pydantic parameter models
+├── enums.py             # Enums and message constants
+├── exceptions.py        # Custom exception classes
+├── utils.py             # Helper utilities and configurations
+└── README.md            # Action-specific documentation
+```
+
+### Module Responsibilities
+
+#### 1. `__init__.py` - Public API
+
+Defines the public interface and maintains backward compatibility:
+
+```python
+# Export all public classes for backward compatibility
+from .action import UploadAction
+from .enums import LogCode, LOG_MESSAGES, UploadStatus
+from .exceptions import ExcelParsingError, ExcelSecurityError
+from .models import UploadParams
+from .run import UploadRun
+from .utils import ExcelMetadataUtils, ExcelSecurityConfig, PathAwareJSONEncoder
+
+__all__ = [
+    'UploadAction',
+    'UploadRun', 
+    'UploadParams',
+    'UploadStatus',
+    'LogCode',
+    'LOG_MESSAGES',
+    'ExcelSecurityError',
+    'ExcelParsingError',
+    'PathAwareJSONEncoder',
+    'ExcelSecurityConfig',
+    'ExcelMetadataUtils',
+]
+```
+
+#### 2. `action.py` - Main Implementation
+
+Contains the core action logic, inheriting from the base `Action` class:
+
+```python
+from synapse_sdk.plugins.categories.base import Action
+from synapse_sdk.plugins.enums import PluginCategory, RunMethod
+
+from .enums import LogCode
+from .models import UploadParams
+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
+```
+
+#### 3. `models.py` - Parameter Validation
+
+Defines Pydantic models for type-safe parameter validation:
+
+```python
+from typing import Annotated
+from pydantic import AfterValidator, BaseModel, field_validator
+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
+    storage: int
+    collection: int
+    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:
+        """Validate storage exists via API."""
+        action = info.context['action']
+        client = action.client
+        try:
+            client.get_storage(value)
+        except ClientError:
+            raise PydanticCustomError('client_error', 'Storage not found')
+        return value
+```
+
+#### 4. `enums.py` - Constants and Enums
+
+Centralizes all enum definitions and constant values:
+
+```python
+from enum import Enum
+from synapse_sdk.plugins.enums import Context
+
+class UploadStatus(str, Enum):
+    """Upload processing status."""
+    PENDING = 'pending'
+    PROCESSING = 'processing'
+    COMPLETED = 'completed'
+    FAILED = 'failed'
+
+class LogCode(str, Enum):
+    """Type-safe logging codes."""
+    UPLOAD_STARTED = 'UPLOAD_STARTED'
+    VALIDATION_FAILED = 'VALIDATION_FAILED'
+    NO_FILES_FOUND = 'NO_FILES_FOUND'
+    UPLOAD_COMPLETED = 'UPLOAD_COMPLETED'
+    # ... additional codes
+
+LOG_MESSAGES = {
+    LogCode.UPLOAD_STARTED: {
+        'message': 'Upload process started.',
+        'level': Context.INFO,
+    },
+    LogCode.VALIDATION_FAILED: {
+        'message': 'Validation failed: {}',
+        'level': Context.DANGER,
+    },
+    # ... message configurations
+}
+```
+
+#### 5. `run.py` - Execution Management
+
+Handles execution flow, progress tracking, and specialized logging:
+
+```python
+from typing import Optional
+from synapse_sdk.plugins.models import Run
+from synapse_sdk.plugins.enums import Context
+
+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)
+        # Additional upload-specific logging logic
+```
+
+#### 6. `exceptions.py` - Custom Exceptions
+
+Defines action-specific exception classes:
+
+```python
+class ExcelSecurityError(Exception):
+    """Raised when Excel file security validation fails."""
+    pass
+
+class ExcelParsingError(Exception):
+    """Raised when Excel file parsing encounters errors."""
+    pass
+
+class UploadValidationError(Exception):
+    """Raised when upload parameter validation fails."""
+    pass
+```
+
+#### 7. `utils.py` - Helper Utilities
+
+Contains utility classes and helper functions:
+
+```python
+import json
+import os
+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)
+        elif hasattr(obj, 'isoformat'):
+            return obj.isoformat()
+        return super().default(obj)
+
+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'))
+        self.MAX_COLUMNS = int(os.getenv('EXCEL_MAX_COLUMNS', '50'))
+```
+
+### Migration Guide
+
+#### From Monolithic to Modular Structure
+
+1. **Identify Components**: Break down the monolithic action into logical components
+2. **Extract Models**: Move parameter validation to `models.py`
+3. **Separate Enums**: Move constants and enums to `enums.py`
+4. **Create Utilities**: Extract helper functions to `utils.py`
+5. **Update Imports**: Ensure backward compatibility through `__init__.py`
+
+#### Example Migration Steps
+
+```python
+# 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)
+# enums.py - Constants and logging codes (156 lines)
+# run.py - Execution management (134 lines)
+# utils.py - Helper utilities (89 lines)
+# exceptions.py - Custom exceptions (6 lines)
+# __init__.py - Public API (20 lines)
+```
+
+### Benefits of Modular Structure
+
+- **Maintainability**: Each file has a single responsibility
+- **Testability**: Individual components can be tested in isolation
+- **Reusability**: Utilities and models can be shared across actions
+- **Type Safety**: Enum-based logging and strong parameter validation
+- **Backward Compatibility**: Public API remains unchanged
+
+**Logging System with Enums:**
+
+```python
+# upload/enums.py
+class LogCode(str, Enum):
+    VALIDATION_FAILED = 'VALIDATION_FAILED'
+    NO_FILES_FOUND = 'NO_FILES_FOUND'
+    # ... 36 total log codes
+
+LOG_MESSAGES = {
+    LogCode.VALIDATION_FAILED: {
+        'message': 'Validation failed.',
+        'level': Context.DANGER,
+    },
+    # ... message configurations
+}
+
+# upload/run.py
+class UploadRun(Run):
+    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'] or Context.INFO
+        
+        if log_level == Context.INFO.value:
+            self.log_message(message, context=log_level.value)
+        else:
+            self.log_upload_event(code, *args, level)
+```
+
+## Development Workflow
+
+### 1. Local Development Setup
+
+```bash
+# Set up development environment
+cd synapse_sdk/plugins/categories/my_category
+python -m pip install -e .
+
+# Create test plugin
+synapse plugin create --category my_category --debug
+```
+
+### 2. Action Testing
+
+```python
+# Test action implementation
+from synapse_sdk.plugins.utils import get_action_class
+
+# Get action class
+ActionClass = get_action_class("my_category", "my_action")
+
+# Create test instance
+action = ActionClass(
+    params={"input_path": "/test/data", "output_path": "/test/output"},
+    plugin_config={"debug": True},
+    envs={"TEST_MODE": "true"}
+)
+
+# Run action
+result = action.run_action()
+assert result["status"] == "success"
+```
+
+### 3. Integration Testing
+
+```python
+# Test with Ray backend
+import ray
+from synapse_sdk.clients.ray import RayClient
+
+# Initialize Ray
+ray.init()
+client = RayClient()
+
+# Test distributed execution
+job_result = client.submit_job(
+    entrypoint="python action.py",
+    runtime_env=action.get_runtime_env()
+)
+```
+
+## Advanced Features
+
+### Custom Progress Categories
+
+```python
+class MyAction(Action):
+    progress_categories = {
+        'data_loading': {
+            'proportion': 10,
+            'description': 'Loading input data'
+        },
+        'feature_extraction': {
+            'proportion': 30,
+            'description': 'Extracting features'
+        },
+        'model_training': {
+            'proportion': 50,
+            'description': 'Training model'
+        },
+        'evaluation': {
+            'proportion': 10,
+            'description': 'Evaluating results'
+        }
+    }
+    
+    def start(self):
+        # Update specific progress categories
+        self.run.set_progress(50, 100, 'data_loading')
+        self.run.set_progress(25, 100, 'feature_extraction')
+```
+
+### Runtime Environment Customization
+
+```python
+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
+```
+
+### Parameter Validation Patterns
+
+```python
+from pydantic import BaseModel, validator, Field
+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:
+            # Auto-generate from data_path
+            data_path = values.get('data_path', '')
+            return f"{data_path}_output"
+        return v
+    
+    @validator('layers')
+    def validate_layers(cls, v):
+        if len(v) < 2:
+            raise ValueError('Must specify at least 2 layers')
+        if v[0] <= 0 or v[-1] <= 0:
+            raise ValueError('Input and output layers must be positive')
+        return v
+```
+
+## Best Practices
+
+### 1. Action Design
+
+- **Single Responsibility**: Each action should have one clear purpose
+- **Parameterization**: Make actions configurable through well-defined parameters
+- **Error Handling**: Implement comprehensive error handling and validation
+- **Progress Reporting**: Provide meaningful progress updates for long operations
+
+### 2. Code Organization
+
+```python
+# Good: Modular structure
+class UploadAction(Action):
+    def start(self):
+        self._validate_inputs()
+        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
+
+# Good: Use of enums for constants
+class LogCode(str, Enum):
+    VALIDATION_FAILED = 'VALIDATION_FAILED'
+    FILE_NOT_FOUND = 'FILE_NOT_FOUND'
+
+# 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
+    """
+```
+
+### 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 generators for memory efficiency
+def _process_large_dataset(self, data_source):
+    """Process data in chunks to avoid memory issues."""
+    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')
+```
+
+### 4. Error Handling
+
+```python
+from synapse_sdk.plugins.exceptions import ActionError
+
+class MyAction(Action):
+    def start(self):
+        try:
+            return self._execute_main_logic()
+        except ValidationError as e:
+            self.run.log_message(f"Validation error: {e}", "ERROR")
+            raise ActionError(f"Parameter validation failed: {e}")
+        except FileNotFoundError as e:
+            self.run.log_message(f"File not found: {e}", "ERROR")
+            raise ActionError(f"Required file missing: {e}")
+        except Exception as e:
+            self.run.log_message(f"Unexpected error: {e}", "ERROR")
+            raise ActionError(f"Action execution failed: {e}")
+```
+
+### 5. Security Considerations
+
+```python
+# Good: Validate file paths
+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
+def _sanitize_filename(self, filename: str) -> str:
+    """Remove unsafe characters from filename."""
+    import re
+    # Remove path separators and control characters
+    safe_name = re.sub(r'[<>:"/\\|?*\x00-\x1f]', '_', filename)
+    return safe_name[:255]  # Limit length
+
+# Good: Validate data sizes
+def _validate_data_size(self, data: bytes) -> None:
+    """Check data size limits."""
+    max_size = 100 * 1024 * 1024  # 100MB
+    if len(data) > max_size:
+        raise ActionError(f"Data too large: {len(data)} bytes (max: {max_size})")
+```
+
+## API Reference
+
+### 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
+- `category`: Plugin category
+- `config`: Plugin configuration
+
+### Utility Functions
+
+```python
+# synapse_sdk/plugins/utils/
+from synapse_sdk.plugins.utils import (
+    get_action_class,      # Get action class by category/name
+    load_plugin_config,    # Load plugin configuration
+    validate_plugin,       # Validate plugin structure
+    register_plugin,       # Register plugin in system
+)
+
+# Usage examples
+ActionClass = get_action_class("upload", "upload")
+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.