bim-change-engine

# 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. ```bash 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`: ```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.