rocket-welder-sdk 1.1.33__py3-none-any.whl → 1.1.34__py3-none-any.whl

rocket_welder_sdk/high_level/data_context.py

@@ -17,7 +17,7 @@ if TYPE_CHECKING:
     from rocket_welder_sdk.keypoints_protocol import IKeyPointsWriter
     from rocket_welder_sdk.segmentation_result import SegmentationResultWriter
 
-    from .schema import KeyPoint, SegmentClass
+    from .schema import KeyPointDefinition, SegmentClass
 
 # Type aliases
 Point = Tuple[int, int]
@@ -37,12 +37,12 @@ class IKeyPointsDataContext(ABC):
         pass
 
     @abstractmethod
-    def add(self, point: KeyPoint, x: int, y: int, confidence: float) -> None:
+    def add(self, point: KeyPointDefinition, x: int, y: int, confidence: float) -> None:
         """
         Add a keypoint detection for this frame.
 
         Args:
-            point: KeyPoint from schema definition
+            point: KeyPointDefinition from schema definition
             x: X coordinate in pixels
             y: Y coordinate in pixels
             confidence: Detection confidence (0.0 to 1.0)
@@ -50,17 +50,22 @@ class IKeyPointsDataContext(ABC):
         pass
 
     @abstractmethod
-    def add_point(self, point: KeyPoint, position: Point, confidence: float) -> None:
+    def add_point(self, point: KeyPointDefinition, position: Point, confidence: float) -> None:
         """
         Add a keypoint detection using a Point tuple.
 
         Args:
-            point: KeyPoint from schema definition
+            point: KeyPointDefinition from schema definition
             position: (x, y) tuple
             confidence: Detection confidence (0.0 to 1.0)
         """
         pass
 
+    @abstractmethod
+    def commit(self) -> None:
+        """Commit the context (called automatically when delegate returns)."""
+        pass
+
 
 class ISegmentationDataContext(ABC):
     """
@@ -92,6 +97,11 @@ class ISegmentationDataContext(ABC):
         """
         pass
 
+    @abstractmethod
+    def commit(self) -> None:
+        """Commit the context (called automatically when delegate returns)."""
+        pass
+
 
 class KeyPointsDataContext(IKeyPointsDataContext):
     """Implementation of keypoints data context."""
@@ -101,8 +111,6 @@ class KeyPointsDataContext(IKeyPointsDataContext):
         frame_id: int,
         writer: IKeyPointsWriter,
     ) -> None:
-        from .schema import KeyPoint  # noqa: F401
-
         self._frame_id = frame_id
         self._writer = writer
 
@@ -110,11 +118,11 @@ class KeyPointsDataContext(IKeyPointsDataContext):
     def frame_id(self) -> int:
         return self._frame_id
 
-    def add(self, point: KeyPoint, x: int, y: int, confidence: float) -> None:
+    def add(self, point: KeyPointDefinition, x: int, y: int, confidence: float) -> None:
         """Add a keypoint detection for this frame."""
         self._writer.append(point.id, x, y, confidence)
 
-    def add_point(self, point: KeyPoint, position: Point, confidence: float) -> None:
+    def add_point(self, point: KeyPointDefinition, position: Point, confidence: float) -> None:
         """Add a keypoint detection using a Point tuple."""
         self._writer.append_point(point.id, position, confidence)
 
@@ -131,8 +139,6 @@ class SegmentationDataContext(ISegmentationDataContext):
         frame_id: int,
         writer: SegmentationResultWriter,
     ) -> None:
-        from .schema import SegmentClass  # noqa: F401
-
         self._frame_id = frame_id
         self._writer = writer
 

rocket_welder_sdk/high_level/schema.py

@@ -10,11 +10,11 @@ from __future__ import annotations
 import json
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
-from typing import Dict, List
+from typing import Dict, List, Any
 
 
 @dataclass(frozen=True)
-class KeyPoint:
+class KeyPointDefinition:
     """
     A keypoint definition with ID and name.
 
@@ -26,7 +26,7 @@ class KeyPoint:
     name: str
 
     def __str__(self) -> str:
-        return f"KeyPoint({self.id}, '{self.name}')"
+        return f"KeyPointDefinition({self.id}, '{self.name}')"
 
 
 @dataclass(frozen=True)
@@ -54,7 +54,7 @@ class IKeyPointsSchema(ABC):
     """
 
     @abstractmethod
-    def define_point(self, name: str) -> KeyPoint:
+    def define_point(self, name: str) -> KeyPointDefinition:
         """
         Define a new keypoint.
 
@@ -62,13 +62,13 @@ class IKeyPointsSchema(ABC):
             name: Human-readable name for the keypoint (e.g., "nose", "left_eye")
 
         Returns:
-            KeyPoint handle for use with IKeyPointsDataContext.add()
+            KeyPointDefinition handle for use with IKeyPointsDataContext.add()
         """
         pass
 
     @property
     @abstractmethod
-    def defined_points(self) -> List[KeyPoint]:
+    def defined_points(self) -> List[KeyPointDefinition]:
         """Get all defined keypoints."""
         pass
 
@@ -116,34 +116,41 @@ class KeyPointsSchema(IKeyPointsSchema):
     """Implementation of keypoints schema."""
 
     def __init__(self) -> None:
-        self._points: Dict[str, KeyPoint] = {}
+        self._points: Dict[str, KeyPointDefinition] = {}
         self._next_id = 0
 
-    def define_point(self, name: str) -> KeyPoint:
+    def define_point(self, name: str) -> KeyPointDefinition:
         """Define a new keypoint."""
         if name in self._points:
             raise ValueError(f"Keypoint '{name}' already defined")
 
-        point = KeyPoint(id=self._next_id, name=name)
+        point = KeyPointDefinition(id=self._next_id, name=name)
         self._points[name] = point
         self._next_id += 1
         return point
 
     @property
-    def defined_points(self) -> List[KeyPoint]:
+    def defined_points(self) -> List[KeyPointDefinition]:
         """Get all defined keypoints."""
         return list(self._points.values())
 
     def get_metadata_json(self) -> str:
-        """Get JSON metadata for serialization."""
-        return json.dumps(
-            {
-                "version": "1.0",
-                "compute_module_name": "",
-                "points": {p.name: p.id for p in self._points.values()},
-            },
-            indent=2,
-        )
+        """
+        Get JSON metadata for serialization.
+
+        Format matches C# SDK:
+        {
+            "version": 1,
+            "type": "keypoints",
+            "points": [{"id": 0, "name": "nose"}, ...]
+        }
+        """
+        metadata: Dict[str, Any] = {
+            "version": 1,
+            "type": "keypoints",
+            "points": [{"id": p.id, "name": p.name} for p in self._points.values()],
+        }
+        return json.dumps(metadata, indent=2)
 
 
 class SegmentationSchema(ISegmentationSchema):
@@ -170,11 +177,21 @@ class SegmentationSchema(ISegmentationSchema):
         return list(self._classes.values())
 
     def get_metadata_json(self) -> str:
-        """Get JSON metadata for serialization."""
-        return json.dumps(
-            {
-                "version": "1.0",
-                "classes": {str(c.class_id): c.name for c in self._classes.values()},
-            },
-            indent=2,
-        )
+        """
+        Get JSON metadata for serialization.
+
+        Format matches C# SDK:
+        {
+            "version": 1,
+            "type": "segmentation",
+            "classes": [{"classId": 1, "name": "person"}, ...]
+        }
+        """
+        metadata: Dict[str, Any] = {
+            "version": 1,
+            "type": "segmentation",
+            "classes": [
+                {"classId": c.class_id, "name": c.name} for c in self._classes.values()
+            ],
+        }
+        return json.dumps(metadata, indent=2)

rocket_welder_sdk/high_level/transport_protocol.py

@@ -1,103 +1,204 @@
 """
-Transport protocol types with composable + operator.
+Unified transport protocol as a value type.
 
-Allows building transport protocols like:
-    protocol = Transport.Nng + Transport.Push + Transport.Ipc
-    # Results in TransportProtocol("nng", "push", "ipc")
+Supports: file://, socket://, nng+push+ipc://, nng+push+tcp://, etc.
+
+Examples:
+    file:///home/user/output.bin   - absolute file path
+    socket:///tmp/my.sock          - Unix domain socket
+    nng+push+ipc://tmp/keypoints   - NNG Push over IPC
+    nng+push+tcp://host:5555       - NNG Push over TCP
 """
 
 from __future__ import annotations
 
-from dataclasses import dataclass
-from typing import Optional
+from enum import Enum, auto
+from typing import ClassVar, Dict, Optional
 
 
-@dataclass(frozen=True)
-class MessagingLibrary:
-    """Messaging library (nng, zeromq, etc.)."""
+class TransportKind(Enum):
+    """Transport kind enumeration."""
 
-    name: str
+    FILE = auto()
+    """File output."""
 
-    def __add__(self, pattern: MessagingPattern) -> TransportBuilder:
-        """Compose with messaging pattern: Nng + Push."""
-        return TransportBuilder(library=self, pattern=pattern)
+    SOCKET = auto()
+    """Unix domain socket (direct, no messaging library)."""
 
-    def __str__(self) -> str:
-        return self.name
+    NNG_PUSH_IPC = auto()
+    """NNG Push over IPC."""
 
+    NNG_PUSH_TCP = auto()
+    """NNG Push over TCP."""
 
-@dataclass(frozen=True)
-class MessagingPattern:
-    """Messaging pattern (push/pull, pub/sub, etc.)."""
+    NNG_PULL_IPC = auto()
+    """NNG Pull over IPC."""
 
-    name: str
+    NNG_PULL_TCP = auto()
+    """NNG Pull over TCP."""
 
-    def __str__(self) -> str:
-        return self.name
+    NNG_PUB_IPC = auto()
+    """NNG Pub over IPC."""
 
+    NNG_PUB_TCP = auto()
+    """NNG Pub over TCP."""
 
-@dataclass(frozen=True)
-class TransportLayer:
-    """Transport layer (ipc, tcp, etc.)."""
+    NNG_SUB_IPC = auto()
+    """NNG Sub over IPC."""
 
-    name: str
-    uri_prefix: str
+    NNG_SUB_TCP = auto()
+    """NNG Sub over TCP."""
 
-    def __str__(self) -> str:
-        return self.name
 
+class TransportProtocol:
+    """
+    Unified transport protocol specification as a value type.
+
+    Supports: file://, socket://, nng+push+ipc://, nng+push+tcp://, etc.
+    """
+
+    # Predefined protocols
+    File: TransportProtocol
+    Socket: TransportProtocol
+    NngPushIpc: TransportProtocol
+    NngPushTcp: TransportProtocol
+    NngPullIpc: TransportProtocol
+    NngPullTcp: TransportProtocol
+    NngPubIpc: TransportProtocol
+    NngPubTcp: TransportProtocol
+    NngSubIpc: TransportProtocol
+    NngSubTcp: TransportProtocol
+
+    _SCHEMA_MAP: ClassVar[Dict[str, TransportKind]] = {
+        "file": TransportKind.FILE,
+        "socket": TransportKind.SOCKET,
+        "nng+push+ipc": TransportKind.NNG_PUSH_IPC,
+        "nng+push+tcp": TransportKind.NNG_PUSH_TCP,
+        "nng+pull+ipc": TransportKind.NNG_PULL_IPC,
+        "nng+pull+tcp": TransportKind.NNG_PULL_TCP,
+        "nng+pub+ipc": TransportKind.NNG_PUB_IPC,
+        "nng+pub+tcp": TransportKind.NNG_PUB_TCP,
+        "nng+sub+ipc": TransportKind.NNG_SUB_IPC,
+        "nng+sub+tcp": TransportKind.NNG_SUB_TCP,
+    }
+
+    _KIND_TO_SCHEMA: ClassVar[Dict[TransportKind, str]] = {}
+
+    def __init__(self, kind: TransportKind, schema: str) -> None:
+        self._kind = kind
+        self._schema = schema
+
+    @property
+    def kind(self) -> TransportKind:
+        """The transport kind."""
+        return self._kind
 
-@dataclass(frozen=True)
-class TransportBuilder:
-    """Builder for constructing transport protocols."""
+    @property
+    def schema(self) -> str:
+        """The schema string (e.g., 'file', 'socket', 'nng+push+ipc')."""
+        return self._schema
 
-    library: MessagingLibrary
-    pattern: MessagingPattern
+    # Classification properties
 
-    def __add__(self, layer: TransportLayer) -> TransportProtocol:
-        """Compose with transport layer: (Nng + Push) + Ipc."""
-        return TransportProtocol(library=self.library, pattern=self.pattern, layer=layer)
+    @property
+    def is_file(self) -> bool:
+        """True if this is a file transport."""
+        return self._kind == TransportKind.FILE
 
-    def __str__(self) -> str:
-        return f"{self.library}+{self.pattern}"
+    @property
+    def is_socket(self) -> bool:
+        """True if this is a Unix socket transport."""
+        return self._kind == TransportKind.SOCKET
 
+    @property
+    def is_nng(self) -> bool:
+        """True if this is any NNG-based transport."""
+        return self._kind in {
+            TransportKind.NNG_PUSH_IPC,
+            TransportKind.NNG_PUSH_TCP,
+            TransportKind.NNG_PULL_IPC,
+            TransportKind.NNG_PULL_TCP,
+            TransportKind.NNG_PUB_IPC,
+            TransportKind.NNG_PUB_TCP,
+            TransportKind.NNG_SUB_IPC,
+            TransportKind.NNG_SUB_TCP,
+        }
 
-@dataclass(frozen=True)
-class TransportProtocol:
-    """Complete transport protocol specification."""
+    @property
+    def is_push(self) -> bool:
+        """True if this is a Push pattern."""
+        return self._kind in {TransportKind.NNG_PUSH_IPC, TransportKind.NNG_PUSH_TCP}
+
+    @property
+    def is_pull(self) -> bool:
+        """True if this is a Pull pattern."""
+        return self._kind in {TransportKind.NNG_PULL_IPC, TransportKind.NNG_PULL_TCP}
+
+    @property
+    def is_pub(self) -> bool:
+        """True if this is a Pub pattern."""
+        return self._kind in {TransportKind.NNG_PUB_IPC, TransportKind.NNG_PUB_TCP}
 
-    library: MessagingLibrary
-    pattern: MessagingPattern
-    layer: TransportLayer
+    @property
+    def is_sub(self) -> bool:
+        """True if this is a Sub pattern."""
+        return self._kind in {TransportKind.NNG_SUB_IPC, TransportKind.NNG_SUB_TCP}
+
+    @property
+    def is_ipc(self) -> bool:
+        """True if this uses IPC layer."""
+        return self._kind in {
+            TransportKind.NNG_PUSH_IPC,
+            TransportKind.NNG_PULL_IPC,
+            TransportKind.NNG_PUB_IPC,
+            TransportKind.NNG_SUB_IPC,
+        }
 
     @property
-    def protocol_string(self) -> str:
-        """Protocol string for parsing (e.g., 'nng+push+ipc')."""
-        return f"{self.library}+{self.pattern}+{self.layer}"
+    def is_tcp(self) -> bool:
+        """True if this uses TCP layer."""
+        return self._kind in {
+            TransportKind.NNG_PUSH_TCP,
+            TransportKind.NNG_PULL_TCP,
+            TransportKind.NNG_PUB_TCP,
+            TransportKind.NNG_SUB_TCP,
+        }
 
     def create_nng_address(self, path_or_host: str) -> str:
         """
         Create the NNG address from a path/host.
 
-        For IPC: adds leading "/" to make absolute path
-        For TCP: uses as-is
+        For IPC: ipc:///path
+        For TCP: tcp://host:port
+
+        Raises:
+            ValueError: If this is not an NNG protocol.
         """
-        if self.layer == Transport.Ipc and not path_or_host.startswith("/"):
-            return f"{self.layer.uri_prefix}/{path_or_host}"
-        return f"{self.layer.uri_prefix}{path_or_host}"
+        if not self.is_nng:
+            raise ValueError(f"Cannot create NNG address for {self._kind} transport")
 
-    @property
-    def is_push(self) -> bool:
-        """Check if this is a push pattern."""
-        return self.pattern == Transport.Push
+        if self.is_ipc:
+            # IPC paths need leading "/" for absolute paths
+            if not path_or_host.startswith("/"):
+                return f"ipc:///{path_or_host}"
+            return f"ipc://{path_or_host}"
 
-    @property
-    def is_pub(self) -> bool:
-        """Check if this is a pub pattern."""
-        return self.pattern == Transport.Pub
+        # TCP
+        return f"tcp://{path_or_host}"
 
     def __str__(self) -> str:
-        return self.protocol_string
+        return self._schema
+
+    def __repr__(self) -> str:
+        return f"TransportProtocol({self._kind.name}, '{self._schema}')"
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, TransportProtocol):
+            return self._kind == other._kind
+        return False
+
+    def __hash__(self) -> int:
+        return hash(self._kind)
 
     @classmethod
     def parse(cls, s: str) -> TransportProtocol:
@@ -108,59 +209,30 @@ class TransportProtocol:
         return result
 
     @classmethod
-    def try_parse(cls, s: str) -> Optional[TransportProtocol]:
+    def try_parse(cls, s: Optional[str]) -> Optional[TransportProtocol]:
         """Try to parse a protocol string."""
         if not s:
             return None
 
-        parts = s.lower().split("+")
-        if len(parts) != 3:
-            return None
-
-        # Parse library
-        if parts[0] == "nng":
-            library = Transport.Nng
-        else:
-            return None
-
-        # Parse pattern
-        if parts[1] == "push":
-            pattern = Transport.Push
-        elif parts[1] == "pull":
-            pattern = Transport.Pull
-        elif parts[1] == "pub":
-            pattern = Transport.Pub
-        elif parts[1] == "sub":
-            pattern = Transport.Sub
-        else:
+        schema = s.lower().strip()
+        kind = cls._SCHEMA_MAP.get(schema)
+        if kind is None:
             return None
 
-        # Parse layer
-        if parts[2] == "ipc":
-            layer = Transport.Ipc
-        elif parts[2] == "tcp":
-            layer = Transport.Tcp
-        else:
-            return None
-
-        return cls(library=library, pattern=pattern, layer=layer)
-
-
-class Transport:
-    """Static helpers for building transport protocols using + operator."""
-
-    # Messaging libraries
-    Nng: MessagingLibrary = MessagingLibrary("nng")
+        return cls(kind, schema)
 
-    # Messaging patterns
-    Push: MessagingPattern = MessagingPattern("push")
-    Pull: MessagingPattern = MessagingPattern("pull")
-    Pub: MessagingPattern = MessagingPattern("pub")
-    Sub: MessagingPattern = MessagingPattern("sub")
 
-    # Transport layers
-    Ipc: TransportLayer = TransportLayer("ipc", "ipc://")
-    Tcp: TransportLayer = TransportLayer("tcp", "tcp://")
+# Initialize predefined protocols
+TransportProtocol.File = TransportProtocol(TransportKind.FILE, "file")
+TransportProtocol.Socket = TransportProtocol(TransportKind.SOCKET, "socket")
+TransportProtocol.NngPushIpc = TransportProtocol(TransportKind.NNG_PUSH_IPC, "nng+push+ipc")
+TransportProtocol.NngPushTcp = TransportProtocol(TransportKind.NNG_PUSH_TCP, "nng+push+tcp")
+TransportProtocol.NngPullIpc = TransportProtocol(TransportKind.NNG_PULL_IPC, "nng+pull+ipc")
+TransportProtocol.NngPullTcp = TransportProtocol(TransportKind.NNG_PULL_TCP, "nng+pull+tcp")
+TransportProtocol.NngPubIpc = TransportProtocol(TransportKind.NNG_PUB_IPC, "nng+pub+ipc")
+TransportProtocol.NngPubTcp = TransportProtocol(TransportKind.NNG_PUB_TCP, "nng+pub+tcp")
+TransportProtocol.NngSubIpc = TransportProtocol(TransportKind.NNG_SUB_IPC, "nng+sub+ipc")
+TransportProtocol.NngSubTcp = TransportProtocol(TransportKind.NNG_SUB_TCP, "nng+sub+tcp")
 
-    # File output (not a real transport)
-    File: str = "file"
+# Initialize reverse lookup map
+TransportProtocol._KIND_TO_SCHEMA = {v: k for k, v in TransportProtocol._SCHEMA_MAP.items()}

rocket_welder_sdk/rocket_welder_client.py

@@ -16,6 +16,12 @@ from .connection_string import ConnectionMode, ConnectionString, Protocol
 from .controllers import DuplexShmController, IController, OneWayShmController
 from .frame_metadata import FrameMetadata  # noqa: TC001 - used at runtime in callbacks
 from .opencv_controller import OpenCvController
+from .session_id import (
+    get_configured_nng_urls,
+    get_nng_urls_from_env,
+    has_explicit_nng_urls,
+)
+from .transport.nng_transport import NngFrameSink
 
 if TYPE_CHECKING:
     import numpy.typing as npt
@@ -53,6 +59,9 @@ class RocketWelderClient:
         self._controller: Optional[IController] = None
         self._lock = threading.Lock()
 
+        # NNG publishers for streaming results (auto-created if SessionId env var is set)
+        self._nng_publishers: dict[str, NngFrameSink] = {}
+
         # Preview support
         self._preview_enabled = (
             self._connection.parameters.get("preview", "false").lower() == "true"
@@ -72,6 +81,50 @@ class RocketWelderClient:
         with self._lock:
             return self._controller is not None and self._controller.is_running
 
+    @property
+    def nng_publishers(self) -> dict[str, NngFrameSink]:
+        """Get NNG publishers for streaming results.
+
+        Returns:
+            Dictionary with 'segmentation', 'keypoints', 'actions' keys.
+            Empty if SessionId env var was not set at startup.
+
+        Example:
+            client.nng_publishers["segmentation"].write_frame(seg_data)
+        """
+        return self._nng_publishers
+
+    def _create_nng_publishers(self) -> None:
+        """Create NNG publishers for result streaming.
+
+        URLs are read from environment variables (preferred) or derived from SessionId (fallback).
+
+        Priority:
+        1. Explicit URLs: SEGMENTATION_SINK_URL, KEYPOINTS_SINK_URL, ACTIONS_SINK_URL
+        2. Derived from SessionId environment variable (backwards compatibility)
+        """
+        try:
+            urls = get_configured_nng_urls()
+
+            for name, url in urls.items():
+                sink = NngFrameSink.create_publisher(url)
+                self._nng_publishers[name] = sink
+                logger.info("NNG publisher ready: %s at %s", name, url)
+
+            # Log configuration summary
+            logger.info(
+                "NNG publishers configured: seg=%s, kp=%s, actions=%s",
+                urls.get("segmentation", "(not configured)"),
+                urls.get("keypoints", "(not configured)"),
+                urls.get("actions", "(not configured)"),
+            )
+        except ValueError as ex:
+            # No URLs configured - this is expected for containers that don't publish results
+            logger.debug("NNG publishers not configured: %s", ex)
+        except Exception as ex:
+            logger.warning("Failed to create NNG publishers: %s", ex)
+            # Don't fail start() - NNG is optional for backwards compatibility
+
     def get_metadata(self) -> Optional[GstMetadata]:
         """
         Get the current GStreamer metadata.
@@ -119,6 +172,21 @@ class RocketWelderClient:
             else:
                 raise ValueError(f"Unsupported protocol: {self._connection.protocol}")
 
+            # Auto-create NNG publishers if URLs are configured
+            # (explicit URLs via SEGMENTATION_SINK_URL etc., or derived from SessionId)
+            if has_explicit_nng_urls():
+                self._create_nng_publishers()
+            else:
+                # Log that NNG is not configured (informational)
+                urls = get_nng_urls_from_env()
+                logger.info(
+                    "NNG sink URLs not configured (this is normal if not publishing AI results). "
+                    "seg=%s, kp=%s, actions=%s",
+                    urls.get("segmentation") or "(not set)",
+                    urls.get("keypoints") or "(not set)",
+                    urls.get("actions") or "(not set)",
+                )
+
             # If preview is enabled, wrap the callback to capture frames
             if self._preview_enabled:
                 self._original_callback = on_frame
@@ -189,6 +257,15 @@ class RocketWelderClient:
                 if self._preview_enabled:
                     self._preview_queue.put(None)  # Sentinel value
 
+                # Clean up NNG publishers
+                for name, sink in self._nng_publishers.items():
+                    try:
+                        sink.close()
+                        logger.debug("Closed NNG publisher: %s", name)
+                    except Exception as ex:
+                        logger.warning("Failed to close NNG publisher %s: %s", name, ex)
+                self._nng_publishers.clear()
+
                 logger.info("RocketWelder client stopped")
 
     def show(self, cancellation_token: Optional[threading.Event] = None) -> None: