synapse-sdk 1.0.0a35__py3-none-any.whl → 2025.11.7__py3-none-any.whl

synapse_sdk/plugins/utils/config.py

@@ -0,0 +1,203 @@
+"""Plugin configuration utilities."""
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+from synapse_sdk.utils.file import get_dict_from_file
+
+
+def read_plugin_config(plugin_path: Optional[Union[str, Path]] = None) -> Dict[str, Any]:
+    """Read plugin configuration from config.yaml file.
+
+    Args:
+        plugin_path: Path to plugin directory. If None, looks for config.yaml in current directory.
+
+    Returns:
+        Dict containing plugin configuration.
+
+    Raises:
+        FileNotFoundError: If config.yaml file is not found.
+        ValueError: If config.yaml is invalid.
+    """
+    config_file_name = 'config.yaml'
+    if plugin_path:
+        config_path = Path(plugin_path) / config_file_name
+    else:
+        config_path = config_file_name
+
+    try:
+        return get_dict_from_file(config_path)
+    except FileNotFoundError:
+        raise FileNotFoundError(f'Plugin config file not found: {config_path}')
+    except Exception as e:
+        raise ValueError(f'Invalid plugin config file: {e}')
+
+
+def get_plugin_actions(
+    config: Optional[Dict[str, Any]] = None, plugin_path: Optional[Union[str, Path]] = None
+) -> List[str]:
+    """Get list of action names from plugin configuration.
+
+    Args:
+        config: Plugin configuration dictionary. If None, reads from plugin_path.
+        plugin_path: Path to plugin directory. Used if config is None.
+
+    Returns:
+        List of action names defined in the plugin.
+
+    Raises:
+        ValueError: If neither config nor plugin_path is provided.
+        KeyError: If 'actions' key is missing from config.
+
+    Examples:
+        >>> get_plugin_actions(plugin_path="./my-plugin")
+        ['train', 'inference', 'test']
+
+        >>> config = {'actions': {'train': {...}, 'test': {...}}}
+        >>> get_plugin_actions(config=config)
+        ['train', 'test']
+    """
+    if config is None:
+        if plugin_path is None:
+            raise ValueError('Either config or plugin_path must be provided')
+        config = read_plugin_config(plugin_path)
+
+    if 'actions' not in config:
+        raise KeyError("'actions' key not found in plugin configuration")
+
+    actions = config['actions']
+    if not isinstance(actions, dict):
+        raise ValueError("'actions' must be a dictionary")
+
+    return list(actions.keys())
+
+
+def get_action_config(
+    action_name: str, config: Optional[Dict[str, Any]] = None, plugin_path: Optional[Union[str, Path]] = None
+) -> Dict[str, Any]:
+    """Get configuration for a specific action.
+
+    Args:
+        action_name: Name of the action to get config for.
+        config: Plugin configuration dictionary. If None, reads from plugin_path.
+        plugin_path: Path to plugin directory. Used if config is None.
+
+    Returns:
+        Dictionary containing action configuration.
+
+    Raises:
+        ValueError: If neither config nor plugin_path is provided.
+        KeyError: If action is not found in plugin configuration.
+
+    Examples:
+        >>> get_action_config('train', plugin_path="./my-plugin")
+        {'entrypoint': 'plugin.train.TrainAction', 'method': 'job'}
+    """
+    if config is None:
+        if plugin_path is None:
+            raise ValueError('Either config or plugin_path must be provided')
+        config = read_plugin_config(plugin_path)
+
+    if 'actions' not in config:
+        raise KeyError("'actions' key not found in plugin configuration")
+
+    actions = config['actions']
+    if action_name not in actions:
+        available_actions = list(actions.keys())
+        raise KeyError(f"Action '{action_name}' not found. Available actions: {available_actions}")
+
+    return actions[action_name]
+
+
+def validate_plugin_config(config: Dict[str, Any]) -> bool:
+    """Validate plugin configuration structure.
+
+    Args:
+        config: Plugin configuration dictionary to validate.
+
+    Returns:
+        True if configuration is valid.
+
+    Raises:
+        ValueError: If configuration is invalid with detailed error message.
+
+    Examples:
+        >>> config = {
+        ...     'name': 'My Plugin',
+        ...     'code': 'my-plugin',
+        ...     'version': '1.0.0',
+        ...     'category': 'neural_net',
+        ...     'actions': {'train': {'entrypoint': 'plugin.train.TrainAction'}}
+        ... }
+        >>> validate_plugin_config(config)
+        True
+    """
+    required_fields = ['name', 'code', 'version', 'category', 'actions']
+
+    # Check required fields
+    for field in required_fields:
+        if field not in config:
+            raise ValueError(f"Required field '{field}' missing from plugin configuration")
+
+    # Validate actions structure
+    actions = config['actions']
+    if not isinstance(actions, dict):
+        raise ValueError("'actions' must be a dictionary")
+
+    if not actions:
+        raise ValueError('Plugin must define at least one action')
+
+    # Validate each action
+    for action_name, action_config in actions.items():
+        if not isinstance(action_config, dict):
+            raise ValueError(f"Action '{action_name}' configuration must be a dictionary")
+
+        # Check for entrypoint (required for most actions)
+        if 'entrypoint' not in action_config and action_config.get('method') != 'restapi':
+            raise ValueError(f"Action '{action_name}' missing required 'entrypoint' field")
+
+    # Validate category
+    from synapse_sdk.plugins.enums import PluginCategory
+
+    valid_categories = [cat.value for cat in PluginCategory]
+    if config['category'] not in valid_categories:
+        raise ValueError(f"Invalid category '{config['category']}'. Must be one of: {valid_categories}")
+
+    return True
+
+
+def get_plugin_metadata(
+    config: Optional[Dict[str, Any]] = None, plugin_path: Optional[Union[str, Path]] = None
+) -> Dict[str, Any]:
+    """Get plugin metadata (name, version, description, etc.).
+
+    Args:
+        config: Plugin configuration dictionary. If None, reads from plugin_path.
+        plugin_path: Path to plugin directory. Used if config is None.
+
+    Returns:
+        Dictionary containing plugin metadata.
+
+    Examples:
+        >>> get_plugin_metadata(plugin_path="./my-plugin")
+        {
+            'name': 'My Plugin',
+            'code': 'my-plugin',
+            'version': '1.0.0',
+            'category': 'neural_net',
+            'description': 'A custom ML plugin'
+        }
+    """
+    if config is None:
+        if plugin_path is None:
+            raise ValueError('Either config or plugin_path must be provided')
+        config = read_plugin_config(plugin_path)
+
+    metadata_fields = ['name', 'code', 'version', 'category', 'description']
+    metadata = {}
+
+    for field in metadata_fields:
+        if field in config:
+            metadata[field] = config[field]
+
+    return metadata

synapse_sdk/plugins/{utils.py → utils/legacy.py}

@@ -1,58 +1,22 @@
-import json
+"""Legacy utility functions for backward compatibility."""
+
 from pathlib import Path
 
 from synapse_sdk.i18n import gettext as _
-from synapse_sdk.plugins.categories.registry import _REGISTERED_ACTIONS, register_actions
-from synapse_sdk.plugins.enums import PluginCategory
 from synapse_sdk.plugins.exceptions import ActionError
-from synapse_sdk.utils.file import get_dict_from_file
-
-
-def get_action(action, params_data, *args, **kwargs):
-    if isinstance(params_data, str):
-        try:
-            params = json.loads(params_data)
-        except json.JSONDecodeError:
-            params = get_dict_from_file(params_data)
-    else:
-        params = params_data
-
-    config_data = kwargs.pop('config', False)
-    if config_data:
-        if isinstance(config_data, str):
-            config = read_plugin_config(plugin_path=config_data)
-        else:
-            config = config_data
-    else:
-        config = read_plugin_config()
-    category = config['category']
-    return get_action_class(category, action)(params, config, *args, **kwargs)
-
 
-def get_action_class(category, action):
-    register_actions()
-    return _REGISTERED_ACTIONS[category][action]
+from .actions import get_action
 
 
-def get_available_actions(category):
-    register_actions()
-    return list(_REGISTERED_ACTIONS[category].keys())
-
-
-def get_plugin_categories():
-    return [plugin_category.value for plugin_category in PluginCategory]
-
-
-def read_plugin_config(plugin_path=None):
-    config_file_name = 'config.yaml'
-    if plugin_path:
-        config_path = Path(plugin_path) / config_file_name
-    else:
-        config_path = config_file_name
-    return get_dict_from_file(config_path)
+def read_requirements(file_path):
+    """Read and parse a requirements.txt file.
 
+    Args:
+        file_path: Path to the requirements.txt file
 
-def read_requirements(file_path):
+    Returns:
+        List of requirement strings, or None if file doesn't exist
+    """
     file_path = Path(file_path)
     if not file_path.exists():
         return None
@@ -76,6 +40,22 @@ def run_plugin(
     debug=False,
     **kwargs,
 ):
+    """Execute a plugin action with the specified parameters.
+
+    Args:
+        action: The action name to execute
+        params: Parameters for the action
+        plugin_config: Plugin configuration dictionary
+        plugin_path: Path to the plugin directory
+        modules: List of modules for debugging
+        requirements: List of requirements
+        envs: Environment variables dictionary
+        debug: Whether to run in debug mode
+        **kwargs: Additional keyword arguments
+
+    Returns:
+        Result of the action execution
+    """
     from synapse_sdk.plugins.models import PluginRelease
 
     if not envs:

synapse_sdk/plugins/utils/ray_gcs.py

@@ -0,0 +1,66 @@
+"""Utilities for converting HTTP URLs to Ray GCS URLs."""
+
+import tempfile
+from pathlib import Path
+
+
+def convert_http_to_ray_gcs(http_url: str) -> str:
+    """Convert HTTP URL to Ray GCS URL by downloading and uploading to Ray's GCS.
+
+    Ray's working_dir only accepts certain protocols (gcs://, s3://, gs://, https://).
+    When SYNAPSE_PLUGIN_STORAGE is an HTTP URL (Django media server), this function
+    converts it to a Ray-compatible gcs:// URL by:
+    1. Downloading the file from HTTP
+    2. Uploading it to Ray's Global Control Store (GCS)
+    3. Returning the content-addressable gcs:// URI
+
+    Args:
+        http_url: HTTP/HTTPS URL to plugin zip file
+
+    Returns:
+        gcs:// URL that Ray can use for working_dir
+        Example: "gcs://_ray_pkg_abc123def456.zip"
+
+    Raises:
+        RuntimeError: If Ray is not initialized or not installed
+        requests.exceptions.RequestException: If HTTP download fails
+
+    Note:
+        - Ray must be initialized (ray.init()) before calling this function
+        - The gcs:// URI is content-addressable (same file = same URI)
+        - Ray automatically deduplicates uploads via package_exists()
+    """
+    try:
+        import ray
+    except ImportError:
+        raise RuntimeError(
+            'Ray is not installed but is required for HTTP → GCS conversion. Install ray with: pip install ray'
+        )
+
+    if not ray.is_initialized():
+        raise RuntimeError(
+            'Ray must be initialized before converting HTTP URLs to GCS. '
+            'Call ray.init() before submitting jobs with HTTP storage.'
+        )
+
+    from ray._private.runtime_env.packaging import (
+        get_uri_for_package,
+        package_exists,
+        upload_package_to_gcs,
+    )
+
+    from synapse_sdk.plugins.upload import download_file
+
+    # Download HTTP file to temporary location
+    with tempfile.TemporaryDirectory() as temp_dir:
+        local_path = Path(download_file(http_url, temp_dir))
+
+        # Generate content-addressable gcs:// URI based on file content
+        gcs_uri = get_uri_for_package(local_path)
+
+        # Check if already exists in Ray GCS (deduplication)
+        if not package_exists(gcs_uri):
+            # Upload to Ray's Global Control Store
+            upload_package_to_gcs(gcs_uri, local_path.read_bytes())
+
+        return gcs_uri

synapse_sdk/plugins/utils/registry.py

@@ -0,0 +1,58 @@
+"""Plugin registry utilities."""
+
+from typing import List
+
+from synapse_sdk.plugins.enums import PluginCategory
+
+
+def get_plugin_categories() -> List[str]:
+    """Get list of all available plugin categories.
+
+    Returns:
+        List of plugin category names.
+
+    Examples:
+        >>> get_plugin_categories()
+        ['neural_net', 'export', 'upload', 'smart_tool', 'post_annotation', 'pre_annotation', 'data_validation']
+    """
+    return [plugin_category.value for plugin_category in PluginCategory]
+
+
+def is_valid_category(category: str) -> bool:
+    """Check if a category is valid.
+
+    Args:
+        category: Category name to validate.
+
+    Returns:
+        True if category is valid, False otherwise.
+
+    Examples:
+        >>> is_valid_category('neural_net')
+        True
+        >>> is_valid_category('invalid_category')
+        False
+    """
+    return category in get_plugin_categories()
+
+
+def get_category_display_name(category: str) -> str:
+    """Get human-readable display name for a category.
+
+    Args:
+        category: Category name.
+
+    Returns:
+        Human-readable category name.
+
+    Examples:
+        >>> get_category_display_name('neural_net')
+        'Neural Net'
+        >>> get_category_display_name('data_validation')
+        'Data Validation'
+    """
+    try:
+        plugin_category = PluginCategory(category)
+        return plugin_category.name.replace('_', ' ').title()
+    except ValueError:
+        return category.replace('_', ' ').title()

synapse_sdk/shared/__init__.py

@@ -0,0 +1,25 @@
+import os
+
+
+def needs_sentry_init():
+    return os.getenv('SENTRY_DSN') is not None
+
+
+def init_sentry():
+    import sentry_sdk
+    from sentry_sdk.integrations.ray import RayIntegration
+
+    dsn = os.getenv('SENTRY_DSN')
+    if dsn is None:
+        return
+
+    sentry_sdk.init(
+        dsn=dsn,
+        environment=os.getenv('DEPLOYMENT_TARGET', 'development'),
+        integrations=[RayIntegration()],
+        send_default_pii=True,
+    )
+
+
+def worker_process_setup_hook(*_, **__):
+    init_sentry()

synapse_sdk/shared/enums.py

@@ -2,7 +2,100 @@ from enum import Enum
 
 
 class Context(str, Enum):
+    """Context levels for logging and message categorization.
+
+    This enum defines different context levels that can be used for logging messages,
+    UI feedback, and other categorization purposes throughout the application.
+
+    Usage:
+        # In logging methods
+        self.log_message("Operation completed", context=Context.SUCCESS.value)
+        self.log_message("Warning: deprecated method", context=Context.WARNING.value)
+
+        # In LOG_MESSAGES dictionary
+        LOG_MESSAGES = {
+            'SUCCESS_CODE': {'message': 'Success!', 'level': Context.SUCCESS},
+            'ERROR_CODE': {'message': 'Error occurred', 'level': Context.DANGER},
+        }
+
+        # In UI components for styling/theming
+        if context == Context.DANGER:
+            render_error_style()
+        elif context == Context.SUCCESS:
+            render_success_style()
+
+    Attributes:
+        INFO: General informational messages (neutral)
+        SUCCESS: Success messages and positive outcomes
+        WARNING: Warning messages for non-critical issues
+        DANGER: Error messages and critical failures
+        ERROR: Legacy error context (use DANGER for new implementations)
+        DEBUG: Debug-level messages for development
+    """
+
     INFO = 'info'
     SUCCESS = 'success'
     WARNING = 'warning'
     DANGER = 'danger'
+    ERROR = 'error'
+    DEBUG = 'debug'
+
+
+class SupportedTools(Enum):
+    """Enum for supported annotation tools.
+
+    * TODO: Need dynamic configuration by referencing apps/annotation/categories/{file_type}/settings.py.
+        * Currently difficult to configure due to non-standardized prompt file types.
+    """
+
+    BOUNDING_BOX = 'bounding_box', 'bounding_box'
+    NAMED_ENTITY = 'named_entity', 'named_entity'
+    CLASSIFICATION = 'classification', 'classification'
+    POLYLINE = 'polyline', 'polyline'
+    KEYPOINT = 'keypoint', 'keypoint'
+    BOUNDING_BOX_3D = '3d_bounding_box', '3d_bounding_box'
+    IMAGE_SEGMENTATION = 'segmentation', 'image_segmentation'
+    VIDEO_SEGMENTATION = 'segmentation', 'video_segmentation'
+    SEGMENTATION_3D = '3d_segmentation', '3d_segmentation'
+    POLYGON = 'polygon', 'polygon'
+    RELATION = 'relation', 'relation'
+    GROUP = 'group', 'group'
+    PROMPT = 'prompt', 'prompt'
+    ANSWER = 'answer', 'answer'
+
+    def __init__(self, annotation_tool, method_name):
+        self.annotation_tool = annotation_tool
+        self.method_name = method_name
+
+    @classmethod
+    def get_all_values(cls):
+        """Get all tool values as a list."""
+        return [tool.value for tool in cls]
+
+    @classmethod
+    def get_tools_for_file_type(cls, file_type):
+        """Get tools supported for a specific file type."""
+        basic_tools = [cls.RELATION, cls.GROUP, cls.CLASSIFICATION]
+
+        if file_type == 'image':
+            basic_tools.extend([
+                cls.BOUNDING_BOX,
+                cls.POLYLINE,
+                cls.KEYPOINT,
+                cls.IMAGE_SEGMENTATION,
+                cls.POLYGON,
+            ])
+        elif file_type == 'video':
+            basic_tools.extend([
+                cls.BOUNDING_BOX,
+                cls.POLYLINE,
+                cls.KEYPOINT,
+                cls.VIDEO_SEGMENTATION,
+                cls.POLYGON,
+            ])
+        elif file_type == 'pcd':
+            basic_tools.extend([cls.BOUNDING_BOX_3D, cls.SEGMENTATION_3D])
+        elif file_type == 'text':
+            basic_tools.extend([cls.PROMPT, cls.ANSWER, cls.NAMED_ENTITY])
+
+        return basic_tools