wifi-densepose/vendor/ruvector/crates/agentic-robotics-node/README.md

# agentic-robotics-node

[![Crates.io](https://img.shields.io/crates/v/agentic-robotics-node.svg)](https://crates.io/crates/agentic-robotics-node)
[![Documentation](https://docs.rs/agentic-robotics-node/badge.svg)](https://docs.rs/agentic-robotics-node)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](../../LICENSE)
[![npm](https://img.shields.io/npm/v/agentic-robotics)](https://www.npmjs.com/package/agentic-robotics)

**Node.js/TypeScript bindings for Agentic Robotics**

Part of the [Agentic Robotics](https://github.com/ruvnet/vibecast) framework - high-performance robotics middleware with ROS2 compatibility.

## Features

- 🌐 **TypeScript Support**: Full type definitions included
- ⚡ **Native Performance**: Rust-powered via NAPI
- 🔄 **Async/Await**: Modern JavaScript async patterns
- 📡 **Pub/Sub**: ROS2-compatible topic messaging
- 🎯 **Type-Safe**: Compile-time type checking in TypeScript
- 🚀 **High Performance**: 540ns serialization, 30ns messaging

## Installation

```bash
npm install agentic-robotics
# or
yarn add agentic-robotics
# or
pnpm add agentic-robotics
```

## Quick Start

### TypeScript

```typescript
import { Node, Publisher, Subscriber } from 'agentic-robotics';

// Create a node
const node = new Node('robot_node');

// Create publisher
const pubStatus = node.createPublisher<string>('/status');

// Create subscriber
const subCommands = node.createSubscriber<string>('/commands');

// Publish messages
pubStatus.publish('Robot initialized');

// Subscribe to messages
subCommands.onMessage((msg) => {
    console.log('Received command:', msg);
});
```

### JavaScript

```javascript
const { Node } = require('agentic-robotics');

const node = new Node('robot_node');

const pubStatus = node.createPublisher('/status');
pubStatus.publish('Robot active');

const subSensor = node.createSubscriber('/sensor');
subSensor.onMessage((data) => {
    console.log('Sensor data:', data);
});
```

## Examples

### Autonomous Navigator

```typescript
import { Node } from 'agentic-robotics';

interface Pose {
    x: number;
    y: number;
    theta: number;
}

interface Velocity {
    linear: number;
    angular: number;
}

const node = new Node('navigator');

// Subscribe to current pose
const subPose = node.createSubscriber<Pose>('/robot/pose');

// Publish velocity commands
const pubCmd = node.createPublisher<Velocity>('/cmd_vel');

// Navigation logic
subPose.onMessage((pose) => {
    const target = { x: 10, y: 10 };
    const cmd = computeVelocity(pose, target);
    pubCmd.publish(cmd);
});

function computeVelocity(current: Pose, target: { x: number; y: number }): Velocity {
    const dx = target.x - current.x;
    const dy = target.y - current.y;
    const distance = Math.sqrt(dx * dx + dy * dy);
    const targetAngle = Math.atan2(dy, dx);
    const angleError = targetAngle - current.theta;

    return {
        linear: Math.min(distance * 0.5, 1.0),
        angular: angleError * 2.0,
    };
}
```

### Vision Processing

```typescript
import { Node } from 'agentic-robotics';

interface Image {
    width: number;
    height: number;
    data: Uint8Array;
}

interface Detection {
    label: string;
    confidence: number;
    bbox: { x: number; y: number; w: number; h: number };
}

const node = new Node('vision_node');

const subImage = node.createSubscriber<Image>('/camera/image');
const pubDetections = node.createPublisher<Detection[]>('/detections');

subImage.onMessage(async (image) => {
    const detections = await detectObjects(image);
    pubDetections.publish(detections);
});

async function detectObjects(image: Image): Promise<Detection[]> {
    // Your ML inference here
    return [
        { label: 'person', confidence: 0.95, bbox: { x: 100, y: 100, w: 50, h: 100 } },
    ];
}
```

### Multi-Robot Coordination

```typescript
import { Node } from 'agentic-robotics';

class RobotAgent {
    private node: Node;
    private id: string;

    constructor(id: string) {
        this.id = id;
        this.node = new Node(`robot_${id}`);

        // Subscribe to team status
        const subTeam = this.node.createSubscriber<TeamStatus>('/team/status');
        subTeam.onMessage((status) => this.onTeamUpdate(status));

        // Publish own status
        const pubStatus = this.node.createPublisher<RobotStatus>(`/robot/${id}/status`);
        setInterval(() => {
            pubStatus.publish({
                id: this.id,
                position: this.getPosition(),
                battery: this.getBatteryLevel(),
            });
        }, 100);
    }

    private onTeamUpdate(status: TeamStatus) {
        console.log(`Robot ${this.id} received team update:`, status);
        // Coordinate with other robots
    }

    private getPosition() {
        return { x: 0, y: 0, z: 0 };
    }

    private getBatteryLevel() {
        return 95;
    }
}

// Create robot swarm
const robots = [
    new RobotAgent('scout_1'),
    new RobotAgent('scout_2'),
    new RobotAgent('worker_1'),
];
```

## API Reference

### Node

```typescript
class Node {
    constructor(name: string);

    createPublisher<T>(topic: string): Publisher<T>;
    createSubscriber<T>(topic: string): Subscriber<T>;

    shutdown(): void;
}
```

### Publisher

```typescript
class Publisher<T> {
    publish(message: T): Promise<void>;
    getTopic(): string;
}
```

### Subscriber

```typescript
class Subscriber<T> {
    onMessage(callback: (message: T) => void): void;
    getTopic(): string;
}
```

## Performance

The Node.js bindings maintain near-native performance:

| Operation | Node.js | Rust Native | Overhead |
|-----------|---------|-------------|----------|
| **Publish** | 850 ns | 540 ns | 57% |
| **Subscribe** | 120 ns | 30 ns | 4x |
| **Serialization** | 1.2 µs | 540 ns | 2.2x |

Still significantly faster than traditional ROS2 Node.js bindings!

## Building from Source

```bash
# Clone repository
git clone https://github.com/ruvnet/vibecast
cd vibecast

# Build Node.js addon
npm install
npm run build:node

# Run tests
npm test
```

## TypeScript Configuration

```json
{
    "compilerOptions": {
        "target": "ES2020",
        "module": "commonjs",
        "strict": true,
        "esModuleInterop": true
    }
}
```

## Examples

See the [examples directory](../../examples) for complete working examples:

- `01-hello-robot.ts` - Basic pub/sub
- `02-autonomous-navigator.ts` - A* pathfinding
- `06-vision-tracking.ts` - Object tracking with Kalman filters
- `08-adaptive-learning.ts` - Experience-based learning

Run any example:

```bash
npm run build:ts
node examples/01-hello-robot.ts
```

## ROS2 Compatibility

The Node.js bindings are fully compatible with ROS2:

```typescript
// Publish to ROS2 topic
const pubCmd = node.createPublisher<Twist>('/cmd_vel');
pubCmd.publish({
    linear: { x: 0.5, y: 0, z: 0 },
    angular: { x: 0, y: 0, z: 0.1 },
});

// Subscribe from ROS2 topic
const subPose = node.createSubscriber<PoseStamped>('/robot/pose');
```

Bridge with ROS2:

```bash
# Terminal 1: Node.js app
node my-robot.js

# Terminal 2: ROS2
ros2 topic echo /cmd_vel
```

## 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-node](https://docs.rs/agentic-robotics-node)
- **npm Package**: [npmjs.com/package/agentic-robotics](https://www.npmjs.com/package/agentic-robotics)
- **Repository**: [github.com/ruvnet/vibecast](https://github.com/ruvnet/vibecast)

---

**Part of the Agentic Robotics framework** • Built with ❤️ by the Agentic Robotics Team