clawdb-ros2 0.4.2__tar.gz

clawdb_ros2-0.4.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClawDB Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clawdb_ros2-0.4.2/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: clawdb-ros2
+Version: 0.4.2
+Summary: Official ROS2 Robotics SDK & Spatial Memory Bridge for ClawDB
+Home-page: https://github.com/Claw-DB/clawdb-ros2
+Author-email: ClawDB Robotics Team <dev@clawdb.dev>
+Maintainer: ClawDB Robotics Team
+Maintainer-email: dev@clawdb.dev
+License: MIT
+Project-URL: Homepage, https://clawdb.dev
+Project-URL: Repository, https://github.com/Claw-DB/clawdb-ros2
+Project-URL: Documentation, https://docs.clawdb.dev/robotics
+Project-URL: Bug Tracker, https://github.com/Claw-DB/clawdb-ros2/issues
+Keywords: ros2,robotics,clawdb,memory,amr,navigation,nav2,spatial-ai,autonomous-systems
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: numpy>=1.20.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: maintainer
+Dynamic: maintainer-email
+
+# ClawDB ROS2 Robotics SDK (`clawdb-ros2`)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![ROS 2](https://img.shields.io/badge/ROS_2-Humble%20%7C%20Iron%20%7C%20Rolling%20%7C%20Jazzy-22314E?logo=ros)](https://docs.ros.org)
+[![PyPI version](https://img.shields.io/pypi/v/clawdb-ros2.svg)](https://pypi.org/project/clawdb-ros2/)
+
+Official ROS2 package and Python SDK for connecting autonomous mobile robots (AMRs), inspection drones, and robotic manipulators to **ClawDB** persistent spatial memory.
+
+---
+
+## ⚡ Key Capabilities
+
+- **Sub-0.1ms Local Spatial Recall**: In-memory spatial index ensures trajectory planners and obstacle avoidance controllers run at full frequency without cloud latency bottlenecks.
+- **Multi-Robot Collective Memory**: Synchronize obstacles, blocked warehouse aisles, and spatial landmarks across an entire fleet in real-time.
+- **Nav2 Costmap Integration**: Easily feed dynamic spatial memories directly into ROS2 Nav2 costmap layers.
+- **Cloud & Edge Resilience**: Local offline caching with automatic background delta sync when network connectivity is restored.
+
+---
+
+## 🚀 Installation
+
+### Option 1: Standard Python Package (PyPI)
+```bash
+pip install clawdb-ros2
+```
+
+### Option 2: Build inside your ROS2 Colcon Workspace
+```bash
+cd ~/ros2_ws/src
+git clone https://github.com/Claw-DB/clawdb-ros2.git
+cd ~/ros2_ws
+colcon build --packages-select clawdb_ros2
+source install/setup.bash
+```
+
+---
+
+## 🤖 Quickstart
+
+### 1. Launch the Spatial Memory Bridge Node
+```bash
+ros2 launch clawdb_ros2 memory_bridge.launch.py \
+  api_key:="your_clawdb_api_key" \
+  workspace_id:="your_workspace_id" \
+  robot_id:="amr_01"
+```
+
+### 2. Record an Obstacle Memory in Python
+```python
+from clawdb_ros2 import ClawClient, SpatialMemoryRecord
+
+# Initialize client
+client = ClawClient(
+    api_key="your_clawdb_api_key",
+    workspace_id="your_workspace_id"
+)
+
+# Record spatial blockage
+client.record_spatial_event(
+    SpatialMemoryRecord(
+        frame_id="map",
+        x=14.5,
+        y=8.2,
+        z=0.0,
+        obstacle_type="pallet_spill",
+        confidence=0.98,
+        tags=["aisle_4", "amr_01"]
+    )
+)
+```
+
+### 3. Query Spatial Horizon in Real-Time (<0.1ms)
+```python
+from clawdb_ros2 import SpatialMemoryIndex
+
+index = SpatialMemoryIndex(memory_ttl_seconds=3600.0)
+
+# Query obstacles within 5.0m radius of current robot coordinates
+nearby = index.query_radius(x=14.0, y=7.5, radius=5.0)
+
+for record, dist in nearby:
+    print(f"Warning: {record.obstacle_type} at distance {dist:.2f}m")
+```
+
+---
+
+## 🧭 ROS2 Node Topics & Parameters
+
+### Subscribed Topics
+| Topic | Type | Description |
+|---|---|---|
+| `~/detected_obstacle` | `geometry_msgs/Point` | Local point detection to ingest into memory |
+
+### Published Topics
+| Topic | Type | Description |
+|---|---|---|
+| `~/fleet_updates` | `std_msgs/String` | JSON stream of spatial deltas received from fleet |
+
+### Parameters
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `api_key` | string | `""` | ClawDB API Key |
+| `workspace_id` | string | `""` | Workspace namespace ID |
+| `robot_id` | string | `"amr-01"` | Machine node identifier |
+| `store_name` | string | `"robot-fleet-memory"` | ClawDB memory store name |
+| `frame_id` | string | `"map"` | Coordinate frame ID |
+| `sync_rate_hz` | double | `1.0` | Background fleet sync frequency |
+| `local_ttl_seconds` | double | `7200.0` | Cache retention TTL (seconds) |
+
+---
+
+## 🧪 Testing
+
+Run unit tests locally:
+```bash
+pytest tests/
+```
+
+---
+
+## 📜 License
+
+MIT Licensed. Maintained by the ClawDB Robotics Team and open-source contributors.

clawdb_ros2-0.4.2/README.md

@@ -0,0 +1,123 @@
+# ClawDB ROS2 Robotics SDK (`clawdb-ros2`)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![ROS 2](https://img.shields.io/badge/ROS_2-Humble%20%7C%20Iron%20%7C%20Rolling%20%7C%20Jazzy-22314E?logo=ros)](https://docs.ros.org)
+[![PyPI version](https://img.shields.io/pypi/v/clawdb-ros2.svg)](https://pypi.org/project/clawdb-ros2/)
+
+Official ROS2 package and Python SDK for connecting autonomous mobile robots (AMRs), inspection drones, and robotic manipulators to **ClawDB** persistent spatial memory.
+
+---
+
+## ⚡ Key Capabilities
+
+- **Sub-0.1ms Local Spatial Recall**: In-memory spatial index ensures trajectory planners and obstacle avoidance controllers run at full frequency without cloud latency bottlenecks.
+- **Multi-Robot Collective Memory**: Synchronize obstacles, blocked warehouse aisles, and spatial landmarks across an entire fleet in real-time.
+- **Nav2 Costmap Integration**: Easily feed dynamic spatial memories directly into ROS2 Nav2 costmap layers.
+- **Cloud & Edge Resilience**: Local offline caching with automatic background delta sync when network connectivity is restored.
+
+---
+
+## 🚀 Installation
+
+### Option 1: Standard Python Package (PyPI)
+```bash
+pip install clawdb-ros2
+```
+
+### Option 2: Build inside your ROS2 Colcon Workspace
+```bash
+cd ~/ros2_ws/src
+git clone https://github.com/Claw-DB/clawdb-ros2.git
+cd ~/ros2_ws
+colcon build --packages-select clawdb_ros2
+source install/setup.bash
+```
+
+---
+
+## 🤖 Quickstart
+
+### 1. Launch the Spatial Memory Bridge Node
+```bash
+ros2 launch clawdb_ros2 memory_bridge.launch.py \
+  api_key:="your_clawdb_api_key" \
+  workspace_id:="your_workspace_id" \
+  robot_id:="amr_01"
+```
+
+### 2. Record an Obstacle Memory in Python
+```python
+from clawdb_ros2 import ClawClient, SpatialMemoryRecord
+
+# Initialize client
+client = ClawClient(
+    api_key="your_clawdb_api_key",
+    workspace_id="your_workspace_id"
+)
+
+# Record spatial blockage
+client.record_spatial_event(
+    SpatialMemoryRecord(
+        frame_id="map",
+        x=14.5,
+        y=8.2,
+        z=0.0,
+        obstacle_type="pallet_spill",
+        confidence=0.98,
+        tags=["aisle_4", "amr_01"]
+    )
+)
+```
+
+### 3. Query Spatial Horizon in Real-Time (<0.1ms)
+```python
+from clawdb_ros2 import SpatialMemoryIndex
+
+index = SpatialMemoryIndex(memory_ttl_seconds=3600.0)
+
+# Query obstacles within 5.0m radius of current robot coordinates
+nearby = index.query_radius(x=14.0, y=7.5, radius=5.0)
+
+for record, dist in nearby:
+    print(f"Warning: {record.obstacle_type} at distance {dist:.2f}m")
+```
+
+---
+
+## 🧭 ROS2 Node Topics & Parameters
+
+### Subscribed Topics
+| Topic | Type | Description |
+|---|---|---|
+| `~/detected_obstacle` | `geometry_msgs/Point` | Local point detection to ingest into memory |
+
+### Published Topics
+| Topic | Type | Description |
+|---|---|---|
+| `~/fleet_updates` | `std_msgs/String` | JSON stream of spatial deltas received from fleet |
+
+### Parameters
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `api_key` | string | `""` | ClawDB API Key |
+| `workspace_id` | string | `""` | Workspace namespace ID |
+| `robot_id` | string | `"amr-01"` | Machine node identifier |
+| `store_name` | string | `"robot-fleet-memory"` | ClawDB memory store name |
+| `frame_id` | string | `"map"` | Coordinate frame ID |
+| `sync_rate_hz` | double | `1.0` | Background fleet sync frequency |
+| `local_ttl_seconds` | double | `7200.0` | Cache retention TTL (seconds) |
+
+---
+
+## 🧪 Testing
+
+Run unit tests locally:
+```bash
+pytest tests/
+```
+
+---
+
+## 📜 License
+
+MIT Licensed. Maintained by the ClawDB Robotics Team and open-source contributors.

clawdb_ros2-0.4.2/clawdb_ros2/__init__.py

@@ -0,0 +1,21 @@
+"""
+ClawDB ROS2 Robotics SDK
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Official ROS2 persistent spatial memory bridge and cognitive state client for ClawDB.
+
+:copyright: (c) 2026 ClawDB Inc.
+:license: MIT, see LICENSE for more details.
+"""
+
+from .client import ClawClient, SpatialMemoryRecord, QueryResult
+from .spatial_index import SpatialMemoryIndex
+from .node import ClawSpatialMemoryNode
+
+__version__ = "0.4.2"
+__all__ = [
+    "ClawClient",
+    "SpatialMemoryRecord",
+    "QueryResult",
+    "SpatialMemoryIndex",
+    "ClawSpatialMemoryNode",
+]

clawdb_ros2-0.4.2/clawdb_ros2/client.py

@@ -0,0 +1,174 @@
+"""
+ClawDB Client for Robotics & ROS2 Nodes
+"""
+
+import time
+import json
+import logging
+from typing import List, Dict, Any, Optional, Tuple
+from dataclasses import dataclass, field, asdict
+import requests
+
+logger = logging.getLogger("clawdb_ros2.client")
+
+@dataclass
+class SpatialMemoryRecord:
+    """Represents a spatial memory event, obstacle, or waypoint heuristic."""
+    id: Optional[str] = None
+    frame_id: str = "map"
+    x: float = 0.0
+    y: float = 0.0
+    z: float = 0.0
+    obstacle_type: str = "general_obstacle"
+    confidence: float = 1.0
+    tags: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    timestamp: float = field(default_factory=time.time)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "SpatialMemoryRecord":
+        return cls(
+            id=data.get("id"),
+            frame_id=data.get("frame_id", "map"),
+            x=float(data.get("x", 0.0)),
+            y=float(data.get("y", 0.0)),
+            z=float(data.get("z", 0.0)),
+            obstacle_type=data.get("obstacle_type", "general_obstacle"),
+            confidence=float(data.get("confidence", 1.0)),
+            tags=data.get("tags", []),
+            metadata=data.get("metadata", {}),
+            timestamp=float(data.get("timestamp", time.time())),
+        )
+
+@dataclass
+class QueryResult:
+    """Result from spatial radius or semantic memory search."""
+    records: List[SpatialMemoryRecord]
+    latency_ms: float
+    total_count: int
+
+class ClawClient:
+    """
+    High-performance HTTP/REST Client for synchronizing robot memory with ClawDB.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        workspace_id: str,
+        endpoint: str = "https://api.clawdb.dev/v1",
+        timeout_seconds: float = 2.0,
+        store_name: str = "robot-fleet-memory"
+    ):
+        self.api_key = api_key
+        self.workspace_id = workspace_id
+        self.endpoint = endpoint.rstrip("/")
+        self.timeout = timeout_seconds
+        self.store_name = store_name
+
+        self._session = requests.Session()
+        self._session.headers.update({
+            "Authorization": f"Bearer {self.api_key}",
+            "X-Workspace-Id": self.workspace_id,
+            "User-Agent": "clawdb-ros2/0.4.2",
+            "Content-Type": "application/json",
+        })
+
+    def record_spatial_event(self, record: SpatialMemoryRecord) -> Dict[str, Any]:
+        """
+        Record a spatial memory point (obstacle, landmark, or navigation failure).
+        """
+        url = f"{self.endpoint}/workspaces/{self.workspace_id}/memory/insert"
+        payload = {
+            "store": self.store_name,
+            "fields": {
+                "frame_id": record.frame_id,
+                "x": record.x,
+                "y": record.y,
+                "z": record.z,
+                "obstacle_type": record.obstacle_type,
+                "confidence": record.confidence,
+                "timestamp": record.timestamp,
+                **record.metadata,
+            },
+            "tags": list(set(record.tags + ["robotics", record.obstacle_type])),
+        }
+
+        try:
+            start_t = time.perf_counter()
+            resp = self._session.post(url, json=payload, timeout=self.timeout)
+            resp.raise_for_status()
+            elapsed_ms = (time.perf_counter() - start_t) * 1000.0
+            data = resp.json()
+            data["latency_ms"] = elapsed_ms
+            return data
+        except Exception as e:
+            logger.warning(f"Failed to push spatial memory to ClawDB cloud: {e}")
+            return {"status": "offline_cached", "error": str(e)}
+
+    def search_nearby(
+        self,
+        x: float,
+        y: float,
+        radius_meters: float = 5.0,
+        frame_id: str = "map",
+        limit: int = 10
+    ) -> QueryResult:
+        """
+        Query nearby spatial memories and obstacle alerts around (x, y) coordinate.
+        """
+        url = f"{self.endpoint}/workspaces/{self.workspace_id}/memory/search"
+        payload = {
+            "store": self.store_name,
+            "query": f"spatial location near ({x:.2f}, {y:.2f}) in frame {frame_id}",
+            "filter": {
+                "frame_id": frame_id,
+            },
+            "limit": limit,
+        }
+
+        start_t = time.perf_counter()
+        try:
+            resp = self._session.post(url, json=payload, timeout=self.timeout)
+            resp.raise_for_status()
+            elapsed_ms = (time.perf_counter() - start_t) * 1000.0
+            data = resp.json()
+            records: List[SpatialMemoryRecord] = []
+            
+            for item in data.get("records", []):
+                fields = item.get("fields", {})
+                records.append(SpatialMemoryRecord(
+                    id=item.get("id"),
+                    frame_id=fields.get("frame_id", frame_id),
+                    x=float(fields.get("x", x)),
+                    y=float(fields.get("y", y)),
+                    z=float(fields.get("z", 0.0)),
+                    obstacle_type=fields.get("obstacle_type", "obstacle"),
+                    confidence=float(fields.get("confidence", 1.0)),
+                    tags=item.get("tags", []),
+                    metadata=fields,
+                    timestamp=float(fields.get("timestamp", time.time()))
+                ))
+
+            return QueryResult(records=records, latency_ms=elapsed_ms, total_count=len(records))
+        except Exception as e:
+            logger.warning(f"Failed to query ClawDB cloud: {e}")
+            elapsed_ms = (time.perf_counter() - start_t) * 1000.0
+            return QueryResult(records=[], latency_ms=elapsed_ms, total_count=0)
+
+    def pull_fleet_deltas(self, since_timestamp: float) -> List[SpatialMemoryRecord]:
+        """
+        Pull memory records written by other fleet nodes since timestamp.
+        """
+        url = f"{self.endpoint}/workspaces/{self.workspace_id}/memory/sync"
+        try:
+            resp = self._session.get(url, params={"store": self.store_name, "since": since_timestamp}, timeout=self.timeout)
+            if resp.status_code == 200:
+                data = resp.json()
+                return [SpatialMemoryRecord.from_dict(item) for item in data.get("deltas", [])]
+            return []
+        except Exception:
+            return []

clawdb_ros2-0.4.2/clawdb_ros2/fleet_sync.py

@@ -0,0 +1,33 @@
+"""
+Standalone Fleet Memory Daemon & Sync CLI
+"""
+
+import sys
+import time
+import argparse
+from .client import ClawClient
+
+def main():
+    parser = argparse.ArgumentParser(description="ClawDB Fleet Memory Synchronization CLI")
+    parser.add_argument("--api-key", required=True, help="ClawDB API Key")
+    parser.add_argument("--workspace-id", required=True, help="ClawDB Workspace ID")
+    parser.add_argument("--store", default="robot-fleet-memory", help="Memory store name")
+    parser.add_argument("--interval", type=float, default=2.0, help="Sync interval in seconds")
+    args = parser.parse_args()
+
+    client = ClawClient(api_key=args.api_key, workspace_id=args.workspace_id, store_name=args.store)
+    print(f"ClawDB Fleet Sync daemon started for workspace: {args.workspace_id} (Store: {args.store})")
+
+    last_sync = time.time()
+    try:
+        while True:
+            deltas = client.pull_fleet_deltas(since_timestamp=last_sync)
+            last_sync = time.time()
+            if deltas:
+                print(f"[{time.strftime('%X')}] Pulled {len(deltas)} updates from fleet.")
+            time.sleep(args.interval)
+    except KeyboardInterrupt:
+        print("\nFleet sync daemon stopped.")
+
+if __name__ == "__main__":
+    main()