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

synapse_sdk/plugins/categories/pre_annotation/actions/to_task/action.py

@@ -0,0 +1,145 @@
+"""Refactored ToTask action using Strategy and Facade patterns."""
+
+from typing import Dict
+
+from synapse_sdk.clients.backend import BackendClient
+from synapse_sdk.clients.backend.models import JobStatus
+from synapse_sdk.plugins.categories.base import Action
+from synapse_sdk.plugins.categories.decorators import register_action
+from synapse_sdk.plugins.enums import PluginCategory, RunMethod
+
+from .enums import LogCode
+from .exceptions import PreAnnotationToTaskFailed
+from .models import ToTaskParams, ToTaskResult
+from .orchestrator import ToTaskOrchestrator
+from .run import ToTaskRun
+from .strategies.base import ToTaskContext
+
+
+@register_action
+class ToTaskAction(Action):
+    """ToTask action for pre-annotation data processing using Strategy and Facade patterns.
+
+    This action handles the process of annotating data to tasks in a project. It supports
+    two annotation methods: file-based annotation and inference-based annotation.
+
+    The action uses a Strategy pattern to handle different annotation methods and validation
+    approaches, coordinated by an Orchestrator (Facade pattern) that manages the complete
+    workflow with rollback capabilities.
+
+    File-based annotation fetches data from file URLs specified in task data units,
+    downloads and processes JSON data, and updates task data with the processed information.
+    It also validates target specification names against file specifications.
+
+    Inference-based annotation uses pre-processor plugins for model inference
+    for automatic data annotation.
+
+    Attrs:
+        name (str): Action name, set to 'to_task'.
+        category (PluginCategory): Plugin category, set to PRE_ANNOTATION.
+        method (RunMethod): Execution method, set to JOB.
+        run_class (Type[ToTaskRun]): Run class for this action.
+        params_model (Type[ToTaskParams]): Parameter validation model.
+        progress_categories (Dict): Progress tracking configuration.
+        metrics_categories (Set[str]): Metrics categories for this action.
+
+    Note:
+        This action requires a valid project with an associated data collection.
+        For file-based annotation, the target_specification_name must exist in the
+        project's file specifications.
+
+    Raises:
+        ValueError: If run instance or parameters are not properly initialized.
+        PreAnnotationToTaskFailed: If the annotation workflow fails.
+    """
+
+    name = 'to_task'
+    category = PluginCategory.PRE_ANNOTATION
+    method = RunMethod.JOB
+    run_class = ToTaskRun
+    params_model = ToTaskParams
+    progress_categories = {
+        'annotate_task_data': {
+            'proportion': 100,
+        },
+    }
+    metrics_categories = {
+        'annotate_task_data': {
+            'stand_by': 0,
+            'failed': 0,
+            'success': 0,
+        }
+    }
+
+    def __init__(self, *args, **kwargs):
+        """Initialize the action with orchestrator context."""
+        super().__init__(*args, **kwargs)
+        self.context = None
+
+    def start(self) -> Dict:
+        """Start to_task action using orchestrator facade.
+
+        The action now uses a simplified workflow:
+        1. Validate initialization
+        2. Create execution context
+        3. Execute workflow through orchestrator
+        4. Handle results and errors
+
+        Returns:
+            dict: Validated result with status and message.
+        """
+        # Validate initialization
+        if not self.run or not self.params:
+            result = ToTaskResult(
+                status=JobStatus.FAILED, message='Run instance or parameters not properly initialized'
+            )
+            raise PreAnnotationToTaskFailed(result.message)
+
+        # Type assertions for better IDE support
+        assert isinstance(self.run, ToTaskRun)
+        assert isinstance(self.run.client, BackendClient)
+
+        # Log action start
+        self.run.log_message_with_code(LogCode.TO_TASK_STARTED)
+
+        try:
+            # Create execution context
+            self.context = ToTaskContext(
+                params=self.params,
+                client=self.run.client,
+                logger=self.run,
+                entrypoint=self.entrypoint,
+                config=self.config,
+                plugin_config=self.plugin_config,
+                job_id=self.job_id,
+                progress_categories=self.progress_categories,
+                metrics_categories=self.metrics_categories,
+            )
+
+            # Create and execute orchestrator
+            orchestrator = ToTaskOrchestrator(self.context)
+            result = orchestrator.execute_workflow()
+
+            # Log successful completion
+            self.run.log_message_with_code(LogCode.TO_TASK_COMPLETED)
+            return result
+
+        except PreAnnotationToTaskFailed as e:
+            # Re-raise pre-annotation specific errors
+            self.run.log_message_with_code(LogCode.TO_TASK_FAILED, str(e))
+            raise e
+
+        except Exception as e:
+            # Handle unexpected errors
+            error_msg = f'ToTask action failed: {str(e)}'
+            self.run.log_message_with_code(LogCode.TO_TASK_FAILED, error_msg)
+            result = ToTaskResult(status=JobStatus.FAILED, message=error_msg)
+            raise PreAnnotationToTaskFailed(result.message)
+
+    def get_context(self) -> ToTaskContext:
+        """Get the current execution context for testing/debugging.
+
+        Returns:
+            ToTaskContext: The current execution context, or None if not initialized.
+        """
+        return self.context

synapse_sdk/plugins/categories/pre_annotation/actions/to_task/enums.py

@@ -0,0 +1,269 @@
+from enum import Enum
+
+from synapse_sdk.shared.enums import Context
+
+
+class AnnotationMethod(str, Enum):
+    FILE = 'file'
+    INFERENCE = 'inference'
+
+
+class AnnotateTaskDataStatus(str, Enum):
+    SUCCESS = 'success'
+    FAILED = 'failed'
+
+
+class LogCode(str, Enum):
+    """Type-safe logging codes for to_task operations.
+
+    Enumeration of all possible log events during to_task processing. Each code
+    corresponds to a specific event or error state with predefined message
+    templates and log levels.
+
+    The codes are organized by category:
+    - Validation codes (INVALID_PROJECT_RESPONSE, NO_DATA_COLLECTION, etc.)
+    - Processing codes (ANNOTATING_DATA, ANNOTATION_COMPLETED, etc.)
+    - Error codes (CRITICAL_ERROR, TASK_PROCESSING_FAILED, etc.)
+    - Inference codes (ANNOTATING_INFERENCE_DATA, INFERENCE_PROCESSING_FAILED, etc.)
+    """
+
+    INVALID_PROJECT_RESPONSE = 'INVALID_PROJECT_RESPONSE'
+    NO_DATA_COLLECTION = 'NO_DATA_COLLECTION'
+    INVALID_DATA_COLLECTION_RESPONSE = 'INVALID_DATA_COLLECTION_RESPONSE'
+    NO_TASKS_FOUND = 'NO_TASKS_FOUND'
+    TARGET_SPEC_REQUIRED = 'TARGET_SPEC_REQUIRED'
+    TARGET_SPEC_NOT_FOUND = 'TARGET_SPEC_NOT_FOUND'
+    UNSUPPORTED_METHOD = 'UNSUPPORTED_METHOD'
+    ANNOTATING_DATA = 'ANNOTATING_DATA'
+    CRITICAL_ERROR = 'CRITICAL_ERROR'
+    TASK_PROCESSING_FAILED = 'TASK_PROCESSING_FAILED'
+    ANNOTATION_COMPLETED = 'ANNOTATION_COMPLETED'
+    INVALID_TASK_RESPONSE = 'INVALID_TASK_RESPONSE'
+    TARGET_SPEC_REQUIRED_FOR_TASK = 'TARGET_SPEC_REQUIRED_FOR_TASK'
+    UNSUPPORTED_METHOD_FOR_TASK = 'UNSUPPORTED_METHOD_FOR_TASK'
+    PRIMARY_IMAGE_URL_NOT_FOUND = 'PRIMARY_IMAGE_URL_NOT_FOUND'
+    FILE_SPEC_NOT_FOUND = 'FILE_SPEC_NOT_FOUND'
+    FILE_ORIGINAL_NAME_NOT_FOUND = 'FILE_ORIGINAL_NAME_NOT_FOUND'
+    URL_NOT_FOUND = 'URL_NOT_FOUND'
+    FETCH_DATA_FAILED = 'FETCH_DATA_FAILED'
+    CONVERT_DATA_FAILED = 'CONVERT_DATA_FAILED'
+    PREPROCESSOR_ID_REQUIRED = 'PREPROCESSOR_ID_REQUIRED'
+    INFERENCE_PROCESSING_FAILED = 'INFERENCE_PROCESSING_FAILED'
+    ANNOTATING_INFERENCE_DATA = 'ANNOTATING_INFERENCE_DATA'
+    INFERENCE_ANNOTATION_COMPLETED = 'INFERENCE_ANNOTATION_COMPLETED'
+    INFERENCE_PREPROCESSOR_FAILED = 'INFERENCE_PREPROCESSOR_FAILED'
+
+    # Orchestrator workflow codes
+    TO_TASK_STARTED = 'TO_TASK_STARTED'
+    TO_TASK_COMPLETED = 'TO_TASK_COMPLETED'
+    TO_TASK_FAILED = 'TO_TASK_FAILED'
+    STEP_STARTED = 'STEP_STARTED'
+    STEP_COMPLETED = 'STEP_COMPLETED'
+    STEP_FAILED = 'STEP_FAILED'
+    ROLLBACK_FAILED = 'ROLLBACK_FAILED'
+    ROLLBACK_ACTION_FAILED = 'ROLLBACK_ACTION_FAILED'
+
+    # Additional strategy codes
+    VALIDATION_FAILED = 'VALIDATION_FAILED'
+    NO_DATA_UNIT = 'NO_DATA_UNIT'
+    NO_DATA_UNIT_FILES = 'NO_DATA_UNIT_FILES'
+    TARGET_SPEC_URL_NOT_FOUND = 'TARGET_SPEC_URL_NOT_FOUND'
+    DATA_DOWNLOAD_FAILED = 'DATA_DOWNLOAD_FAILED'
+    JSON_DECODE_FAILED = 'JSON_DECODE_FAILED'
+    ANNOTATION_SUBMISSION_FAILED = 'ANNOTATION_SUBMISSION_FAILED'
+    NO_PREPROCESSOR_ID = 'NO_PREPROCESSOR_ID'
+    DATA_EXTRACTION_FAILED = 'DATA_EXTRACTION_FAILED'
+    PROGRESS_UPDATE_FAILED = 'PROGRESS_UPDATE_FAILED'
+    METRICS_RECORDING_FAILED = 'METRICS_RECORDING_FAILED'
+    METRICS_UPDATE_FAILED = 'METRICS_UPDATE_FAILED'
+    METRICS_FINALIZATION_FAILED = 'METRICS_FINALIZATION_FAILED'
+
+
+LOG_MESSAGES = {
+    LogCode.INVALID_PROJECT_RESPONSE: {
+        'message': 'Invalid project response received.',
+        'level': Context.DANGER,
+    },
+    LogCode.NO_DATA_COLLECTION: {
+        'message': 'Project does not have a data collection.',
+        'level': Context.DANGER,
+    },
+    LogCode.INVALID_DATA_COLLECTION_RESPONSE: {
+        'message': 'Invalid data collection response received.',
+        'level': Context.DANGER,
+    },
+    LogCode.NO_TASKS_FOUND: {
+        'message': 'Tasks to annotate not found.',
+        'level': Context.WARNING,
+    },
+    LogCode.TARGET_SPEC_REQUIRED: {
+        'message': 'Target specification name is required for file annotation method.',
+        'level': Context.DANGER,
+    },
+    LogCode.TARGET_SPEC_NOT_FOUND: {
+        'message': 'Target specification name "{}" not found in file specifications',
+        'level': Context.DANGER,
+    },
+    LogCode.UNSUPPORTED_METHOD: {
+        'message': 'Unsupported annotation method: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.ANNOTATING_DATA: {
+        'message': 'Annotating data to tasks...',
+        'level': None,
+    },
+    LogCode.CRITICAL_ERROR: {
+        'message': 'Critical error occured while processing task. Stopping the job.',
+        'level': Context.DANGER,
+    },
+    LogCode.TASK_PROCESSING_FAILED: {
+        'message': 'Failed to process task {}: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.ANNOTATION_COMPLETED: {
+        'message': 'Annotation completed. Success: {}, Failed: {}',
+        'level': None,
+    },
+    LogCode.INVALID_TASK_RESPONSE: {
+        'message': 'Invalid task response received for task {}',
+        'level': Context.DANGER,
+    },
+    LogCode.TARGET_SPEC_REQUIRED_FOR_TASK: {
+        'message': 'Target specification name is required for file annotation method for task {}',
+        'level': Context.DANGER,
+    },
+    LogCode.UNSUPPORTED_METHOD_FOR_TASK: {
+        'message': 'Unsupported annotation method: {} for task {}',
+        'level': Context.DANGER,
+    },
+    LogCode.PRIMARY_IMAGE_URL_NOT_FOUND: {
+        'message': 'Primary image URL not found in task data for task {}',
+        'level': Context.DANGER,
+    },
+    LogCode.FILE_SPEC_NOT_FOUND: {
+        'message': 'File specification not found for task {}',
+        'level': Context.DANGER,
+    },
+    LogCode.FILE_ORIGINAL_NAME_NOT_FOUND: {
+        'message': 'File original name not found for task {}',
+        'level': Context.DANGER,
+    },
+    LogCode.URL_NOT_FOUND: {
+        'message': 'URL not found for task {}',
+        'level': Context.DANGER,
+    },
+    LogCode.FETCH_DATA_FAILED: {
+        'message': 'Failed to fetch data from URL: {} for task {}',
+        'level': Context.DANGER,
+    },
+    LogCode.CONVERT_DATA_FAILED: {
+        'message': 'Failed to convert data to task object: {} for task {}',
+        'level': Context.DANGER,
+    },
+    LogCode.PREPROCESSOR_ID_REQUIRED: {
+        'message': 'Pre-processor ID is required for inference annotation method for task {}',
+        'level': Context.DANGER,
+    },
+    LogCode.INFERENCE_PROCESSING_FAILED: {
+        'message': 'Failed to process inference for task {}: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.ANNOTATING_INFERENCE_DATA: {
+        'message': 'Annotating data to tasks using inference...',
+        'level': None,
+    },
+    LogCode.INFERENCE_ANNOTATION_COMPLETED: {
+        'message': 'Inference annotation completed. Success: {}, Failed: {}',
+        'level': None,
+    },
+    LogCode.INFERENCE_PREPROCESSOR_FAILED: {
+        'message': 'Inference pre processor failed for task {}: {}',
+        'level': Context.DANGER,
+    },
+    # Orchestrator workflow messages
+    LogCode.TO_TASK_STARTED: {
+        'message': 'ToTask action started.',
+        'level': Context.INFO,
+    },
+    LogCode.TO_TASK_COMPLETED: {
+        'message': 'ToTask action completed successfully.',
+        'level': Context.SUCCESS,
+    },
+    LogCode.TO_TASK_FAILED: {
+        'message': 'ToTask action failed: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.STEP_STARTED: {
+        'message': 'Starting workflow step: {}',
+        'level': Context.INFO,
+    },
+    LogCode.STEP_COMPLETED: {
+        'message': 'Completed workflow step: {}',
+        'level': Context.INFO,
+    },
+    LogCode.STEP_FAILED: {
+        'message': 'Failed workflow step {}: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.ROLLBACK_FAILED: {
+        'message': 'Failed to rollback step {}: {}',
+        'level': Context.WARNING,
+    },
+    LogCode.ROLLBACK_ACTION_FAILED: {
+        'message': 'Failed to execute rollback action: {}',
+        'level': Context.WARNING,
+    },
+    # Additional strategy messages
+    LogCode.VALIDATION_FAILED: {
+        'message': 'Validation failed: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.NO_DATA_UNIT: {
+        'message': 'Task does not have a data unit',
+        'level': Context.DANGER,
+    },
+    LogCode.NO_DATA_UNIT_FILES: {
+        'message': 'Data unit does not have files',
+        'level': Context.DANGER,
+    },
+    LogCode.TARGET_SPEC_URL_NOT_FOUND: {
+        'message': 'Target specification URL not found for {} in task {}',
+        'level': Context.DANGER,
+    },
+    LogCode.DATA_DOWNLOAD_FAILED: {
+        'message': 'Failed to download data for task {}: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.JSON_DECODE_FAILED: {
+        'message': 'Failed to decode JSON data for task {}: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.ANNOTATION_SUBMISSION_FAILED: {
+        'message': 'Failed to submit annotation data for task {}: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.NO_PREPROCESSOR_ID: {
+        'message': 'Pre-processor ID is required for inference annotation method',
+        'level': Context.DANGER,
+    },
+    LogCode.DATA_EXTRACTION_FAILED: {
+        'message': 'Data extraction failed: {}',
+        'level': Context.DANGER,
+    },
+    LogCode.PROGRESS_UPDATE_FAILED: {
+        'message': 'Progress update failed: {}',
+        'level': Context.WARNING,
+    },
+    LogCode.METRICS_RECORDING_FAILED: {
+        'message': 'Metrics recording failed: {}',
+        'level': Context.WARNING,
+    },
+    LogCode.METRICS_UPDATE_FAILED: {
+        'message': 'Metrics update failed: {}',
+        'level': Context.WARNING,
+    },
+    LogCode.METRICS_FINALIZATION_FAILED: {
+        'message': 'Metrics finalization failed: {}',
+        'level': Context.WARNING,
+    },
+}

synapse_sdk/plugins/categories/pre_annotation/actions/to_task/exceptions.py

@@ -0,0 +1,14 @@
+class CriticalError(Exception):
+    """Critical error."""
+
+    def __init__(self, message: str = 'Critical error occured while processing task'):
+        self.message = message
+        super().__init__(self.message)
+
+
+class PreAnnotationToTaskFailed(Exception):
+    """Pre-annotation to task failed."""
+
+    def __init__(self, message: str = 'Pre-annotation to task failed'):
+        self.message = message
+        super().__init__(self.message)

synapse_sdk/plugins/categories/pre_annotation/actions/to_task/factory.py

@@ -0,0 +1,76 @@
+"""Factory for creating ToTask strategies based on context."""
+
+from typing import Dict, Type
+
+from .enums import AnnotationMethod
+from .strategies.base import (
+    AnnotationStrategy,
+    DataExtractionStrategy,
+    MetricsStrategy,
+    PreProcessorStrategy,
+    ValidationStrategy,
+)
+
+
+class ToTaskStrategyFactory:
+    """Factory for creating action strategies based on context."""
+
+    def __init__(self):
+        # Import strategies here to avoid circular imports
+        from .strategies.annotation import FileAnnotationStrategy, InferenceAnnotationStrategy
+        from .strategies.extraction import FileUrlExtractionStrategy, InferenceDataExtractionStrategy
+        from .strategies.metrics import ProgressTrackingStrategy
+        from .strategies.preprocessor import PreProcessorManagementStrategy
+        from .strategies.validation import (
+            ProjectValidationStrategy,
+            TargetSpecificationValidationStrategy,
+            TaskValidationStrategy,
+        )
+
+        self._annotation_strategies: Dict[AnnotationMethod, Type[AnnotationStrategy]] = {
+            AnnotationMethod.FILE: FileAnnotationStrategy,
+            AnnotationMethod.INFERENCE: InferenceAnnotationStrategy,
+        }
+
+        self._validation_strategies = {
+            'project': ProjectValidationStrategy,
+            'task': TaskValidationStrategy,
+            'target_spec': TargetSpecificationValidationStrategy,
+        }
+
+        self._extraction_strategies = {
+            AnnotationMethod.FILE: FileUrlExtractionStrategy,
+            AnnotationMethod.INFERENCE: InferenceDataExtractionStrategy,
+        }
+
+        self._preprocessor_strategy = PreProcessorManagementStrategy
+        self._metrics_strategy = ProgressTrackingStrategy
+
+    def create_annotation_strategy(self, method: AnnotationMethod) -> AnnotationStrategy:
+        """Create annotation strategy based on method."""
+        strategy_class = self._annotation_strategies.get(method)
+        if not strategy_class:
+            raise ValueError(f'No annotation strategy available for method: {method}')
+        return strategy_class()
+
+    def create_validation_strategy(self, validation_type: str) -> ValidationStrategy:
+        """Create validation strategy based on type."""
+        strategy_class = self._validation_strategies.get(validation_type)
+        if not strategy_class:
+            raise ValueError(f'No validation strategy available for type: {validation_type}')
+        return strategy_class()
+
+    def create_extraction_strategy(self, method: AnnotationMethod) -> DataExtractionStrategy:
+        """Create data extraction strategy based on method."""
+        strategy_class = self._extraction_strategies.get(method)
+        if not strategy_class:
+            raise ValueError(f'No extraction strategy available for method: {method}')
+        return strategy_class()
+
+    def create_preprocessor_strategy(self) -> PreProcessorStrategy:
+        """Create pre-processor management strategy."""
+        return self._preprocessor_strategy()
+
+    def create_metrics_strategy(self) -> MetricsStrategy:
+        """Create metrics tracking strategy."""
+        return self._metrics_strategy()

synapse_sdk/plugins/categories/pre_annotation/actions/to_task/models.py

@@ -0,0 +1,97 @@
+from typing import Annotated, Any, Dict, Optional
+
+from pydantic import AfterValidator, BaseModel, field_validator
+from pydantic_core import PydanticCustomError
+
+from synapse_sdk.clients.backend.models import JobStatus
+from synapse_sdk.clients.exceptions import ClientError
+from synapse_sdk.shared.enums import Context
+from synapse_sdk.utils.pydantic.validators import non_blank
+
+from .enums import AnnotateTaskDataStatus
+
+
+class ToTaskParams(BaseModel):
+    """ToTask action parameters.
+
+    Args:
+        name (str): The name of the action.
+        description (str | None): The description of the action.
+        project (int): The project ID.
+        agent (int): The agent ID.
+        task_filters (dict): The filters of tasks.
+        method (AnnotationMethod): The method of annotation.
+        target_specification_name (str | None): The name of the target specification.
+        model (int): The model ID.
+        pre_processor (int | None): The pre processor ID.
+        pre_processor_params (dict): The params of the pre processor.
+    """
+
+    name: Annotated[str, AfterValidator(non_blank)]
+    description: Optional[str] = None
+    project: int
+    agent: int
+    task_filters: Dict[str, Any]
+    method: Optional[str] = None
+    target_specification_name: Optional[str] = None
+    model: Optional[int] = None
+    pre_processor: Optional[int] = None
+    pre_processor_params: Dict[str, Any]
+
+    @field_validator('project', mode='before')
+    @classmethod
+    def check_project_exists(cls, value: int, info) -> int:
+        """Validate synapse-backend project exists."""
+        if not value:
+            return value
+
+        action = info.context['action']
+        client = action.client
+        try:
+            client.get_project(value)
+        except ClientError:
+            raise PydanticCustomError('client_error', 'Error occurred while checking project exists.')
+        return value
+
+
+class ToTaskResult(BaseModel):
+    """Result model for ToTaskAction.start method.
+
+    Args:
+        status (JobStatus): The job status from the action execution.
+        message (str): A descriptive message about the action result.
+    """
+
+    status: JobStatus
+    message: str
+
+    def model_dump(self, **kwargs):
+        """Override model_dump to return status as enum value."""
+        data = super().model_dump(**kwargs)
+        if 'status' in data and isinstance(data['status'], JobStatus):
+            data['status'] = data['status'].value
+        return data
+
+
+class AnnotateTaskEventLog(BaseModel):
+    """Annotate task event log model."""
+
+    info: Optional[str] = None
+    status: Context
+    created: str
+
+
+class AnnotateTaskDataLog(BaseModel):
+    """Log model for annotate task data."""
+
+    task_info: Optional[str] = None
+    status: AnnotateTaskDataStatus
+    created: str
+
+
+class MetricsRecord(BaseModel):
+    """Metrics record model."""
+
+    stand_by: int
+    failed: int
+    success: int