physicalai-studio-plugin 0.1.0__py3-none-any.whl

physicalai_studio_plugin/__init__.py

@@ -0,0 +1,28 @@
+"""Public API for the Physical AI Studio plugin."""
+
+from .assets import RobotAsset
+from .catalog import (
+    BuildRobotCallable,
+    CatalogRobot,
+    PayloadContainer,
+    RobotAdapterOptions,
+    RobotCatalogDefinition,
+    RobotCatalogRegistry,
+)
+from .factory import CatalogRobotFactory
+from .probe import PortScanner, RobotProbe
+from .schemas import SerialPortInfo
+
+__all__ = [
+    "BuildRobotCallable",
+    "CatalogRobot",
+    "CatalogRobotFactory",
+    "PayloadContainer",
+    "PortScanner",
+    "RobotAdapterOptions",
+    "RobotAsset",
+    "RobotCatalogDefinition",
+    "RobotCatalogRegistry",
+    "RobotProbe",
+    "SerialPortInfo",
+]

physicalai_studio_plugin/assets.py

@@ -0,0 +1,20 @@
+"""Data structures describing robot visualization assets."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+
+@dataclass(frozen=True)
+class RobotAsset:
+    """Filesystem configuration for a robot's visual model and ROS packages."""
+
+    urdf_relative_path: Path
+    packages: dict[str, Path]
+    joint_map: dict[str, list[str]]
+    root_resolver: Callable[[], Path] | None = None

physicalai_studio_plugin/catalog.py

@@ -0,0 +1,71 @@
+"""Core plugin catalog protocol and definition types."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Generic, Literal, Protocol, TypeVar
+
+from physicalai.robot.interface import Robot as PhysicalAIRobot
+from pydantic import BaseModel
+
+from .factory import CatalogRobotFactory
+
+if TYPE_CHECKING:
+    from .assets import RobotAsset
+    from .probe import RobotProbe
+
+
+@dataclass(frozen=True)
+class RobotAdapterOptions:
+    """Controls adapter behavior for velocity, timing, and effort handling."""
+
+    include_velocities: bool = False
+    goal_time_scale: float = 1.0
+    external_effort_gain: float | None = 0.1
+
+
+_PayloadT = TypeVar("_PayloadT", bound=BaseModel)
+_PayloadModelT = type[_PayloadT]
+
+
+class PayloadContainer(Protocol[_PayloadT]):
+    """Object with a typed ``payload`` attribute."""
+
+    payload: _PayloadT
+
+
+class CatalogRobot(PayloadContainer[_PayloadT], Protocol[_PayloadT]):
+    """Typed robot descriptor passed to catalog robot builders."""
+
+    type: str
+
+
+_RobotT = TypeVar("_RobotT", bound=CatalogRobot[Any])
+_FactoryT = TypeVar("_FactoryT", bound=CatalogRobotFactory)
+
+
+BuildRobotCallable = Callable[[_RobotT, _FactoryT], Awaitable[PhysicalAIRobot]]
+
+
+@dataclass
+class RobotCatalogDefinition(Generic[_PayloadT]):
+    """Complete definition of a plugin robot type for Studio registration."""
+
+    type: str
+    display_name: str
+    role: Literal["follower", "leader"]
+    robot_builder: BuildRobotCallable | None = None
+    robot_payload: _PayloadModelT | None = None
+    asset: RobotAsset | None = None
+
+    adapter_options: RobotAdapterOptions = field(default_factory=RobotAdapterOptions)
+    probe: RobotProbe[_PayloadT] | None = None
+
+
+class RobotCatalogRegistry(Protocol):
+    """Registry interface used by plugin entry points to add robot definitions."""
+
+    def register_robot(self, definition: RobotCatalogDefinition) -> None:
+        """Register one robot catalog definition with Studio."""
+        ...

physicalai_studio_plugin/factory.py

@@ -0,0 +1,19 @@
+"""Factory protocol exposed to plugin robot-builder callables."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from .schemas import SerialPortInfo
+
+
+class CatalogRobotFactory(Protocol):
+    """Factory protocol provided by Studio to robot builders.
+
+    Plugin ``robot_builder`` callables receive an instance of this protocol
+    so they can resolve serial ports at build time.
+    """
+
+    async def find_port(self, port_info: SerialPortInfo) -> str | None:
+        """Return the resolved connection port, if present."""

physicalai_studio_plugin/probe.py

@@ -0,0 +1,56 @@
+"""Probe and scanner protocols used by plugin robot integrations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, TypeVar, runtime_checkable
+
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from .schemas import SerialPortInfo
+
+_PayloadT_contra = TypeVar("_PayloadT_contra", bound=BaseModel, contravariant=True)
+
+
+class PortScanner(Protocol):
+    """Duck-type for serial port scanners (e.g. RobotConnectionManager).
+
+    Used by RobotProbe to accept scan results without coupling to a specific
+    manager implementation.
+    """
+
+    async def find_robots(self) -> None:
+        """Refresh discovered robot connections."""
+
+    @property
+    def robots(self) -> list[SerialPortInfo]:
+        """Return currently discovered robot connections."""
+
+
+@runtime_checkable
+class RobotProbe(Protocol[_PayloadT_contra]):
+    """Hardware interaction interface for a robot type.
+
+    Each built-in or plugin-provided robot type implements this protocol
+    to encapsulate device discovery, visual identification, and online
+    status checking. The type parameter ``_PayloadT`` is the robot's
+    payload model (a pydantic ``BaseModel`` subclass).
+    """
+
+    async def discover(self, manager: PortScanner) -> list[SerialPortInfo]:
+        """Discover robots and return current connection metadata."""
+
+    async def identify(
+        self,
+        payload: _PayloadT_contra,
+        manager: PortScanner | None,
+        joint: str | None = None,
+    ) -> None:
+        """Trigger physical identification behavior for a robot."""
+
+    async def is_online(
+        self,
+        payload: _PayloadT_contra,
+        manager: PortScanner | None = None,
+    ) -> bool:
+        """Return whether the robot appears online."""

physicalai_studio_plugin/schemas.py

@@ -0,0 +1,12 @@
+"""Pydantic schemas shared by plugin protocols."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class SerialPortInfo(BaseModel):
+    """Connection metadata for a discovered serial or network robot."""
+
+    connection_string: str | None
+    serial_number: str | None

physicalai_studio_plugin-0.1.0.dist-info/METADATA

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: physicalai-studio-plugin
+Version: 0.1.0
+Summary: Plugin SDK for Physical AI Studio — types and protocols for building robot catalog plugins
+Requires-Python: >=3.12
+Requires-Dist: physicalai
+Requires-Dist: pydantic>=2.12

physicalai_studio_plugin-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+physicalai_studio_plugin/__init__.py,sha256=HbK5lwiMmM9hihsBJla9oHsKAxsAapnUTgzneOgqfjc,646
+physicalai_studio_plugin/assets.py,sha256=GAGIE00TgQ7wfEydF8dOVaNKwgRKlwQUrPhGwu_5ISE,526
+physicalai_studio_plugin/catalog.py,sha256=r8qnd3VMfOJoNK86VN7rUa7QggT4v8HbiK59y0rC7Pg,2056
+physicalai_studio_plugin/factory.py,sha256=Y8UWSmBwYNnXv2fJJ2K_KmMynnqDLZURf5oeCefns5s,579
+physicalai_studio_plugin/probe.py,sha256=m_c6BpOYb-qbseIg38g3g-sSFWRSZbxQjmWLnREDtB8,1751
+physicalai_studio_plugin/schemas.py,sha256=7kjqR3xak_70OlZM4Z8P_mWFeDiVGMqhSbHqs0ow7Kc,291
+physicalai_studio_plugin-0.1.0.dist-info/METADATA,sha256=AkoCAwbD-12f5ary_PDSGPf9ATMfZmPrKWWzmuAiyNA,250
+physicalai_studio_plugin-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+physicalai_studio_plugin-0.1.0.dist-info/RECORD,,

physicalai_studio_plugin-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any