synapse-sdk 2025.10.5__py3-none-any.whl → 2025.10.6__py3-none-any.whl

synapse_sdk/plugins/categories/neural_net/actions/tune.py

@@ -23,16 +23,86 @@ class TuneRun(TrainRun):
 
 
 class SearchAlgo(BaseModel):
+    """
+    Configuration for Ray Tune search algorithms.
+
+    Supported algorithms:
+        - 'bayesoptsearch': Bayesian optimization using Gaussian Processes
+        - 'hyperoptsearch': Tree-structured Parzen Estimator (TPE)
+        - 'basicvariantgenerator': Random search (default)
+
+    Attributes:
+        name (str): Name of the search algorithm (case-insensitive)
+        points_to_evaluate (Optional[dict]): Optional initial hyperparameter
+            configurations to evaluate before starting optimization
+
+    Example:
+        {
+            "name": "hyperoptsearch",
+            "points_to_evaluate": [
+                {"learning_rate": 0.001, "batch_size": 32}
+            ]
+        }
+    """
+
     name: str
     points_to_evaluate: Optional[dict] = None
 
 
 class Scheduler(BaseModel):
+    """
+    Configuration for Ray Tune schedulers.
+
+    Supported schedulers:
+        - 'fifo': First-In-First-Out scheduler (default, runs all trials)
+        - 'hyperband': HyperBand early stopping scheduler
+
+    Attributes:
+        name (str): Name of the scheduler (case-insensitive)
+        options (Optional[str]): Optional scheduler-specific configuration parameters
+
+    Example:
+        {
+            "name": "hyperband",
+            "options": {
+                "max_t": 100,
+                "reduction_factor": 3
+            }
+        }
+    """
+
     name: str
     options: Optional[str] = None
 
 
 class TuneConfig(BaseModel):
+    """
+    Configuration for Ray Tune hyperparameter optimization.
+
+    Attributes:
+        mode (Optional[str]): Optimization mode - 'max' or 'min'
+        metric (Optional[str]): Name of the metric to optimize
+        num_samples (int): Number of hyperparameter configurations to try (default: 1)
+        max_concurrent_trials (Optional[int]): Maximum number of trials to run in parallel
+        search_alg (Optional[SearchAlgo]): Search algorithm configuration
+        scheduler (Optional[Scheduler]): Trial scheduler configuration
+
+    Example:
+        {
+            "mode": "max",
+            "metric": "accuracy",
+            "num_samples": 20,
+            "max_concurrent_trials": 4,
+            "search_alg": {
+                "name": "hyperoptsearch"
+            },
+            "scheduler": {
+                "name": "hyperband",
+                "options": {"max_t": 100}
+            }
+        }
+    """
+
     mode: Optional[str] = None
     metric: Optional[str] = None
     num_samples: int = 1
@@ -42,10 +112,51 @@ class TuneConfig(BaseModel):
 
 
 class TuneParams(BaseModel):
+    """
+    Parameters for TuneAction (DEPRECATED - use TrainAction with is_tune=True instead).
+
+    Attributes:
+        name (str): Name for the tuning job
+        description (str): Description of the job
+        checkpoint (int | None): Optional checkpoint ID to resume from
+        dataset (int): Dataset ID to use for training
+        hyperparameter (list): Hyperparameter search space
+        tune_config (TuneConfig): Tune configuration
+
+    Hyperparameter format:
+        Each item in hyperparameter list must have:
+        - 'name': Parameter name (string)
+        - 'type': Distribution type (string)
+        - Type-specific parameters:
+            - uniform/quniform: 'min', 'max'
+            - loguniform/qloguniform: 'min', 'max', 'base'
+            - randn/qrandn: 'mean', 'sd'
+            - randint/qrandint: 'min', 'max'
+            - lograndint/qlograndint: 'min', 'max', 'base'
+            - choice/grid_search: 'options'
+
+    Example:
+        {
+            "name": "my_tuning",
+            "dataset": 123,
+            "hyperparameter": [
+                {"name": "batch_size", "type": "choice", "options": [16, 32, 64]},
+                {"name": "learning_rate", "type": "loguniform", "min": 0.0001, "max": 0.01, "base": 10},
+                {"name": "epochs", "type": "randint", "min": 5, "max": 15}
+            ],
+            "tune_config": {
+                "mode": "max",
+                "metric": "accuracy",
+                "num_samples": 10
+            }
+        }
+    """
+
     name: Annotated[str, AfterValidator(non_blank)]
     description: str
     checkpoint: int | None
     dataset: int
+    hyperparameter: list
     tune_config: TuneConfig
 
     @field_validator('name')
@@ -73,6 +184,23 @@ class TuneParams(BaseModel):
 @register_action
 class TuneAction(TrainAction):
     """
+    **DEPRECATED**: This action is deprecated. Please use TrainAction with is_tune=True instead.
+
+    To migrate from tune to train with tuning:
+    - Change action from "tune" to "train"
+    - Add "is_tune": true to params
+    - Keep tune_config and hyperparameter as they are
+
+    Example:
+    {
+      "action": "train",
+      "params": {
+        "is_tune": true,
+        "tune_config": { ... },
+        "hyperparameter": [ ... ]
+      }
+    }
+
     **Must read** Important notes before using Tune:
 
     1. Path to the model output (which is the return value of your train function)
@@ -256,6 +384,10 @@ class TuneAction(TrainAction):
 
         Returns:
             object: Ray Tune scheduler instance.
+
+        Supported schedulers:
+            - 'fifo': FIFOScheduler (default)
+            - 'hyperband': HyperBandScheduler
         """
 
         from ray.tune.schedulers import (
@@ -278,7 +410,12 @@ class TuneAction(TrainAction):
         }
 
         scheduler_type = tune_config['scheduler'].get('name', 'fifo').lower()
-        scheduler_class = scheduler_map.get(scheduler_type, ASHAScheduler)
+        scheduler_class = scheduler_map.get(scheduler_type)
+
+        if scheduler_class is None:
+            raise ValueError(
+                f'Unsupported scheduler: {scheduler_type}. Supported schedulers are: {", ".join(scheduler_map.keys())}'
+            )
 
         # 옵션이 있는 경우 전달하고, 없으면 기본 생성자 호출
         options = tune_config['scheduler'].get('options')
@@ -291,13 +428,18 @@ class TuneAction(TrainAction):
     @staticmethod
     def convert_tune_search_alg(tune_config):
         """
-        Convert YAML hyperparameter configuration to Ray Tune search algorithm and scheduler.
+        Convert YAML hyperparameter configuration to Ray Tune search algorithm.
 
         Args:
             tune_config (dict): Hyperparameter configuration.
 
         Returns:
-            dict: Ray Tune search algorithm and scheduler
+            object: Ray Tune search algorithm instance or None
+
+        Supported search algorithms:
+            - 'bayesoptsearch': Bayesian optimization
+            - 'hyperoptsearch': Tree-structured Parzen Estimator
+            - 'basicvariantgenerator': Random search (default)
         """
 
         if tune_config.get('search_alg') is None:
@@ -328,6 +470,11 @@ class TuneAction(TrainAction):
             from ray.tune.search.basic_variant import BasicVariantGenerator
 
             search_alg = BasicVariantGenerator(points_to_evaluate=points_to_evaluate)
+        else:
+            raise ValueError(
+                f'Unsupported search algorithm: {search_alg_name}. '
+                f'Supported algorithms are: bayesoptsearch, hyperoptsearch, basicvariantgenerator'
+            )
 
         return search_alg
 

synapse_sdk/plugins/categories/upload/templates/README.md

@@ -7,6 +7,7 @@ The Upload Plugin provides comprehensive file and data upload functionality with
 ### CLI Usage Examples
 
 #### Standard Upload (Single Directory)
+
 ```bash
 synapse plugin run upload '{
   "name": "Dataset Upload",
@@ -21,6 +22,7 @@ synapse plugin run upload '{
 ```
 
 #### Multi-Path Upload (Different Locations)
+
 ```bash
 synapse plugin run upload '{
   "name": "Complex Dataset Upload",
@@ -39,6 +41,7 @@ synapse plugin run upload '{
 ### Common Use Cases
 
 #### 1. Simple Dataset Upload
+
 ```json
 {
   "name": "Training Dataset",
@@ -52,6 +55,7 @@ synapse plugin run upload '{
 ```
 
 #### 2. Multi-Source Dataset Upload
+
 ```json
 {
   "name": "Multi-Camera Dataset",
@@ -59,14 +63,15 @@ synapse plugin run upload '{
   "collection": 2,
   "use_single_path": true,
   "assets": {
-    "front_camera": {"path": "/cameras/front", "recursive": true},
-    "rear_camera": {"path": "/cameras/rear", "recursive": true},
-    "lidar": {"path": "/sensors/lidar", "recursive": false}
+    "front_camera": { "path": "/cameras/front", "recursive": true },
+    "rear_camera": { "path": "/cameras/rear", "recursive": true },
+    "lidar": { "path": "/sensors/lidar", "recursive": false }
   }
 }
 ```
 
 #### 3. Dataset with Metadata
+
 ```json
 {
   "name": "Annotated Dataset",
@@ -84,23 +89,23 @@ synapse plugin run upload '{
 
 ### Required Parameters
 
-| Parameter | Type | Description | Example |
-|-----------|------|-------------|---------|
-| `name` | string | Display name for the upload | `"My Dataset"` |
-| `storage` | integer | Storage backend ID | `1` |
-| `collection` | integer | Collection ID defining file specs | `2` |
-| `assets` | object | Path configuration (varies by mode) | See examples below |
+| Parameter    | Type    | Description                         | Example            |
+| ------------ | ------- | ----------------------------------- | ------------------ |
+| `name`       | string  | Display name for the upload         | `"My Dataset"`     |
+| `storage`    | integer | Storage backend ID                  | `1`                |
+| `collection` | integer | Collection ID defining file specs   | `2`                |
+| `assets`     | object  | Path configuration (varies by mode) | See examples below |
 
 ### Optional Parameters
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `description` | string | `null` | Upload description |
-| `project` | integer | `null` | Project ID to associate |
-| `use_single_path` | boolean | `false` | Enable individual path mode |
-| `is_recursive` | boolean | `false` | Global recursive setting |
-| `excel_metadata_path` | `string` | `null` | File path to Excel metadata file (will be deprecated in future, consider using `excel_metadata`) |
-| `excel_metadata` | `object` | `null` | Base64 encoded Excel metadata (recommended) |
+| Parameter             | Type     | Default | Description                                                                      |
+| --------------------- | -------- | ------- | -------------------------------------------------------------------------------- |
+| `description`         | string   | `null`  | Upload description                                                               |
+| `project`             | integer  | `null`  | Project ID to associate                                                          |
+| `use_single_path`     | boolean  | `false` | Enable individual path mode                                                      |
+| `is_recursive`        | boolean  | `false` | Global recursive setting                                                         |
+| `excel_metadata_path` | `string` | `null`  | **DEPRECATED** - File path to Excel metadata file (use `excel_metadata` instead) |
+| `excel_metadata`      | `object` | `null`  | Base64 encoded Excel metadata (recommended)                                      |
 
 ## Excel Metadata Support
 
@@ -110,11 +115,11 @@ The upload plugin provides advanced Excel metadata processing with flexible head
 
 There are two separate parameters for providing Excel metadata:
 
-#### 1. File Path Method (`excel_metadata_path`)
+#### 1. File Path Method (`excel_metadata_path`) - **DEPRECATED**
 
-:::info Future Deprecation Notice
-This parameter will be deprecated in a future version.
-We recommend using the `excel_metadata` parameter with base64 encoding for new implementations.
+:::warning Deprecation Notice
+This parameter is **deprecated** and will be removed in a future version.
+Please migrate to using the `excel_metadata` parameter with base64 encoding instead.
 :::
 
 **Use case:** Traditional file-based uploads where the Excel file exists on the server's file system.
@@ -128,13 +133,12 @@ Simple string path to an Excel file:
 ```
 
 **Advantages:**
+
 - Backward compatible with existing implementations
 - Simple and straightforward
 - Direct file system access
 
-**Note:** Consider migrating to base64 encoded method for future compatibility (see Method 2 below)
-
-#### 2. Base64 Encoded Method (`excel_metadata`) - **RECOMMENDED**
+#### 2. Base64 Encoded Method (`excel_metadata`)
 
 **Use case:** Web frontends, APIs, and cloud integrations where files are transmitted as encoded data.
 
@@ -150,6 +154,7 @@ Send Excel file as base64-encoded data with original filename:
 ```
 
 **Advantages:**
+
 - No intermediate file storage required
 - Perfect for web upload forms
 - API-friendly JSON payload
@@ -158,16 +163,17 @@ Send Excel file as base64-encoded data with original filename:
 
 **Important:** You cannot use both `excel_metadata_path` and `excel_metadata` at the same time
 
-**Future-Proof Migration Example:**
+**Migration Example:**
+
 ```python
 import base64
 
-# Current approach (will be deprecated in future)
+# Old way (deprecated)
 params = {
     "excel_metadata_path": "/data/metadata.xlsx"
 }
 
-# Recommended approach for new implementations
+# New way (recommended)
 with open("/data/metadata.xlsx", "rb") as f:
     encoded = base64.b64encode(f.read()).decode("utf-8")
 params = {
@@ -179,12 +185,14 @@ params = {
 ```
 
 ### Excel Format Example
-| filename | category | quality | notes |
-|----------|----------|---------|-------|
-| sample001 | vehicle | high | Clear visibility |
-| sample002 | pedestrian | medium | Partial occlusion |
+
+| filename  | category   | quality | notes             |
+| --------- | ---------- | ------- | ----------------- |
+| sample001 | vehicle    | high    | Clear visibility  |
+| sample002 | pedestrian | medium  | Partial occlusion |
 
 ### Security Limits
+
 - Max file size: 10MB
 - Max rows: 10,000
 - Max columns: 50
@@ -192,6 +200,7 @@ params = {
 ## File Matching Logic
 
 Files are matched by **stem name** (filename without extension):
+
 - `sample001.jpg` → stem: "sample001"
 - `sample001.pcd` → stem: "sample001"
 - `sample001.json` → stem: "sample001"
@@ -203,6 +212,7 @@ These files form a single dataset named "sample001".
 ### Common Issues
 
 #### "No Files Found" Error
+
 ```bash
 # Check path exists and is readable
 ls -la /path/to/data
@@ -213,6 +223,7 @@ find /path/to/data -name "*.jpg" | head -10
 ```
 
 #### Excel Processing Errors
+
 ```bash
 # Check file format and size
 file /path/to/metadata.xlsx
@@ -228,6 +239,7 @@ print(f'Rows: {wb.active.max_row}')
 ```
 
 #### Upload Failures
+
 ```bash
 # Test storage connection
 synapse storage test --storage-id 1
@@ -242,16 +254,19 @@ synapse plugin run upload '{}' --debug
 ## Best Practices
 
 ### Directory Organization
+
 - Use clear, descriptive directory names
 - Keep reasonable directory sizes (< 10,000 files)
 - Use absolute paths for reliability
 
 ### Performance Optimization
+
 - Enable recursive only when needed
 - Keep Excel files under 5MB
 - Organize files in balanced directory structures
 
 ### Security Considerations
+
 - Validate all paths before processing
 - Use read-only permissions for source data
 - Set appropriate Excel size limits
@@ -259,18 +274,24 @@ synapse plugin run upload '{}' --debug
 ## Advanced Features
 
 ### Batch Processing
+
 The plugin automatically optimizes batch sizes based on dataset size:
+
 - Small datasets (< 50 files): batch size 50
 - Large datasets: dynamic batch size (10-100)
 
 ### Progress Tracking
+
 Real-time progress updates with categories:
+
 - Collection analysis: 2%
 - File upload: 38%
 - Data unit generation: 60%
 
 ### Error Handling
+
 Comprehensive validation at multiple levels:
+
 - Parameter validation (Pydantic)
 - Runtime path validation
 - File format validation
@@ -279,6 +300,7 @@ Comprehensive validation at multiple levels:
 ## Environment Variables
 
 Configure Excel processing limits:
+
 ```bash
 # File size limits
 EXCEL_MAX_FILE_SIZE_MB=10
@@ -296,20 +318,24 @@ EXCEL_MAX_METADATA_VALUE_LENGTH=1000
 ## Migration Guide
 
 ### Upgrading from Previous Versions
+
 All existing configurations continue to work. New features are additive:
 
 #### Test Current Configuration
+
 ```bash
 synapse plugin run upload '{}' --debug
 ```
 
 #### Convert to Explicit Mode
+
 ```python
 # Add explicit mode setting
 config["use_single_path"] = False  # or True for single path mode
 ```
 
 #### Gradual Migration to Single Path Mode
+
 ```python
 # Start with subset
 test_config = {
@@ -332,6 +358,7 @@ production_config = {
 ## Storage Backend Support
 
 The plugin supports multiple storage backends:
+
 - **Local filesystem**: Optimized for high I/O
 - **S3/GCS**: Cloud storage with retry logic
 - **SFTP**: Connection pooling for remote servers
@@ -340,6 +367,7 @@ The plugin supports multiple storage backends:
 ## API Reference
 
 ### Plugin Class
+
 ```python
 from synapse import Plugin
 
@@ -348,6 +376,7 @@ result = plugin.run(config, debug=True)
 ```
 
 ### Result Structure
+
 ```python
 {
     "status": "success",
@@ -362,4 +391,4 @@ result = plugin.run(config, debug=True)
 
 - **Documentation**: Full API documentation at [synapse-docs]
 - **Issues**: Report bugs at [issue-tracker]
-- **Examples**: More examples at [examples-repo]
+- **Examples**: More examples at [examples-repo]