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

🌐 Live demo — the twin in your browser

▶ Open the live demo →

The WorldGraph semantic twin rendered in 3D over a 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.

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

cargo add wifi-densepose-worldgraph   # the typed digital-twin graph

| crate | role | |-------|------| | wifi-densepose-geo | Geospatial grounding — IP geolocation, satellite tiles, SRTM elevation, OSM buildings/roads, ENU↔geo transforms | | wifi-densepose-worldgraph | The digital twin — a petgraph graph of typed nodes + relations; provenance-mandatory semantic beliefs; JSON persistence | | 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 ecosystem (ADR-139).

Build

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 and LICENSE-APACHE.