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.
