Bim Change Engine

A working prototype that diffs two versions of a Speckle model, produces grounded role-tailored impact reports through Claude, and refuses to fabricate facts it cannot verify.

That sentence is the whole product. Everything below is how to run it and what it tells you.

---

The demo, in one natural-language prompt

One universal prompt drives the whole demo.

Run my bim-change-engine prototype against my latest Speckle model. It watches a Speckle BIM model, compares two versions, and produces grounded role-specific impact reports — one engine, swappable lens per role. Walk me through: what changed in the latest version, what a BIM coordinator, a construction estimator, and a site engineer each need to do next about it, and what the engine deliberately refuses to verify. The point of the design is that the same diff produces completely different actions per role, and the system declines to fabricate facts the data cannot support.

In one response the viewer sees:

1. What changed — severity-ranked, every entry keyed to an applicationId.
2. The multi-role next-actions — the same change interpreted three ways (coordination, cost, field).
3. The architecture punchline — one engine, swappable lens, demonstrated by the contrast.
4. The refusal contract — what the diff carries vs. doesn't, and what the agent declines to fabricate.

Claude internally calls diff_latest_two once and summarize_diff_for_persona three times — no packaged-demo wrapper, the prompt drives the orchestration.

The refusal beat is the natural follow-up:

Using the bim-change-engine, what were the actual numeric coordinates of the wall movements between those two versions?

The agent declines and explains. That moment is the one to screen-record.

---

What the engine refuses to verify

The groundedness contract, plain English.

The diff carries: element identity across versions (by applicationId), the added / removed / modified status of each element, and the before-and-after values of scalar properties like door width or fire rating.

The diff does not carry: coordinate magnitudes of geometry changes, mesh vertex detail, or visual diffs. When asked for one of those, the agent declines and explains, rather than fabricating a number. Most AI tools applied to building data confidently invent numbers; this one stops.

---

Architecture

   You / Claude Desktop
         │
         │  prompt
         ▼
   mcp_server.py     (FastMCP, runs locally over stdio)
         │
         ├─► personas.py   (4 personas → route to lens)
         │        │
         │        └─► lenses.py    (3 rule books, dispatched by name)
         │                 │
         │                 └─► diff.py     (the engine itself, pure Python)
         │
         └─► specklepy SDK
                  │
                  ▼
              Speckle cloud  (your project + model + versions)

diff.py has no Speckle dependency in its core comparison path. It takes two Speckle Base trees and returns a DiffResult. The same pattern would drive any versioned object graph.

---

Quickstart

Prerequisites: uv installed. uv fetches Python and dependencies itself.

git clone https://github.com/rishibajaj-Prodman/bim-change-engine.git
cd bim-change-engine
uv sync

# Configure your Speckle Personal Access Token
cp .env.example .env
# Edit .env, paste your PAT from app.speckle.systems profile settings.

# Verify auth (should print your Speckle username)
uv run sanity_check.py

# Seed a sandbox project with two versions of a small mock building
uv run phase_1_seed.py

# Run the diff against the latest two versions, printed to stdout
uv run phase_2_diff.py

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

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

Fully restart Claude Desktop. The engine appears under tools.

---

MCP tools

Six tools, public:

Tool	Purpose
list_projects	Projects in the active Speckle workspace
list_models	Models in a project
list_versions	Recent versions of a model
diff_versions	Structural diff between two named versions
diff_latest_two	Diff the latest two versions, auto-resolving project and model when one of each exists
summarize_diff_for_persona	Role-tailored impact report — routes a diff through one persona's primary lens and returns an executive brief plus the top actions for that role

The natural-language prompt drives orchestration: Claude calls diff_latest_two once, then summarize_diff_for_persona per role, and synthesizes the multi-role "who does what next" answer.

Internal helpers (Python, not exposed as MCP tools): apply_persona_lens, summarize_diff, the three rule books.

---

Repository contents

diff.py             the engine (pure Python, no Speckle in the comparison path)
lenses.py           three rule books — coordination, cost, field
personas.py         four personas that route a diff through a primary lens
mcp_server.py       the six MCP tools
sanity_check.py     prints your Speckle username if auth is wired correctly
phase_1_seed.py     seeds a sandbox project with two versions of a mock building
phase_2_diff.py     runs the diff against the latest two versions and prints the result
BUILD_JOURNAL.md    honest narrative of how this was built agentically

---

License

Personal prototype, no license attached. Do not redistribute without asking.