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

synapse_sdk/plugins/datasets/formats/dm.py

@@ -0,0 +1,351 @@
+"""DatamakerV1 and DatamakerV2 format Pydantic models.
+
+Supports both schema versions:
+- DMv1: Event-based, per-assignment structure (annotations keyed by asset)
+- DMv2: Collection-based, organized by media type (images array)
+
+Version must be explicitly specified when using converters.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class DMVersion(StrEnum):
+    """DataMaker schema version."""
+
+    V1 = 'v1'
+    V2 = 'v2'
+
+
+# =============================================================================
+# Shared Types
+# =============================================================================
+
+
+class DMAttribute(BaseModel):
+    """Attribute on an annotation (shared between v1/v2).
+
+    Attributes:
+        name: Attribute name.
+        value: Attribute value (string, number, boolean, or list).
+    """
+
+    name: str
+    value: str | int | float | bool | list[str]
+
+
+# =============================================================================
+# DataMaker V1 Models (Event-based, per-assignment)
+# =============================================================================
+
+
+class DMv1Classification(BaseModel):
+    """V1 classification as flat key-value pairs.
+
+    Structure defined by admin but stored flat.
+    """
+
+    model_config = {'extra': 'allow'}
+
+
+class DMv1AnnotationBase(BaseModel):
+    """V1 base annotation object.
+
+    Attributes:
+        id: Unique annotation ID.
+        tool: Name of the tool used.
+        isLocked: Whether annotation is locked.
+        isVisible: Whether annotation is visible.
+        classification: Flat key-value classification attributes.
+    """
+
+    id: str
+    tool: str
+    isLocked: bool = False
+    isVisible: bool = True
+    classification: DMv1Classification | None = None
+
+    model_config = {'extra': 'allow'}
+
+
+class DMv1RelationItem(BaseModel):
+    """V1 relation (edge) between annotations.
+
+    Attributes:
+        id: Unique relation ID.
+        tool: Always 'relation'.
+        annotationId: Source annotation ID.
+        targetAnnotationId: Target annotation ID.
+        classification: Attributes assigned to the relation.
+    """
+
+    id: str
+    tool: str = 'relation'
+    isLocked: bool = False
+    isVisible: bool = True
+    annotationId: str
+    targetAnnotationId: str
+    classification: DMv1Classification | None = None
+
+
+class DMv1GroupMemberItem(BaseModel):
+    """V1 group member with optional hierarchy.
+
+    Attributes:
+        annotationId: ID of annotation in group.
+        children: Sub-groups or hierarchical structure.
+    """
+
+    annotationId: str
+    children: list[DMv1GroupMemberItem] = Field(default_factory=list)
+
+
+class DMv1AnnotationGroupItem(BaseModel):
+    """V1 annotation group.
+
+    Attributes:
+        id: Unique group ID.
+        tool: Always 'annotationGroup'.
+        classification: Group classification.
+        annotationList: List of group members.
+    """
+
+    id: str
+    tool: str = 'annotationGroup'
+    isLocked: bool = False
+    classification: DMv1Classification | None = None
+    annotationList: list[DMv1GroupMemberItem] = Field(default_factory=list)
+
+
+class DMv1AnnotationDataItem(BaseModel):
+    """V1 supplementary annotation data (frames, model results).
+
+    Attributes:
+        frameIndex: Frame number for video/time-series.
+        section: Start/end frame range.
+        input: Prompt input.
+        output: Model output.
+    """
+
+    frameIndex: int | None = None
+    section: dict[str, int] | None = None  # {startFrame, endFrame}
+    input: str | None = None
+    output: str | None = None
+
+
+class DMv1Dataset(BaseModel):
+    """DataMaker V1 dataset schema (event-based).
+
+    Per-assignment structure with annotations keyed by asset.
+
+    Attributes:
+        assignmentId: Optional job identifier.
+        extra: Asset-level additional metadata.
+        annotations: Annotations per asset (Record<string, AnnotationBase[]>).
+        relations: Relationships between annotations.
+        annotationGroups: Grouping information.
+        annotationsData: Supplementary data (frames, model results).
+
+    Example:
+        >>> dataset = DMv1Dataset(
+        ...     assignmentId='job-123',
+        ...     annotations={'image_0': [annotation1, annotation2]},
+        ... )
+    """
+
+    assignmentId: str | None = None
+    extra: dict | None = None
+    annotations: dict[str, list[DMv1AnnotationBase]] = Field(default_factory=dict)
+    relations: dict[str, list[DMv1RelationItem]] = Field(default_factory=dict)
+    annotationGroups: dict[str, list[DMv1AnnotationGroupItem]] = Field(default_factory=dict)
+    annotationsData: dict[str, list[DMv1AnnotationDataItem]] = Field(default_factory=dict)
+
+
+# =============================================================================
+# DataMaker V2 Models (Collection-based, organized by media type)
+# =============================================================================
+
+
+class DMv2AnnotationBase(BaseModel):
+    """V2 base annotation with id, classification, and attrs.
+
+    Attributes:
+        id: Unique annotation ID (alphanumeric, typically 10 chars).
+        classification: Class label for this annotation.
+        attrs: Optional list of attributes.
+    """
+
+    id: str = Field(pattern=r'^[a-zA-Z0-9_-]+$')
+    classification: str
+    attrs: list[DMAttribute] = Field(default_factory=list)
+
+
+class DMv2BoundingBox(DMv2AnnotationBase):
+    """V2 bounding box annotation.
+
+    Attributes:
+        data: [x, y, width, height] in absolute pixel coordinates.
+    """
+
+    data: tuple[float, float, float, float]
+
+
+class DMv2Polygon(DMv2AnnotationBase):
+    """V2 polygon annotation.
+
+    Attributes:
+        data: List of [x, y] points forming the polygon.
+    """
+
+    data: list[tuple[float, float]]
+
+
+class DMv2Polyline(DMv2AnnotationBase):
+    """V2 polyline annotation (open path).
+
+    Attributes:
+        data: List of [x, y] points forming the polyline.
+    """
+
+    data: list[tuple[float, float]]
+
+
+class DMv2Keypoint(DMv2AnnotationBase):
+    """V2 single keypoint annotation.
+
+    Attributes:
+        data: [x, y] coordinate.
+    """
+
+    data: tuple[float, float]
+
+
+class DMv2Relation(DMv2AnnotationBase):
+    """V2 relation annotation linking two annotations.
+
+    Attributes:
+        data: [from_id, to_id] annotation IDs.
+    """
+
+    data: tuple[str, str]
+
+
+class DMv2Group(DMv2AnnotationBase):
+    """V2 group annotation containing multiple annotation IDs.
+
+    Attributes:
+        data: List of annotation IDs in the group.
+    """
+
+    data: list[str]
+
+
+class DMv2ImageItem(BaseModel):
+    """V2 container for 2D image annotations.
+
+    Groups all annotation types for a single image.
+    """
+
+    bounding_box: list[DMv2BoundingBox] = Field(default_factory=list)
+    polygon: list[DMv2Polygon] = Field(default_factory=list)
+    polyline: list[DMv2Polyline] = Field(default_factory=list)
+    keypoint: list[DMv2Keypoint] = Field(default_factory=list)
+    relation: list[DMv2Relation] = Field(default_factory=list)
+    group: list[DMv2Group] = Field(default_factory=list)
+
+
+class DMv2Dataset(BaseModel):
+    """DataMaker V2 dataset schema (collection-based).
+
+    Organized by media type with typed annotation arrays.
+
+    Attributes:
+        classification: Mapping of tool types to available class labels.
+        images: List of image annotation containers.
+
+    Example:
+        >>> dataset = DMv2Dataset(
+        ...     classification={'bounding_box': ['car', 'person']},
+        ...     images=[DMv2ImageItem(bounding_box=[...])],
+        ... )
+        >>> class_names = dataset.get_class_names('bounding_box')
+    """
+
+    classification: dict[str, list[str]] = Field(default_factory=dict)
+    images: list[DMv2ImageItem] = Field(default_factory=list)
+
+    def get_class_names(self, tool: str = 'bounding_box') -> list[str]:
+        """Get class names for a specific annotation tool.
+
+        Args:
+            tool: Tool type (e.g., 'bounding_box', 'polygon').
+
+        Returns:
+            List of class names for the tool.
+        """
+        return self.classification.get(tool, [])
+
+    def get_all_class_names(self) -> list[str]:
+        """Get all unique class names across all tools.
+
+        Returns:
+            Sorted list of unique class names.
+        """
+        all_classes: set[str] = set()
+        for classes in self.classification.values():
+            all_classes.update(classes)
+        return sorted(all_classes)
+
+
+# =============================================================================
+# Aliases for backward compatibility / convenience
+# =============================================================================
+
+# Default to V2 models for convenience
+DMBoundingBox = DMv2BoundingBox
+DMPolygon = DMv2Polygon
+DMPolyline = DMv2Polyline
+DMKeypoint = DMv2Keypoint
+DMRelation = DMv2Relation
+DMGroup = DMv2Group
+DMImageItem = DMv2ImageItem
+DMDataset = DMv2Dataset
+
+
+__all__ = [
+    # Version enum
+    'DMVersion',
+    # Shared
+    'DMAttribute',
+    # V1 Models
+    'DMv1AnnotationBase',
+    'DMv1AnnotationDataItem',
+    'DMv1AnnotationGroupItem',
+    'DMv1Classification',
+    'DMv1Dataset',
+    'DMv1GroupMemberItem',
+    'DMv1RelationItem',
+    # V2 Models
+    'DMv2AnnotationBase',
+    'DMv2BoundingBox',
+    'DMv2Dataset',
+    'DMv2Group',
+    'DMv2ImageItem',
+    'DMv2Keypoint',
+    'DMv2Polygon',
+    'DMv2Polyline',
+    'DMv2Relation',
+    # Aliases (default to V2)
+    'DMBoundingBox',
+    'DMDataset',
+    'DMGroup',
+    'DMImageItem',
+    'DMKeypoint',
+    'DMPolygon',
+    'DMPolyline',
+    'DMRelation',
+]

synapse_sdk/plugins/datasets/formats/yolo.py

@@ -0,0 +1,240 @@
+"""YOLO format Pydantic models.
+
+Supports standard YOLO detection format with normalized coordinates.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+
+class YOLOAnnotation(BaseModel):
+    """Single YOLO annotation line.
+
+    YOLO format uses normalized center coordinates:
+    `class_id cx cy w h`
+
+    All coordinates are normalized to [0, 1] range.
+
+    Attributes:
+        class_id: Class index (0-based).
+        cx: Normalized center x coordinate.
+        cy: Normalized center y coordinate.
+        w: Normalized width.
+        h: Normalized height.
+    """
+
+    class_id: int = Field(ge=0)
+    cx: float = Field(ge=0, le=1)
+    cy: float = Field(ge=0, le=1)
+    w: float = Field(ge=0, le=1)
+    h: float = Field(ge=0, le=1)
+
+    def to_line(self) -> str:
+        """Convert to YOLO label line format.
+
+        Returns:
+            String in format: `class_id cx cy w h`
+        """
+        return f'{self.class_id} {self.cx:.6f} {self.cy:.6f} {self.w:.6f} {self.h:.6f}'
+
+    @classmethod
+    def from_line(cls, line: str) -> YOLOAnnotation:
+        """Parse from YOLO label line.
+
+        Args:
+            line: String in format: `class_id cx cy w h`
+
+        Returns:
+            YOLOAnnotation instance.
+        """
+        parts = line.strip().split()
+        return cls(
+            class_id=int(parts[0]),
+            cx=float(parts[1]),
+            cy=float(parts[2]),
+            w=float(parts[3]),
+            h=float(parts[4]),
+        )
+
+    def to_absolute(self, width: int, height: int) -> tuple[float, float, float, float]:
+        """Convert to absolute pixel coordinates.
+
+        Args:
+            width: Image width in pixels.
+            height: Image height in pixels.
+
+        Returns:
+            Tuple of (x, y, w, h) in absolute coordinates.
+        """
+        abs_w = self.w * width
+        abs_h = self.h * height
+        abs_x = (self.cx * width) - (abs_w / 2)
+        abs_y = (self.cy * height) - (abs_h / 2)
+        return abs_x, abs_y, abs_w, abs_h
+
+    @classmethod
+    def from_absolute(
+        cls,
+        class_id: int,
+        x: float,
+        y: float,
+        w: float,
+        h: float,
+        img_width: int,
+        img_height: int,
+    ) -> YOLOAnnotation:
+        """Create from absolute pixel coordinates.
+
+        Args:
+            class_id: Class index.
+            x: Top-left x coordinate.
+            y: Top-left y coordinate.
+            w: Box width.
+            h: Box height.
+            img_width: Image width in pixels.
+            img_height: Image height in pixels.
+
+        Returns:
+            YOLOAnnotation with normalized coordinates.
+        """
+        cx = (x + w / 2) / img_width
+        cy = (y + h / 2) / img_height
+        nw = w / img_width
+        nh = h / img_height
+        return cls(class_id=class_id, cx=cx, cy=cy, w=nw, h=nh)
+
+
+class YOLODatasetConfig(BaseModel):
+    """YOLO dataset.yaml configuration.
+
+    Standard YOLO dataset configuration file structure.
+
+    Attributes:
+        path: Root path to dataset.
+        train: Relative path to training images.
+        val: Relative path to validation images.
+        test: Optional relative path to test images.
+        nc: Number of classes.
+        names: List of class names.
+    """
+
+    path: str = '.'
+    train: str = 'train/images'
+    val: str = 'valid/images'
+    test: str | None = None
+    nc: int
+    names: list[str]
+
+    def to_yaml(self) -> str:
+        """Convert to YAML string.
+
+        Returns:
+            YAML-formatted string for dataset.yaml.
+        """
+        lines = [
+            f'path: {self.path}',
+            f'train: {self.train}',
+            f'val: {self.val}',
+        ]
+        if self.test:
+            lines.append(f'test: {self.test}')
+        lines.extend([
+            '',
+            f'nc: {self.nc}',
+            f'names: {self.names}',
+            '',
+        ])
+        return '\n'.join(lines)
+
+    @classmethod
+    def from_yaml(cls, yaml_path: Path | str) -> YOLODatasetConfig:
+        """Load from YAML file.
+
+        Args:
+            yaml_path: Path to dataset.yaml file.
+
+        Returns:
+            YOLODatasetConfig instance.
+        """
+        import yaml
+
+        with open(yaml_path) as f:
+            data = yaml.safe_load(f)
+
+        return cls(
+            path=data.get('path', '.'),
+            train=data.get('train', 'train/images'),
+            val=data.get('val', 'valid/images'),
+            test=data.get('test'),
+            nc=data['nc'],
+            names=data['names'],
+        )
+
+
+class YOLOImage(BaseModel):
+    """YOLO image with its label file content.
+
+    Represents a single image and its annotations.
+
+    Attributes:
+        image_path: Path to the image file.
+        annotations: List of YOLO annotations.
+    """
+
+    image_path: Path
+    annotations: list[YOLOAnnotation] = Field(default_factory=list)
+
+    def to_label_content(self) -> str:
+        """Convert annotations to label file content.
+
+        Returns:
+            Newline-separated YOLO annotation lines.
+        """
+        return '\n'.join(ann.to_line() for ann in self.annotations)
+
+    @classmethod
+    def from_label_file(cls, image_path: Path, label_path: Path) -> YOLOImage:
+        """Load from image and label file pair.
+
+        Args:
+            image_path: Path to image file.
+            label_path: Path to corresponding label file.
+
+        Returns:
+            YOLOImage instance.
+        """
+        annotations = []
+        if label_path.exists():
+            for line in label_path.read_text().strip().splitlines():
+                if line.strip():
+                    annotations.append(YOLOAnnotation.from_line(line))
+        return cls(image_path=image_path, annotations=annotations)
+
+
+class YOLODataset(BaseModel):
+    """Full YOLO dataset structure.
+
+    Contains configuration and images for all splits.
+
+    Attributes:
+        config: Dataset configuration (dataset.yaml content).
+        train_images: Training images with annotations.
+        val_images: Validation images with annotations.
+        test_images: Test images with annotations (optional).
+    """
+
+    config: YOLODatasetConfig
+    train_images: list[YOLOImage] = Field(default_factory=list)
+    val_images: list[YOLOImage] = Field(default_factory=list)
+    test_images: list[YOLOImage] = Field(default_factory=list)
+
+
+__all__ = [
+    'YOLOAnnotation',
+    'YOLODataset',
+    'YOLODatasetConfig',
+    'YOLOImage',
+]

synapse_sdk/plugins/decorators.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from functools import wraps
+from typing import Any, Callable, TypeVar
+
+from pydantic import BaseModel
+
+from synapse_sdk.plugins.enums import PluginCategory
+
+F = TypeVar('F', bound=Callable[..., Any])
+
+
+def action(
+    name: str | None = None,
+    description: str = '',
+    params: type[BaseModel] | None = None,
+    result: type[BaseModel] | None = None,
+    category: PluginCategory | None = None,
+) -> Callable[[F], F]:
+    """Decorator to register a function as a plugin action.
+
+    Use this decorator to define function-based actions. The decorated function
+    should accept (params, context) arguments where params is a Pydantic model
+    instance and context is a RunContext.
+
+    Args:
+        name: Action name (defaults to function name).
+        description: Human-readable description of the action.
+        params: Pydantic model class for parameter validation.
+        result: Pydantic model class for result validation (optional).
+        category: Plugin category for grouping actions (optional).
+
+    Returns:
+        Decorated function with action metadata attached.
+
+    Example (without result schema):
+        >>> from pydantic import BaseModel
+        >>> from synapse_sdk.plugins.decorators import action
+        >>>
+        >>> class TrainParams(BaseModel):
+        ...     epochs: int = 10
+        >>>
+        >>> @action(params=TrainParams, description='Train a model')
+        ... def train(params: TrainParams, context: RunContext) -> dict:
+        ...     return {'epochs_trained': params.epochs}
+
+    Example (with result schema):
+        >>> class TrainResult(BaseModel):
+        ...     weights_path: str
+        ...     final_loss: float
+        >>>
+        >>> @action(params=TrainParams, result=TrainResult)
+        ... def train(params: TrainParams, context: RunContext) -> TrainResult:
+        ...     return TrainResult(weights_path='/model.pt', final_loss=0.05)
+        >>>
+        >>> # Access action metadata
+        >>> train._action_name  # 'train'
+        >>> train._action_params  # TrainParams
+        >>> train._action_result  # TrainResult
+        >>> train._action_category  # PluginCategory.NEURAL_NET
+    """
+
+    def decorator(func: F) -> F:
+        action_name = name or func.__name__
+
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            return func(*args, **kwargs)
+
+        # Attach action metadata
+        wrapper._is_action = True  # type: ignore[attr-defined]
+        wrapper._action_name = action_name  # type: ignore[attr-defined]
+        wrapper._action_description = description  # type: ignore[attr-defined]
+        wrapper._action_params = params  # type: ignore[attr-defined]
+        wrapper._action_result = result  # type: ignore[attr-defined]
+        wrapper._action_category = category  # type: ignore[attr-defined]
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+__all__ = ['action']