bim-change-engine

A change-intelligence layer above Speckle's version graph. Diff engine + swappable audience lenses + persona routing + MCP, with a groundedness contract that refuses to invent facts the toolset can't verify.

What this is

When a BIM model changes — a beam moves, a door widens, a wall shifts — the downstream consequences ripple across coordination, cost, and the field. Most "AI on BIM" tooling either reports nothing useful or confidently fabricates magnitudes it cannot verify. This engine does the opposite:

• A diff engine walks two versions of a Speckle model and computes a deterministic, grounded "what changed" — every entry keyed to a stable applicationId, never to content hash.

• A lens layer interprets the diff for a specific audience — coordination, cost, or field — through rule books anchored on real, citable industry sources.

• A persona router picks the right lens for the role you ask about (BIM coordinator, construction estimator, structural engineer) and filters the output to their workflow concerns.

• An MCP server exposes everything to Claude (or any modern agent) as structured tools.

• A groundedness contract separates verified_facts (from the diff) from inferred_impacts (from the rule book), surfaces scenario citations with verbatim quotes from named public sources, and explicitly refuses when asked for magnitudes the toolset cannot verify.

The result: an agent that talks fluently about change impact, cites real industry data, and won't fabricate.

The demo

In Claude Desktop with this MCP server wired in, the canonical 7-beat demo runs in ~4 minutes:

1. Discovery — "What can the bim-change-engine do?"

2. Industry framing — "Where does this fit in AEC tech?"

3. The change story — "What just changed in my model?"

4. Persona routing — "Show me what a BIM coordinator would care about."

5. Groundedness beat — "What were the actual coordinates that changed?" → explicit refusal with explanation.

6. Pluggability — "Now show me the same change from a quantity surveyor's perspective."

7. Closing — "Summarize where this fits in the industry's JTBDs."

(See describe_demo_flow MCP tool for the full beat sheet, or WHAT_WE_BUILT.md §5 for the demo punchline.)

Architecture

   You / Claude Desktop
         │
         │  natural-language prompts
         ▼
   mcp_server.py     (FastMCP, local stdio)
         │
         ├─► personas.py    (real-anchored personas + routing)
         │        │
         │        └─► lenses.py    (rule books + scenario citations)
         │                 │
         │                 └─► diff.py     (the engine — pure Python)
         │
         └─► specklepy SDK
                  │
                  ▼
              Speckle cloud (GraphQL + REST over HTTPS)
                  │
                  ▼
              Your project / model / versions

The engine itself (diff.py) has no Speckle dependency in its core comparison logic. It takes two Speckle Base trees and computes a DiffResult. Same pattern can drive any versioned object graph.

Quickstart

Prerequisites: Windows / macOS / Linux with uv (the rest installs automatically).

# 1. Clone
git clone https://github.com/<your-github>/bim-change-engine.git
cd bim-change-engine

# 2. Install (uv handles Python + deps)
uv sync

# 3. Configure your Speckle Personal Access Token
cp .env.example .env
# Then edit .env and paste your PAT from app.speckle.systems

# 4. Sanity check — should print your Speckle username
uv run sanity_check.py

# 5. Seed a sandbox project with two versions of a mock BIM model
uv run phase_1_seed.py

# 6. Run the diff engine against the latest two versions
uv run phase_2_diff.py

# 7. Run the full multi-lens test (all 3 lenses + 3 personas)
uv run phase_4_test.py

To wire into Claude Desktop, add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "bim-change-engine": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/bim-change-engine", "run", "mcp_server.py"]
    }
  }
}

Restart Claude Desktop. The engine will appear under tools.

MCP tools

What's grounded vs what's inferred

The system surfaces this distinction in every output:

• verified_facts come from the diff. Example: "width: 800 → 1200 (Δ +400, +50%)" — the diff carries both values for this scalar property, so the magnitude is verifiable.

• inferred_impacts come from a rule book. Example: "Door width changed — clear-opening compliance, structural lintel size, and MEP routing through the opening are all potentially stale." Interpretation, not measurement.

• scenario_citations name real, public, citable sources. Each citation includes a verbatim quote. Example: Suffolk Construction's pattern of ~$860k average rework cost per project (Speckle blog, 2026); the 10–14 day / $1k–3k RFI cost baseline (marsbim.com).

• Refusals surface when asked for what's not verified. Example: coordinate magnitudes for wall geometry shifts live inside opaque Base members. The diff records that geometry changed; it does not carry the numbers. The agent explicitly declines rather than fabricating.

Status

Early prototype. The engine, lens architecture, persona routing, and MCP surface are all working. The coordination and cost rule books are research-anchored (every impact statement cites a real, public source with a verbatim quote). The field rule book is being research-anchored next. See the backlog at the bottom of the README.

Backlog

• Field rule book research-anchoring (in progress).

• fetch_object_geometry escalation tool — surfaces concrete coordinate values from opaque Base members when a user explicitly asks for them.

• Speckle Automate Function packaging — same engine, repackaged as a function that runs inside Speckle's infrastructure on every new model version.

• Webhook receiver for live model-change triggers.

• Portfolio lens (the fifth industry JTBD — cross-project benchmarking).

License

Personal prototype, no license attached. Don't redistribute without asking.