synapse-sdk 1.0.0a11__py3-none-any.whl → 2026.1.1b2__py3-none-any.whl

synapse_sdk/plugins/config.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from synapse_sdk.plugins.enums import (
+    AnnotationCategory,
+    AnnotationType,
+    DataType,
+    PackageManager,
+    PluginCategory,
+    RunMethod,
+    SmartToolType,
+)
+
+
+class ActionConfig(BaseModel):
+    """Configuration for a single plugin action.
+
+    Attributes:
+        name: Action name (e.g., 'train', 'infer', 'export').
+        description: Human-readable description of the action.
+        entrypoint: Module path to action class (e.g., 'my_plugin.actions:TrainAction').
+        method: Execution method (job, task, or serve).
+        params_schema: Pydantic model class for parameter validation.
+        input_type: Semantic input type (e.g., 'yolo_dataset'). Auto-synced from code.
+        output_type: Semantic output type (e.g., 'model_weights'). Auto-synced from code.
+    """
+
+    name: str
+    description: str = ''
+    entrypoint: str = ''
+    method: RunMethod = RunMethod.TASK
+    params_schema: type[BaseModel] | None = None
+
+    # Semantic types for pipeline compatibility (auto-synced from action class)
+    input_type: str | None = None
+    output_type: str | None = None
+
+    model_config = {'arbitrary_types_allowed': True}
+
+
+class PluginConfig(BaseModel):
+    """Configuration for a plugin.
+
+    Attributes:
+        name: Human-readable plugin name.
+        code: Unique identifier for the plugin (e.g., 'yolov8').
+        version: Semantic version string.
+        category: Plugin category for organization.
+        description: Human-readable description.
+        readme: Path to README file relative to plugin root.
+        package_manager: Package manager for dependencies ('pip' or 'uv').
+        package_manager_options: Additional options for package manager.
+        wheels_dir: Directory containing .whl files for local installation (default: 'wheels').
+        env: Environment variables to inject into runtime environment.
+        runtime_env: Full Ray runtime_env configuration (merged with auto-generated settings).
+        data_type: Primary data type handled by the plugin.
+        tasks: List of tasks in format 'data_type.task_name' (e.g., 'image.object_detection').
+        supported_data_type: Data types supported by upload plugins.
+        annotation_category: Annotation category for smart tools.
+        annotation_type: Annotation type for smart tools.
+        smart_tool: Smart tool implementation type.
+        actions: Dictionary of action name to ActionConfig.
+    """
+
+    name: str
+    code: str
+    version: str = '0.1.0'
+    category: PluginCategory = PluginCategory.CUSTOM
+    description: str = ''
+    readme: str = 'README.md'
+
+    # Package management
+    package_manager: PackageManager = PackageManager.PIP
+    package_manager_options: list[str] = Field(default_factory=list)
+    wheels_dir: str = 'wheels'
+
+    # Runtime environment
+    env: dict[str, Any] = Field(default_factory=dict)
+    runtime_env: dict[str, Any] = Field(default_factory=dict)
+
+    # Data type configuration
+    data_type: DataType | None = None
+    tasks: list[str] = Field(default_factory=list)
+    supported_data_type: list[DataType] = Field(default_factory=list)
+
+    # Smart tool configuration
+    annotation_category: AnnotationCategory | None = None
+    annotation_type: AnnotationType | None = None
+    smart_tool: SmartToolType | None = None
+
+    # Actions
+    actions: dict[str, ActionConfig] = Field(default_factory=dict)
+
+
+__all__ = ['ActionConfig', 'PluginConfig']

synapse_sdk/plugins/context/__init__.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from synapse_sdk.plugins.context.env import PluginEnvironment
+
+if TYPE_CHECKING:
+    from synapse_sdk.clients.agent import AgentClient
+    from synapse_sdk.clients.backend import BackendClient
+    from synapse_sdk.loggers import BaseLogger
+
+
+@dataclass
+class RuntimeContext:
+    """Runtime context injected into actions.
+
+    Provides access to logging, environment, and client dependencies.
+    All action dependencies are accessed through this context object.
+
+    Attributes:
+        logger: Logger instance for progress, metrics, and event logging.
+        env: Environment variables and configuration as PluginEnvironment.
+        job_id: Optional job identifier for tracking.
+        client: Optional backend client for API access.
+        agent_client: Optional agent client for Ray operations.
+        checkpoint: Optional checkpoint info for pretrained models.
+            Contains 'category' ('base' or fine-tuned) and 'path' to model.
+
+    Example:
+        >>> ctx = RuntimeContext(
+        ...     logger=ConsoleLogger(),
+        ...     env=PluginEnvironment.from_environ(),
+        ...     job_id='job-123',
+        ...     checkpoint={'category': 'base', 'path': '/models/yolov8n.pt'},
+        ... )
+        >>> ctx.set_progress(50, 100)
+        >>> ctx.log('checkpoint', {'epoch': 5})
+    """
+
+    logger: BaseLogger
+    env: PluginEnvironment
+    job_id: str | None = None
+    client: BackendClient | None = None
+    agent_client: AgentClient | None = None
+    checkpoint: dict[str, Any] | None = None
+
+    def log(self, event: str, data: dict[str, Any], file: str | None = None) -> None:
+        """Log an event with data.
+
+        Args:
+            event: Event name/type.
+            data: Dictionary of event data.
+            file: Optional file path associated with the event.
+        """
+        from synapse_sdk.plugins.models.logger import LogLevel
+
+        self.logger.log(LogLevel.INFO, event, data, file)
+
+    def set_progress(self, current: int, total: int, category: str | None = None) -> None:
+        """Set progress for the current operation.
+
+        Args:
+            current: Current progress value (0 to total).
+            total: Total progress value.
+            category: Optional category name for multi-phase progress.
+        """
+        self.logger.set_progress(current, total, category)
+
+    def set_metrics(self, value: dict[str, Any], category: str) -> None:
+        """Set metrics for a category.
+
+        Args:
+            value: Dictionary of metric values.
+            category: Non-empty category name.
+        """
+        self.logger.set_metrics(value, category)
+
+    def log_message(self, message: str, context: str = 'info') -> None:
+        """Log a user-facing message.
+
+        Args:
+            message: Message content.
+            context: Message context/level ('info', 'warning', 'danger', 'success').
+        """
+        from synapse_sdk.plugins.models.logger import LogLevel
+
+        self.logger.log(LogLevel.INFO, 'message', {'context': context, 'content': message})
+
+    def log_dev_event(self, message: str, data: dict[str, Any] | None = None) -> None:
+        """Log a development/debug event.
+
+        For plugin developers to log custom events during execution.
+        Not shown to end users by default.
+
+        Args:
+            message: Event message.
+            data: Optional additional data.
+        """
+        from synapse_sdk.plugins.models.logger import LogLevel
+
+        self.logger.log(LogLevel.DEBUG, 'dev_event', {'message': message, 'data': data})
+
+    def end_log(self) -> None:
+        """Signal that plugin execution is complete."""
+        self.log_message('Plugin run is complete.')
+
+
+__all__ = ['PluginEnvironment', 'RuntimeContext']

synapse_sdk/plugins/context/env.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Any
+
+
+class PluginEnvironment:
+    """Environment configuration for plugin execution.
+
+    Auto-loads from:
+    1. os.environ (lowest priority)
+    2. Config file if provided (highest priority)
+
+    Example:
+        >>> env = PluginEnvironment.from_environ()
+        >>> env.get_str('API_KEY')
+        >>> env.get_int('BATCH_SIZE', default=32)
+        >>> env.get_bool('DEBUG', default=False)
+    """
+
+    def __init__(self, data: dict[str, Any] | None = None) -> None:
+        self._data: dict[str, Any] = data or {}
+
+    @classmethod
+    def from_environ(cls, prefix: str = '') -> PluginEnvironment:
+        """Load from os.environ, optionally filtering by prefix."""
+        data = {}
+        for key, value in os.environ.items():
+            if prefix and not key.startswith(prefix):
+                continue
+            clean_key = key[len(prefix) :] if prefix else key
+            data[clean_key] = value
+        return cls(data)
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> PluginEnvironment:
+        """Load from TOML config file."""
+        path = Path(path)
+        if not path.exists():
+            raise FileNotFoundError(f'Config file not found: {path}')
+        with path.open('rb') as f:
+            data = tomllib.load(f)
+        return cls(data)
+
+    @classmethod
+    def merge(cls, *envs: PluginEnvironment) -> PluginEnvironment:
+        """Merge multiple environments (later overrides earlier)."""
+        merged: dict[str, Any] = {}
+        for env in envs:
+            merged.update(env._data)
+        return cls(merged)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get raw value."""
+        return self._data.get(key, default)
+
+    def get_str(self, key: str, default: str | None = None) -> str | None:
+        """Get string value."""
+        val = self._data.get(key)
+        if val is None:
+            return default
+        return str(val)
+
+    def get_int(self, key: str, default: int | None = None) -> int | None:
+        """Get integer value."""
+        val = self._data.get(key)
+        if val is None:
+            return default
+        return int(val)
+
+    def get_float(self, key: str, default: float | None = None) -> float | None:
+        """Get float value."""
+        val = self._data.get(key)
+        if val is None:
+            return default
+        return float(val)
+
+    def get_bool(self, key: str, default: bool | None = None) -> bool | None:
+        """Get boolean value (handles string 'true'/'false')."""
+        val = self._data.get(key)
+        if val is None:
+            return default
+        if isinstance(val, bool):
+            return val
+        if isinstance(val, str):
+            return val.lower() in ('true', '1', 'yes')
+        return bool(val)
+
+    def get_list(self, key: str, default: list | None = None) -> list | None:
+        """Get list value (splits comma-separated strings)."""
+        val = self._data.get(key)
+        if val is None:
+            return default
+        if isinstance(val, list):
+            return val
+        if isinstance(val, str):
+            return [s.strip() for s in val.split(',') if s.strip()]
+        return default
+
+    def to_dict(self) -> dict[str, Any]:
+        """Export as dictionary."""
+        return dict(self._data)
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._data
+
+    def __getitem__(self, key: str) -> Any:
+        return self._data[key]
+
+
+__all__ = ['PluginEnvironment']

synapse_sdk/plugins/datasets/__init__.py

@@ -0,0 +1,113 @@
+"""Dataset formats and converters.
+
+This module provides:
+- Pydantic models for dataset formats (Datamaker v1/v2, YOLO)
+- Bidirectional converters between formats
+
+For dataset download and conversion workflows, use DatasetAction:
+    from synapse_sdk.plugins.actions import DatasetAction, DatasetParams
+
+For pipeline orchestration:
+    from synapse_sdk.plugins.pipelines import ActionPipeline
+
+Example:
+    >>> from synapse_sdk.plugins.datasets import (
+    ...     DatasetFormat,
+    ...     FromDMToYOLOConverter,
+    ...     DMVersion,
+    ... )
+    >>> from synapse_sdk.plugins.actions import DatasetAction
+    >>> from synapse_sdk.plugins.pipelines import ActionPipeline
+    >>>
+    >>> # Pipeline: Download | Convert | Train
+    >>> pipeline = ActionPipeline([DatasetAction, DatasetAction, TrainAction])
+"""
+
+from __future__ import annotations
+
+from synapse_sdk.plugins.datasets.converters import (
+    BaseConverter,
+    DatasetFormat,
+    FromDMConverter,
+    FromDMToYOLOConverter,
+    ToDMConverter,
+    YOLOToDMConverter,
+    get_converter,
+)
+from synapse_sdk.plugins.datasets.formats import (
+    # DM Shared
+    DMAttribute,
+    # DM Aliases (V2)
+    DMBoundingBox,
+    DMDataset,
+    DMGroup,
+    DMImageItem,
+    DMKeypoint,
+    DMPolygon,
+    DMPolyline,
+    DMRelation,
+    # DM V1
+    DMv1AnnotationBase,
+    DMv1Classification,
+    DMv1Dataset,
+    # DM V2
+    DMv2BoundingBox,
+    DMv2Dataset,
+    DMv2Group,
+    DMv2ImageItem,
+    DMv2Keypoint,
+    DMv2Polygon,
+    DMv2Polyline,
+    DMv2Relation,
+    # DM Version
+    DMVersion,
+    # YOLO
+    YOLOAnnotation,
+    YOLODataset,
+    YOLODatasetConfig,
+    YOLOImage,
+)
+
+__all__ = [
+    # DM Version
+    'DMVersion',
+    # DM Shared
+    'DMAttribute',
+    # DM V1
+    'DMv1AnnotationBase',
+    'DMv1Classification',
+    'DMv1Dataset',
+    # DM V2
+    'DMv2BoundingBox',
+    'DMv2Dataset',
+    'DMv2ImageItem',
+    'DMv2Keypoint',
+    'DMv2Polygon',
+    'DMv2Polyline',
+    'DMv2Relation',
+    'DMv2Group',
+    # DM Aliases (V2 default)
+    'DMBoundingBox',
+    'DMDataset',
+    'DMGroup',
+    'DMImageItem',
+    'DMKeypoint',
+    'DMPolygon',
+    'DMPolyline',
+    'DMRelation',
+    # YOLO Formats
+    'YOLOAnnotation',
+    'YOLODataset',
+    'YOLODatasetConfig',
+    'YOLOImage',
+    # Converters - Base
+    'BaseConverter',
+    'DatasetFormat',
+    'FromDMConverter',
+    'ToDMConverter',
+    # Converters - YOLO
+    'FromDMToYOLOConverter',
+    'YOLOToDMConverter',
+    # Converter factory
+    'get_converter',
+]

synapse_sdk/plugins/datasets/converters/__init__.py

@@ -0,0 +1,76 @@
+"""Dataset format converters.
+
+Structure:
+- base.py: BaseConverter, FromDMConverter, ToDMConverter
+- yolo/: YOLO format converters
+  - from_dm.py: DM -> YOLO
+  - to_dm.py: YOLO -> DM
+"""
+
+from synapse_sdk.plugins.datasets.converters.base import (
+    BaseConverter,
+    DatasetFormat,
+    FromDMConverter,
+    ToDMConverter,
+)
+from synapse_sdk.plugins.datasets.converters.yolo import (
+    FromDMToYOLOConverter,
+    YOLOToDMConverter,
+)
+
+
+def get_converter(
+    source: DatasetFormat | str,
+    target: DatasetFormat | str,
+    **kwargs,
+) -> BaseConverter:
+    """Get converter for source -> target format conversion.
+
+    Args:
+        source: Source dataset format.
+        target: Target dataset format.
+        **kwargs: Additional arguments passed to converter constructor.
+
+    Returns:
+        Converter instance.
+
+    Raises:
+        ValueError: If no converter exists for the format pair.
+
+    Example:
+        >>> converter = get_converter('dm_v2', 'yolo', is_categorized=True)
+        >>> converter.convert()
+        >>> converter.save_to_folder('/output')
+    """
+    source = DatasetFormat(source)
+    target = DatasetFormat(target)
+
+    # Map format pairs to converter classes
+    converters: dict[tuple[DatasetFormat, DatasetFormat], type[BaseConverter]] = {
+        # DM -> YOLO
+        (DatasetFormat.DM_V1, DatasetFormat.YOLO): FromDMToYOLOConverter,
+        (DatasetFormat.DM_V2, DatasetFormat.YOLO): FromDMToYOLOConverter,
+        # YOLO -> DM
+        (DatasetFormat.YOLO, DatasetFormat.DM_V1): YOLOToDMConverter,
+        (DatasetFormat.YOLO, DatasetFormat.DM_V2): YOLOToDMConverter,
+    }
+
+    converter_cls = converters.get((source, target))
+    if converter_cls is None:
+        raise ValueError(f'No converter available for {source} -> {target}')
+
+    return converter_cls(**kwargs)
+
+
+__all__ = [
+    # Base classes
+    'BaseConverter',
+    'DatasetFormat',
+    'FromDMConverter',
+    'ToDMConverter',
+    # YOLO converters
+    'FromDMToYOLOConverter',
+    'YOLOToDMConverter',
+    # Factory
+    'get_converter',
+]