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, what it tells you, and how it gets positioned for the seven construction-tech companies it was built to be shown to.

---

The demo, in one natural-language prompt

One universal prompt — works for every conversation. What changes per audience is the verbal framing you give before running it (see the per-company paragraphs below), and the outreach email you send before the conversation (see outreach/<company>.md).

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.

---

Per-company positioning

What to say in a conversation, per company. One paragraph each. Outreach emails for each company live in outreach/.

Speckle (CEO call). A working prototype that adds the missing layer above Speckle's version history. Watches a model, compares two versions, produces grounded impact reports tailored to whoever is asking. The demo runs against my sandbox project and shows the same model change producing two completely different actionable outputs depending on the role. The moment worth recording is when the agent refuses to fabricate a coordinate magnitude because the diff cannot verify it.

Revizto (open role). A working slice of governed AI on top of BIM data. Diffs two model versions, identifies elements by stable cross-version ID, routes the change through audience-specific rule books, refuses unverified detail. The MCP and governance discipline the JD describes, shipped as code.

Cosuno (open role). A change-impact engine for tendering. When a BIM model changes mid-tender, the system surfaces which tender packages went stale, which scope lines moved, which supplier prices need a fresh quote. Demoed by contrasting a quantity surveyor's view with a BIM coordinator's view of the same change. Built as an MCP server in roughly 1,500 lines of Python.

Dalux (open role). A version-diff engine that treats document and BIM version intelligence as the same problem. Identity-by-stable-ID translates from BIM objects to document drafts directly. Includes a cost-impact view that bridges naturally to Dalux Tender.

PlanRadar (open role). A working MCP prototype that catches what is stale in the field when a BIM model updates: setting-out drawings, fabrication orders, check sheets. The system was built agentically, with the conversation documented in BUILD_JOURNAL.md. Both the product and the process answer what the JD asks for.

ConxAI (CEO call). Same architecture as ConxAI's, opposite source direction. ConxAI runs field reality through to structured BIM; this prototype runs structured BIM through to actionable meaning. The shared architectural pattern (diff engine, audience routing, refusal contract) is the conversation hook.

Allplan (relationship). A tangible answer to your earlier question about Revit-like queryable Python objects. The diff engine walks any Speckle object graph and yields each element by applicationId. Demo focuses on the element-extraction primitive, which sits at the heart of the larger system.

---

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
outreach/           one markdown file per company with subject + body
BUILD_JOURNAL.md    honest narrative of how this was built agentically

---

License

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