diff --git a/docs/pipeline-infographic.html b/docs/pipeline-infographic.html new file mode 100644 index 0000000..a332bea --- /dev/null +++ b/docs/pipeline-infographic.html @@ -0,0 +1,187 @@ + + + + +Conflict Checker — How Your Plans Get Reviewed + + + + +
+

🔍 CONFLICT CHECKER

+
How your construction plans get reviewed — a team of AI assistants, each with one job, passing notes down the line.
+
+ +
+ + +
+
+
1
+
📄
+

The Scanner

+

Turns every page of your PDF blueprints into a picture the AI can read.

+
+
→
+
+
2
+
👓
+

The Readers

+

One assistant per page, all working at once. Each writes down every fact: dimensions, notes, materials, callouts.

+
+
→
+
+
3
+
📚
+

Librarian & Code Scout

+

Builds the table of contents (electrical, plumbing, structural…) and figures out where the project is, so the right building codes apply.

+
+
→
+
+
4
+
🔗
+

The Connector

+

Connects the dots across sheets — "this water heater on the plumbing sheet is the same one on the electrical sheet" — and sorts facts into topic piles.

+
+
+ +
↓
+ + +
+
+
5
+
🕵️
+

The Detectives

+

One per topic pile. Compares sheets that should agree and hunts for contradictions: "wall shown here, but not on the structural plan."

+
+
→
+
+
6
+
👷
+

The Specialists

+

Three experts at once: a code inspector, a veteran builder ("can this actually be built?"), and a checklist keeper ("is anything missing?").

+
+
→
+
+
7
+
🧠
+

The Brain

+

The senior reviewer. Collects every finding, merges duplicates, discards weak ones, and ranks the rest by how much trouble they'd cause.

+
+
→
+
+
8
+
✅
+

Human Review

+

The important and uncertain findings land on your desk. You confirm, reject, or mark unsure — nothing goes out unapproved.

+
+
+ +
↓
+ +
+
📋 Final Report + ✉️ Draft RFIs
+
A prioritized list of every problem found — plus ready-to-send "please clarify" letters (Requests For Information) for the design team.
+
+ +
+ Good to know: everyone shares one notebook, so each step builds on the last. + If one page can't be read, the team keeps going and that page is flagged as a gap + instead of stopping the whole review. Every finding links back to the sheet it came from. +
+ +
+ + + + + diff --git a/docs/pipeline-infographic.png b/docs/pipeline-infographic.png new file mode 100644 index 0000000..a2c014a Binary files /dev/null and b/docs/pipeline-infographic.png differ diff --git a/docs/pipeline-overview.md b/docs/pipeline-overview.md new file mode 100644 index 0000000..89bf39e --- /dev/null +++ b/docs/pipeline-overview.md @@ -0,0 +1,174 @@ +# 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`.*