Conflict_Checker/docs/pipeline-overview.md

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 between sheets, mistakes within a single sheet, 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". Now also    |
   |     catches contradictions WITHIN a single sheet         |
   +----------------------------------------------------------+
                            |
                            v
   +----------------------------------------------------------+
   |  5. THREE SPECIALISTS  (work side by side)               |
   |     * Drawing Checker  — problems on a sheet BY ITSELF:  |
   |       a callout pointing to a detail that isn't there,   |
   |       a schedule that disagrees with its own plan,       |
   |       dimensions that don't add up, missing scale        |
   |     * Builder          — can this actually be built as   |
   |       drawn? (access, clearances, sequencing)            |
   |     * Completeness Checker — is anything MISSING from    |
   |       the set? (sheets, schedules, required details)     |
   |     (A Code Inspector also lives here but is turned OFF  |
   |      by default — the focus is the drawings themselves)  |
   +----------------------------------------------------------+
                            |
                            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
   +----------------------------------------------------------+
   |  6.5 THE BRAIN DOUBLE-CHECKS  (asks for a second look)   |
   |     For the findings it's unsure about, the Brain sends  |
   |     them back to a fact-checker that re-reads the actual |
   |     sheet (zoomed-in image + the page's real text) to    |
   |     confirm or debunk. Debunked findings are dropped     |
   |     before they ever reach you                           |
   +----------------------------------------------------------+
                            |
                            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, across a discipline's own sheets, or within one sheet
5	Drawing Integrity Agent	Proofreader	Checks each sheet on its own: dangling callouts, a schedule vs its own plan, dimensions that don't sum, missing scale/north/title-block
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
5	Code Agent (off by default)	Code inspector	Building-code/ADA checks — kept in the codebase but disabled so the review focuses on the drawings; one flag turns it back on
6	Brain	Chief estimator	Deduplicates, judges, and prioritizes all findings
6.5	Brain (clarification)	Second opinion	For findings it distrusts, sends them back to the fact-checker to re-read the sheet; debunked findings are dropped
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

(Several items from earlier versions have since shipped — noted below.)

1. Coverage — "make sure every page actually got read" ✅ largely shipped

• Failed pages used to quietly disappear, and the Completeness Checker would then report a sheet as "missing" when it was really just unread.
• Done: a retry ladder now re-reads a page (text-only pass, then a deterministic text-layer fallback) so no text-bearing page goes dark, and the report separates "sheet doesn't exist" from "sheet couldn't be read."
• Still open: try a different backup model on the hardest pages.

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. (The truncation bug itself is now fixed.)

4. Smarter detective work — "catch conflicts that span piles" ✅ shipped

• The Detectives only saw one topic pile at a time, so a contradiction spanning two piles — or a mistake on a single sheet — could slip through.
• Done: the Detectives now also flag contradictions within a single sheet, a new Drawing Checker proofreads every sheet on its own, and after the Brain sorts everything it can send doubtful findings back for a zoomed-in second look (wave 6.5) and drop the ones that don't hold up.
• Still open: revisit the hard cap on how many topic piles are kept on very large sets.

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" ✅ partially shipped

• Done: the fact-checker already pulls a zoomed-in crop of the exact spot on the sheet when it re-reads a finding.
• Still open: attach that crop to the finding in the final report so a non-technical reader can verify it in seconds without opening the PDF.

---

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.