https://github.com/ruvnet/worldgraph
Privacy-aware environmental digital twin for ambient/RF sensing in Rust — a typed, provenance-tracked graph of rooms, sensors, people & beliefs, geospatially grounded with predictive occupancy (OccWorld). ADR-139.
https://github.com/ruvnet/worldgraph
ambient-intelligence digital-twin edge-computing environmental-monitoring geospatial graph knowledge-graph occupancy-grid petgraph provenance robotics rust sensor-fusion smart-home spatial-computing wifi-sensing world-model
Last synced: 9 days ago
JSON representation
Privacy-aware environmental digital twin for ambient/RF sensing in Rust — a typed, provenance-tracked graph of rooms, sensors, people & beliefs, geospatially grounded with predictive occupancy (OccWorld). ADR-139.
- Host: GitHub
- URL: https://github.com/ruvnet/worldgraph
- Owner: ruvnet
- License: apache-2.0
- Created: 2026-06-16T18:11:30.000Z (23 days ago)
- Default Branch: main
- Last Pushed: 2026-06-27T03:46:51.000Z (12 days ago)
- Last Synced: 2026-06-27T05:12:31.873Z (12 days ago)
- Topics: ambient-intelligence, digital-twin, edge-computing, environmental-monitoring, geospatial, graph, knowledge-graph, occupancy-grid, petgraph, provenance, robotics, rust, sensor-fusion, smart-home, spatial-computing, wifi-sensing, world-model
- Language: Rust
- Size: 163 KB
- Stars: 7
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# worldgraph
**A privacy-aware environmental digital twin — and an AI agent that helps you build one.**
`worldgraph` is two things in one project:
1. **A Rust library** that models a physical space as a typed, provenance-tracked graph — rooms, zones, sensors, people, and *beliefs* about what's happening — geospatially grounded and able to **forecast occupancy**.
2. **An AI coding agent** (`npx worldgraphs`) — architect → implement → review → test — that helps you build digital twins and spatial/sensor applications on top of it.
**Keywords:** digital twin · world model · environmental digital twin · spatial computing · indoor positioning · sensor fusion · occupancy modeling · ambient intelligence · knowledge graph · scene graph · WiFi sensing · RF sensing · privacy-by-design · provenance · geospatial · occupancy forecasting · Rust · AI coding agent · agent harness
[](https://www.npmjs.com/package/worldgraphs)
[](#license)
[](#-the-library--rust-crates)
---
## 🌐 Live demo — the twin in your browser
[](https://ruvnet.github.io/worldgraph/)
**▶ [Open the live demo →](https://ruvnet.github.io/worldgraph/)**
The WorldGraph semantic twin rendered in 3D over a [SuperSplat](https://github.com/playcanvas/supersplat)-style scene — compiled to **WebAssembly** and running **entirely client-side** (no backend). Drag to orbit, click any element for its privacy-aware **provenance card**, and hit *Simulate* to see the OccWorld occupancy forecast. Person tracks carry no identity by construction.
---
## Two ways to use it
### 🤖 The AI agent — `npx worldgraphs`
A focused coding harness (architect / implementer / reviewer / test-writer) that drops into your AI host and helps you design, build, review, and test digital-twin code.
```bash
npx worldgraphs init # wire the agents into your AI host (Claude Code, Codex, Copilot, …)
npx worldgraphs doctor # health check
# or install globally:
npm i -g worldgraphs
worldgraphs init
```
> **Why `worldgraphs` (plural)?** npm reserves the bare name `worldgraph` (too similar to
> the existing `world-graph` package), so the npm package is published as `worldgraphs`.
> You can also run it straight from this repo: `npx ruvnet/worldgraph`.
Then ask your host to design or implement a change — the four agents run an opinionated pipeline so you get a plan, clean code, a bug-hunting review, and the missing tests. Ships adapters for **9 hosts**: Claude Code, Codex, Copilot, OpenCode, GitHub Actions, pi-dev, Hermes, OpenClaw, RVM.
| Agent | Role |
|-------|------|
| **architect** | Designs the change before any code is written |
| **implementer** | Writes code that matches the surrounding style |
| **reviewer** | Hunts correctness bugs in the diff |
| **test-writer** | Adds the missing tests for the change |
### 📦 The library — Rust crates
```bash
cargo add wifi-densepose-worldgraph # the typed digital-twin graph
```
| crate | role |
|-------|------|
| [`wifi-densepose-geo`](./wifi-densepose-geo) | **Geospatial grounding** — IP geolocation, satellite tiles, SRTM elevation, OSM buildings/roads, ENU↔geo transforms |
| [`wifi-densepose-worldgraph`](./wifi-densepose-worldgraph) | **The digital twin** — a `petgraph` graph of typed nodes + relations; provenance-mandatory semantic beliefs; JSON persistence |
| [`wifi-densepose-worldmodel`](./wifi-densepose-worldmodel) | **Predictive layer** — bridges person-track history to an OccWorld occupancy model and returns trajectory priors |
---
## What is an "environmental digital twin"?
A digital twin is a live, queryable model of a real space. `worldgraph` builds one as a **typed graph** — rooms, zones, walls, doorways, sensors, RF links, person tracks, object anchors, events, and semantic-state *beliefs* — connected by typed relations (`observes`, `located_in`, `adjacent_to`, `supports`, `contradicts`, `derived_from`, `privacy_limited_by`).
It stores **what is believed about the space**, not raw sensor frames — and **every belief is auditable** back to the evidence that produced it.
### What makes it trustworthy
- **Provenance is mandatory** — every semantic belief carries `SemanticProvenance` (signal evidence + model + calibration + privacy decision). You can't record a belief without recording *why*.
- **Privacy is first-class** — a `PrivacyRollup` and `privacy_limited_by` relations make the privacy posture of any belief queryable; downstream consumers respect it.
- **Deterministic & versioned** — a serde enum model → a deterministic, schema-versioned wire layout; `to_json` / `from_json` round-trips the whole graph.
- **Geospatially grounded** — ties the local scene to real coordinates, terrain, and map features.
- **Predictive** — forecasts occupancy and emits trajectory priors that improve downstream tracking.
### Where it sits
```
sensor fusion → worldgraph (digital twin) → semantic / agent layer
fused beliefs typed belief graph queries, reasoning, eval
│
└─→ worldmodel → occupancy forecast / trajectory priors
```
Part of the [RuView / wifi-densepose](https://github.com/ruvnet/wifi-densepose) ecosystem (ADR-139).
## Build
```bash
cargo build && cargo test # the Rust library
npm install && npm test # the agent harness
```
## License
Dual-licensed **MIT OR Apache-2.0** — see [`LICENSE-MIT`](./LICENSE-MIT) and [`LICENSE-APACHE`](./LICENSE-APACHE).