devagent-physical-engine 0.10.0__py3-none-any.whl

devagent_physical_engine/robot_platform.py

@@ -0,0 +1,411 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum, IntEnum
+from types import MappingProxyType
+from typing import Any, Iterable, Mapping
+
+from .models import Capability, Resource
+
+
+class RobotPlatformError(ValueError):
+    pass
+
+
+class QualificationState(str, Enum):
+    QUALIFIED = "qualified"
+    EXPERIMENTAL = "experimental"
+    NOT_QUALIFIED = "not_qualified"
+    NOT_SUPPORTED = "not_supported"
+
+
+class SimulationTier(str, Enum):
+    DETERMINISTIC = "deterministic"
+    KINEMATIC = "kinematic"
+    PHYSICS = "physics"
+    VISUAL = "visual"
+
+
+class RobotLifecycleLevel(IntEnum):
+    DISCOVERED = 0
+    SIM_READY = 1
+    SIM_QUALIFIED = 2
+    HARDWARE_VERIFIED = 3
+    SIM_REAL_CORRELATED = 4
+    SITE_QUALIFIED = 5
+
+
+@dataclass(frozen=True, slots=True)
+class RosIntegration:
+    """Robot-facing integration contract, not a claim that a package is installed."""
+
+    ros2_compatible: bool
+    joint_state_interface: str | None = None
+    trajectory_interface: str | None = None
+    robot_description: str | None = None
+    moveit_config: str | None = None
+    hardware_driver: str | None = None
+
+    def __post_init__(self) -> None:
+        for name in (
+            "joint_state_interface",
+            "trajectory_interface",
+            "robot_description",
+            "moveit_config",
+            "hardware_driver",
+        ):
+            value = getattr(self, name)
+            if value is not None and not value.strip():
+                raise RobotPlatformError(f"empty_ros_integration_field:{name}")
+        if not self.ros2_compatible and any(
+            getattr(self, name) is not None
+            for name in (
+                "joint_state_interface",
+                "trajectory_interface",
+                "robot_description",
+                "moveit_config",
+                "hardware_driver",
+            )
+        ):
+            raise RobotPlatformError("non_ros_profile_cannot_declare_ros_packages")
+
+
+@dataclass(frozen=True, slots=True)
+class RobotQualification:
+    simulation: Mapping[SimulationTier, QualificationState]
+    hardware_shadow: QualificationState = QualificationState.NOT_QUALIFIED
+    sim_real_correlation: QualificationState = QualificationState.NOT_QUALIFIED
+    site_qualification: QualificationState = QualificationState.NOT_QUALIFIED
+
+    def __post_init__(self) -> None:
+        normalized = {
+            tier: self.simulation.get(tier, QualificationState.NOT_QUALIFIED)
+            for tier in SimulationTier
+        }
+        object.__setattr__(self, "simulation", MappingProxyType(normalized))
+
+    def state_for(self, tier: SimulationTier) -> QualificationState:
+        return self.simulation[tier]
+
+    @property
+    def highest_qualified_simulation_tier(self) -> SimulationTier | None:
+        order = (
+            SimulationTier.DETERMINISTIC,
+            SimulationTier.KINEMATIC,
+            SimulationTier.PHYSICS,
+            SimulationTier.VISUAL,
+        )
+        qualified = [
+            tier
+            for tier in order
+            if self.simulation[tier] is QualificationState.QUALIFIED
+        ]
+        return qualified[-1] if qualified else None
+
+
+@dataclass(frozen=True, slots=True)
+class RobotLimits:
+    payload_kg: float | None = None
+    reach_m: float | None = None
+
+    def __post_init__(self) -> None:
+        if self.payload_kg is not None and self.payload_kg <= 0:
+            raise RobotPlatformError("payload_limit_invalid")
+        if self.reach_m is not None and self.reach_m <= 0:
+            raise RobotPlatformError("reach_limit_invalid")
+
+
+@dataclass(frozen=True, slots=True)
+class RobotProfile:
+    key: str
+    vendor: str
+    model: str
+    capabilities: frozenset[Capability]
+    qualification: RobotQualification
+    ros: RosIntegration
+    limits: RobotLimits = field(default_factory=RobotLimits)
+    aliases: tuple[str, ...] = ()
+    resource_type: str = "industrial_arm"
+    controller_family: str | None = None
+    legacy_qualification: str | None = None
+    notes: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        key = self.key.strip().lower()
+        vendor = self.vendor.strip().lower()
+        model = self.model.strip().lower()
+        if not key or not vendor or not model:
+            raise RobotPlatformError("robot_profile_identity_required")
+        if not self.resource_type.strip():
+            raise RobotPlatformError("robot_resource_type_required")
+        if not self.capabilities:
+            raise RobotPlatformError("robot_capabilities_required")
+        if any(not alias.strip() for alias in self.aliases):
+            raise RobotPlatformError("empty_robot_alias")
+        if len(set(alias.strip().lower() for alias in self.aliases)) != len(self.aliases):
+            raise RobotPlatformError("duplicate_robot_alias")
+        if self.legacy_qualification is not None and not self.legacy_qualification.strip():
+            raise RobotPlatformError("empty_legacy_qualification")
+        if any(not note.strip() for note in self.notes):
+            raise RobotPlatformError("empty_robot_note")
+        object.__setattr__(self, "key", key)
+        object.__setattr__(self, "vendor", vendor)
+        object.__setattr__(self, "model", model)
+        object.__setattr__(
+            self,
+            "aliases",
+            tuple(alias.strip().lower() for alias in self.aliases),
+        )
+        if self.legacy_qualification is not None:
+            object.__setattr__(
+                self,
+                "legacy_qualification",
+                self.legacy_qualification.strip().lower(),
+            )
+
+    @property
+    def lifecycle_level(self) -> RobotLifecycleLevel:
+        if self.qualification.site_qualification is QualificationState.QUALIFIED:
+            return RobotLifecycleLevel.SITE_QUALIFIED
+        if self.qualification.sim_real_correlation is QualificationState.QUALIFIED:
+            return RobotLifecycleLevel.SIM_REAL_CORRELATED
+        if self.qualification.hardware_shadow is QualificationState.QUALIFIED:
+            return RobotLifecycleLevel.HARDWARE_VERIFIED
+
+        physical_states = tuple(
+            self.qualification.state_for(tier)
+            for tier in (
+                SimulationTier.KINEMATIC,
+                SimulationTier.PHYSICS,
+                SimulationTier.VISUAL,
+            )
+        )
+        if any(state is QualificationState.QUALIFIED for state in physical_states):
+            return RobotLifecycleLevel.SIM_QUALIFIED
+        if any(state is QualificationState.EXPERIMENTAL for state in physical_states):
+            return RobotLifecycleLevel.SIM_READY
+        return RobotLifecycleLevel.DISCOVERED
+
+    def to_resource(self, resource_id: str = "robot_01") -> Resource:
+        if not resource_id.strip():
+            raise RobotPlatformError("resource_id_required")
+        highest = self.qualification.highest_qualified_simulation_tier
+        metadata: dict[str, Any] = {
+            "robot_profile": self.key,
+            "vendor": self.vendor,
+            "model": self.model,
+            "qualification": self.legacy_qualification
+            or (highest.value if highest is not None else "not_qualified"),
+            "simulation_qualification": {
+                tier.value: self.qualification.state_for(tier).value
+                for tier in SimulationTier
+            },
+            "hardware_shadow_qualification": self.qualification.hardware_shadow.value,
+            "sim_real_qualification": self.qualification.sim_real_correlation.value,
+            "site_qualification": self.qualification.site_qualification.value,
+            "lifecycle_level": int(self.lifecycle_level),
+            "lifecycle_name": self.lifecycle_level.name.lower(),
+            "real_execution_locked": True,
+        }
+        if self.controller_family:
+            metadata["controller_family"] = self.controller_family
+        return Resource(
+            resource_id,
+            self.resource_type,
+            self.capabilities,
+            metadata,
+        )
+
+
+class RobotProfileRegistry:
+    """Vendor-neutral profile registry with deterministic alias resolution."""
+
+    def __init__(self, profiles: Iterable[RobotProfile] = ()) -> None:
+        self._profiles: dict[str, RobotProfile] = {}
+        self._aliases: dict[str, str] = {}
+        for profile in profiles:
+            self.register(profile)
+
+    @staticmethod
+    def _normalize(value: str) -> str:
+        return "_".join(value.strip().lower().replace("-", " ").split())
+
+    def register(self, profile: RobotProfile, *, replace: bool = False) -> None:
+        key = self._normalize(profile.key)
+        aliases = {
+            self._normalize(profile.key),
+            self._normalize(f"{profile.vendor} {profile.model}"),
+            *(self._normalize(alias) for alias in profile.aliases),
+        }
+        if key in self._profiles and not replace:
+            raise RobotPlatformError(f"duplicate_robot_profile:{key}")
+        for alias in aliases:
+            owner = self._aliases.get(alias)
+            # replace=True may update the same profile, but it must never steal
+            # an alias owned by a different robot profile.
+            if owner is not None and owner != key:
+                raise RobotPlatformError(f"duplicate_robot_alias:{alias}")
+
+        if replace and key in self._profiles:
+            stale = [alias for alias, owner in self._aliases.items() if owner == key]
+            for alias in stale:
+                del self._aliases[alias]
+
+        self._profiles[key] = profile
+        for alias in aliases:
+            self._aliases[alias] = key
+
+    def resolve(self, name: str) -> RobotProfile:
+        normalized = self._normalize(name)
+        try:
+            key = self._aliases[normalized]
+            return self._profiles[key]
+        except KeyError as exc:
+            raise RobotPlatformError(f"unknown_robot_profile:{normalized}") from exc
+
+    def get(self, key: str) -> RobotProfile:
+        normalized = self._normalize(key)
+        try:
+            return self._profiles[normalized]
+        except KeyError as exc:
+            raise RobotPlatformError(f"unknown_robot_profile:{normalized}") from exc
+
+    def keys(self) -> tuple[str, ...]:
+        return tuple(sorted(self._profiles))
+
+    def all(self) -> tuple[RobotProfile, ...]:
+        return tuple(self._profiles[key] for key in self.keys())
+
+    def capability_matrix(self) -> tuple[dict[str, Any], ...]:
+        rows: list[dict[str, Any]] = []
+        for profile in self.all():
+            rows.append(
+                {
+                    "robot": profile.key,
+                    "vendor": profile.vendor,
+                    "model": profile.model,
+                    "ros2": profile.ros.ros2_compatible,
+                    "lifecycle_level": int(profile.lifecycle_level),
+                    "lifecycle_name": profile.lifecycle_level.name.lower(),
+                    "simulation": {
+                        tier.value: profile.qualification.state_for(tier).value
+                        for tier in SimulationTier
+                    },
+                    "hardware_shadow": profile.qualification.hardware_shadow.value,
+                    "sim_real": profile.qualification.sim_real_correlation.value,
+                    "site": profile.qualification.site_qualification.value,
+                }
+            )
+        return tuple(rows)
+
+
+ARM_CAPABILITIES = frozenset(
+    {
+        Capability.MOVE,
+        Capability.PICK,
+        Capability.PLACE,
+        Capability.WAIT,
+        Capability.TRANSFER,
+    }
+)
+
+
+def _qualification(
+    *,
+    deterministic: QualificationState = QualificationState.QUALIFIED,
+    kinematic: QualificationState = QualificationState.NOT_QUALIFIED,
+    physics: QualificationState = QualificationState.NOT_QUALIFIED,
+    visual: QualificationState = QualificationState.NOT_QUALIFIED,
+) -> RobotQualification:
+    return RobotQualification(
+        {
+            SimulationTier.DETERMINISTIC: deterministic,
+            SimulationTier.KINEMATIC: kinematic,
+            SimulationTier.PHYSICS: physics,
+            SimulationTier.VISUAL: visual,
+        }
+    )
+
+
+# These statuses describe only evidence already established inside DevAgent.
+# They intentionally do not infer hardware or sim-real qualification from the
+# existence of an external vendor/ROS package.
+BUILTIN_ROBOT_PROFILES = RobotProfileRegistry(
+    (
+        RobotProfile(
+            key="ur5e",
+            vendor="universal_robots",
+            model="ur5e",
+            capabilities=ARM_CAPABILITIES,
+            qualification=_qualification(
+                kinematic=QualificationState.QUALIFIED,
+                physics=QualificationState.QUALIFIED,
+                visual=QualificationState.QUALIFIED,
+            ),
+            ros=RosIntegration(
+                ros2_compatible=True,
+                joint_state_interface="/joint_states",
+                trajectory_interface="joint_trajectory_controller/follow_joint_trajectory",
+                robot_description="ur_description",
+                moveit_config="ur_moveit_config",
+                hardware_driver="ur_robot_driver",
+            ),
+            aliases=("ur 5e", "universal robots ur5e", "universal robot ur5e"),
+            legacy_qualification="primary",
+            notes=(
+                "DevAgent visual Gazebo/MoveIt workstation qualification exists; real execution remains locked.",
+            ),
+        ),
+        RobotProfile(
+            key="fanuc_crx",
+            vendor="fanuc",
+            model="crx",
+            capabilities=ARM_CAPABILITIES,
+            qualification=_qualification(),
+            ros=RosIntegration(
+                ros2_compatible=True,
+                joint_state_interface="/joint_states",
+                trajectory_interface="follow_joint_trajectory",
+            ),
+            aliases=("fanuc crx", "crx"),
+            legacy_qualification="primary",
+            notes=(
+                "Deterministic DevAgent qualification only until an exact ROS/simulator/controller profile is qualified.",
+            ),
+        ),
+        RobotProfile(
+            key="kuka_kr",
+            vendor="kuka",
+            model="kr",
+            capabilities=ARM_CAPABILITIES,
+            qualification=_qualification(),
+            ros=RosIntegration(
+                ros2_compatible=True,
+                joint_state_interface="/joint_states",
+                trajectory_interface="follow_joint_trajectory",
+            ),
+            aliases=("kuka kr",),
+            legacy_qualification="primary",
+            notes=(
+                "Deterministic DevAgent qualification only until an exact KR/controller profile is qualified.",
+            ),
+        ),
+        RobotProfile(
+            key="abb_irb",
+            vendor="abb",
+            model="irb",
+            capabilities=ARM_CAPABILITIES,
+            qualification=_qualification(),
+            ros=RosIntegration(
+                ros2_compatible=True,
+                joint_state_interface="/joint_states",
+                trajectory_interface="follow_joint_trajectory",
+            ),
+            aliases=("abb irb",),
+            legacy_qualification="simulation",
+            notes=(
+                "Generic IRB family placeholder; exact ABB model/controller qualification is required before physical claims.",
+            ),
+        ),
+    )
+)

devagent_physical_engine/robots.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, Mapping
+
+from .models import Resource
+from .robot_platform import (
+    ARM_CAPABILITIES,
+    BUILTIN_ROBOT_PROFILES,
+    RobotPlatformError,
+    RobotProfileRegistry,
+)
+
+
+PROFILE_REGISTRY: RobotProfileRegistry = BUILTIN_ROBOT_PROFILES
+
+
+def _resource(profile_key: str, resource_id: str) -> Resource:
+    return PROFILE_REGISTRY.get(profile_key).to_resource(resource_id)
+
+
+def ur5e(resource_id: str = "robot_01") -> Resource:
+    return _resource("ur5e", resource_id)
+
+
+def fanuc_crx(resource_id: str = "robot_01") -> Resource:
+    return _resource("fanuc_crx", resource_id)
+
+
+def kuka_kr(resource_id: str = "robot_01") -> Resource:
+    return _resource("kuka_kr", resource_id)
+
+
+def abb_irb(resource_id: str = "robot_01") -> Resource:
+    return _resource("abb_irb", resource_id)
+
+
+class _RegistryBackedCatalog(Mapping[str, Callable[..., Resource]]):
+    """Compatibility view for older core code that expects CATALOG[key]().
+
+    Membership, iteration, and lookup are backed by RobotProfileRegistry. New
+    profiles therefore do not require changes in request/qualification core.
+    Aliases resolve to the profile's canonical identity before a Resource is built.
+
+    ``Mapping`` requires missing keys to raise ``KeyError``. The registry uses
+    ``RobotPlatformError`` for unknown robot identities, so that exception is
+    translated at this compatibility boundary. This preserves legacy
+    ``key in CATALOG`` / ``key not in CATALOG`` semantics without weakening the
+    registry's explicit error contract elsewhere.
+    """
+
+    def __init__(self, registry: RobotProfileRegistry) -> None:
+        self.registry = registry
+
+    def __getitem__(self, key: str) -> Callable[..., Resource]:
+        try:
+            profile = self.registry.resolve(key)
+        except RobotPlatformError as exc:
+            raise KeyError(key) from exc
+
+        def factory(resource_id: str = "robot_01") -> Resource:
+            return profile.to_resource(resource_id)
+
+        return factory
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.registry.keys())
+
+    def __len__(self) -> int:
+        return len(self.registry.keys())
+
+
+# Backward-compatible callable catalog used by v0.6/v0.7. New code should use
+# PROFILE_REGISTRY directly for qualification and integration metadata.
+CATALOG: Mapping[str, Callable[..., Resource]] = _RegistryBackedCatalog(
+    PROFILE_REGISTRY
+)

devagent_physical_engine/ros2/__init__.py

@@ -0,0 +1,35 @@
+from .acceptance import AcceptanceStage, LaptopAcceptanceReport, UR5eLaptopAcceptance
+from .commands import CommandResult, SubprocessRosRunner
+from .doctor import RosCheck, RosDoctor, RosDoctorReport
+from .trajectory import (
+    JointStateSnapshot,
+    RosTrajectoryError,
+    execute_joint_trajectory,
+    follow_joint_trajectory_command,
+    read_joint_state,
+)
+from .ur5e import UR5eSimulationLauncher, official_ur5e_moveit_command, official_ur_motion_smoke_command
+from .ur5e_adapter import UR5E_JOINTS, UR5eGazeboAdapter
+from .ur5e_v10_adapter import UR5eCanonicalTwinAdapter
+
+__all__ = [
+    "AcceptanceStage",
+    "LaptopAcceptanceReport",
+    "UR5eLaptopAcceptance",
+    "CommandResult",
+    "SubprocessRosRunner",
+    "RosCheck",
+    "RosDoctor",
+    "RosDoctorReport",
+    "JointStateSnapshot",
+    "RosTrajectoryError",
+    "execute_joint_trajectory",
+    "follow_joint_trajectory_command",
+    "read_joint_state",
+    "UR5E_JOINTS",
+    "UR5eGazeboAdapter",
+    "UR5eCanonicalTwinAdapter",
+    "UR5eSimulationLauncher",
+    "official_ur5e_moveit_command",
+    "official_ur_motion_smoke_command",
+]