foodforthought-cli 0.2.8__py3-none-any.whl → 0.3.0__py3-none-any.whl

ate/robot/types.py

@@ -0,0 +1,242 @@
+"""
+Unified type definitions for robot joints and servos.
+
+This module provides a single source of truth for joint-related enums,
+avoiding inconsistencies across different modules.
+
+Two distinct concepts:
+- JointType: How the joint moves mechanically (URDF standard)
+- JointRole: What function the joint serves on the robot body
+"""
+
+from enum import Enum
+from typing import Optional, List
+
+
+class JointType(Enum):
+    """
+    Mechanical joint type following URDF conventions.
+
+    Describes HOW the joint moves, not what it's used for.
+    Compatible with standard robotics formats (URDF, SDF, MJCF).
+    """
+    UNKNOWN = "unknown"
+    REVOLUTE = "revolute"      # Rotation around an axis with limits
+    PRISMATIC = "prismatic"    # Linear translation along an axis
+    CONTINUOUS = "continuous"  # Rotation without limits (wheels)
+    FIXED = "fixed"            # No relative motion
+    FLOATING = "floating"      # 6DOF free motion (rare)
+    PLANAR = "planar"          # 2D motion in a plane (rare)
+
+    @classmethod
+    def from_string(cls, value: str) -> "JointType":
+        """
+        Parse joint type from string, with helpful error messages.
+
+        Accepts common variations and provides suggestions on failure.
+        """
+        if not value:
+            return cls.UNKNOWN
+
+        normalized = value.lower().strip()
+
+        # Direct match
+        for member in cls:
+            if member.value == normalized:
+                return member
+
+        # Common aliases
+        aliases = {
+            "rotary": cls.REVOLUTE,
+            "rotation": cls.REVOLUTE,
+            "rotate": cls.REVOLUTE,
+            "linear": cls.PRISMATIC,
+            "sliding": cls.PRISMATIC,
+            "slide": cls.PRISMATIC,
+            "wheel": cls.CONTINUOUS,
+            "static": cls.FIXED,
+            "rigid": cls.FIXED,
+            "free": cls.FLOATING,
+        }
+
+        if normalized in aliases:
+            return aliases[normalized]
+
+        # Fuzzy match - check if value contains any known type
+        for member in cls:
+            if member.value in normalized or normalized in member.value:
+                return member
+
+        # No match - return UNKNOWN but could raise with suggestions
+        return cls.UNKNOWN
+
+    @classmethod
+    def valid_values(cls) -> List[str]:
+        """Return list of valid values for error messages."""
+        return [m.value for m in cls if m != cls.UNKNOWN]
+
+
+class JointRole(Enum):
+    """
+    Semantic role/function of a joint on the robot body.
+
+    Describes WHAT the joint does, not how it moves mechanically.
+    Used for semantic skill development and pose mapping.
+    """
+    UNKNOWN = "unknown"
+
+    # Locomotion - Legs
+    HIP_ROLL = "hip_roll"
+    HIP_PITCH = "hip_pitch"
+    HIP_YAW = "hip_yaw"
+    KNEE = "knee"
+    ANKLE = "ankle"
+    ANKLE_ROLL = "ankle_roll"
+
+    # Arm - Shoulder
+    SHOULDER_PAN = "shoulder_pan"
+    SHOULDER_LIFT = "shoulder_lift"
+    SHOULDER_ROLL = "shoulder_roll"
+
+    # Arm - Elbow/Wrist
+    ELBOW = "elbow"
+    ELBOW_ROLL = "elbow_roll"
+    WRIST_ROLL = "wrist_roll"
+    WRIST_PITCH = "wrist_pitch"
+    WRIST_YAW = "wrist_yaw"
+
+    # End Effector
+    GRIPPER = "gripper"
+    FINGER = "finger"
+
+    # Body/Head
+    HEAD_PAN = "head_pan"
+    HEAD_TILT = "head_tilt"
+    BODY_PITCH = "body_pitch"
+    BODY_ROLL = "body_roll"
+    TORSO = "torso"
+
+    # Wheels/Tracks
+    WHEEL = "wheel"
+    TRACK = "track"
+
+    @classmethod
+    def from_string(cls, value: str) -> "JointRole":
+        """
+        Parse joint role from string, with intelligent fallbacks.
+
+        Handles common variations and provides best-effort matching.
+        """
+        if not value:
+            return cls.UNKNOWN
+
+        normalized = value.lower().strip().replace("-", "_").replace(" ", "_")
+
+        # Direct match
+        for member in cls:
+            if member.value == normalized:
+                return member
+
+        # Common aliases and partial matches
+        aliases = {
+            # Arm shortcuts
+            "shoulder": cls.SHOULDER_LIFT,
+            "arm_shoulder": cls.SHOULDER_LIFT,
+            "arm_elbow": cls.ELBOW,
+            "arm_wrist": cls.WRIST_ROLL,
+
+            # Leg shortcuts
+            "hip": cls.HIP_PITCH,
+            "thigh": cls.HIP_PITCH,
+            "calf": cls.KNEE,
+            "shin": cls.KNEE,
+            "foot": cls.ANKLE,
+
+            # Generic URDF types -> infer role from context
+            "revolute": cls.UNKNOWN,  # Could be anything
+            "prismatic": cls.UNKNOWN,
+            "continuous": cls.WHEEL,
+
+            # End effector
+            "claw": cls.GRIPPER,
+            "hand": cls.GRIPPER,
+            "pincer": cls.GRIPPER,
+        }
+
+        if normalized in aliases:
+            return aliases[normalized]
+
+        # Fuzzy match - check if value contains any known role
+        for member in cls:
+            if member.value in normalized:
+                return member
+            if normalized in member.value:
+                return member
+
+        return cls.UNKNOWN
+
+    @classmethod
+    def valid_values(cls) -> List[str]:
+        """Return list of valid values for error messages."""
+        return [m.value for m in cls if m != cls.UNKNOWN]
+
+    @classmethod
+    def suggest_similar(cls, value: str, max_suggestions: int = 3) -> List[str]:
+        """
+        Suggest similar valid values for a given invalid input.
+
+        Uses simple substring matching for suggestions.
+        """
+        if not value:
+            return []
+
+        normalized = value.lower().strip()
+        suggestions = []
+
+        for member in cls:
+            if member == cls.UNKNOWN:
+                continue
+            # Check for partial matches
+            if normalized in member.value or member.value in normalized:
+                suggestions.append(member.value)
+            # Check for word overlap
+            elif any(word in member.value for word in normalized.split("_")):
+                suggestions.append(member.value)
+
+        return suggestions[:max_suggestions]
+
+
+def infer_joint_type_from_role(role: JointRole) -> JointType:
+    """
+    Infer the most likely mechanical joint type from a semantic role.
+
+    Most robot joints are revolute, with some exceptions.
+    """
+    prismatic_roles = {
+        JointRole.GRIPPER,  # Many grippers are linear
+        JointRole.FINGER,
+    }
+
+    continuous_roles = {
+        JointRole.WHEEL,
+        JointRole.TRACK,
+    }
+
+    if role in prismatic_roles:
+        return JointType.REVOLUTE  # Actually most grippers are revolute too
+    elif role in continuous_roles:
+        return JointType.CONTINUOUS
+    elif role == JointRole.UNKNOWN:
+        return JointType.UNKNOWN
+    else:
+        return JointType.REVOLUTE  # Default for most robot joints
+
+
+def format_valid_options(enum_class, prefix: str = "Valid options") -> str:
+    """Format valid enum options for error messages."""
+    values = [m.value for m in enum_class if m.value != "unknown"]
+    return f"{prefix}: {', '.join(values)}"
+
+
+# Type aliases for backwards compatibility
+ServoType = JointRole  # Alias for semantic clarity in servo contexts

ate/robot/visual_labeler.py

@@ -1037,3 +1037,12 @@ def list_skill_libraries() -> List[str]:
     if not lib_dir.exists():
         return []
     return [p.stem for p in lib_dir.glob("*.json")]
+
+
+def save_skill_library(library: SkillLibrary) -> Path:
+    """Save a skill library to disk."""
+    lib_dir = Path.home() / ".ate" / "skill_libraries"
+    lib_dir.mkdir(parents=True, exist_ok=True)
+    lib_path = lib_dir / f"{library.robot_name}.json"
+    library.save(lib_path)
+    return lib_path