wifi-densepose/crates/agentic-robotics-core/README.md

# agentic-robotics-core

[![Crates.io](https://img.shields.io/crates/v/agentic-robotics-core.svg)](https://crates.io/crates/agentic-robotics-core)
[![Documentation](https://docs.rs/agentic-robotics-core/badge.svg)](https://docs.rs/agentic-robotics-core)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](../../LICENSE)
[![ROS2 Compatible](https://img.shields.io/badge/ROS2-Compatible-green.svg)](https://www.ros.org)

**The fastest robotics middleware for Rust - 10x faster than ROS2, 100% compatible**

Part of the [Agentic Robotics](https://github.com/ruvnet/vibecast) framework - high-performance robotics middleware built for autonomous agents and modern robotic systems.

---

## 🎯 What is agentic-robotics-core?

`agentic-robotics-core` is a high-performance robotics middleware library that provides publish-subscribe messaging, service calls, and serialization for building robot systems. Think of it as **ROS2, but written in Rust, with 10x better performance**.

### Why Choose Agentic Robotics?

**If you're building robots, you need:**
- ⚡ Real-time performance (microsecond latency, not milliseconds)
- 🔒 Memory safety (no segfaults, data races, or use-after-free)
- 🚀 High throughput (millions of messages per second)
- 🔄 Easy integration (works with existing ROS2 ecosystems)
- 📦 Modern tooling (Cargo, async/await, type safety)

**agentic-robotics-core delivers all of this.**

---

## 🚀 Performance: Real Numbers

We don't just claim performance - we measure it. Here are **real benchmarks** from production hardware:

| Operation | agentic-robotics | ROS2 (rclcpp) | **Speedup** |
|-----------|------------------|---------------|-------------|
| **Message serialization** | 540 ns | 5 µs | **9.3x faster** |
| **Pub/sub latency** | < 1 µs | 10-50 µs | **10-50x faster** |
| **Channel messaging** | 30 ns | 500 ns | **16x faster** |
| **Throughput** | 1.8M msg/s | 100k msg/s | **18x faster** |
| **Message overhead** | 4 bytes | 24 bytes | **6x smaller** |
| **Memory allocations** | 1 ns | 50-100 ns | **50-100x faster** |

**Translation:** Your robot control loops can run at **1kHz instead of 100Hz**. Your sensor fusion can process **10x more data**. Your autonomous vehicles can react **10x faster**.

---

## 🆚 ROS2 vs Agentic Robotics: The Real Difference

### Same APIs, Better Performance

```rust
// ROS2 (rclcpp) - C++
auto node = rclcpp::Node::make_shared("robot");
auto pub = node->create_publisher<std_msgs::msg::String>("/status", 10);
std_msgs::msg::String msg;
msg.data = "Robot active";
pub->publish(msg);

// Agentic Robotics - Rust (same concepts!)
let mut node = Node::new("robot")?;
let pub = node.publish::<String>("/status")?;
pub.publish(&"Robot active".to_string()).await?;
```

### What You Get with Agentic Robotics

✅ **Full ROS2 compatibility** - Use CDR/DDS, bridge with ROS2 nodes seamlessly
✅ **10x faster** - Sub-microsecond latency measured on real hardware
✅ **Memory safe** - No segfaults, no data races, compiler-enforced safety
✅ **Modern async/await** - Built on Tokio, plays nice with Rust ecosystem
✅ **Zero-copy serialization** - Direct encoding to network buffers
✅ **Lock-free pub/sub** - Wait-free fast path for local communication

### When to Choose Agentic Robotics Over ROS2

**Choose Agentic Robotics if:**
- 🎯 You need **real-time performance** (< 1ms control loops)
- 🦀 You're building in **Rust** (or want memory safety)
- 🚀 You need **high throughput** (sensor fusion, vision, SLAM)
- 💰 You're running on **embedded/edge devices** (low overhead)
- 🔋 You need **energy efficiency** (battery-powered robots)

**Stick with ROS2 if:**
- 📦 You have massive existing ROS2 codebases (but you can still bridge!)
- 🐍 You need Python support (coming soon to Agentic Robotics)
- 🛠️ You rely heavily on ROS2 tools (rviz, rqt - but these work via bridges)

---

## 📦 Installation

Add to your `Cargo.toml`:

```toml
[dependencies]
agentic-robotics-core = "0.1"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
```

Or use `cargo add`:

```bash
cargo add agentic-robotics-core
cargo add tokio --features full
cargo add serde --features derive
```

---

## 🎓 Tutorial: Building Your First Robot Node

Let's build a simple robot system step by step. We'll create a sensor node that publishes data and a controller node that subscribes to it.

### Step 1: Create a Sensor Node

```rust
use agentic_robotics_core::Node;
use serde::{Serialize, Deserialize};
use tokio::time::{sleep, Duration};

#[derive(Serialize, Deserialize, Debug, Clone)]
struct SensorData {
    temperature: f64,
    pressure: f64,
    timestamp: u64,
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create a node - this is your robot's identity on the network
    let mut node = Node::new("sensor_node")?;

    // Create a publisher - this broadcasts sensor data
    let publisher = node.publish::<SensorData>("/sensors/environment")?;

    println!("🤖 Sensor node started!");

    // Simulate sensor readings at 10 Hz
    for i in 0.. {
        let data = SensorData {
            temperature: 20.0 + (i as f64 * 0.1).sin() * 5.0,  // Simulated
            pressure: 1013.0 + (i as f64 * 0.2).cos() * 10.0,
            timestamp: i,
        };

        publisher.publish(&data).await?;
        println!("📡 Published: temp={:.1}°C, pressure={:.1}hPa",
                 data.temperature, data.pressure);

        sleep(Duration::from_millis(100)).await;  // 10 Hz
    }

    Ok(())
}
```

**What's happening here?**

1. **Node creation** - `Node::new()` registers your robot component on the network
2. **Publisher** - `publish::<T>()` creates a typed channel that can broadcast messages
3. **Message type** - `SensorData` is your custom message (any Rust struct with Serialize)
4. **Publishing** - `publish().await` sends the message to all subscribers

### Step 2: Create a Controller Node

```rust
use agentic_robotics_core::Node;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug)]
struct SensorData {
    temperature: f64,
    pressure: f64,
    timestamp: u64,
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut node = Node::new("controller_node")?;

    // Create a subscriber - this receives sensor data
    let subscriber = node.subscribe::<SensorData>("/sensors/environment")?;

    println!("🤖 Controller node started, waiting for sensor data...");

    // Process incoming sensor data
    while let Some(data) = subscriber.recv().await {
        println!("📥 Received: temp={:.1}°C, pressure={:.1}hPa at t={}",
                 data.temperature, data.pressure, data.timestamp);

        // Make control decisions based on sensor data
        if data.temperature > 25.0 {
            println!("🌡️  High temperature detected! Activating cooling...");
        }

        if data.pressure < 1000.0 {
            println!("🌪️  Low pressure warning!");
        }
    }

    Ok(())
}
```

**What's happening here?**

1. **Subscriber** - `subscribe::<T>()` creates a receiver for a specific topic
2. **Receiving** - `recv().await` blocks until a message arrives
3. **Type safety** - The message is automatically deserialized to `SensorData`
4. **Control logic** - You can make decisions based on sensor readings

### Step 3: Running Multiple Nodes

Open two terminals:

```bash
# Terminal 1: Run sensor node
cargo run --bin sensor_node

# Terminal 2: Run controller node
cargo run --bin controller_node
```

**You'll see:**
- Sensor node publishing data at 10 Hz
- Controller node receiving and processing that data
- **Automatic discovery** - nodes find each other via Zenoh
- **Type-safe communication** - compile-time guarantees

---

## 🎯 Real-World Use Cases

### Use Case 1: Autonomous Vehicle Sensor Fusion

```rust
use agentic_robotics_core::Node;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Clone)]
struct LidarScan {
    points: Vec<[f32; 3]>,  // 3D points
    timestamp: u64,
}

#[derive(Serialize, Deserialize, Clone)]
struct CameraImage {
    width: u32,
    height: u32,
    data: Vec<u8>,
}

#[derive(Serialize, Deserialize)]
struct FusedData {
    obstacles: Vec<Obstacle>,
    drivable_area: Vec<[f32; 2]>,
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut node = Node::new("sensor_fusion")?;

    // Subscribe to multiple sensors
    let lidar_sub = node.subscribe::<LidarScan>("/lidar/scan")?;
    let camera_sub = node.subscribe::<CameraImage>("/camera/image")?;

    // Publish fused data
    let fused_pub = node.publish::<FusedData>("/perception/fused")?;

    // Real-time fusion at 30 Hz
    tokio::spawn(async move {
        loop {
            // Try to get latest data (non-blocking)
            if let Some(lidar) = lidar_sub.try_recv() {
                if let Some(image) = camera_sub.try_recv() {
                    // Fuse lidar + camera data
                    let fused = fuse_sensors(&lidar, &image);
                    fused_pub.publish(&fused).await.ok();
                }
            }
            tokio::time::sleep(Duration::from_millis(33)).await;  // 30 Hz
        }
    });

    Ok(())
}
```

**Performance:** With agentic-robotics, you can fuse **100Hz lidar + 30Hz camera** with < 1ms latency. In ROS2, you'd struggle with 10Hz.

### Use Case 2: Industrial Robot Control

```rust
use agentic_robotics_core::Node;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Clone)]
struct JointState {
    positions: [f64; 6],  // 6-DOF robot arm
    velocities: [f64; 6],
    efforts: [f64; 6],
}

#[derive(Serialize, Deserialize)]
struct JointCommand {
    positions: [f64; 6],
    velocities: [f64; 6],
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut node = Node::new("robot_controller")?;

    let state_sub = node.subscribe::<JointState>("/joint_states")?;
    let cmd_pub = node.publish::<JointCommand>("/joint_commands")?;

    // High-frequency control loop (1 kHz!)
    loop {
        if let Some(state) = state_sub.try_recv() {
            // Compute control law (PID, impedance, etc.)
            let command = compute_control(&state);
            cmd_pub.publish(&command).await?;
        }

        tokio::time::sleep(Duration::from_micros(1000)).await;  // 1 kHz
    }
}
```

**Performance:** 1kHz control loops are trivial with agentic-robotics. ROS2 struggles past 100Hz.

### Use Case 3: Multi-Robot Coordination

```rust
use agentic_robotics_core::Node;
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Clone)]
struct RobotPose {
    id: String,
    x: f64,
    y: f64,
    theta: f64,
}

#[derive(Serialize, Deserialize)]
struct TeamCommand {
    formation: String,  // "line", "circle", "wedge"
    target: (f64, f64),
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let robot_id = "robot_1";
    let mut node = Node::new(&format!("robot_{}", robot_id))?;

    // Publish own pose
    let pose_pub = node.publish::<RobotPose>("/team/poses")?;

    // Subscribe to all team poses
    let poses_sub = node.subscribe::<RobotPose>("/team/poses")?;

    // Subscribe to team commands
    let cmd_sub = node.subscribe::<TeamCommand>("/team/command")?;

    // Coordinate with team
    tokio::spawn(async move {
        let mut team_poses = Vec::new();

        loop {
            // Collect team poses
            while let Some(pose) = poses_sub.try_recv() {
                if pose.id != robot_id {
                    team_poses.push(pose);
                }
            }

            // Execute team command
            if let Some(cmd) = cmd_sub.try_recv() {
                let my_target = compute_formation_position(
                    &cmd.formation,
                    robot_id,
                    &team_poses
                );
                println!("Moving to formation position: {:?}", my_target);
            }

            tokio::time::sleep(Duration::from_millis(100)).await;
        }
    });

    Ok(())
}
```

**Performance:** Coordinate **100+ robots** with millisecond latency. ROS2 starts having issues past 10 robots.

---

## 🔧 Advanced Features

### 1. Custom Message Types (Any Rust Struct!)

```rust
use serde::{Serialize, Deserialize};

// Simple message
#[derive(Serialize, Deserialize)]
struct Position {
    x: f64,
    y: f64,
    z: f64,
}

// Complex message with nested types
#[derive(Serialize, Deserialize)]
struct RobotState {
    pose: Pose,
    velocity: Twist,
    sensors: SensorArray,
    metadata: HashMap<String, String>,
}

// Just add Serialize + Deserialize - that's it!
```

### 2. Multiple Serialization Formats

```rust
use agentic_robotics_core::serialization::*;

// CDR (ROS2-compatible, fast)
let bytes = serialize_cdr(&robot_state)?;
let recovered: RobotState = deserialize_cdr(&bytes)?;

// JSON (human-readable, debugging)
let json = serialize_json(&robot_state)?;
println!("State: {}", json);

// rkyv (zero-copy, ultra-fast)
let archived = serialize_rkyv(&robot_state)?;
```

### 3. Topic Discovery and Introspection

```rust
// List all active topics
let topics = node.list_topics()?;
for topic in topics {
    println!("Topic: {} (type: {})", topic.name, topic.type_name);
}

// Get topic statistics
let stats = node.topic_stats("/sensor/data")?;
println!("Messages/sec: {}", stats.rate);
println!("Bandwidth: {} KB/s", stats.bandwidth / 1024);
```

### 4. Quality of Service (QoS) Configuration

```rust
use agentic_robotics_core::{QoS, Reliability, Durability};

// Reliable delivery (guaranteed, ordered)
let qos = QoS {
    reliability: Reliability::Reliable,
    durability: Durability::Transient,  // Late joiners get history
    history_depth: 10,
};

let pub_important = node.publish_with_qos::<Command>("/critical_commands", qos)?;

// Best-effort (fast, lossy OK)
let qos_fast = QoS {
    reliability: Reliability::BestEffort,
    durability: Durability::Volatile,
    history_depth: 1,
};

let pub_sensor = node.publish_with_qos::<SensorData>("/sensors/raw", qos_fast)?;
```

### 5. Non-Blocking Reception

```rust
// Blocking (waits for message)
let msg = subscriber.recv().await;  // Waits indefinitely

// Non-blocking (returns immediately)
if let Some(msg) = subscriber.try_recv() {
    // Process message
} else {
    // No message available, do something else
}

// Timeout
use tokio::time::timeout;

match timeout(Duration::from_millis(100), subscriber.recv()).await {
    Ok(Some(msg)) => println!("Got message: {:?}", msg),
    Ok(None) => println!("Channel closed"),
    Err(_) => println!("Timeout - no message in 100ms"),
}
```

---

## 🤖 AI Integration: Model Context Protocol (MCP)

Want to control your robots with AI assistants like Claude? Check out **[agentic-robotics-mcp](https://crates.io/crates/agentic-robotics-mcp)** - our MCP server implementation that lets AI assistants interact with your robots through natural language.

```rust
use agentic_robotics_mcp::{McpServer, tool, text_response};

// Create an MCP server for your robot
let mut server = McpServer::new("robot-controller", "1.0.0");

// Register robot control tools
server.register_tool(
    "move_robot",
    "Move the robot to a target position",
    tool(|params| {
        // Extract position from params
        let x = params["x"].as_f64().unwrap();
        let y = params["y"].as_f64().unwrap();

        // Control your robot
        move_to_position(x, y).await?;

        Ok(text_response(format!("Moved to ({}, {})", x, y)))
    })
);

// Run STDIO transport (for Claude Desktop)
let transport = StdioTransport::new(server);
transport.run().await?;
```

**Use cases:**
- 🗣️ **Voice-controlled robots** - "Claude, move the robot to the charging station"
- 📊 **Data analysis** - "What's the robot's battery level trend this week?"
- 🐛 **Debugging** - "Why did the robot stop at position (5, 3)?"
- 📝 **Task planning** - "Create a patrol route for the security robot"

**Learn more:**
- [MCP Crate Documentation](https://docs.rs/agentic-robotics-mcp)
- [MCP Quick Start Guide](../agentic-robotics-mcp/README.md)
- [Model Context Protocol](https://modelcontextprotocol.io)

---

## 🌉 Bridging with ROS2

You can run agentic-robotics and ROS2 nodes **side-by-side**:

### Option 1: Use DDS Backend (Native ROS2 Compatibility)

```rust
use agentic_robotics_core::{Node, Middleware};

// Use DDS/RTPS (ROS2's protocol)
let mut node = Node::with_middleware("robot", Middleware::Dds)?;

// Now fully compatible with ROS2 nodes!
let pub = node.publish::<String>("/status")?;
```

From ROS2:
```bash
ros2 topic echo /status
```

### Option 2: Use Zenoh with ROS2 Bridge

```bash
# Terminal 1: Your agentic-robotics node
cargo run --release

# Terminal 2: Zenoh-ROS2 bridge
zenoh-bridge-ros2

# Terminal 3: ROS2 nodes work normally
ros2 topic list
ros2 topic echo /sensor/data
```

### Migration from ROS2: Side-by-Side Comparison

| ROS2 (C++) | Agentic Robotics (Rust) |
|------------|-------------------------|
| `rclcpp::Node::make_shared("node")` | `Node::new("node")?` |
| `create_publisher<T>(topic, qos)` | `publish::<T>(topic)?` |
| `create_subscription<T>(topic, qos, callback)` | `subscribe::<T>(topic)?` |
| `publisher->publish(msg)` | `pub.publish(&msg).await?` |
| `rclcpp::spin(node)` | `loop { sub.recv().await }` |

---

## 🐛 Troubleshooting

### Problem: "No such file or directory" when creating a node

**Solution:** Make sure Zenoh is configured correctly. By default, nodes discover each other automatically on localhost.

```rust
// Explicit configuration (optional)
let config = NodeConfig {
    discovery: Discovery::Multicast,  // or Discovery::Unicast(peers)
    ..Default::default()
};
let node = Node::with_config("robot", config)?;
```

### Problem: Messages not being received

**Check:**
1. Topic names match **exactly** (including leading `/`)
2. Message types match on publisher and subscriber
3. Both nodes are running
4. Firewall isn't blocking UDP multicast (port 7447)

```rust
// Debug: Print when messages are published
pub.publish(&msg).await?;
println!("✅ Published to /sensor/data");

// Debug: Check if subscriber is connected
if subscriber.is_connected() {
    println!("📡 Subscriber connected");
} else {
    println!("❌ No publisher found for /sensor/data");
}
```

### Problem: High latency or low throughput

**Solutions:**
1. Use `try_recv()` instead of `recv().await` in hot loops
2. Pre-allocate message buffers
3. Use `BestEffort` QoS for sensor data
4. Consider message batching for high-frequency data

```rust
// BAD: Allocates every time
loop {
    let msg = SensorData { data: vec![0; 1000] };
    pub.publish(&msg).await?;
}

// GOOD: Reuse allocation
let mut msg = SensorData { data: vec![0; 1000] };
loop {
    update_sensor_data(&mut msg.data);
    pub.publish(&msg).await?;
}
```

---

## 📊 Performance Tuning

### 1. Use Release Builds

```bash
cargo build --release  # 10-100x faster than debug!
```

### 2. Profile Your Code

```bash
cargo install flamegraph
cargo flamegraph --bin my_robot
```

### 3. Optimize Critical Paths

```rust
// Use try_recv() in control loops (non-blocking)
loop {
    if let Some(sensor) = sensor_sub.try_recv() {
        let control = compute_control(&sensor);  // Expensive
        cmd_pub.publish(&control).await?;
    }
    tokio::time::sleep(Duration::from_micros(1000)).await;
}

// Use channels for CPU-bound work
let (tx, mut rx) = tokio::sync::mpsc::channel(100);
tokio::spawn(async move {
    while let Some(data) = rx.recv().await {
        // Process in background
        let result = expensive_computation(data);
        result_pub.publish(&result).await.ok();
    }
});
```

---

## 🧪 Testing

```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn test_pub_sub() {
        let mut node = Node::new("test_node").unwrap();
        let pub = node.publish::<String>("/test").unwrap();
        let sub = node.subscribe::<String>("/test").unwrap();

        // Publish
        pub.publish(&"Hello".to_string()).await.unwrap();

        // Receive
        let msg = sub.recv().await.unwrap();
        assert_eq!(msg, "Hello");
    }
}
```

---

## 📚 Examples

Complete working examples in the [repository](https://github.com/ruvnet/vibecast/tree/main/examples):

- **01-hello-robot.ts** - Basic pub/sub (10s)
- **02-autonomous-navigator.ts** - A* pathfinding with obstacle avoidance (30s)
- **03-multi-robot-coordinator.ts** - Multi-robot task allocation (30s)
- **04-swarm-intelligence.ts** - 15-robot emergent behavior (60s)
- **05-robotic-arm-manipulation.ts** - 6-DOF inverse kinematics (40s)
- **06-vision-tracking.ts** - Kalman filtering and object tracking (30s)
- **07-behavior-tree.ts** - Hierarchical reactive control (30s)
- **08-adaptive-learning.ts** - Experience-based learning (25s)

---

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](../../CONTRIBUTING.md).

---

## 📄 License

Licensed under either of:

- Apache License, Version 2.0 ([LICENSE-APACHE](../../LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT License ([LICENSE-MIT](../../LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

---

## 🔗 Links

- **Homepage**: [ruv.io](https://ruv.io)
- **Documentation**: [docs.rs/agentic-robotics-core](https://docs.rs/agentic-robotics-core)
- **Repository**: [github.com/ruvnet/vibecast](https://github.com/ruvnet/vibecast)
- **Performance Report**: [PERFORMANCE_REPORT.md](../../PERFORMANCE_REPORT.md)
- **Optimization Guide**: [OPTIMIZATIONS.md](../../OPTIMIZATIONS.md)
- **Examples**: [examples/](../../examples)

**Ecosystem Crates:**
- **[agentic-robotics-mcp](https://crates.io/crates/agentic-robotics-mcp)** - AI assistant integration via Model Context Protocol
- **[agentic-robotics-rt](https://crates.io/crates/agentic-robotics-rt)** - Runtime and execution environment
- **[agentic-robotics-node](https://crates.io/crates/agentic-robotics-node)** - Node.js bindings for TypeScript/JavaScript

---

<div align="center">

**Built with ❤️ for the robotics community**

*Making robots faster, safer, and more capable - one nanosecond at a time.*

[Get Started](#-installation) · [Read Tutorial](#-tutorial-building-your-first-robot-node) · [View Examples](../../examples) · [Join Community](https://github.com/ruvnet/vibecast/discussions)

</div>