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

synapse_sdk/mcp/tools/__init__.py

@@ -0,0 +1,6 @@
+"""MCP Tools for Synapse SDK.
+
+Tools are registered directly in server.py using @mcp.tool() decorators.
+This package exists for future organization if tools need to be split into
+separate modules.
+"""

synapse_sdk/plugins/__init__.py

@@ -1,13 +1,137 @@
-import os
+"""Plugin architecture for Synapse SDK.
 
-from dotenv import load_dotenv
+This module provides the core plugin framework including:
+- Plugin configuration and discovery
+- Action definition (class-based and function-based)
+- Execution modes (local, task, job)
+- Pipeline patterns (step-based workflows)
 
-from synapse_sdk.plugins.cli import cli
+Example:
+    >>> from synapse_sdk.plugins import action, run_plugin
+    >>> from pydantic import BaseModel
+    >>>
+    >>> class TrainParams(BaseModel):
+    ...     epochs: int = 10
+    >>>
+    >>> @action(params=TrainParams)
+    ... def train(params: TrainParams, context) -> dict:
+    ...     return {'trained': True}
+    >>>
+    >>> # Execute the plugin action
+    >>> result = run_plugin('my_plugin', 'train', {'epochs': 20})
+"""
 
+from synapse_sdk.plugins.action import BaseAction, NoResult, validate_result
+from synapse_sdk.plugins.actions import (
+    BaseDeploymentAction,
+    BaseExportAction,
+    BaseInferenceAction,
+    BaseServeDeployment,
+    BaseTrainAction,
+    BaseUploadAction,
+    DeploymentContext,
+    DeploymentProgressCategories,
+    ExportContext,
+    ExportProgressCategories,
+    InferenceContext,
+    InferenceProgressCategories,
+    TrainContext,
+    TrainProgressCategories,
+    UploadContext,
+    UploadProgressCategories,
+    create_serve_multiplexed_model_id,
+)
+from synapse_sdk.plugins.config import ActionConfig, PluginConfig
+from synapse_sdk.plugins.context import RuntimeContext
+from synapse_sdk.plugins.decorators import action
+from synapse_sdk.plugins.enums import PluginCategory
+from synapse_sdk.plugins.errors import (
+    ActionNotFoundError,
+    ExecutionError,
+    PluginError,
+    ValidationError,
+)
+from synapse_sdk.plugins.runner import run_plugin
+from synapse_sdk.plugins.schemas import (
+    ExportResult,
+    InferenceResult,
+    MetricsResult,
+    TrainResult,
+    UploadResult,
+    WeightsResult,
+)
+from synapse_sdk.plugins.steps import (
+    BaseStep,
+    BaseStepContext,
+    LoggingStep,
+    Orchestrator,
+    StepRegistry,
+    StepResult,
+    TimingStep,
+    ValidationStep,
+)
+from synapse_sdk.plugins.utils import get_action_ui_schema, pydantic_to_ui_schema
 
-def init():
-    load_dotenv(os.path.join(os.getcwd(), '.env'))
-    cli(obj={}, auto_envvar_prefix='SYNAPSE_PLUGIN')
-
-
-__all__ = ['init']
+__all__ = [
+    # Types
+    'PluginCategory',
+    # Config
+    'ActionConfig',
+    'PluginConfig',
+    # Context
+    'RuntimeContext',
+    # Errors
+    'ActionNotFoundError',
+    'ExecutionError',
+    'PluginError',
+    'ValidationError',
+    # Actions - Base
+    'BaseAction',
+    'NoResult',
+    'validate_result',
+    'action',
+    # Actions - Train
+    'BaseTrainAction',
+    'TrainContext',
+    'TrainProgressCategories',
+    # Actions - Export
+    'BaseExportAction',
+    'ExportContext',
+    'ExportProgressCategories',
+    # Actions - Upload
+    'BaseUploadAction',
+    'UploadContext',
+    'UploadProgressCategories',
+    # Actions - Inference
+    'BaseInferenceAction',
+    'InferenceContext',
+    'InferenceProgressCategories',
+    # Actions - Deployment
+    'BaseDeploymentAction',
+    'DeploymentContext',
+    'DeploymentProgressCategories',
+    # Ray Serve
+    'BaseServeDeployment',
+    'create_serve_multiplexed_model_id',
+    # Pipeline Steps
+    'BaseStep',
+    'BaseStepContext',
+    'StepResult',
+    'StepRegistry',
+    'Orchestrator',
+    'LoggingStep',
+    'TimingStep',
+    'ValidationStep',
+    # Runner
+    'run_plugin',
+    # Schema utilities
+    'pydantic_to_ui_schema',
+    'get_action_ui_schema',
+    # Result types
+    'ExportResult',
+    'InferenceResult',
+    'MetricsResult',
+    'TrainResult',
+    'UploadResult',
+    'WeightsResult',
+]

synapse_sdk/plugins/action.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Generic, TypeVar, get_args, get_origin
+
+from pydantic import BaseModel, ValidationError as PydanticValidationError
+
+from synapse_sdk.plugins.enums import PluginCategory
+from synapse_sdk.plugins.types import DataType
+
+if TYPE_CHECKING:
+    from synapse_sdk.plugins.context import RuntimeContext
+
+P = TypeVar('P', bound=BaseModel)
+
+_logger = logging.getLogger(__name__)
+
+
+class NoResult:
+    """Sentinel indicating no result schema is defined.
+
+    Used as the default for result_model to indicate that an action
+    does not have a typed result schema.
+
+    Example:
+        >>> class MyAction(BaseAction[MyParams]):
+        ...     pass  # result_model defaults to NoResult
+        >>>
+        >>> class TypedAction(BaseAction[MyParams]):
+        ...     result_model = MyResult  # Explicitly set result schema
+    """
+
+    pass
+
+
+class BaseAction(ABC, Generic[P]):
+    """Base class for plugin actions with typed params and optional result schema.
+
+    Supports typed input parameters via the generic parameter, and optional
+    typed output via the result_model class attribute.
+
+    Class Attributes:
+        action_name: Action name used for invocation (optional, from config.yaml).
+        category: Category for grouping actions (optional, from config.yaml).
+        input_type: DataType subclass declaring expected input (e.g., YOLODataset).
+        output_type: DataType subclass declaring produced output (e.g., ModelWeights).
+        params_model: Pydantic model class for input validation (auto-extracted from generic).
+        result_model: Pydantic model class for output validation (optional, defaults to NoResult).
+
+    Instance Attributes:
+        params: Pre-validated parameters (Pydantic model instance).
+        ctx: Runtime context with logger, env, etc.
+
+    Example (without result schema):
+        >>> class TrainParams(BaseModel):
+        ...     epochs: int = 10
+        >>>
+        >>> class TrainAction(BaseAction[TrainParams]):
+        ...     def execute(self) -> dict:
+        ...         return {'status': 'completed'}
+
+    Example (with type declarations):
+        >>> from synapse_sdk.plugins.types import YOLODataset, ModelWeights
+        >>>
+        >>> class TrainAction(BaseAction[TrainParams]):
+        ...     input_type = YOLODataset
+        ...     output_type = ModelWeights
+        ...     result_model = TrainResult
+        ...
+        ...     def execute(self) -> TrainResult:
+        ...         return TrainResult(weights_path='/model.pt', final_loss=0.1)
+    """
+
+    # Optional: injected from config.yaml during discovery if not set
+    action_name: str | None = None
+    category: PluginCategory | None = None
+
+    # Semantic types for pipeline compatibility validation
+    # Use DataType subclasses for type-safe declarations
+    input_type: type[DataType] | None = None
+    output_type: type[DataType] | None = None
+
+    # Auto-extracted from generic parameter, can be overridden
+    params_model: type[P]
+
+    # Optional: set to a Pydantic model to enable result validation
+    result_model: type[BaseModel] | type[NoResult] = NoResult
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Extract params_model from generic type parameter."""
+        super().__init_subclass__(**kwargs)
+
+        # Skip if params_model is explicitly set
+        if 'params_model' in cls.__dict__:
+            return
+
+        # Extract from generic parameter: BaseAction[TrainParams] -> TrainParams
+        for base in getattr(cls, '__orig_bases__', ()):
+            origin = get_origin(base)
+            if origin is None:
+                continue
+
+            # Check if this base is BaseAction or a subclass
+            if isinstance(origin, type) and issubclass(origin, BaseAction):
+                args = get_args(base)
+                if args and isinstance(args[0], type) and issubclass(args[0], BaseModel):
+                    cls.params_model = args[0]
+                    return
+
+    def __init__(self, params: P, ctx: RuntimeContext) -> None:
+        """Initialize action with validated params and runtime context.
+
+        Args:
+            params: Pre-validated Pydantic model instance.
+            ctx: Runtime context with logger, env, etc.
+        """
+        self.params = params
+        self.ctx = ctx
+
+    @abstractmethod
+    def execute(self) -> Any:
+        """Execute the action.
+
+        Implement this method with your action's main logic.
+        Use self.params for input and self.ctx for dependencies.
+
+        Returns:
+            Action result (should be serializable).
+
+        Raises:
+            ExecutionError: If execution fails.
+        """
+        ...
+
+    @property
+    def logger(self):
+        """Access the logger from context."""
+        return self.ctx.logger
+
+    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.
+        """
+        self.ctx.log(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.ctx.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.ctx.set_metrics(value, category)
+
+
+def validate_result(
+    result: Any,
+    result_model: type[BaseModel] | type[NoResult],
+    logger: Any = None,
+) -> Any:
+    """Validate action result against schema with warning-only mode.
+
+    This function validates the result returned by an action's execute() method
+    against its declared result_model schema. If validation fails, it logs a
+    warning but still returns the original result (warning-only mode).
+
+    Args:
+        result: The raw result from execute().
+        result_model: The expected Pydantic model, or NoResult to skip validation.
+        logger: Optional logger for warnings. Falls back to module logger if None.
+
+    Returns:
+        The original result (unchanged even if validation fails).
+
+    Example:
+        >>> class MyResult(BaseModel):
+        ...     value: int
+        >>>
+        >>> result = validate_result({'value': 42}, MyResult)
+        >>> # No warning, result passes validation
+        >>>
+        >>> result = validate_result({'wrong': 'data'}, MyResult)
+        >>> # Logs warning, returns {'wrong': 'data'} unchanged
+    """
+    if result_model is NoResult:
+        return result
+
+    log = logger if logger else _logger
+
+    try:
+        # If result is already the correct model instance, it's valid
+        if isinstance(result, result_model):
+            return result
+
+        # If result is a dict, try to validate it against the model
+        if isinstance(result, dict):
+            result_model.model_validate(result)
+        else:
+            # Result is neither a model instance nor a dict
+            if hasattr(log, 'warning'):
+                log.warning(
+                    f'Result type mismatch: expected {result_model.__name__} or dict, got {type(result).__name__}'
+                )
+    except PydanticValidationError as e:
+        if hasattr(log, 'warning'):
+            log.warning(f'Result validation warning for {result_model.__name__}: {e}')
+    except Exception as e:
+        if hasattr(log, 'warning'):
+            log.warning(f'Result validation failed: {e}')
+
+    return result
+
+
+__all__ = ['BaseAction', 'NoResult', 'validate_result']

synapse_sdk/plugins/actions/__init__.py

@@ -0,0 +1,82 @@
+"""Category-specific action base classes.
+
+Provides specialized base classes for common action types:
+    - DatasetAction: Download and convert dataset workflows
+    - BaseTrainAction: Training workflows with dataset/model helpers
+    - BaseExportAction: Export workflows with filtered results
+    - BaseUploadAction: Upload workflows with step-based execution
+    - BaseInferenceAction: Inference workflows with model loading
+    - BaseDeploymentAction: Ray Serve deployment workflows
+
+Each base class provides:
+    - Standard progress category names
+    - Helper methods with sensible defaults
+    - Override points for custom behavior
+    - Optional step-based workflow execution
+
+For pipeline orchestration, use the pipelines module:
+    from synapse_sdk.plugins.pipelines import ActionPipeline
+"""
+
+from synapse_sdk.plugins.actions.dataset import (
+    DatasetAction,
+    DatasetOperation,
+    DatasetParams,
+    DatasetResult,
+)
+from synapse_sdk.plugins.actions.export import (
+    BaseExportAction,
+    ExportContext,
+    ExportProgressCategories,
+)
+from synapse_sdk.plugins.actions.inference import (
+    BaseDeploymentAction,
+    BaseInferenceAction,
+    BaseServeDeployment,
+    DeploymentContext,
+    DeploymentProgressCategories,
+    InferenceContext,
+    InferenceProgressCategories,
+    create_serve_multiplexed_model_id,
+)
+from synapse_sdk.plugins.actions.train import (
+    BaseTrainAction,
+    TrainContext,
+    TrainProgressCategories,
+)
+from synapse_sdk.plugins.actions.upload import (
+    BaseUploadAction,
+    UploadContext,
+    UploadProgressCategories,
+)
+
+__all__ = [
+    # Dataset
+    'DatasetAction',
+    'DatasetOperation',
+    'DatasetParams',
+    'DatasetResult',
+    # Train
+    'BaseTrainAction',
+    'TrainContext',
+    'TrainProgressCategories',
+    # Export
+    'BaseExportAction',
+    'ExportContext',
+    'ExportProgressCategories',
+    # Upload
+    'BaseUploadAction',
+    'UploadContext',
+    'UploadProgressCategories',
+    # Inference
+    'BaseInferenceAction',
+    'InferenceContext',
+    'InferenceProgressCategories',
+    # Deployment
+    'BaseDeploymentAction',
+    'DeploymentContext',
+    'DeploymentProgressCategories',
+    # Serve
+    'BaseServeDeployment',
+    'create_serve_multiplexed_model_id',
+]

synapse_sdk/plugins/actions/dataset/__init__.py

@@ -0,0 +1,37 @@
+"""Dataset actions for download and conversion workflows.
+
+Provides a single DatasetAction that can perform either download or convert
+operations based on the operation parameter. This allows for flexible
+pipeline composition.
+
+Example:
+    >>> from synapse_sdk.plugins.pipelines import ActionPipeline
+    >>> from synapse_sdk.plugins.actions.dataset import DatasetAction
+    >>>
+    >>> # Create a download -> convert pipeline
+    >>> pipeline = ActionPipeline([
+    ...     DatasetAction,  # operation='download'
+    ...     DatasetAction,  # operation='convert', uses path from download
+    ...     TrainAction,
+    ... ])
+    >>>
+    >>> result = pipeline.execute({
+    ...     'operation': 'download',
+    ...     'dataset_id': 123,
+    ...     'target_format': 'yolo',  # for convert step
+    ... }, ctx)
+"""
+
+from synapse_sdk.plugins.actions.dataset.action import (
+    DatasetAction,
+    DatasetOperation,
+    DatasetParams,
+    DatasetResult,
+)
+
+__all__ = [
+    'DatasetAction',
+    'DatasetOperation',
+    'DatasetParams',
+    'DatasetResult',
+]