synapse-sdk 2025.9.4__tar.gz → 2025.10.1__tar.gz

{synapse_sdk-2025.9.4/synapse_sdk.egg-info → synapse_sdk-2025.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synapse-sdk
-Version: 2025.9.4
+Version: 2025.10.1
 Summary: synapse sdk
 Author-email: datamaker <developer@datamaker.io>
 License: MIT
@@ -26,7 +26,7 @@ Requires-Dist: websockets
 Requires-Dist: ffmpeg-python==0.2.0
 Requires-Dist: sentry-sdk==2.38.0
 Provides-Extra: all
-Requires-Dist: ray[all]==2.49.1; extra == "all"
+Requires-Dist: ray[all]==2.50.0; extra == "all"
 Requires-Dist: python-nmap; extra == "all"
 Requires-Dist: hyperopt; extra == "all"
 Requires-Dist: bayesian-optimization==1.4.3; extra == "all"
@@ -62,6 +62,19 @@ A Python SDK for building and managing ML plugins, data annotation workflows, an
 - **🛠️ Development Tools**: Interactive web dashboard for monitoring and debugging
 - **⚡ CLI Interface**: Command-line tool for configuration, plugin management, and development
 
+## 📅 Versioning
+
+Synapse SDK uses **CalVer (Calendar Versioning)**.  
+The version format is `YYYY.MM.PATCH`, based on the release year and month.
+
+Examples:
+
+- `2025.9.5` → 5th release in September 2025  
+- `2025.10.1` → 1st release in October 2025  
+
+We recommend using the latest monthly release.  
+If needed, you can pin to a specific month, e.g. `2025.9.*`.
+
 ## 🚀 Quick Start
 
 ```bash

{synapse_sdk-2025.9.4 → synapse_sdk-2025.10.1}/README.md

@@ -13,6 +13,19 @@ A Python SDK for building and managing ML plugins, data annotation workflows, an
 - **🛠️ Development Tools**: Interactive web dashboard for monitoring and debugging
 - **⚡ CLI Interface**: Command-line tool for configuration, plugin management, and development
 
+## 📅 Versioning
+
+Synapse SDK uses **CalVer (Calendar Versioning)**.  
+The version format is `YYYY.MM.PATCH`, based on the release year and month.
+
+Examples:
+
+- `2025.9.5` → 5th release in September 2025  
+- `2025.10.1` → 1st release in October 2025  
+
+We recommend using the latest monthly release.  
+If needed, you can pin to a specific month, e.g. `2025.9.*`.
+
 ## 🚀 Quick Start
 
 ```bash

{synapse_sdk-2025.9.4 → synapse_sdk-2025.10.1}/pyproject.toml

@@ -35,7 +35,7 @@ dynamic = ["version"]
 
 [project.optional-dependencies]
 all = [
-    "ray[all]==2.49.1",
+    "ray[all]==2.50.0",
     "python-nmap",
     "hyperopt",
     "bayesian-optimization==1.4.3"

synapse_sdk-2025.10.1/synapse_sdk/devtools/docs/docs/api/plugins/models.md

@@ -0,0 +1,114 @@
+---
+id: models
+title: Plugin Models
+sidebar_position: 1
+---
+
+# Plugin Models
+
+Core data models and structures for the plugin system.
+
+## PluginRelease
+
+Represents a specific version of a plugin.
+
+```python
+from synapse_sdk.plugins.models import PluginRelease
+
+release = PluginRelease(plugin_path="./my-plugin")
+```
+
+### Properties
+
+- `plugin`: Plugin code identifier
+- `version`: Plugin version
+- `code`: Combined plugin and version string
+- `category`: Plugin category
+- `name`: Human-readable plugin name
+- `actions`: Available plugin actions
+
+## PluginAction
+
+Represents a plugin action execution request.
+
+```python
+from synapse_sdk.plugins.models import PluginAction
+
+action = PluginAction(
+    plugin="my-plugin",
+    version="1.0.0",
+    action="process",
+    params={"input": "data"}
+)
+```
+
+## Run
+
+Execution context for plugin actions.
+
+```python
+def start(self):
+    # Log messages
+    self.run.log("Processing started")
+
+    # Update progress
+    self.run.set_progress(0.5)
+
+    # Set metrics
+    self.run.set_metrics({"processed": 100})
+```
+
+### Development Logging
+
+The `Run` class includes a specialized logging system for plugin developers with the `log_dev_event()` method and `DevLog` model.
+
+#### DevLog Model
+
+Structured model for development event logging:
+
+```python
+from synapse_sdk.shared.enums import Context
+
+class DevLog(BaseModel):
+    event_type: str          # Event category (automatically generated as '{action_name}_dev_log')
+    message: str             # Descriptive message
+    data: dict | None        # Optional additional data
+    level: Context           # Event severity level
+    created: str             # ISO timestamp
+```
+
+#### log_dev_event Method
+
+Log custom development events for debugging and monitoring:
+
+```python
+def start(self):
+    # Basic event logging (event_type automatically set to '{action_name}_dev_log')
+    self.run.log_dev_event('Data validation completed', {'records_count': 100})
+
+    # Performance tracking
+    self.run.log_dev_event('Processing time recorded', {'duration_ms': 1500})
+
+    # Debug with warning level
+    self.run.log_dev_event('Variable state checkpoint',
+                          {'variable_x': 42}, level=Context.WARNING)
+
+    # Simple event without data
+    self.run.log_dev_event('Plugin initialization complete')
+```
+
+**Parameters:**
+
+- `message` (str): Human-readable description
+- `data` (dict, optional): Additional context data
+- `level` (Context, optional): Event severity (default: Context.INFO)
+
+**Note:** The `event_type` is automatically generated as `{action_name}_dev_log` and cannot be modified by plugin developers.
+
+**Use Cases:**
+
+- **Debugging**: Track variable states and execution flow
+- **Performance**: Record processing times and resource usage
+- **Validation**: Log data validation results
+- **Error Tracking**: Capture detailed error information
+- **Progress Monitoring**: Record intermediate states in long-running tasks

{synapse_sdk-2025.9.4 → synapse_sdk-2025.10.1}/synapse_sdk/devtools/docs/docs/plugins/export-plugins.md

@@ -169,6 +169,45 @@ flowchart TD
 
 The design follows the **Template Method Pattern** where `BaseExporter.export()` defines the algorithm skeleton, and subclasses customize specific steps through the hook methods.
 
+## Plugin Configuration
+
+Export plugin templates include configuration fields for filtering and plugin discovery:
+
+```yaml
+actions:
+  export:
+    entrypoint: plugin.export.Exporter
+    annotation_types:
+      - image
+      - video
+      - audio
+      - text
+      - pcd
+      - prompt
+
+data_types:
+  - image
+  - video
+  - audio
+  - text
+  - pcd
+```
+
+### Configuration Fields
+
+- **data_types**: List of supported data types for filtering export plugins (plugin-level filter)
+
+  - Supported values: `image`, `video`, `audio`, `text`, `pcd`
+  - Used by the platform to filter and display relevant export plugins to users based on their data type
+
+- **annotation_types**: List of supported annotation types for filtering export plugins (action-level filter)
+  - Supported values: `image`, `video`, `audio`, `text`, `pcd`, `prompt`
+  - Defined within each action's configuration (e.g., `actions.export.annotation_types`)
+  - Used by the platform to filter and display relevant export plugins to users based on their annotation type
+  - Each action can have different annotation type requirements
+
+**Best Practice**: Customize these fields to accurately reflect your plugin's capabilities. The template includes all common types as examples, but you should modify the list to match what your plugin actually supports.
+
 ## BaseExporter Class Structure
 
 The new BaseExporter class provides an object-oriented approach for export plugins:

synapse_sdk-2025.10.1/synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/api/plugins/models.md

@@ -0,0 +1,114 @@
+---
+id: models
+title: 플러그인 모델
+sidebar_position: 1
+---
+
+# 플러그인 모델
+
+플러그인 시스템의 핵심 데이터 모델 및 구조입니다.
+
+## PluginRelease
+
+플러그인의 특정 버전을 나타냅니다.
+
+```python
+from synapse_sdk.plugins.models import PluginRelease
+
+release = PluginRelease(plugin_path="./my-plugin")
+```
+
+### 속성
+
+- `plugin`: 플러그인 코드 식별자
+- `version`: 플러그인 버전
+- `code`: 플러그인과 버전이 결합된 문자열
+- `category`: 플러그인 카테고리
+- `name`: 사람이 읽을 수 있는 플러그인 이름
+- `actions`: 사용 가능한 플러그인 액션
+
+## PluginAction
+
+플러그인 액션 실행 요청을 나타냅니다.
+
+```python
+from synapse_sdk.plugins.models import PluginAction
+
+action = PluginAction(
+    plugin="my-plugin",
+    version="1.0.0",
+    action="process",
+    params={"input": "data"}
+)
+```
+
+## Run
+
+플러그인 액션의 실행 컨텍스트입니다.
+
+```python
+def start(self):
+    # 메시지 로깅
+    self.run.log("Processing started")
+
+    # 진행률 업데이트
+    self.run.set_progress(0.5)
+
+    # 메트릭 설정
+    self.run.set_metrics({"processed": 100})
+```
+
+### 개발 로깅
+
+`Run` 클래스는 `log_dev_event()` 메서드와 `DevLog` 모델을 통해 플러그인 개발자를 위한 특수 로깅 시스템을 포함합니다.
+
+#### DevLog 모델
+
+개발 이벤트 로깅을 위한 구조화된 모델:
+
+```python
+from synapse_sdk.shared.enums import Context
+
+class DevLog(BaseModel):
+    event_type: str          # 이벤트 카테고리 ('{action_name}_dev_log' 형태로 자동 생성)
+    message: str             # 설명 메시지
+    data: dict | None        # 선택적 추가 데이터
+    level: Context           # 이벤트 심각도 수준
+    created: str             # ISO 타임스탬프
+```
+
+#### log_dev_event 메서드
+
+디버깅 및 모니터링을 위한 커스텀 개발 이벤트 로깅:
+
+```python
+def start(self):
+    # 기본 이벤트 로깅 (event_type은 '{action_name}_dev_log' 형태로 자동 설정)
+    self.run.log_dev_event('데이터 검증 완료', {'records_count': 100})
+
+    # 성능 추적
+    self.run.log_dev_event('처리 시간 기록', {'duration_ms': 1500})
+
+    # 경고 레벨의 디버그
+    self.run.log_dev_event('변수 상태 체크포인트',
+                          {'variable_x': 42}, level=Context.WARNING)
+
+    # 데이터 없는 간단한 이벤트
+    self.run.log_dev_event('플러그인 초기화 완료')
+```
+
+**매개변수:**
+
+- `message` (str): 사람이 읽을 수 있는 설명
+- `data` (dict, 선택사항): 추가 컨텍스트 데이터
+- `level` (Context, 선택사항): 이벤트 심각도 (기본값: Context.INFO)
+
+**참고:** `event_type`은 `{action_name}_dev_log` 형태로 자동 생성되며 플러그인 개발자가 수정할 수 없습니다.
+
+**사용 사례:**
+
+- **디버깅**: 변수 상태 및 실행 흐름 추적
+- **성능**: 처리 시간 및 리소스 사용량 기록
+- **검증**: 데이터 검증 결과 로깅
+- **오류 추적**: 상세한 오류 정보 캡처
+- **진행 상황 모니터링**: 장기 실행 작업의 중간 상태 기록

{synapse_sdk-2025.9.4 → synapse_sdk-2025.10.1}/synapse_sdk/devtools/docs/i18n/ko/docusaurus-plugin-content-docs/current/plugins/export-plugins.md

@@ -169,6 +169,45 @@ flowchart TD
 
 이 설계는 **템플릿 메서드 패턴**을 따르며, `BaseExporter.export()`가 알고리즘 골격을 정의하고 서브클래스가 훅 메서드를 통해 특정 단계를 커스터마이징합니다.
 
+## 플러그인 설정
+
+Export 플러그인 템플릿은 필터링 및 플러그인 검색을 위한 설정 필드를 포함합니다:
+
+```yaml
+actions:
+  export:
+    entrypoint: plugin.export.Exporter
+    annotation_types:
+      - image
+      - video
+      - audio
+      - text
+      - pcd
+      - prompt
+
+data_types:
+  - image
+  - video
+  - audio
+  - text
+  - pcd
+```
+
+### 설정 필드
+
+- **data_types**: Export 플러그인 필터링을 위한 지원 데이터 타입 목록 (플러그인 레벨 필터)
+
+  - 지원 값: `image`, `video`, `audio`, `text`, `pcd`
+  - 플랫폼에서 사용자의 데이터 타입에 따라 관련 export 플러그인을 필터링하고 표시하는 데 사용됩니다
+
+- **annotation_types**: Export 플러그인 필터링을 위한 어노테이션 타입 목록 (액션 레벨 필터)
+  - 지원 값: `image`, `video`, `audio`, `text`, `pcd`, `prompt`
+  - 각 액션의 설정 내에서 정의됩니다 (예: `actions.export.annotation_types`)
+  - 플랫폼에서 사용자의 주석 타입에 따라 관련 export 플러그인을 필터링하고 표시하는 데 사용됩니다
+  - 각 액션마다 다른 어노테이션 타입 요구사항을 가질 수 있습니다
+
+**모범 사례**: 플러그인의 실제 기능을 정확히 반영하도록 이 필드들을 커스터마이징하세요. 템플릿에는 모든 일반적인 타입이 예시로 포함되어 있지만, 플러그인이 실제로 지원하는 항목에 맞게 목록을 수정해야 합니다.
+
 ## BaseExporter 클래스 구조
 
 새로운 BaseExporter 클래스는 export 플러그인을 위한 객체지향적 접근 방식을 제공합니다:

{synapse_sdk-2025.9.4 → synapse_sdk-2025.10.1}/synapse_sdk/devtools/docs/sidebars.ts

@@ -66,6 +66,13 @@ const sidebars: SidebarsConfig = {
             'api/clients/base',
           ],
         },
+        {
+          type: 'category',
+          label: 'Plugins',
+          items: [
+            'api/plugins/models',
+          ],
+        },
       ],
     },
     'configuration',

{synapse_sdk-2025.9.4 → synapse_sdk-2025.10.1}/synapse_sdk/plugins/categories/base.py

@@ -164,6 +164,7 @@ class Action:
             'params': self.params,
             'envs': self.envs,
             'debug': self.debug,
+            'action_name': self.name,
         }
         return self.run_class(self.job_id, context)
 
@@ -184,7 +185,7 @@ class Action:
 
         # Sentry init if SENTRY_DSN is set
         if needs_sentry_init():
-            runtime_env['worker_process_setup_hook'] = init_sentry
+            runtime_env['worker_process_setup_hook'] = 'synapse_sdk.shared'
 
         # 맨 마지막에 진행되어야 함
         runtime_env['env_vars'] = self.envs

synapse_sdk-2025.10.1/synapse_sdk/plugins/categories/export/templates/config.yaml

@@ -0,0 +1,21 @@
+actions:
+  export:
+    entrypoint: plugin.export.Exporter
+    # Filter to only export action specific annotation types (e.g., only export image annotations project)
+    # Supported types: image, video, audio, text, pcd, prompt
+    annotation_types:
+      - image
+      - video
+      - audio
+      - text
+      - pcd
+      - prompt
+
+# Filter to only export specific data types (e.g., only export image data)
+# Supported types: image, video, audio, text, pcd
+data_types:
+  - image
+  - video
+  - audio
+  - text
+  - pcd

synapse_sdk-2025.10.1/synapse_sdk/plugins/categories/export/templates/plugin/export.py

@@ -0,0 +1,160 @@
+from pathlib import Path
+from typing import Generator
+
+from . import BaseExporter
+
+
+class Exporter(BaseExporter):
+    """Plugin export action interface for organizing files.
+
+    This class provides a minimal interface for plugin developers to implement
+    their own export logic.
+    """
+
+    def __init__(self, run, export_items: Generator, path_root: Path, **params):
+        """Initialize the plugin export action class.
+        Args:
+            run: Plugin run object with logging capabilities.
+            export_items (generator):
+                - data (dict): dm_schema_data information.
+                - files (dict): File information. Includes file URL, original file path, metadata, etc.
+                - id (int): target ID (ex. assignment id, task id, ground_truth_event id)
+            path_root: pathlib object, the path to export
+            **params: Additional parameters
+                - name (str): The name of the action.
+                - description (str | None): The description of the action.
+                - storage (int): The storage ID to save the exported data.
+                - save_original_file (bool): Whether to save the original file.
+                - path (str): The path to save the exported data.
+                - target (str): The target source to export data from. (ex. ground_truth, assignment, task)
+                - filter (dict): The filter criteria to apply.
+                - extra_params (dict | None): Additional parameters for export customization.
+                    Example: {"include_metadata": True, "compression": "gzip"}
+                - count (int): Total number of results.
+                - results (list): List of results fetched through the list API.
+                - project_id (int): Project ID.
+                - configuration (dict): Project configuration.
+        """
+        super().__init__(run, export_items, path_root, **params)
+
+    def export(self, export_items=None, results=None, **kwargs) -> dict:
+        """Executes the export task using the base class implementation.
+
+        Args:
+            export_items: Optional export items to process. If not provided, uses self.export_items.
+            results: Optional results data to process alongside export_items.
+            **kwargs: Additional parameters for export customization.
+
+        Returns:
+            dict: Result
+        """
+        return super().export(export_items, results, **kwargs)
+
+    def convert_data(self, data):
+        """Converts the data."""
+        return data
+
+    def before_convert(self, data):
+        """Preprocesses the data before conversion."""
+        return data
+
+    def after_convert(self, data):
+        """Post-processes the data after conversion."""
+        return data
+
+    def sample_dev_log(self):
+        """Sample development logging examples for plugin developers.
+
+        This method demonstrates various ways to use log_dev_event() for debugging,
+        monitoring, and tracking plugin execution. The event_type is automatically
+        generated as 'export_dev_log' for export actions and cannot be modified.
+
+        Use Cases:
+        1. Process Tracking: Log when important processes start/complete
+        2. Error Handling: Capture detailed error information with appropriate severity
+        3. Performance Monitoring: Record timing and resource usage
+        4. Data Validation: Log validation results and data quality metrics
+        5. Debug Information: Track variable states and execution flow
+
+        Examples show different scenarios where development logging is beneficial:
+        - Basic process logging with structured data
+        - Error logging with exception details and danger level
+        - Performance tracking with timing information
+        - Validation logging with success/failure status
+        """
+        # Example 1: Basic Process Tracking
+        # Use when: Starting important processes that you want to monitor
+        # Benefits: Helps track execution flow and identify bottlenecks
+        self.run.log_dev_event(
+            'Starting data conversion process',
+            {'data_type': 'img', 'data_size': 'unknown', 'conversion_method': 'custom_format'},
+        )
+
+        # Example 2: Error Handling with Detailed Information
+        # Use when: Catching exceptions that you want to analyze later
+        # Benefits: Provides structured error data for debugging and monitoring
+        from synapse_sdk.shared.enums import Context
+
+        try:
+            # Simulated operation that might fail
+            pass
+        except Exception as e:
+            self.run.log_dev_event(
+                f'Data conversion failed: {str(e)}',
+                {
+                    'error_type': type(e).__name__,
+                    'error_details': str(e),
+                    'operation': 'data_conversion',
+                    'recovery_attempted': False,
+                },
+                level=Context.DANGER,
+            )
+
+        # Example 3: Performance Monitoring
+        # Use when: Tracking processing time for optimization
+        # Benefits: Identifies performance bottlenecks and optimization opportunities
+        import time
+
+        start_time = time.time()
+        # Simulated processing work
+        time.sleep(0.001)
+        processing_time = time.time() - start_time
+
+        self.run.log_dev_event(
+            'File processing completed',
+            {
+                'processing_time_ms': round(processing_time * 1000, 2),
+                'files_processed': 1,
+                'performance_rating': 'excellent' if processing_time < 0.1 else 'normal',
+            },
+        )
+
+        # Example 4: Data Validation Logging
+        # Use when: Validating data quality or structure
+        # Benefits: Helps identify data issues and track validation metrics
+        validation_passed = True  # Simulated validation result
+        self.run.log_dev_event(
+            'Data validation completed',
+            {
+                'validation_passed': validation_passed,
+                'validation_rules': ['format_check', 'required_fields', 'data_types'],
+                'data_quality_score': 95.5,
+            },
+            level=Context.SUCCESS if validation_passed else Context.WARNING,
+        )
+
+        # Example 5: Debug Information with Variable States
+        # Use when: Debugging complex logic or tracking variable changes
+        # Benefits: Provides insight into execution state at specific points
+        current_batch_size = 100
+        memory_usage = 45.2  # Simulated memory usage in MB
+
+        self.run.log_dev_event(
+            'Processing checkpoint reached',
+            {
+                'current_batch_size': current_batch_size,
+                'memory_usage_mb': memory_usage,
+                'checkpoint_location': 'after_data_preprocessing',
+                'next_operation': 'file_saving',
+            },
+        )