175 lines
9.1 KiB
Markdown
175 lines
9.1 KiB
Markdown
# Conflict Checker — How It Works (Plain Language)
|
|
|
|
**What it does:** You upload a set of construction drawings (a PDF of blueprints).
|
|
A team of AI assistants reads every page, compares everything against everything
|
|
else, and hands you a list of problems — contradictions, code violations, missing
|
|
information, and things that would be hard to build — before they cost you money
|
|
in the field.
|
|
|
|
Think of it like hiring a room full of specialist consultants to review your
|
|
plans overnight. Each one has a specific job, they pass their notes down the
|
|
table, and a senior reviewer at the end sorts it all into one clean report.
|
|
|
|
---
|
|
|
|
## The Big Picture (one sentence per step)
|
|
|
|
```
|
|
YOUR PDF OF BLUEPRINTS
|
|
|
|
|
v
|
|
+----------------------------------------------------------+
|
|
| 0. SCANNER |
|
|
| Turns every PDF page into a picture the AI can read |
|
|
+----------------------------------------------------------+
|
|
|
|
|
v
|
|
+----------------------------------------------------------+
|
|
| 1. READERS (one assistant per page, all at once) |
|
|
| Reads each sheet and writes down every fact: |
|
|
| dimensions, notes, materials, room names, callouts |
|
|
+----------------------------------------------------------+
|
|
|
|
|
v
|
|
+----------------------------------------------------------+
|
|
| 2. LIBRARIAN + LOCAL-CODE SCOUT (work side by side) |
|
|
| Librarian: builds the table of contents — which |
|
|
| sheets exist (electrical, plumbing, structural...) |
|
|
| Scout: figures out WHERE the project is, so we know |
|
|
| which building codes apply |
|
|
+----------------------------------------------------------+
|
|
|
|
|
v
|
|
+----------------------------------------------------------+
|
|
| 3. CONNECTOR |
|
|
| Connects the dots across sheets — e.g. "the water |
|
|
| heater on the plumbing sheet is the same one on the |
|
|
| electrical sheet" — and groups related facts into |
|
|
| topic piles (clusters) |
|
|
+----------------------------------------------------------+
|
|
|
|
|
v
|
|
+----------------------------------------------------------+
|
|
| 4. CONFLICT DETECTIVES (one per topic pile) |
|
|
| Compares sheets that should agree and looks for |
|
|
| contradictions: "Wall shown here on A-201 but not |
|
|
| on S-101", "Pipe runs through the duct" |
|
|
+----------------------------------------------------------+
|
|
|
|
|
v
|
|
+----------------------------------------------------------+
|
|
| 5. THREE SPECIALISTS (work side by side) |
|
|
| * Code Inspector — does anything break the local |
|
|
| building code? |
|
|
| * Builder — can this actually be built as |
|
|
| drawn? (access, clearances, sequencing) |
|
|
| * Completeness Checker — is anything MISSING from |
|
|
| the set? (sheets, schedules, required details) |
|
|
+----------------------------------------------------------+
|
|
|
|
|
v
|
|
+----------------------------------------------------------+
|
|
| 6. THE BRAIN (senior reviewer) |
|
|
| Collects EVERY finding from everyone, merges the |
|
|
| duplicates, throws out the weak ones, and ranks the |
|
|
| rest by how much trouble they'd cause |
|
|
+----------------------------------------------------------+
|
|
|
|
|
v
|
|
+----------------------------------------------------------+
|
|
| 7. HUMAN REVIEW GATE |
|
|
| The important/uncertain findings are queued for a |
|
|
| real person to Confirm / Reject / mark Unsure |
|
|
+----------------------------------------------------------+
|
|
|
|
|
v
|
|
+----------------------------------------------------------+
|
|
| 8. LETTER WRITER |
|
|
| Drafts a formal RFI (Request For Information — the |
|
|
| official "please clarify this" letter) for each |
|
|
| confirmed issue, ready to send to the design team |
|
|
+----------------------------------------------------------+
|
|
|
|
|
v
|
|
FINAL REPORT + DRAFT RFIs
|
|
```
|
|
|
|
---
|
|
|
|
## Who's Who (the "agents")
|
|
|
|
| # | Name | Analogy | What it actually does |
|
|
|---|------|---------|-----------------------|
|
|
| 0 | PDF Scanner | Photocopier | Converts each PDF page into an image the AI can "see" |
|
|
| 1 | Sheet Extractor | Speed-reader | Reads one page, writes structured notes (every page gets its own reader, in parallel) |
|
|
| 2 | Sheet Indexer | Librarian | Builds the table of contents of the drawing set |
|
|
| 2 | Jurisdiction Scout | Local guide | Identifies the project's location so the right building codes are used |
|
|
| 3 | Linker | Connector | Groups related facts from different sheets into topic clusters |
|
|
| 4 | Conflict Critic | Detective | Examines each cluster for contradictions between disciplines |
|
|
| 5 | Code Agent | Code inspector | Flags building-code violations, using the jurisdiction from step 2 |
|
|
| 5 | Constructability Agent | Veteran builder | Flags things that are drawn fine but can't be built practically |
|
|
| 5 | Completeness Agent | Checklist keeper | Flags missing sheets, missing details, gaps in the set |
|
|
| 6 | Brain | Chief estimator | Deduplicates, judges, and prioritizes all findings |
|
|
| 7 | Review Gate | Your desk | Presents the findings a human should approve before anything goes out |
|
|
| 8 | RFI Writer | Secretary | Writes the formal clarification letters for confirmed issues |
|
|
|
|
Everything the assistants learn is kept in a shared notebook (the "project
|
|
memory"), so each step builds on the last. If one reader fails on one page, the
|
|
rest of the team keeps going — that page is noted as a gap instead of crashing
|
|
the whole review.
|
|
|
|
---
|
|
|
|
## Where Improvements Could Be Made
|
|
|
|
### 1. Coverage — "make sure every page actually got read"
|
|
- Today, if a Reader fails on a page (the AI's answer gets cut off or comes back
|
|
garbled), that page quietly disappears from everything downstream. Worse, the
|
|
Completeness Checker can then report the sheet as "missing from the set" when
|
|
really it was there but unread — a false alarm.
|
|
- **Improvement:** retry failed pages with a backup model, and clearly separate
|
|
"sheet doesn't exist" from "sheet couldn't be read" in the report.
|
|
|
|
### 2. Speed — "the team waits in line more than it needs to"
|
|
- The steps run strictly one after another, but some could start earlier. The
|
|
Jurisdiction Scout only needs the cover page — it could run while the other
|
|
Readers are still working. The Letter Writer could start on high-confidence
|
|
findings instead of waiting for all human review.
|
|
- **Improvement:** overlap independent steps; start drafting letters for
|
|
confirmed/high-confidence findings sooner.
|
|
|
|
### 3. Cost — "smarter reading, fewer wasted words"
|
|
- Every page is read by a large, expensive AI model, and that model's
|
|
"thinking time" counts against its answer budget — we've seen it spend its
|
|
whole budget thinking and return a cut-off answer.
|
|
- **Improvement:** use cheaper models for simple pages (schedules, title
|
|
sheets), save the expensive model for dense drawings; keep tuning the
|
|
thinking budget knobs; reuse cached answers when the same plan set is
|
|
re-run.
|
|
|
|
### 4. Smarter grouping — "better piles, better detective work"
|
|
- The Connector caps how many topic piles it keeps (a fixed limit), so on big
|
|
sets some connections may never be made. The Detectives only see one pile at
|
|
a time, so a contradiction spanning two piles can slip through.
|
|
- **Improvement:** revisit the pile limit, and let the Brain (or a second-pass
|
|
Detective) look for conflicts that span multiple piles.
|
|
|
|
### 5. Human time — "review less, but review what matters"
|
|
- Today the review queue is built from rules about severity and confidence.
|
|
- **Improvement:** learn from your past Confirm/Reject decisions to sort the
|
|
queue better — the system already records your feedback, so it can get
|
|
smarter over time about what actually needs your eyes.
|
|
|
|
### 6. Trust — "show the receipts"
|
|
- Findings carry evidence, but a non-technical reader can't easily see *where
|
|
on the drawing* the problem is.
|
|
- **Improvement:** attach a cropped image snippet of the exact spot on the
|
|
sheet to each finding, so anyone can verify it in seconds.
|
|
|
|
---
|
|
|
|
*Technical reference for the curious: the pipeline lives in
|
|
`backend/agents/runner.py` (the waves above are the "Agent wave N" stages), the
|
|
team's shared notebook is `backend/agents/memory.py`, and the review queue is
|
|
`backend/review/gate.py` + `backend/review/finalizer.py`.*
|