synapse-sdk 1.0.0b5__py3-none-any.whl → 2025.12.3__py3-none-any.whl

synapse_sdk/utils/converters/dm/tools/__init__.py

@@ -0,0 +1,214 @@
+"""
+DM Schema V1/V2 Tool-Specific Processors
+
+Created: 2025-12-11
+
+Implement and register processors in this module when adding new tool support.
+"""
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ToolProcessor(Protocol):
+    """Tool-Specific Conversion Processor Interface
+
+    Implement this protocol when adding new tool support.
+
+    Attributes:
+        tool_name: Tool name (e.g., 'bounding_box', 'polygon')
+
+    Example:
+        >>> class KeypointProcessor:
+        ...     tool_name = "keypoint"
+        ...
+        ...     def to_v2(self, v1_annotation, v1_data):
+        ...         # V1 → V2 conversion logic
+        ...         return {...}
+        ...
+        ...     def to_v1(self, v2_annotation):
+        ...         # V2 → V1 conversion logic
+        ...         return ({...}, {...})
+    """
+
+    @property
+    def tool_name(self) -> str:
+        """Tool name (e.g., 'bounding_box', 'polygon')"""
+        ...
+
+    def to_v2(self, v1_annotation: dict[str, Any], v1_data: dict[str, Any]) -> dict[str, Any]:
+        """Convert V1 annotation to V2 format
+
+        Args:
+            v1_annotation: V1 annotations[] item
+            v1_data: V1 annotationsData[] item (same ID)
+
+        Returns:
+            V2 format annotation object (id, classification, attrs, data)
+
+        Raises:
+            ValueError: Data cannot be converted
+        """
+        ...
+
+    def to_v1(self, v2_annotation: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Convert V2 annotation to V1 format
+
+        Args:
+            v2_annotation: V2 annotation object
+
+        Returns:
+            (V1 annotation, V1 annotationData) tuple
+
+        Raises:
+            ValueError: Data cannot be converted
+        """
+        ...
+
+
+# =============================================================================
+# Processor Registry
+# =============================================================================
+
+# Global registry storing registered processors
+_PROCESSOR_REGISTRY: dict[str, ToolProcessor] = {}
+
+
+def register_tool_processor(processor: ToolProcessor) -> None:
+    """Register a tool processor to the global registry
+
+    Args:
+        processor: ToolProcessor implementation
+    """
+    _PROCESSOR_REGISTRY[processor.tool_name] = processor
+
+
+def get_tool_processor(tool_name: str) -> ToolProcessor | None:
+    """Get a tool processor from the global registry
+
+    Args:
+        tool_name: Tool name
+
+    Returns:
+        Registered processor or None
+    """
+    return _PROCESSOR_REGISTRY.get(tool_name)
+
+
+def get_all_processors() -> dict[str, ToolProcessor]:
+    """Return all registered processors
+
+    Returns:
+        Tool name → processor dictionary
+    """
+    return _PROCESSOR_REGISTRY.copy()
+
+
+# =============================================================================
+# Processor Import and Auto-Registration
+# =============================================================================
+
+# Auto-registered when processor modules are imported
+# Note: Actual processors are imported later to prevent circular imports
+
+
+def _register_default_processors() -> None:
+    """Register default processors
+
+    Called on module load to register default processors.
+    """
+    try:
+        from .bounding_box import BoundingBoxProcessor
+
+        register_tool_processor(BoundingBoxProcessor())
+    except ImportError:
+        pass  # Not yet implemented
+
+    try:
+        from .polygon import PolygonProcessor
+
+        register_tool_processor(PolygonProcessor())
+    except ImportError:
+        pass  # Not yet implemented
+
+    try:
+        from .polyline import PolylineProcessor
+
+        register_tool_processor(PolylineProcessor())
+    except ImportError:
+        pass  # Not yet implemented
+
+    try:
+        from .keypoint import KeypointProcessor
+
+        register_tool_processor(KeypointProcessor())
+    except ImportError:
+        pass  # Not yet implemented
+
+    try:
+        from .bounding_box_3d import BoundingBox3DProcessor
+
+        register_tool_processor(BoundingBox3DProcessor())
+    except ImportError:
+        pass  # Not yet implemented
+
+    try:
+        from .segmentation import SegmentationProcessor
+
+        register_tool_processor(SegmentationProcessor())
+    except ImportError:
+        pass  # Not yet implemented
+
+    try:
+        from .named_entity import NamedEntityProcessor
+
+        register_tool_processor(NamedEntityProcessor())
+    except ImportError:
+        pass  # Not yet implemented
+
+    try:
+        from .segmentation_3d import Segmentation3DProcessor
+
+        register_tool_processor(Segmentation3DProcessor())
+    except ImportError:
+        pass  # Not yet implemented
+
+    try:
+        from .classification import ClassificationProcessor
+
+        register_tool_processor(ClassificationProcessor())
+    except ImportError:
+        pass  # Not yet implemented
+
+    try:
+        from .relation import RelationProcessor
+
+        register_tool_processor(RelationProcessor())
+    except ImportError:
+        pass  # Not yet implemented
+
+    try:
+        from .prompt import PromptProcessor
+
+        register_tool_processor(PromptProcessor())
+    except ImportError:
+        pass  # Not yet implemented
+
+    try:
+        from .answer import AnswerProcessor
+
+        register_tool_processor(AnswerProcessor())
+    except ImportError:
+        pass  # Not yet implemented
+
+
+# Attempt to register default processors on module load
+_register_default_processors()
+
+
+__all__ = [
+    'ToolProcessor',
+    'register_tool_processor',
+    'get_tool_processor',
+    'get_all_processors',
+]

synapse_sdk/utils/converters/dm/tools/answer.py

@@ -0,0 +1,95 @@
+"""
+Answer Tool Processor
+
+Created: 2025-12-12
+
+Conversion Rules (see data-model.md 9.11):
+V1 → V2:
+  - output → data.output
+  - model, displayName, generatedBy, promptAnnotationId → preserved in data
+  - classification.class → classification
+  - classification.{other} → attrs[{name, value}]
+
+V2 → V1:
+  - data.output → output
+  - Other fields from data → preserved in annotationsData
+  - classification → classification.class
+  - attrs[{name, value}] → classification.{name: value}
+"""
+
+from typing import Any
+
+
+class AnswerProcessor:
+    """Answer Tool Processor
+
+    V1 annotationsData: {id, tool, model, output: [{type, value, primaryKey, changeHistory}],
+                         displayName, generatedBy, promptAnnotationId}
+    V2 data: {output: [...], model, displayName, generatedBy, promptAnnotationId, timestamp?}
+
+    Answer annotation data conversion.
+    """
+
+    tool_name = 'answer'
+
+    _META_FIELDS = {'isLocked', 'isVisible', 'isValid', 'isDrawCompleted', 'label', 'id', 'tool'}
+    _INTERNAL_ATTR_PREFIX = '_'
+    # Fields to copy from annotationsData to V2 data
+    _DATA_FIELDS = {'output', 'model', 'displayName', 'generatedBy', 'promptAnnotationId', 'timestamp'}
+
+    def to_v2(self, v1_annotation: dict[str, Any], v1_data: dict[str, Any]) -> dict[str, Any]:
+        """Convert V1 answer to V2"""
+        classification_obj = v1_annotation.get('classification') or {}
+
+        # Build V2 data (output and other fields)
+        data: dict[str, Any] = {}
+        for key in self._DATA_FIELDS:
+            if key in v1_data:
+                data[key] = v1_data[key]
+
+        # Build V2 attrs (all classification properties excluding class)
+        attrs: list[dict[str, Any]] = []
+        for key, value in classification_obj.items():
+            if key != 'class':
+                attrs.append({'name': key, 'value': value})
+
+        return {
+            'id': v1_annotation.get('id', ''),
+            'classification': classification_obj.get('class', ''),
+            'attrs': attrs,
+            'data': data,
+        }
+
+    def to_v1(self, v2_annotation: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Convert V2 answer to V1"""
+        annotation_id = v2_annotation.get('id', '')
+        classification_str = v2_annotation.get('classification', '')
+        attrs = v2_annotation.get('attrs', [])
+        data = v2_annotation.get('data', {})
+
+        # Build V1 classification
+        classification: dict[str, Any] = {'class': classification_str}
+        for attr in attrs:
+            name = attr.get('name', '')
+            value = attr.get('value')
+            if not name.startswith(self._INTERNAL_ATTR_PREFIX):
+                classification[name] = value
+
+        v1_annotation: dict[str, Any] = {
+            'id': annotation_id,
+            'tool': self.tool_name,
+            'classification': classification,
+        }
+
+        # Build V1 annotationsData
+        v1_data: dict[str, Any] = {
+            'id': annotation_id,
+            'tool': self.tool_name,
+        }
+
+        # Copy fields from data
+        for key in self._DATA_FIELDS:
+            if key in data:
+                v1_data[key] = data[key]
+
+        return v1_annotation, v1_data

synapse_sdk/utils/converters/dm/tools/bounding_box.py

@@ -0,0 +1,132 @@
+"""
+Bounding Box Tool Processor
+
+Created: 2025-12-11
+
+Conversion Rules (see data-model.md 4.1):
+V1 → V2:
+  - coordinate.{x, y, width, height} → data[x, y, width, height]
+  - coordinate.rotation → attrs[{name:"rotation", value}]
+  - classification.class → classification
+  - classification.{other} → attrs[{name, value}]
+
+V2 → V1:
+  - data[0,1,2,3] → coordinate.{x, y, width, height}
+  - attrs.rotation → coordinate.rotation
+  - classification → classification.class
+  - attrs[{name, value}] → classification.{name: value} (excluding special attrs)
+"""
+
+from typing import Any
+
+
+class BoundingBoxProcessor:
+    """Bounding Box Tool Processor
+
+    V1 coordinate: {x, y, width, height, rotation?}
+    V2 data: [x, y, width, height]
+    """
+
+    tool_name = 'bounding_box'
+
+    # V1 meta fields (not stored in attrs)
+    _META_FIELDS = {'isLocked', 'isVisible', 'isValid', 'isDrawCompleted', 'label', 'id', 'tool'}
+
+    # Fields to restore from V2 attrs to coordinate
+    _COORDINATE_ATTRS = {'rotation'}
+
+    # Special attrs not restored to V1 classification (_ prefix)
+    _INTERNAL_ATTR_PREFIX = '_'
+
+    def to_v2(self, v1_annotation: dict[str, Any], v1_data: dict[str, Any]) -> dict[str, Any]:
+        """Convert V1 bounding box to V2
+
+        Args:
+            v1_annotation: V1 annotations[] item
+            v1_data: V1 annotationsData[] item (same ID)
+
+        Returns:
+            V2 format bounding box annotation
+        """
+        coordinate = v1_data.get('coordinate', {})
+        classification_obj = v1_annotation.get('classification') or {}
+
+        # V2 data: [x, y, width, height]
+        data = [
+            coordinate.get('x', 0),
+            coordinate.get('y', 0),
+            coordinate.get('width', 0),
+            coordinate.get('height', 0),
+        ]
+
+        # Build V2 attrs
+        attrs: list[dict[str, Any]] = []
+
+        # Add rotation to attrs
+        if 'rotation' in coordinate:
+            attrs.append({'name': 'rotation', 'value': coordinate['rotation']})
+
+        # Add other classification properties to attrs (excluding class)
+        for key, value in classification_obj.items():
+            if key != 'class':
+                attrs.append({'name': key, 'value': value})
+
+        # Build V2 annotation
+        return {
+            'id': v1_annotation.get('id', ''),
+            'classification': classification_obj.get('class', ''),
+            'attrs': attrs,
+            'data': data,
+        }
+
+    def to_v1(self, v2_annotation: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Convert V2 bounding box to V1
+
+        Args:
+            v2_annotation: V2 annotation object
+
+        Returns:
+            (V1 annotation, V1 annotationData) tuple
+        """
+        annotation_id = v2_annotation.get('id', '')
+        classification_str = v2_annotation.get('classification', '')
+        attrs = v2_annotation.get('attrs', [])
+        data = v2_annotation.get('data', [0, 0, 0, 0])
+
+        # Build V1 coordinate
+        coordinate: dict[str, Any] = {
+            'x': data[0] if len(data) > 0 else 0,
+            'y': data[1] if len(data) > 1 else 0,
+            'width': data[2] if len(data) > 2 else 0,
+            'height': data[3] if len(data) > 3 else 0,
+        }
+
+        # Build V1 classification
+        classification: dict[str, Any] = {'class': classification_str}
+
+        # Restore properties from attrs
+        for attr in attrs:
+            name = attr.get('name', '')
+            value = attr.get('value')
+
+            if name in self._COORDINATE_ATTRS:
+                # Add rotation etc. to coordinate
+                coordinate[name] = value
+            elif not name.startswith(self._INTERNAL_ATTR_PREFIX):
+                # Add non-internal attrs to classification
+                classification[name] = value
+
+        # V1 annotation (meta info)
+        v1_annotation: dict[str, Any] = {
+            'id': annotation_id,
+            'tool': self.tool_name,
+            'classification': classification,
+        }
+
+        # V1 annotationData (coordinate info)
+        v1_data: dict[str, Any] = {
+            'id': annotation_id,
+            'coordinate': coordinate,
+        }
+
+        return v1_annotation, v1_data

synapse_sdk/utils/converters/dm/tools/bounding_box_3d.py

@@ -0,0 +1,121 @@
+"""
+3D Bounding Box Tool Processor
+
+Created: 2025-12-12
+
+Conversion Rules (see data-model.md 9.6):
+V1 → V2:
+  - psr {position, scale, rotation} → data {position, scale, rotation}
+  - classification.class → classification
+  - classification.{other} → attrs[{name, value}]
+
+V2 → V1:
+  - data {position, scale, rotation} → psr {position, scale, rotation}
+  - classification → classification.class
+  - attrs[{name, value}] → classification.{name: value} (excluding special attrs)
+"""
+
+from typing import Any
+
+
+class BoundingBox3DProcessor:
+    """3D Bounding Box Tool Processor
+
+    V1 psr: {position, scale, rotation} each {x, y, z}
+    V2 data: {position, scale, rotation} each {x, y, z}
+
+    PSR structure is identical, only key name changes (psr → data).
+    Used with pcd (point cloud) media type.
+    """
+
+    tool_name = '3d_bounding_box'
+
+    # V1 meta fields (not stored in attrs)
+    _META_FIELDS = {'isLocked', 'isVisible', 'isValid', 'isDrawCompleted', 'label', 'id', 'tool'}
+
+    # Special attrs not restored to V1 classification (_ prefix)
+    _INTERNAL_ATTR_PREFIX = '_'
+
+    def to_v2(self, v1_annotation: dict[str, Any], v1_data: dict[str, Any]) -> dict[str, Any]:
+        """Convert V1 3D bounding box to V2
+
+        Args:
+            v1_annotation: V1 annotations[] item
+            v1_data: V1 annotationsData[] item (same ID)
+
+        Returns:
+            V2 format 3D bounding box annotation
+        """
+        psr = v1_data.get('psr', {})
+        classification_obj = v1_annotation.get('classification') or {}
+
+        # V2 data: copy psr structure as-is
+        data = {
+            'position': psr.get('position', {'x': 0, 'y': 0, 'z': 0}),
+            'scale': psr.get('scale', {'x': 0, 'y': 0, 'z': 0}),
+            'rotation': psr.get('rotation', {'x': 0, 'y': 0, 'z': 0}),
+        }
+
+        # Build V2 attrs
+        attrs: list[dict[str, Any]] = []
+
+        # Add other classification properties to attrs (excluding class)
+        for key, value in classification_obj.items():
+            if key != 'class':
+                attrs.append({'name': key, 'value': value})
+
+        # Build V2 annotation
+        return {
+            'id': v1_annotation.get('id', ''),
+            'classification': classification_obj.get('class', ''),
+            'attrs': attrs,
+            'data': data,
+        }
+
+    def to_v1(self, v2_annotation: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Convert V2 3D bounding box to V1
+
+        Args:
+            v2_annotation: V2 annotation object
+
+        Returns:
+            (V1 annotation, V1 annotationData) tuple
+        """
+        annotation_id = v2_annotation.get('id', '')
+        classification_str = v2_annotation.get('classification', '')
+        attrs = v2_annotation.get('attrs', [])
+        data = v2_annotation.get('data', {})
+
+        # Build V1 psr: copy data structure as-is
+        psr: dict[str, Any] = {
+            'position': data.get('position', {'x': 0, 'y': 0, 'z': 0}),
+            'scale': data.get('scale', {'x': 0, 'y': 0, 'z': 0}),
+            'rotation': data.get('rotation', {'x': 0, 'y': 0, 'z': 0}),
+        }
+
+        # Build V1 classification
+        classification: dict[str, Any] = {'class': classification_str}
+
+        # Restore properties from attrs
+        for attr in attrs:
+            name = attr.get('name', '')
+            value = attr.get('value')
+
+            if not name.startswith(self._INTERNAL_ATTR_PREFIX):
+                # Add non-internal attrs to classification
+                classification[name] = value
+
+        # V1 annotation (meta info)
+        v1_annotation: dict[str, Any] = {
+            'id': annotation_id,
+            'tool': self.tool_name,
+            'classification': classification,
+        }
+
+        # V1 annotationData (coordinate info)
+        v1_data: dict[str, Any] = {
+            'id': annotation_id,
+            'psr': psr,
+        }
+
+        return v1_annotation, v1_data

synapse_sdk/utils/converters/dm/tools/classification.py

@@ -0,0 +1,75 @@
+"""
+Classification Tool Processor
+
+Created: 2025-12-12
+
+Conversion Rules (see data-model.md 9.8):
+V1 → V2:
+  - classification.class → classification
+  - classification.{other} → attrs[{name, value}]
+  - annotationsData contains only id
+
+V2 → V1:
+  - classification → classification.class
+  - attrs[{name, value}] → classification.{name: value}
+  - data is empty object {}
+"""
+
+from typing import Any
+
+
+class ClassificationProcessor:
+    """Classification Tool Processor
+
+    V1: All properties in annotations, only id in annotationsData
+    V2: data is empty object, all properties stored in attrs
+    """
+
+    tool_name = 'classification'
+
+    _META_FIELDS = {'isLocked', 'isVisible', 'isValid', 'isDrawCompleted', 'label', 'id', 'tool'}
+    _INTERNAL_ATTR_PREFIX = '_'
+
+    def to_v2(self, v1_annotation: dict[str, Any], v1_data: dict[str, Any]) -> dict[str, Any]:
+        """Convert V1 classification to V2"""
+        classification_obj = v1_annotation.get('classification') or {}
+
+        # Build V2 attrs (all properties excluding class)
+        attrs: list[dict[str, Any]] = []
+        for key, value in classification_obj.items():
+            if key != 'class':
+                attrs.append({'name': key, 'value': value})
+
+        return {
+            'id': v1_annotation.get('id', ''),
+            'classification': classification_obj.get('class', ''),
+            'attrs': attrs,
+            'data': {},  # Empty object
+        }
+
+    def to_v1(self, v2_annotation: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Convert V2 classification to V1"""
+        annotation_id = v2_annotation.get('id', '')
+        classification_str = v2_annotation.get('classification', '')
+        attrs = v2_annotation.get('attrs', [])
+
+        # Build V1 classification
+        classification: dict[str, Any] = {'class': classification_str}
+        for attr in attrs:
+            name = attr.get('name', '')
+            value = attr.get('value')
+            if not name.startswith(self._INTERNAL_ATTR_PREFIX):
+                classification[name] = value
+
+        v1_annotation: dict[str, Any] = {
+            'id': annotation_id,
+            'tool': self.tool_name,
+            'classification': classification,
+        }
+
+        # annotationsData contains only id
+        v1_data: dict[str, Any] = {
+            'id': annotation_id,
+        }
+
+        return v1_annotation, v1_data