d803bfe2b1
git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
140 lines
6.0 KiB
Markdown
140 lines
6.0 KiB
Markdown
# ruvector-robotics
|
|
|
|
Unified cognitive robotics platform built on ruvector's vector database, graph neural networks, and self-learning infrastructure.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────┐
|
|
│ ruvector-robotics │
|
|
├────────────┬────────────┬──────────┬────────────┤
|
|
│ bridge │ perception │cognitive │ mcp │
|
|
├────────────┼────────────┼──────────┼────────────┤
|
|
│ Point3D │ SceneGraph │ Behavior │ Tool │
|
|
│ PointCloud │ Builder │ Trees │ Registry │
|
|
│ RobotState │ Obstacle │ Cognitive│ 15+ Tools │
|
|
│ Pose │ Detector │ Core │ MCP Schema │
|
|
│ SceneGraph │ Anomaly │ Memory │ │
|
|
│ Trajectory │ Detection │ Skills │ │
|
|
│ Spatial │ Trajectory │ Swarm │ │
|
|
│ Index │ Predict │ World │ │
|
|
│ Pipeline │ │ Model │ │
|
|
│ Converters │ │ Decision │ │
|
|
└────────────┴────────────┴──────────┴────────────┘
|
|
```
|
|
|
|
## Modules
|
|
|
|
### bridge — Core Types & Spatial Operations
|
|
- **Types**: Point3D, PointCloud, RobotState, Pose, Quaternion, SensorFrame, OccupancyGrid, SceneObject, SceneGraph, Trajectory
|
|
- **SpatialIndex**: Brute-force kNN and radius search with Euclidean/Cosine/Manhattan metrics
|
|
- **Converters**: Bidirectional conversion between robotics messages and flat vectors
|
|
- **Pipeline**: Lightweight perception pipeline with obstacle detection and trajectory prediction
|
|
|
|
### perception — Scene Understanding
|
|
- **SceneGraphBuilder**: Spatial hash clustering with union-find for point cloud segmentation
|
|
- **ObstacleDetector**: Grid-based obstacle detection with heuristic classification (Static/Dynamic/Unknown)
|
|
- **PerceptionPipeline**: Full perception stack with obstacle detection, scene graph construction, attention focusing, anomaly detection
|
|
|
|
### cognitive — Autonomous Intelligence
|
|
- **BehaviorTree**: Composable reactive control structures (Sequence, Selector, Parallel, Decorators)
|
|
- **CognitiveCore**: Perceive-Think-Act-Learn loop with dual-process theory (Reactive/Deliberative/Emergency modes)
|
|
- **DecisionEngine**: Multi-criteria utility-based action selection (reward, risk, energy, curiosity)
|
|
- **MemorySystem**: Three-tier memory (Working, Episodic, Semantic) with similarity-based recall
|
|
- **SkillLearning**: Learning-from-demonstration with trajectory averaging and reinforcement
|
|
- **SwarmIntelligence**: Multi-robot coordination with task allocation and formation control
|
|
- **WorldModel**: Object tracking, occupancy mapping, and state prediction
|
|
|
|
### mcp — AI Agent Integration
|
|
- **ToolRegistry**: 15 registered MCP tools across 6 categories
|
|
- **Categories**: Perception, Navigation, Cognition, Swarm, Memory, Planning
|
|
- **Schema**: Full MCP-compatible JSON schema generation
|
|
|
|
## Quick Start
|
|
|
|
```rust
|
|
use ruvector_robotics::bridge::{Point3D, PointCloud, SpatialIndex};
|
|
|
|
// Create sensor data
|
|
let cloud = PointCloud::new(
|
|
vec![Point3D::new(1.0, 2.0, 3.0), Point3D::new(4.0, 5.0, 6.0)],
|
|
1000,
|
|
);
|
|
|
|
// Index and search
|
|
let mut index = SpatialIndex::new(3);
|
|
index.insert_point_cloud(&cloud);
|
|
let nearest = index.search_nearest(&[2.0, 3.0, 4.0], 1).unwrap();
|
|
```
|
|
|
|
```rust
|
|
use ruvector_robotics::cognitive::{BehaviorTree, BehaviorNode, BehaviorStatus};
|
|
|
|
// Build a patrol behavior tree
|
|
let tree = BehaviorTree::new(BehaviorNode::Sequence(vec![
|
|
BehaviorNode::Action("scan_environment".into()),
|
|
BehaviorNode::Action("move_to_waypoint".into()),
|
|
BehaviorNode::Action("report_status".into()),
|
|
]));
|
|
```
|
|
|
|
## Examples
|
|
|
|
Run any example from the repository root:
|
|
|
|
```bash
|
|
# Practical
|
|
cargo run -p ruvector-robotics-examples --bin 01_basic_perception
|
|
cargo run -p ruvector-robotics-examples --bin 02_obstacle_avoidance
|
|
|
|
# Intermediate
|
|
cargo run -p ruvector-robotics-examples --bin 03_scene_graph
|
|
cargo run -p ruvector-robotics-examples --bin 04_behavior_tree
|
|
|
|
# Advanced
|
|
cargo run -p ruvector-robotics-examples --bin 05_cognitive_robot
|
|
cargo run -p ruvector-robotics-examples --bin 06_swarm_coordination
|
|
cargo run -p ruvector-robotics-examples --bin 07_skill_learning
|
|
|
|
# Exotic
|
|
cargo run -p ruvector-robotics-examples --bin 08_world_model
|
|
cargo run -p ruvector-robotics-examples --bin 09_mcp_tools
|
|
cargo run -p ruvector-robotics-examples --bin 10_full_pipeline
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Run all tests
|
|
cargo test -p ruvector-robotics
|
|
|
|
# Run benchmarks
|
|
cargo bench -p ruvector-robotics
|
|
```
|
|
|
|
## Design Philosophy
|
|
|
|
This crate is designed thinking 50 years into the future while running on today's hardware:
|
|
|
|
1. **Zero external robotics deps** — All types are self-contained. No ROS/ROS2 dependency.
|
|
2. **Vector-first architecture** — Everything converts to flat vectors for indexing and search.
|
|
3. **Cognitive-inspired** — Dual-process theory, episodic memory, behavior trees from cognitive science.
|
|
4. **Swarm-native** — Multi-robot coordination built in from the start.
|
|
5. **MCP-ready** — All capabilities exposed as AI-agent-callable tools.
|
|
6. **No-std friendly core types** — Bridge types use only serde + standard library.
|
|
|
|
## Performance Targets
|
|
|
|
| Operation | Target | Notes |
|
|
|-----------|--------|-------|
|
|
| Point cloud indexing | 10K pts < 5ms | Brute-force flat index |
|
|
| kNN search (k=10) | < 1ms on 10K pts | Sorted partial select |
|
|
| Obstacle detection | < 10ms on 10K pts | Spatial hash + union-find |
|
|
| Scene graph build | < 5ms for 100 objects | Pairwise distance |
|
|
| Behavior tree tick | < 100μs for 50 nodes | Recursive evaluation |
|
|
| Memory recall | < 1ms for 1K items | Dot-product similarity |
|
|
|
|
## License
|
|
|
|
MIT
|