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

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

@@ -0,0 +1,534 @@
+import copy
+import tempfile
+from numbers import Number
+from pathlib import Path
+from typing import Annotated, Optional
+
+from pydantic import AfterValidator, BaseModel, field_validator
+from pydantic_core import PydanticCustomError
+
+from synapse_sdk.clients.exceptions import ClientError
+from synapse_sdk.plugins.categories.decorators import register_action
+from synapse_sdk.plugins.categories.neural_net.actions.train import TrainAction, TrainRun
+from synapse_sdk.plugins.enums import PluginCategory, RunMethod
+from synapse_sdk.utils.file import archive
+from synapse_sdk.utils.module_loading import import_string
+from synapse_sdk.utils.pydantic.validators import non_blank
+
+
+class TuneRun(TrainRun):
+    is_tune = True
+    completed_samples = 0
+    num_samples = 0
+    checkpoint_output = None
+
+
+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
+    max_concurrent_trials: Optional[int] = None
+    search_alg: Optional[SearchAlgo] = None
+    scheduler: Optional[Scheduler] = None
+
+
+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')
+    @staticmethod
+    def unique_name(value, info):
+        action = info.context['action']
+        client = action.client
+        try:
+            job_exists = client.exists(
+                'list_jobs',
+                params={
+                    'ids_ex': action.job_id,
+                    'category': 'neural_net',
+                    'job__action': 'tune',
+                    'is_active': True,
+                    'params': f'name:{value}',
+                },
+            )
+            assert not job_exists, '존재하는 튜닝 작업 이름입니다.'
+        except ClientError:
+            raise PydanticCustomError('client_error', '')
+        return value
+
+
+@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)
+       should be set to the checkpoint_output attribute of the run object **before**
+       starting the training.
+    2. Before exiting the training function, report the results to Tune.
+    3. When using own tune.py, take note of the difference in the order of parameters.
+       tune() function starts with hyperparameter, run, dataset, checkpoint, **kwargs
+       whereas the train() function starts with run, dataset, hyperparameter, checkpoint, **kwargs.
+    ----
+    1)
+    Set the output path for the checkpoint to export best model
+
+    output_path = Path('path/to/your/weights')
+    run.checkpoint_output = str(output_path)
+
+    2)
+    Before exiting the training function, report the results to Tune.
+    The results_dict should contain the metrics you want to report.
+
+    Example: (In train function)
+    results_dict = {
+        "accuracy": accuracy,
+        "loss": loss,
+        # Add other metrics as needed
+    }
+    if hasattr(self.dm_run, 'is_tune') and self.dm_run.is_tune:
+        tune.report(results_dict, checkpoint=tune.Checkpoint.from_directory(self.dm_run.checkpoint_output))
+
+
+    3)
+    tune() function takes hyperparameter, run, dataset, checkpoint, **kwargs in that order
+    whereas train() function takes run, dataset, hyperparameter, checkpoint, **kwargs in that order.
+
+    --------------------------------------------------------------------------------------------------------
+
+    **중요** Tune 사용 전 반드시 읽어야 할 사항들
+
+    1. 본 플러그인의 train 함수에서, 학습을 진행하기 코드 전에
+       결과 모델 파일의 경로(train함수의 리턴 값)을 checkpoint_output 속성에 설정해야 합니다.
+    2. 학습이 종료되기 전에, 결과를 Tune에 보고해야 합니다.
+    3. 플러그인에서 tune.py를 직접 생성해서 사용할 시, 매개변수의 순서가 다릅니다.
+
+    ----
+    1)
+    체크포인트를 설정할 경로를 지정합니다.
+    output_path = Path('path/to/your/weights')
+    run.checkpoint_output = str(output_path)
+
+    2)
+    학습이 종료되기 전에, 결과를 Tune에 보고합니다.
+    results_dict = {
+        "accuracy": accuracy,
+        "loss": loss,
+        # 필요한 다른 메트릭 추가
+    }
+    if hasattr(self.dm_run, 'is_tune') and self.dm_run.is_tune:
+        tune.report(results_dict, checkpoint=tune.Checkpoint.from_directory(self.dm_run.checkpoint_output))
+
+    3)
+    tune() 함수는 hyperparameter, run, dataset, checkpoint, **kwargs 순서이고
+    train() 함수는 run, dataset, hyperparameter, checkpoint, **kwargs 순서입니다.
+    """
+
+    name = 'tune'
+    category = PluginCategory.NEURAL_NET
+    method = RunMethod.JOB
+    run_class = TuneRun
+    params_model = TuneParams
+    progress_categories = {
+        'dataset': {
+            'proportion': 5,
+        },
+        'trials': {
+            'proportion': 90,
+        },
+        'model_upload': {
+            'proportion': 5,
+        },
+    }
+
+    def start(self):
+        from ray import tune
+
+        # download dataset
+        self.run.log_message('Preparing dataset for hyperparameter tuning.')
+        input_dataset = self.get_dataset()
+
+        # retrieve checkpoint
+        checkpoint = None
+        if self.params['checkpoint']:
+            self.run.log_message('Retrieving checkpoint.')
+            checkpoint = self.get_model(self.params['checkpoint'])
+
+        # train dataset
+        self.run.log_message('Starting training for hyperparameter tuning.')
+
+        # Save num_samples to TuneRun for logging
+        self.run.num_samples = self.params['tune_config']['num_samples']
+
+        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):
+                result = train_entrypoint(run, dataset, param_space, checkpoint, **kwargs)
+                if isinstance(result, Number) or isinstance(result, dict):
+                    return result
+                return {'result': result}
+
+            entrypoint = _tune
+
+        trainable = tune.with_parameters(entrypoint, run=self.run, dataset=input_dataset, checkpoint=checkpoint)
+
+        tune_config = self.params['tune_config']
+
+        tune_config['search_alg'] = self.convert_tune_search_alg(tune_config)
+        tune_config['scheduler'] = self.convert_tune_scheduler(tune_config)
+
+        hyperparameter = self.params['hyperparameter']
+        param_space = self.convert_tune_params(hyperparameter)
+        temp_path = tempfile.TemporaryDirectory()
+
+        tuner = tune.Tuner(
+            tune.with_resources(trainable, resources=self.tune_resources),
+            tune_config=tune.TuneConfig(**tune_config),
+            run_config=tune.RunConfig(
+                name=f'synapse_tune_hpo_{self.job_id}',
+                log_to_file=('stdout.log', 'stderr.log'),
+                storage_path=temp_path.name,
+            ),
+            param_space=param_space,
+        )
+        result = tuner.fit()
+
+        best_result = result.get_best_result()
+
+        # upload model_data
+        self.run.log_message('Registering best model data.')
+        self.run.set_progress(0, 1, category='model_upload')
+        self.create_model_from_result(best_result)
+        self.run.set_progress(1, 1, category='model_upload')
+
+        self.run.end_log()
+
+        return {'best_result': best_result.config}
+
+    @property
+    def tune_resources(self):
+        resources = {}
+        for option in ['num_cpus', 'num_gpus']:
+            option_value = self.params.get(option)
+            if option_value:
+                # Remove the 'num_' prefix and trailing s from the option name
+                resources[(lambda s: s[4:-1])(option)] = option_value
+        return resources
+
+    def create_model_from_result(self, result):
+        params = copy.deepcopy(self.params)
+        configuration_fields = ['hyperparameter']
+        configuration = {field: params.pop(field) for field in configuration_fields}
+
+        with tempfile.TemporaryDirectory() as temp_path:
+            archive_path = Path(temp_path, 'archive.zip')
+
+            # Archive tune results
+            # https://docs.ray.io/en/latest/tune/tutorials/tune_get_data_in_and_out.html#getting-data-out-of-tune-using-checkpoints-other-artifacts
+            archive(result.path, archive_path)
+
+            return self.client.create_model({
+                'plugin': self.plugin_release.plugin,
+                'version': self.plugin_release.version,
+                'file': str(archive_path),
+                'configuration': configuration,
+                **params,
+            })
+
+    @staticmethod
+    def convert_tune_scheduler(tune_config):
+        """
+        Convert YAML hyperparameter configuration to a Ray Tune scheduler.
+
+        Args:
+            tune_config (dict): Hyperparameter configuration.
+
+        Returns:
+            object: Ray Tune scheduler instance.
+
+        Supported schedulers:
+            - 'fifo': FIFOScheduler (default)
+            - 'hyperband': HyperBandScheduler
+        """
+
+        from ray.tune.schedulers import (
+            ASHAScheduler,
+            FIFOScheduler,
+            HyperBandScheduler,
+            MedianStoppingRule,
+            PopulationBasedTraining,
+        )
+
+        if tune_config.get('scheduler') is None:
+            return None
+
+        scheduler_map = {
+            'fifo': FIFOScheduler,
+            'asha': ASHAScheduler,
+            'hyperband': HyperBandScheduler,
+            'pbt': PopulationBasedTraining,
+            'median': MedianStoppingRule,
+        }
+
+        scheduler_type = tune_config['scheduler'].get('name', 'fifo').lower()
+        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')
+
+        # options가 None이거나 빈 딕셔너리가 아닌 경우에만 전달
+        scheduler = scheduler_class(**options) if options else scheduler_class()
+
+        return scheduler
+
+    @staticmethod
+    def convert_tune_search_alg(tune_config):
+        """
+        Convert YAML hyperparameter configuration to Ray Tune search algorithm.
+
+        Args:
+            tune_config (dict): Hyperparameter configuration.
+
+        Returns:
+            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:
+            return None
+
+        search_alg_name = tune_config['search_alg']['name'].lower()
+        metric = tune_config['metric']
+        mode = tune_config['mode']
+        points_to_evaluate = tune_config['search_alg'].get('points_to_evaluate', None)
+
+        if search_alg_name == 'axsearch':
+            from ray.tune.search.ax import AxSearch
+
+            search_alg = AxSearch(metric=metric, mode=mode)
+        elif search_alg_name == 'bayesoptsearch':
+            from ray.tune.search.bayesopt import BayesOptSearch
+
+            search_alg = BayesOptSearch(metric=metric, mode=mode)
+        elif search_alg_name == 'hyperoptsearch':
+            from ray.tune.search.hyperopt import HyperOptSearch
+
+            search_alg = HyperOptSearch(metric=metric, mode=mode)
+        elif search_alg_name == 'optunasearch':
+            from ray.tune.search.optuna import OptunaSearch
+
+            search_alg = OptunaSearch(metric=metric, mode=mode)
+        elif search_alg_name == 'basicvariantgenerator':
+            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
+
+    @staticmethod
+    def convert_tune_params(param_list):
+        """
+        Convert YAML hyperparameter configuration to Ray Tune parameter dictionary.
+
+        Args:
+            param_list (list): List of hyperparameter configurations.
+
+        Returns:
+            dict: Ray Tune parameter dictionary
+        """
+        from ray import tune
+
+        param_handlers = {
+            'uniform': lambda p: tune.uniform(p['min'], p['max']),
+            'quniform': lambda p: tune.quniform(p['min'], p['max']),
+            'loguniform': lambda p: tune.loguniform(p['min'], p['max'], p['base']),
+            'qloguniform': lambda p: tune.qloguniform(p['min'], p['max'], p['base']),
+            'randn': lambda p: tune.randn(p['mean'], p['sd']),
+            'qrandn': lambda p: tune.qrandn(p['mean'], p['sd']),
+            'randint': lambda p: tune.randint(p['min'], p['max']),
+            'qrandint': lambda p: tune.qrandint(p['min'], p['max']),
+            'lograndint': lambda p: tune.lograndint(p['min'], p['max'], p['base']),
+            'qlograndint': lambda p: tune.qlograndint(p['min'], p['max'], p['base']),
+            'choice': lambda p: tune.choice(p['options']),
+            'grid_search': lambda p: tune.grid_search(p['options']),
+        }
+
+        param_space = {}
+
+        for param in param_list:
+            name = param['name']
+            param_type = param['type']
+
+            if param_type in param_handlers:
+                param_space[name] = param_handlers[param_type](param)
+            else:
+                raise ValueError(f'Unknown parameter type: {param_type}')
+
+        return param_space
+
+    @staticmethod
+    def _tune_override_exists(module_path='plugin.tune') -> bool:
+        try:
+            import_string(module_path)
+            return True
+        except ImportError:
+            return False

synapse_sdk/plugins/categories/neural_net/base/inference.py

@@ -1,10 +1,10 @@
 import tempfile
 
 import jwt
-from clients.backend import BackendClient
 from fastapi import FastAPI
 from ray import serve
 
+from synapse_sdk.clients.backend import BackendClient
 from synapse_sdk.utils.file import unarchive
 
 app = FastAPI()

synapse_sdk/plugins/categories/neural_net/templates/config.yaml

@@ -1,18 +1,46 @@
-task: object_detection
+name: plugin_name
+code: plugin_code
+version: plugin_version
+readme: README.md
+description: This is plugin_name plugin
+category: neural_net
+tasks:
+  - image.object_detection
 data_type: image
+package_manager: uv
 actions:
   train:
     dataset: dataset
     entrypoint: plugin.train.train
     metrics:
-      epoch:
-        - loss
-        - miou
+      train:
+        epoch:
+          loss: # Use the plugin's internal variable as the key, and the user-facing title in name.
+            name: Loss
+      validation:
+        epoch:
+          acc:
+            name: Accuracy
+    hyperparameters:
+      ui_schema: |
+        Dumped FormKit Schema for hyperparameters
+    visualizations:
+      validation_samples_per_epochs: # put in log_visualization name
+        type: vis_type
+        name: user-facing title
+        options:
+          group_name: Epoch
+          thumbnail_size: [50, 50]
+    options:
+      visualize: false # Whether to visualize the training process
   deployment:
     entrypoint: plugin.inference.MockNetInference
   inference:
     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

synapse_sdk/plugins/categories/neural_net/templates/plugin/inference.py

@@ -1,14 +1,30 @@
-from ray import serve
+from pydantic import BaseModel
 
+# for load file with synapse
+# from synapse_sdk.types import FileField
+from synapse_sdk.plugins.categories.neural_net.base.inference import BaseInference, app
 
-class MockNetInference:
-    model_id = None
 
-    @serve.multiplexed()
-    async def get_model(self, model_id: str):
-        return model_id
+class InputData(BaseModel):  # Pydantic
+    input_string: str
 
-    async def __call__(self):
-        model_id = await self.get_model(serve.get_multiplexed_model_id())
-        message = 'hello datamaker!!!'
-        return {'model_id': model_id, 'message': message}
+
+class ResNetInference(BaseInference):
+    async def _get_model(self, model):  # Load model
+        model_directory_path = model['path']
+
+        # implement model_load code
+        model = model_directory_path
+
+        return model  # return loaded_model
+
+    @app.post('/load_model')
+    async def load_model(self):
+        await self.get_model()
+
+    @app.post('/')
+    async def infer(self, data: InputData):
+        model = await self.get_model()
+        results = model(data.input_string)  # This is Sample code. implement your model's prediction code
+
+        return results

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/{export/actions/export.py → pre_annotation/actions/pre_annotation/action.py}

@@ -4,7 +4,7 @@ from synapse_sdk.plugins.enums import PluginCategory, RunMethod
 
 
 @register_action
-class ExportAction(Action):
-    name = 'export'
-    category = PluginCategory.EXPORT
-    method = RunMethod.JOB
+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',
+]