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

synapse_sdk/plugins/steps/base.py

@@ -0,0 +1,128 @@
+"""Workflow step base class and result dataclass.
+
+Provides the foundation for defining workflow steps
+with execution, skip conditions, and rollback support.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from synapse_sdk.plugins.steps.context import BaseStepContext
+
+
+@dataclass
+class StepResult:
+    """Result of a workflow step execution.
+
+    Attributes:
+        success: Whether the step completed successfully.
+        data: Output data from the step.
+        error: Error message if step failed.
+        rollback_data: Data needed for rollback on failure.
+        skipped: Whether the step was skipped.
+        timestamp: When the step completed.
+
+    Example:
+        >>> result = StepResult(success=True, data={'files': 10})
+        >>> if not result.success:
+        ...     print(f"Failed: {result.error}")
+    """
+
+    success: bool = True
+    data: dict[str, Any] = field(default_factory=dict)
+    error: str | None = None
+    rollback_data: dict[str, Any] = field(default_factory=dict)
+    skipped: bool = False
+    timestamp: datetime = field(default_factory=datetime.now)
+
+
+class BaseStep[C: BaseStepContext](ABC):
+    """Abstract base class for workflow steps.
+
+    Type parameter C is the context type (must extend BaseStepContext).
+    Implement this class to define custom workflow steps with
+    execution, skip conditions, and rollback support.
+
+    Attributes:
+        name: Unique identifier for the step.
+        progress_weight: Relative weight (0.0-1.0) for progress calculation.
+
+    Example:
+        >>> class ValidateStep(BaseStep[MyContext]):
+        ...     @property
+        ...     def name(self) -> str:
+        ...         return 'validate'
+        ...
+        ...     @property
+        ...     def progress_weight(self) -> float:
+        ...         return 0.1
+        ...
+        ...     def execute(self, context: MyContext) -> StepResult:
+        ...         if not context.data:
+        ...             return StepResult(success=False, error='No data')
+        ...         return StepResult(success=True)
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Step identifier.
+
+        Returns:
+            Unique name for this step.
+        """
+        ...
+
+    @property
+    @abstractmethod
+    def progress_weight(self) -> float:
+        """Relative weight for progress calculation.
+
+        Returns:
+            Float between 0.0 and 1.0 representing this step's
+            portion of total workflow progress.
+        """
+        ...
+
+    @abstractmethod
+    def execute(self, context: C) -> StepResult:
+        """Execute the step.
+
+        Args:
+            context: Shared context with params and state.
+
+        Returns:
+            StepResult indicating success/failure and any output data.
+        """
+        ...
+
+    def can_skip(self, context: C) -> bool:
+        """Check if step can be skipped.
+
+        Override to implement conditional step execution.
+
+        Args:
+            context: Shared context.
+
+        Returns:
+            True if step should be skipped, False otherwise.
+            Default: False.
+        """
+        return False
+
+    def rollback(self, context: C, result: StepResult) -> None:
+        """Rollback step on workflow failure.
+
+        Override to implement cleanup when a later step fails.
+        Called in reverse order for all executed steps.
+
+        Args:
+            context: Shared context.
+            result: The result from this step's execution.
+        """
+        pass

synapse_sdk/plugins/steps/context.py

@@ -0,0 +1,90 @@
+"""Base context for step-based workflows.
+
+Provides the abstract base class for sharing state between workflow steps.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from synapse_sdk.plugins.context import RuntimeContext
+    from synapse_sdk.plugins.steps.base import StepResult
+
+
+@dataclass
+class BaseStepContext:
+    """Abstract base context for step-based workflows.
+
+    Provides the common interface for step contexts. Subclass this
+    to add action-specific state fields.
+
+    Attributes:
+        runtime_ctx: Parent RuntimeContext with logger, env, client.
+        step_results: Results from each executed step.
+        errors: Accumulated error messages.
+        current_step: Name of the currently executing step (set by Orchestrator).
+
+    Example:
+        >>> @dataclass
+        ... class UploadContext(BaseStepContext):
+        ...     params: dict[str, Any] = field(default_factory=dict)
+        ...     uploaded_files: list[str] = field(default_factory=list)
+        >>>
+        >>> ctx = UploadContext(runtime_ctx=runtime_ctx)
+        >>> ctx.log('upload_start', {'count': 10})
+    """
+
+    runtime_ctx: RuntimeContext
+    step_results: list[StepResult] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    current_step: str | None = field(default=None, init=False)
+
+    def _set_current_step(self, step_name: str | None) -> None:
+        """Set the currently executing step name (internal use by Orchestrator).
+
+        Args:
+            step_name: Name of the step being executed, or None to clear.
+        """
+        self.current_step = step_name
+
+    def log(self, event: str, data: dict[str, Any], file: str | None = None) -> None:
+        """Log an event via runtime context.
+
+        Args:
+            event: Event name/type.
+            data: Dictionary of event data.
+            file: Optional file path associated with the event.
+        """
+        self.runtime_ctx.log(event, data, file)
+
+    def set_progress(self, current: int, total: int, category: str | None = None) -> None:
+        """Set progress via runtime context.
+
+        If category is not provided, uses current_step as the category.
+
+        Args:
+            current: Current progress value.
+            total: Total progress value.
+            category: Optional category name. Defaults to current_step if not provided.
+        """
+        effective_category = category if category is not None else self.current_step
+        self.runtime_ctx.set_progress(current, total, effective_category)
+
+    def set_metrics(self, value: dict[str, Any], category: str | None = None) -> None:
+        """Set metrics via runtime context.
+
+        If category is not provided, uses current_step as the category.
+
+        Args:
+            value: Dictionary of metric values.
+            category: Category name. Defaults to current_step if not provided.
+
+        Raises:
+            ValueError: If category is not provided and current_step is None.
+        """
+        effective_category = category if category is not None else self.current_step
+        if effective_category is None:
+            raise ValueError('category must be provided when not executing within a step (current_step is None)')
+        self.runtime_ctx.set_metrics(value, effective_category)

synapse_sdk/plugins/steps/orchestrator.py

@@ -0,0 +1,128 @@
+"""Orchestrator for executing workflow steps with rollback support."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from synapse_sdk.plugins.steps.base import BaseStep, StepResult
+
+if TYPE_CHECKING:
+    from synapse_sdk.plugins.steps.context import BaseStepContext
+    from synapse_sdk.plugins.steps.registry import StepRegistry
+
+
+class Orchestrator[C: BaseStepContext]:
+    """Executes workflow steps with progress tracking and rollback.
+
+    Type parameter C is the context type shared between steps.
+    Runs steps in order, tracking progress based on step weights.
+    On failure, automatically rolls back executed steps in reverse order.
+
+    Attributes:
+        registry: StepRegistry containing ordered steps.
+        context: Shared context for step communication.
+        progress_callback: Optional callback for progress updates.
+
+    Example:
+        >>> registry = StepRegistry[MyContext]()
+        >>> registry.register(InitStep())
+        >>> registry.register(ProcessStep())
+        >>> context = MyContext(runtime_ctx=runtime_ctx)
+        >>> orchestrator = Orchestrator(registry, context)
+        >>> result = orchestrator.execute()
+    """
+
+    def __init__(
+        self,
+        registry: StepRegistry[C],
+        context: C,
+        progress_callback: Callable[[int, int], None] | None = None,
+    ) -> None:
+        """Initialize orchestrator.
+
+        Args:
+            registry: StepRegistry with steps to execute.
+            context: Shared context for steps.
+            progress_callback: Optional callback(current, total) for progress.
+        """
+        self._registry = registry
+        self._context = context
+        self._progress_callback = progress_callback
+        self._executed_steps: list[tuple[BaseStep[C], StepResult]] = []
+
+    def execute(self) -> dict[str, Any]:
+        """Execute all steps in order with rollback on failure.
+
+        Returns:
+            Dict with success status and step count.
+
+        Raises:
+            RuntimeError: If any step fails (after rollback).
+        """
+        steps = self._registry.get_steps()
+        total_weight = self._registry.total_weight
+        completed_weight = 0.0
+
+        try:
+            for step in steps:
+                # Set current step name for auto-category support
+                self._context._set_current_step(step.name)
+
+                # Check skip condition
+                if step.can_skip(self._context):
+                    result = StepResult(success=True, skipped=True)
+                    self._context.step_results.append(result)
+                    completed_weight += step.progress_weight
+                    self._update_progress(completed_weight, total_weight)
+                    continue
+
+                # Execute step
+                try:
+                    result = step.execute(self._context)
+                except Exception as e:
+                    result = StepResult(success=False, error=str(e))
+
+                self._context.step_results.append(result)
+                self._executed_steps.append((step, result))
+
+                if not result.success:
+                    self._rollback()
+                    raise RuntimeError(f"Step '{step.name}' failed: {result.error}")
+
+                # Update progress
+                completed_weight += step.progress_weight
+                self._update_progress(completed_weight, total_weight)
+
+            return {
+                'success': True,
+                'steps_executed': len(self._executed_steps),
+                'steps_total': len(steps),
+            }
+        finally:
+            # Clear current step after execution completes or fails
+            self._context._set_current_step(None)
+
+    def _update_progress(self, completed: float, total: float) -> None:
+        """Update progress via callback.
+
+        Args:
+            completed: Completed weight sum.
+            total: Total weight sum.
+        """
+        if self._progress_callback and total > 0:
+            progress_pct = int((completed / total) * 100)
+            self._progress_callback(progress_pct, 100)
+
+    def _rollback(self) -> None:
+        """Rollback executed steps in reverse order.
+
+        Best-effort rollback - errors during rollback are logged but
+        do not prevent other steps from rolling back.
+        """
+        for step, result in reversed(self._executed_steps):
+            try:
+                step.rollback(self._context, result)
+            except Exception:
+                # Best effort rollback - log but continue
+                self._context.errors.append(f"Rollback failed for step '{step.name}'")

synapse_sdk/plugins/steps/registry.py

@@ -0,0 +1,103 @@
+"""Step registry for managing ordered workflow steps."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from synapse_sdk.plugins.steps.base import BaseStep
+    from synapse_sdk.plugins.steps.context import BaseStepContext
+
+
+class StepRegistry[C: BaseStepContext]:
+    """Registry for managing ordered workflow steps.
+
+    Type parameter C is the context type for steps in this registry.
+    Maintains an ordered list of steps and provides methods for
+    registration, removal, and insertion at specific positions.
+
+    Example:
+        >>> registry = StepRegistry[MyContext]()
+        >>> registry.register(InitStep())
+        >>> registry.register(ProcessStep())
+        >>> registry.insert_before('process', ValidateStep())
+        >>> for step in registry.get_steps():
+        ...     print(step.name)  # init, validate, process
+    """
+
+    def __init__(self) -> None:
+        """Initialize empty registry."""
+        self._steps: list[BaseStep[C]] = []
+
+    def register(self, step: BaseStep[C]) -> None:
+        """Add step to end of workflow.
+
+        Args:
+            step: Step instance to register.
+        """
+        self._steps.append(step)
+
+    def unregister(self, name: str) -> None:
+        """Remove step by name.
+
+        Args:
+            name: Name of step to remove.
+        """
+        self._steps = [s for s in self._steps if s.name != name]
+
+    def get_steps(self) -> list[BaseStep[C]]:
+        """Get ordered list of steps.
+
+        Returns:
+            Copy of the step list in execution order.
+        """
+        return list(self._steps)
+
+    def insert_after(self, after_name: str, step: BaseStep[C]) -> None:
+        """Insert step after another step.
+
+        Args:
+            after_name: Name of existing step to insert after.
+            step: Step instance to insert.
+
+        Raises:
+            ValueError: If step with after_name not found.
+        """
+        for i, s in enumerate(self._steps):
+            if s.name == after_name:
+                self._steps.insert(i + 1, step)
+                return
+        raise ValueError(f"Step '{after_name}' not found")
+
+    def insert_before(self, before_name: str, step: BaseStep[C]) -> None:
+        """Insert step before another step.
+
+        Args:
+            before_name: Name of existing step to insert before.
+            step: Step instance to insert.
+
+        Raises:
+            ValueError: If step with before_name not found.
+        """
+        for i, s in enumerate(self._steps):
+            if s.name == before_name:
+                self._steps.insert(i, step)
+                return
+        raise ValueError(f"Step '{before_name}' not found")
+
+    @property
+    def total_weight(self) -> float:
+        """Sum of all step weights.
+
+        Returns:
+            Total progress weight across all registered steps.
+        """
+        return sum(s.progress_weight for s in self._steps)
+
+    def __len__(self) -> int:
+        """Return number of registered steps."""
+        return len(self._steps)
+
+    def __bool__(self) -> bool:
+        """Return True if any steps are registered."""
+        return bool(self._steps)

synapse_sdk/plugins/steps/utils/__init__.py

@@ -0,0 +1,20 @@
+"""Utility step wrappers for Synapse SDK.
+
+This module provides utility step wrappers that enhance step execution
+with additional functionality such as logging, timing, and validation.
+
+Classes:
+    LoggingStep: Wrapper that adds logging to step execution.
+    TimingStep: Wrapper that adds timing measurement to step execution.
+    ValidationStep: Wrapper that adds pre-execution validation to steps.
+"""
+
+from synapse_sdk.plugins.steps.utils.logging import LoggingStep
+from synapse_sdk.plugins.steps.utils.timing import TimingStep
+from synapse_sdk.plugins.steps.utils.validation import ValidationStep
+
+__all__ = [
+    'LoggingStep',
+    'TimingStep',
+    'ValidationStep',
+]

synapse_sdk/plugins/steps/utils/logging.py

@@ -0,0 +1,85 @@
+"""Logging step wrapper for workflow steps."""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+from synapse_sdk.plugins.steps.base import BaseStep, StepResult
+
+if TYPE_CHECKING:
+    from synapse_sdk.plugins.steps.context import BaseStepContext
+
+
+class LoggingStep[C: BaseStepContext](BaseStep[C]):
+    """Wraps a step with start/end logging including timing.
+
+    Logs step_start event before execution and step_end event after,
+    including elapsed time in seconds.
+
+    Example:
+        >>> logged_step = LoggingStep(MyProcessStep())
+        >>> registry.register(logged_step)
+        >>> # Logs: step_start {'step': 'process'}
+        >>> # Logs: step_end {'step': 'process', 'elapsed': 1.23, 'success': True}
+    """
+
+    def __init__(self, step: BaseStep[C]) -> None:
+        """Initialize with step to wrap.
+
+        Args:
+            step: The step to wrap with logging.
+        """
+        self._wrapped = step
+
+    @property
+    def name(self) -> str:
+        """Return wrapped step name with 'logged_' prefix."""
+        return f'logged_{self._wrapped.name}'
+
+    @property
+    def progress_weight(self) -> float:
+        """Return wrapped step's progress weight."""
+        return self._wrapped.progress_weight
+
+    def execute(self, context: C) -> StepResult:
+        """Execute wrapped step with logging.
+
+        Args:
+            context: Shared context.
+
+        Returns:
+            Result from wrapped step execution.
+        """
+        step_name = self._wrapped.name
+        context.log('step_start', {'step': step_name})
+
+        start = time.perf_counter()
+        result = self._wrapped.execute(context)
+        elapsed = time.perf_counter() - start
+
+        context.log(
+            'step_end',
+            {
+                'step': step_name,
+                'elapsed': round(elapsed, 3),
+                'success': result.success,
+                'skipped': result.skipped,
+            },
+        )
+
+        return result
+
+    def can_skip(self, context: C) -> bool:
+        """Delegate to wrapped step."""
+        return self._wrapped.can_skip(context)
+
+    def rollback(self, context: C, result: StepResult) -> None:
+        """Delegate rollback to wrapped step with logging.
+
+        Args:
+            context: Shared context.
+            result: Result from this step's execution.
+        """
+        context.log('step_rollback', {'step': self._wrapped.name})
+        self._wrapped.rollback(context, result)

synapse_sdk/plugins/steps/utils/timing.py

@@ -0,0 +1,71 @@
+"""Timing step wrapper for workflow steps."""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+from synapse_sdk.plugins.steps.base import BaseStep, StepResult
+
+if TYPE_CHECKING:
+    from synapse_sdk.plugins.steps.context import BaseStepContext
+
+
+class TimingStep[C: BaseStepContext](BaseStep[C]):
+    """Wraps a step with duration measurement.
+
+    Measures execution time and adds 'duration_seconds' to result data.
+
+    Example:
+        >>> timed_step = TimingStep(MyProcessStep())
+        >>> registry.register(timed_step)
+        >>> result = orchestrator.execute()
+        >>> print(result.data['duration_seconds'])  # 1.234
+    """
+
+    def __init__(self, step: BaseStep[C]) -> None:
+        """Initialize with step to wrap.
+
+        Args:
+            step: The step to wrap with timing.
+        """
+        self._wrapped = step
+
+    @property
+    def name(self) -> str:
+        """Return wrapped step name with 'timed_' prefix."""
+        return f'timed_{self._wrapped.name}'
+
+    @property
+    def progress_weight(self) -> float:
+        """Return wrapped step's progress weight."""
+        return self._wrapped.progress_weight
+
+    def execute(self, context: C) -> StepResult:
+        """Execute wrapped step with timing.
+
+        Args:
+            context: Shared context.
+
+        Returns:
+            Result from wrapped step with duration_seconds added.
+        """
+        start = time.perf_counter()
+        result = self._wrapped.execute(context)
+        elapsed = time.perf_counter() - start
+
+        result.data['duration_seconds'] = round(elapsed, 6)
+        return result
+
+    def can_skip(self, context: C) -> bool:
+        """Delegate to wrapped step."""
+        return self._wrapped.can_skip(context)
+
+    def rollback(self, context: C, result: StepResult) -> None:
+        """Delegate rollback to wrapped step.
+
+        Args:
+            context: Shared context.
+            result: Result from this step's execution.
+        """
+        self._wrapped.rollback(context, result)

synapse_sdk/plugins/steps/utils/validation.py

@@ -0,0 +1,68 @@
+"""Validation step for checking context state."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from synapse_sdk.plugins.steps.base import BaseStep, StepResult
+
+if TYPE_CHECKING:
+    from synapse_sdk.plugins.steps.context import BaseStepContext
+
+
+class ValidationStep[C: BaseStepContext](BaseStep[C]):
+    """Validates context state before proceeding.
+
+    Takes a validator function that checks context and returns
+    (is_valid, error_message). Fails the step if validation fails.
+
+    Example:
+        >>> def check_data(ctx: MyContext) -> tuple[bool, str | None]:
+        ...     if not ctx.data:
+        ...         return False, 'No data loaded'
+        ...     return True, None
+        >>>
+        >>> registry.register(ValidationStep(check_data, name='validate_data'))
+    """
+
+    def __init__(
+        self,
+        validator: Callable[[C], tuple[bool, str | None]],
+        name: str = 'validate',
+        progress_weight: float = 0.05,
+    ) -> None:
+        """Initialize validation step.
+
+        Args:
+            validator: Function that takes context and returns (is_valid, error).
+            name: Step name (default: 'validate').
+            progress_weight: Progress weight (default: 0.05).
+        """
+        self._validator = validator
+        self._name = name
+        self._progress_weight = progress_weight
+
+    @property
+    def name(self) -> str:
+        """Return step name."""
+        return self._name
+
+    @property
+    def progress_weight(self) -> float:
+        """Return progress weight."""
+        return self._progress_weight
+
+    def execute(self, context: C) -> StepResult:
+        """Execute validation.
+
+        Args:
+            context: Shared context to validate.
+
+        Returns:
+            StepResult with success=False if validation fails.
+        """
+        is_valid, error = self._validator(context)
+        if not is_valid:
+            return StepResult(success=False, error=error)
+        return StepResult(success=True)