slashml-robotics 1.0.0__tar.gz

slashml_robotics-1.0.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: slashml-robotics
+Version: 1.0.0
+Summary: Official Robotics & Spatial Memory SDK for SlashML
+Author: SlashML Robotics Inc.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://slashml.ai
+Project-URL: Repository, https://github.com/slashml-ai/slashml-robotics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: slashml-memory>=1.0.9
+Requires-Dist: numpy>=1.24.0
+
+# SlashML Robotics Python SDK
+
+Ultra-low-latency spatial memory and dynamic belief tracking for embodied AI, mobile manipulation, and autonomous robots.
+
+## Overview
+
+`slashml-robotics` provides a sub-millisecond, zero-recomputation spatial memory substrate for robotics perception pipelines and mission planners:
+- **O(1) Dynamic Spatial Supersession**: Updates object locations instantly and marks obsolete historical coordinates as superseded without full-database reindexing.
+- **Sub-Microsecond `where_is`**: Query active 6-DoF poses and room zones with sub-microsecond retrieval latency.
+- **Chronological Trajectory Reconstruction**: Full movement history tracking across workspaces and rooms.
+- **Physical Affordance Search**: Discover tools and objects based on functional capabilities (e.g. `fastening`, `measuring`, `stripping`).
+
+## Installation
+
+```bash
+pip install slashml-robotics
+```
+
+## Quickstart
+
+```python
+from slashml_robotics import RoboticMemory, Pose6D
+
+# Initialize client connected to SlashML engine daemon or cloud endpoint
+memory = RoboticMemory(base_url="http://localhost:8000", api_key="sk_...")
+
+# 1. Ingest camera / perception detection
+memory.add_observation(
+    object_name="torque_wrench",
+    room_zone="machining_bay",
+    pose=Pose6D(x=1.24, y=-0.52, z=0.85, qx=0.0, qy=0.0, qz=0.0, qw=1.0),
+    tags=["tool", "hardware"],
+)
+
+# 2. Query active location
+loc = memory.where_is("torque_wrench")
+if loc:
+    print(f"Found {loc.object_name} in {loc.room_zone} at ({loc.pose.x}, {loc.pose.y}, {loc.pose.z})")
+
+# 3. Retrieve movement trajectory
+trajectory = memory.get_trajectory("torque_wrench")
+print(f"Total waypoints recorded: {trajectory.total_waypoints}")
+
+# 4. Search by physical affordance
+tools = memory.find_by_affordance("fastening", room_zone="machining_bay")
+for t in tools:
+    print(f"Available fastening tool: {t.object_name}")
+```
+
+## License
+
+Apache-2.0

slashml_robotics-1.0.0/README.md

@@ -0,0 +1,52 @@
+# SlashML Robotics Python SDK
+
+Ultra-low-latency spatial memory and dynamic belief tracking for embodied AI, mobile manipulation, and autonomous robots.
+
+## Overview
+
+`slashml-robotics` provides a sub-millisecond, zero-recomputation spatial memory substrate for robotics perception pipelines and mission planners:
+- **O(1) Dynamic Spatial Supersession**: Updates object locations instantly and marks obsolete historical coordinates as superseded without full-database reindexing.
+- **Sub-Microsecond `where_is`**: Query active 6-DoF poses and room zones with sub-microsecond retrieval latency.
+- **Chronological Trajectory Reconstruction**: Full movement history tracking across workspaces and rooms.
+- **Physical Affordance Search**: Discover tools and objects based on functional capabilities (e.g. `fastening`, `measuring`, `stripping`).
+
+## Installation
+
+```bash
+pip install slashml-robotics
+```
+
+## Quickstart
+
+```python
+from slashml_robotics import RoboticMemory, Pose6D
+
+# Initialize client connected to SlashML engine daemon or cloud endpoint
+memory = RoboticMemory(base_url="http://localhost:8000", api_key="sk_...")
+
+# 1. Ingest camera / perception detection
+memory.add_observation(
+    object_name="torque_wrench",
+    room_zone="machining_bay",
+    pose=Pose6D(x=1.24, y=-0.52, z=0.85, qx=0.0, qy=0.0, qz=0.0, qw=1.0),
+    tags=["tool", "hardware"],
+)
+
+# 2. Query active location
+loc = memory.where_is("torque_wrench")
+if loc:
+    print(f"Found {loc.object_name} in {loc.room_zone} at ({loc.pose.x}, {loc.pose.y}, {loc.pose.z})")
+
+# 3. Retrieve movement trajectory
+trajectory = memory.get_trajectory("torque_wrench")
+print(f"Total waypoints recorded: {trajectory.total_waypoints}")
+
+# 4. Search by physical affordance
+tools = memory.find_by_affordance("fastening", room_zone="machining_bay")
+for t in tools:
+    print(f"Available fastening tool: {t.object_name}")
+```
+
+## License
+
+Apache-2.0

slashml_robotics-1.0.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "slashml-robotics"
+version = "1.0.0"
+description = "Official Robotics & Spatial Memory SDK for SlashML"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{name = "SlashML Robotics Inc."}]
+dependencies = [
+    "slashml-memory>=1.0.9",
+    "numpy>=1.24.0",
+]
+
+[project.urls]
+Homepage = "https://slashml.ai"
+Repository = "https://github.com/slashml-ai/slashml-robotics"
+
+[tool.setuptools]
+packages = [
+    "slashml_robotics",
+    "slashml_robotics.ros2",
+    "slashml_robotics.mcp",
+]

slashml_robotics-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

slashml_robotics-1.0.0/slashml_robotics/__init__.py

@@ -0,0 +1,44 @@
+"""SlashML Robotics: Ultra-low-latency spatial memory SDK for embodied AI.
+
+Public interface for physical robotics stacks, perception pipelines, and task planners.
+"""
+
+from slashml_robotics.client import RoboticMemory
+from slashml_robotics.types import (
+    BoundingBox3D,
+    LocationResult,
+    PhysicalObservation,
+    Pose6D,
+    Trajectory,
+    Waypoint,
+)
+from slashml_robotics.vocabulary import (
+    AFFORDANCES_AND_STATES,
+    AFFORDANCE_TO_OBJECTS,
+    CONTAINERS_AND_STORAGE,
+    ELECTRONICS_AND_COMPONENTS,
+    TOOLS_AND_HARDWARE,
+    ZONES_AND_FURNITURE,
+    get_objects_for_affordance,
+    is_known_tool,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "RoboticMemory",
+    "Pose6D",
+    "BoundingBox3D",
+    "Waypoint",
+    "LocationResult",
+    "Trajectory",
+    "PhysicalObservation",
+    "get_objects_for_affordance",
+    "is_known_tool",
+    "TOOLS_AND_HARDWARE",
+    "CONTAINERS_AND_STORAGE",
+    "ELECTRONICS_AND_COMPONENTS",
+    "ZONES_AND_FURNITURE",
+    "AFFORDANCES_AND_STATES",
+    "AFFORDANCE_TO_OBJECTS",
+]

slashml_robotics-1.0.0/slashml_robotics/client.py

@@ -0,0 +1,369 @@
+"""High-level client for SlashML Robotics spatial memory.
+
+Wraps the underlying SlashML transport to deliver sub-millisecond, zero-recomputation
+spatial memory operations:
+- O(1) dynamic spatial supersession
+- Sub-microsecond where_is lookup
+- Chronological trajectory reconstruction
+- Affordance-based object discovery
+"""
+
+from __future__ import annotations
+
+import time
+import urllib.parse
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from slashml import MemoryClient, SlashMLMemory
+from slashml_robotics.types import (
+    BoundingBox3D,
+    LocationResult,
+    PhysicalObservation,
+    Pose6D,
+    Trajectory,
+    Waypoint,
+)
+from slashml_robotics.vocabulary import get_objects_for_affordance
+
+
+class RoboticMemory:
+    """Specialized robotics memory interface built on top of SlashML.
+    
+    Provides physical spatial semantics, 6-DoF poses, automatic spatial supersession,
+    and trajectory queries with sub-millisecond retrieval latency.
+    """
+
+    def __init__(
+        self,
+        client: Optional[Union[MemoryClient, SlashMLMemory]] = None,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        robot_id: str = "robot_default",
+    ) -> None:
+        if client is not None:
+            self._client = client
+        else:
+            self._client = MemoryClient(base_url=base_url, api_key=api_key)
+        self.robot_id = robot_id
+
+    @property
+    def client(self) -> Union[MemoryClient, SlashMLMemory]:
+        return self._client
+
+    def add_observation(
+        self,
+        object_name: str,
+        room_zone: str,
+        pose: Union[Pose6D, Sequence[float]],
+        tags: Optional[List[str]] = None,
+        confidence: float = 1.0,
+        timestamp: Optional[float] = None,
+        bounding_box: Optional[BoundingBox3D] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> LocationResult:
+        """Record a physical detection/observation into spatial memory.
+        
+        Automatically updates active belief and marks older locations of this
+        exact object as superseded in O(1) time.
+        """
+        pose_obj = pose if isinstance(pose, Pose6D) else Pose6D.from_list(pose)
+        ts = timestamp if timestamp is not None else time.time()
+        tag_list = list(tags) if tags is not None else []
+        meta = dict(metadata) if metadata is not None else {}
+
+        # Canonical memory payload for SlashML engine
+        payload: Dict[str, Any] = {
+            "object_name": object_name,
+            "room_zone": room_zone,
+            "pose": pose_obj.to_dict(),
+            "confidence": confidence,
+            "timestamp": ts,
+            "robot_id": self.robot_id,
+            "spatial_memory_type": "physical_observation",
+            **meta,
+        }
+        if bounding_box:
+            payload["bounding_box"] = bounding_box.to_dict()
+
+        # Canonical normalized key for object identity (normalize spaces and underscores)
+        norm_name = object_name.lower().strip().replace(" ", "_")
+        all_tags = [f"obj:{norm_name}", f"obj:{object_name.lower().strip()}"]
+        for t in tag_list:
+            clean_t = t.lower().strip()
+            if not clean_t.startswith("obj:"):
+                all_tags.append(clean_t)
+
+        # Try native live /v1/robotics/observations endpoint first
+        if hasattr(self._client, "_request"):
+            try:
+                res_native = self._client._request(
+                    "POST",
+                    "/v1/robotics/observations",
+                    payload={
+                        "object_name": object_name,
+                        "room_zone": room_zone,
+                        "pose": pose_obj.to_dict(),
+                        "tags": all_tags,
+                        "confidence": confidence,
+                        "timestamp": ts,
+                        "bounding_box": bounding_box.to_dict() if bounding_box else None,
+                        "metadata": meta,
+                    },
+                )
+                if isinstance(res_native, dict) and res_native.get("status") == "recorded":
+                    p_data = res_native.get("pose", pose_obj.to_dict())
+                    p_obj = Pose6D(**p_data) if isinstance(p_data, dict) else Pose6D.from_list(p_data)
+                    return LocationResult(
+                        object_name=str(res_native.get("object_name", object_name)),
+                        room_zone=str(res_native.get("room_zone", room_zone)),
+                        pose=p_obj,
+                        timestamp=float(res_native.get("timestamp", ts)),
+                        confidence=float(res_native.get("confidence", confidence)),
+                        is_superseded=bool(res_native.get("is_superseded", False)),
+                        observation_id=str(res_native.get("observation_id", "")),
+                        metadata=meta,
+                    )
+            except Exception:
+                pass
+
+        # Fallback to general memory add()
+        obs_text = f"Observed {object_name} in {room_zone} at position ({pose_obj.x:.3f}, {pose_obj.y:.3f}, {pose_obj.z:.3f})"
+        
+        # Use add() with structured metadata
+        res = self._client.add(
+            messages=[{"role": "user", "content": obs_text}],
+            user_id=self.robot_id,
+            metadata=payload,
+            filters={"tags": all_tags},
+        )
+
+        obs_id = ""
+        if isinstance(res, dict):
+            obs_id = str(res.get("id") or res.get("record_id") or "")
+        elif isinstance(res, list) and len(res) > 0 and isinstance(res[0], dict):
+            obs_id = str(res[0].get("id") or res[0].get("record_id") or "")
+
+        return LocationResult(
+            object_name=object_name,
+            room_zone=room_zone,
+            pose=pose_obj,
+            timestamp=ts,
+            confidence=confidence,
+            is_superseded=False,
+            observation_id=obs_id,
+            metadata=meta,
+        )
+
+    def where_is(self, object_name: str) -> Optional[LocationResult]:
+        """Sub-microsecond query returning the latest active 6-DoF location of an object.
+        
+        Returns None if the object has never been observed or has been removed.
+        """
+        # Try native live /v1/robotics/where_is/{object_name} endpoint first
+        if hasattr(self._client, "_request"):
+            try:
+                encoded_name = urllib.parse.quote(object_name, safe="")
+                res_native = self._client._request("GET", f"/v1/robotics/where_is/{encoded_name}")
+                if isinstance(res_native, dict):
+                    p_data = res_native.get("pose", [0.0, 0.0, 0.0])
+                    p_obj = Pose6D(**p_data) if isinstance(p_data, dict) else Pose6D.from_list(p_data)
+                    return LocationResult(
+                        object_name=str(res_native.get("object_name", object_name)),
+                        room_zone=str(res_native.get("room_zone", "unknown")),
+                        pose=p_obj,
+                        timestamp=float(res_native.get("timestamp", 0.0)),
+                        confidence=float(res_native.get("confidence", 1.0)),
+                        is_superseded=bool(res_native.get("is_superseded", False)),
+                        observation_id=str(res_native.get("observation_id", "")),
+                        metadata={},
+                    )
+            except Exception as e:
+                status_code = getattr(e, "status_code", None)
+                if status_code == 404 or "404" in str(e):
+                    return None
+
+        obj_key = object_name.lower().strip()
+        obj_key_norm = obj_key.replace(" ", "_")
+        
+        # Query engine with object tag filter, requesting active un-superseded records
+        try:
+            memories = self._client.get_all(
+                user_id=self.robot_id,
+                filters={"tags": [f"obj:{obj_key}", f"obj:{obj_key_norm}"], "is_superseded": False},
+                limit=1,
+            )
+        except Exception:
+            # Fallback query if filtering is unsupported by mock transport
+            memories = self._client.search(
+                query=f"where is {object_name}",
+                user_id=self.robot_id,
+                limit=1,
+            )
+
+        if not memories:
+            return None
+
+        # Extract record
+        item = memories[0] if isinstance(memories, list) else memories
+        meta = item.get("metadata", {}) if isinstance(item, dict) else {}
+        
+        pose_data = meta.get("pose", [0.0, 0.0, 0.0])
+        pose_obj = Pose6D.from_list(pose_data) if isinstance(pose_data, (list, tuple)) else Pose6D(**pose_data)
+        
+        return LocationResult(
+            object_name=meta.get("object_name", object_name),
+            room_zone=meta.get("room_zone", "unknown"),
+            pose=pose_obj,
+            timestamp=float(meta.get("timestamp", item.get("created_at_epoch", 0.0))),
+            confidence=float(meta.get("confidence", 1.0)),
+            is_superseded=bool(meta.get("is_superseded", False)),
+            observation_id=str(item.get("id", "")),
+            metadata={k: v for k, v in meta.items() if k not in ("pose", "room_zone", "object_name")},
+        )
+
+    def get_trajectory(self, object_name: str) -> Trajectory:
+        """Reconstruct chronological waypoint trajectory for an object across all time."""
+        # Try native live /v1/robotics/trajectory/{object_name} endpoint first
+        if hasattr(self._client, "_request"):
+            try:
+                encoded_name = urllib.parse.quote(object_name, safe="")
+                res_native = self._client._request("GET", f"/v1/robotics/trajectory/{encoded_name}")
+                if isinstance(res_native, dict) and "waypoints" in res_native:
+                    wps = []
+                    for wp in res_native.get("waypoints", []):
+                        p_data = wp.get("pose", [0.0, 0.0, 0.0])
+                        p_obj = Pose6D(**p_data) if isinstance(p_data, dict) else Pose6D.from_list(p_data)
+                        wps.append(Waypoint(
+                            timestamp=float(wp.get("timestamp", 0.0)),
+                            room_zone=str(wp.get("room_zone", "unknown")),
+                            pose=p_obj,
+                            confidence=float(wp.get("confidence", 1.0)),
+                            metadata={},
+                        ))
+                    return Trajectory(object_name=object_name, waypoints=wps)
+            except Exception:
+                pass
+
+        obj_key = object_name.lower().strip()
+        
+        try:
+            records = self._client.get_all(
+                user_id=self.robot_id,
+                filters={"tags": [f"obj:{obj_key}"]},
+                limit=1000,
+            )
+        except Exception:
+            records = self._client.search(
+                query=f"trajectory history of {object_name}",
+                user_id=self.robot_id,
+                limit=100,
+            )
+
+        if not isinstance(records, list):
+            records = [records] if records else []
+
+        waypoints: List[Waypoint] = []
+        for item in records:
+            if not isinstance(item, dict):
+                continue
+            meta = item.get("metadata", {})
+            if meta.get("object_name", "").lower().strip() != obj_key:
+                continue
+            pose_data = meta.get("pose", [0.0, 0.0, 0.0])
+            pose_obj = Pose6D.from_list(pose_data) if isinstance(pose_data, (list, tuple)) else Pose6D(**pose_data)
+            wp = Waypoint(
+                timestamp=float(meta.get("timestamp", 0.0)),
+                room_zone=str(meta.get("room_zone", "unknown")),
+                pose=pose_obj,
+                confidence=float(meta.get("confidence", 1.0)),
+                metadata={k: v for k, v in meta.items() if k not in ("pose", "room_zone", "object_name")},
+            )
+            waypoints.append(wp)
+
+        # Sort chronologically
+        waypoints.sort(key=lambda w: w.timestamp)
+        return Trajectory(object_name=object_name, waypoints=waypoints)
+
+    def search_spatial(
+        self,
+        query: str,
+        room_zone: Optional[str] = None,
+        top_k: int = 5,
+    ) -> List[LocationResult]:
+        """Perform semantic/visual similarity search filtered by spatial context."""
+        # Try native live /v1/robotics/search endpoint first
+        if hasattr(self._client, "_request"):
+            try:
+                res_native = self._client._request(
+                    "POST",
+                    "/v1/robotics/search",
+                    payload={"query": query, "room_zone": room_zone, "top_k": top_k},
+                )
+                if isinstance(res_native, dict) and "results" in res_native:
+                    out: List[LocationResult] = []
+                    for r in res_native.get("results", []):
+                        p_data = r.get("pose", [0.0, 0.0, 0.0])
+                        p_obj = Pose6D(**p_data) if isinstance(p_data, dict) else Pose6D.from_list(p_data)
+                        out.append(LocationResult(
+                            object_name=str(r.get("object_name", "")),
+                            room_zone=str(r.get("room_zone", "unknown")),
+                            pose=p_obj,
+                            timestamp=float(r.get("timestamp", 0.0)),
+                            confidence=float(r.get("confidence", 1.0)),
+                            is_superseded=bool(r.get("is_superseded", False)),
+                            observation_id=str(r.get("observation_id", "")),
+                            metadata={},
+                        ))
+                    return out
+            except Exception:
+                pass
+
+        filters: Dict[str, Any] = {"is_superseded": False}
+        if room_zone:
+            filters["room_zone"] = room_zone
+
+        results = self._client.search(
+            query=query,
+            user_id=self.robot_id,
+            filters=filters,
+            limit=top_k,
+        )
+
+        loc_results: List[LocationResult] = []
+        for item in results if isinstance(results, list) else [results]:
+            if not isinstance(item, dict):
+                continue
+            meta = item.get("metadata", {})
+            pose_data = meta.get("pose", [0.0, 0.0, 0.0])
+            pose_obj = Pose6D.from_list(pose_data) if isinstance(pose_data, (list, tuple)) else Pose6D(**pose_data)
+            loc_results.append(
+                LocationResult(
+                    object_name=str(meta.get("object_name", item.get("memory", ""))),
+                    room_zone=str(meta.get("room_zone", "unknown")),
+                    pose=pose_obj,
+                    timestamp=float(meta.get("timestamp", 0.0)),
+                    confidence=float(item.get("score", 1.0)),
+                    is_superseded=bool(meta.get("is_superseded", False)),
+                    observation_id=str(item.get("id", "")),
+                    metadata=meta,
+                )
+            )
+        return loc_results
+
+    def find_by_affordance(
+        self,
+        action: str,
+        room_zone: Optional[str] = None,
+    ) -> List[LocationResult]:
+        """Find active physical objects in the workspace that satisfy an affordance.
+        
+        Example: find_by_affordance("fastening") -> returns active screwdrivers, wrenches.
+        """
+        candidates = get_objects_for_affordance(action)
+        matches: List[LocationResult] = []
+        for cand in candidates:
+            loc = self.where_is(cand)
+            if loc is not None and not loc.is_superseded:
+                if room_zone is None or loc.room_zone.lower() == room_zone.lower():
+                    matches.append(loc)
+        return matches

slashml_robotics-1.0.0/slashml_robotics/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Embodied Agentic Model Context Protocol (MCP) server for SlashML Robotics."""
+
+from slashml_robotics.mcp.server import EmbodiedRoboticsMCPServer, ROBOTICS_TOOLS
+
+__all__ = ["EmbodiedRoboticsMCPServer", "ROBOTICS_TOOLS"]