# worldgraph

**Repository Path**: virgil123/worldgraph

## Basic Information

- **Project Name**: worldgraph
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## 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.

<sub>**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</sub>

[![npm](https://img.shields.io/npm/v/worldgraphs.svg)](https://www.npmjs.com/package/worldgraphs)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](#license)
[![Rust](https://img.shields.io/badge/rust-stable-orange.svg)](#-the-library--rust-crates)

---

## 🌐 Live demo — the twin in your browser

[![WorldGraph × SuperSplat — live 3D demo](https://raw.githubusercontent.com/ruvnet/worldgraph/main/docs/demo.png)](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 |
| [`worldgraph-stream`](./worldgraph-stream) | **Live replication** — authorized snapshots/deltas, pseudonymous presence, and the self-hosted WebSocket server |

---

## 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
cd supersplat-bridge && npm ci && npm test && npm run build
```

## Self-host the live stream

The stream server validates audience-bound, short-lived JWTs, applies the same
privacy policy to snapshots and deltas, and exposes authenticated producer
ingest. See [`deploy/README.md`](deploy/README.md) for token scopes, TLS proxy
requirements, and the hardened Docker Compose deployment.

```bash
export WORLDGRAPH_TOKEN_SECRET="$(openssl rand -base64 48)"
docker compose up --build --detach
```

For the complete local browser → WebSocket → Rust/WASM demonstration:

```bash
docker compose -f compose.yaml -f compose.demo.yaml up --build
```

Then open <http://127.0.0.1:4173>. This explicit demo overlay uses a
loopback-only development token issuer and moving synthetic track; it is not a
production authentication configuration. See [`demo/web/README.md`](demo/web/README.md)
for the browser test and [`deploy/README.md`](deploy/README.md) for deployment
boundaries.

## License

Dual-licensed **MIT OR Apache-2.0** — see [`LICENSE-MIT`](./LICENSE-MIT) and [`LICENSE-APACHE`](./LICENSE-APACHE).