synapse-sdk 1.0.0b5__py3-none-any.whl → 2025.12.3__py3-none-any.whl

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

@@ -1,5 +1,6 @@
 import copy
 import tempfile
+from numbers import Number
 from pathlib import Path
 from typing import Annotated, Optional
 
@@ -23,16 +24,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 +113,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 +185,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)
@@ -176,8 +305,13 @@ class TuneAction(TrainAction):
         entrypoint = self.entrypoint
         if not self._tune_override_exists():
             # entrypoint must be train entrypoint
+            train_entrypoint = entrypoint
+
             def _tune(param_space, run, dataset, checkpoint=None, **kwargs):
-                return entrypoint(run, dataset, param_space, checkpoint, **kwargs)
+                result = train_entrypoint(run, dataset, param_space, checkpoint, **kwargs)
+                if isinstance(result, Number) or isinstance(result, dict):
+                    return result
+                return {'result': result}
 
             entrypoint = _tune
 
@@ -256,6 +390,10 @@ class TuneAction(TrainAction):
 
         Returns:
             object: Ray Tune scheduler instance.
+
+        Supported schedulers:
+            - 'fifo': FIFOScheduler (default)
+            - 'hyperband': HyperBandScheduler
         """
 
         from ray.tune.schedulers import (
@@ -278,7 +416,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 +434,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 +476,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/neural_net/templates/config.yaml

@@ -14,8 +14,8 @@ actions:
     entrypoint: plugin.train.train
     metrics:
       train:
-        epoch:  
-          loss:  # Use the plugin's internal variable as the key, and the user-facing title in name.
+        epoch:
+          loss: # Use the plugin's internal variable as the key, and the user-facing title in name.
             name: Loss
       validation:
         epoch:
@@ -25,7 +25,7 @@ actions:
       ui_schema: |
         Dumped FormKit Schema for hyperparameters
     visualizations:
-      validation_samples_per_epochs:   # put in log_visualization name
+      validation_samples_per_epochs: # put in log_visualization name
         type: vis_type
         name: user-facing title
         options:
@@ -39,5 +39,8 @@ actions:
     method: restapi
     endpoints:
       - method: get
+    required_resources: # Specify required resources for inference deployment
+      required_cpu_count: 1
+      required_gpu_count: 0.1
   test:
-    entrypoint: plugin.test.test
+    entrypoint: plugin.test.test

synapse_sdk/plugins/categories/pre_annotation/actions/__init__.py

@@ -0,0 +1,4 @@
+from .pre_annotation.action import PreAnnotationAction
+from .to_task.action import ToTaskAction
+
+__all__ = ['PreAnnotationAction', 'ToTaskAction']

synapse_sdk/plugins/categories/pre_annotation/actions/pre_annotation/__init__.py

@@ -0,0 +1,3 @@
+from .action import PreAnnotationAction
+
+__all__ = ['PreAnnotationAction']

synapse_sdk/plugins/categories/pre_annotation/actions/pre_annotation/action.py

@@ -0,0 +1,10 @@
+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
+
+
+@register_action
+class PreAnnotationAction(Action):
+    name = 'pre_annotation'
+    category = PluginCategory.PRE_ANNOTATION
+    method = RunMethod.TASK

synapse_sdk/plugins/categories/pre_annotation/actions/to_task/__init__.py

@@ -0,0 +1,28 @@
+from .action import ToTaskAction
+from .enums import AnnotateTaskDataStatus, AnnotationMethod, LogCode
+from .exceptions import CriticalError, PreAnnotationToTaskFailed
+
+# Advanced imports for extending the system
+from .factory import ToTaskStrategyFactory
+from .models import MetricsRecord, ToTaskParams, ToTaskResult
+from .orchestrator import ToTaskOrchestrator
+from .run import ToTaskRun
+from .strategies.base import ToTaskContext
+
+__all__ = [
+    # Core public API (maintains backward compatibility)
+    'ToTaskAction',
+    'ToTaskRun',
+    'ToTaskParams',
+    'ToTaskResult',
+    'AnnotationMethod',
+    'AnnotateTaskDataStatus',
+    'LogCode',
+    'CriticalError',
+    'PreAnnotationToTaskFailed',
+    'MetricsRecord',
+    # Advanced components for customization and testing
+    'ToTaskOrchestrator',
+    'ToTaskContext',
+    'ToTaskStrategyFactory',
+]

synapse_sdk/plugins/categories/pre_annotation/actions/to_task/action.py

@@ -0,0 +1,148 @@
+"""Refactored ToTask action using Strategy and Facade patterns."""
+
+from typing import Dict
+
+from synapse_sdk.clients.backend import BackendClient
+from synapse_sdk.clients.backend.models import JobStatus
+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 .enums import LogCode
+from .exceptions import PreAnnotationToTaskFailed
+from .models import ToTaskParams, ToTaskResult
+from .orchestrator import ToTaskOrchestrator
+from .run import ToTaskRun
+from .strategies.base import ToTaskContext
+
+
+@register_action
+class ToTaskAction(Action):
+    """ToTask action for pre-annotation data processing using Strategy and Facade patterns.
+
+    This action handles the process of annotating data to tasks in a project. It supports
+    two annotation methods: file-based annotation and inference-based annotation.
+
+    The action uses a Strategy pattern to handle different annotation methods and validation
+    approaches, coordinated by an Orchestrator (Facade pattern) that manages the complete
+    workflow with rollback capabilities.
+
+    File-based annotation fetches data from file URLs specified in task data units,
+    downloads and processes JSON data, and updates task data with the processed information.
+    It also validates target specification names against file specifications.
+
+    Inference-based annotation uses pre-processor plugins for model inference
+    for automatic data annotation.
+
+    Attrs:
+        name (str): Action name, set to 'to_task'.
+        category (PluginCategory): Plugin category, set to PRE_ANNOTATION.
+        method (RunMethod): Execution method, set to JOB.
+        run_class (Type[ToTaskRun]): Run class for this action.
+        params_model (Type[ToTaskParams]): Parameter validation model.
+        progress_categories (Dict): Progress tracking configuration.
+        metrics_categories (Set[str]): Metrics categories for this action.
+
+    Note:
+        This action requires a valid project with an associated data collection.
+        For file-based annotation, the target_specification_name must exist in the
+        project's file specifications.
+
+    Raises:
+        ValueError: If run instance or parameters are not properly initialized.
+        PreAnnotationToTaskFailed: If the annotation workflow fails.
+    """
+
+    name = 'to_task'
+    category = PluginCategory.PRE_ANNOTATION
+    method = RunMethod.JOB
+    run_class = ToTaskRun
+    params_model = ToTaskParams
+    progress_categories = {
+        'annotate_task_data': {
+            'proportion': 100,
+        },
+    }
+    metrics_categories = {
+        'annotate_task_data': {
+            'stand_by': 0,
+            'failed': 0,
+            'success': 0,
+        }
+    }
+
+    def __init__(self, *args, **kwargs):
+        """Initialize the action with orchestrator context."""
+        super().__init__(*args, **kwargs)
+        self.context = None
+
+    def start(self) -> Dict:
+        """Start to_task action using orchestrator facade.
+
+        The action now uses a simplified workflow:
+        1. Validate initialization
+        2. Create execution context
+        3. Execute workflow through orchestrator
+        4. Handle results and errors
+
+        Returns:
+            dict: Validated result with status and message.
+        """
+        # Validate initialization
+        if not self.run or not self.params:
+            result = ToTaskResult(
+                status=JobStatus.FAILED, message='Run instance or parameters not properly initialized'
+            )
+            raise PreAnnotationToTaskFailed(result.message)
+
+        # Type assertions for better IDE support
+        assert isinstance(self.run, ToTaskRun)
+        assert isinstance(self.run.client, BackendClient)
+
+        # Log action start
+        self.run.log_message_with_code(LogCode.TO_TASK_STARTED)
+
+        try:
+            # Create execution context
+            self.context = ToTaskContext(
+                params=self.params,
+                client=self.run.client,
+                logger=self.run,
+                entrypoint=self.entrypoint,
+                config=self.config,
+                plugin_config=self.plugin_config,
+                job_id=self.job_id,
+                progress_categories=self.progress_categories,
+                metrics_categories=self.metrics_categories,
+            )
+
+            # Create and execute orchestrator
+            orchestrator = ToTaskOrchestrator(self.context)
+            result = orchestrator.execute_workflow()
+
+            # Log successful completion
+            self.run.log_message_with_code(LogCode.TO_TASK_COMPLETED)
+            return result
+
+        except PreAnnotationToTaskFailed as e:
+            # Re-raise pre-annotation specific errors
+            self.run.log_message_with_code(LogCode.TO_TASK_FAILED, str(e))
+            raise e
+
+        except Exception as e:
+            # Handle unexpected errors
+            error_msg = f'ToTask action failed: {str(e)}'
+            self.run.log_message_with_code(LogCode.TO_TASK_FAILED, error_msg)
+            result = ToTaskResult(status=JobStatus.FAILED, message=error_msg)
+            raise PreAnnotationToTaskFailed(result.message)
+        finally:
+            # Always emit completion log so backend can record end time even on failures
+            self.run.end_log()
+
+    def get_context(self) -> ToTaskContext:
+        """Get the current execution context for testing/debugging.
+
+        Returns:
+            ToTaskContext: The current execution context, or None if not initialized.
+        """
+        return self.context