woogi/Conflict_Checker
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Add non-technical pipeline overview: infographic + flow explainer doc
Docker Release / build-and-push (push) Successful in 59s
Details
Docker Release / release (push) Skipped
Details

Browse Source
This commit is contained in:
woogi
2026-08-10 08:21:57 -05:00
parent 228e8bd031
commit 0ea0b0e897
3 changed files with 361 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/pipeline-infographic.html
+187
View File
@@ -0,0 +1,187 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Conflict Checker — How Your Plans Get Reviewed</title>
<style>
* { box-sizing: border-box; margin: 0; padding: 0; }
body {
font-family: "Segoe UI", "Helvetica Neue", Arial, sans-serif;
background: #f4f7fb;
color: #1f2d3d;
width: 1280px;
padding: 40px 48px;
}
header { text-align: center; margin-bottom: 10px; }
h1 { font-size: 34px; color: #123c6e; letter-spacing: 0.5px; }
.subtitle { font-size: 17px; color: #5a6b7f; margin-top: 8px; }
.blueprint {
background: #ffffff;
border: 2px solid #d5e3f2;
border-radius: 18px;
padding: 32px 36px;
margin-top: 24px;
background-image:
linear-gradient(#eef4fb 1px, transparent 1px),
linear-gradient(90deg, #eef4fb 1px, transparent 1px);
background-size: 28px 28px;
}
.row { display: flex; justify-content: center; align-items: stretch; gap: 0; }
.row + .connector-down { margin: 0; }
.card {
background: #ffffff;
border-radius: 14px;
border: 2px solid #cfdcec;
box-shadow: 0 3px 8px rgba(18,60,110,0.08);
width: 250px;
padding: 16px 16px 14px;
position: relative;
flex-shrink: 0;
}
.card .num {
position: absolute; top: -16px; left: -14px;
width: 36px; height: 36px; border-radius: 50%;
background: #123c6e; color: #fff;
font-weight: 700; font-size: 18px;
display: flex; align-items: center; justify-content: center;
box-shadow: 0 2px 5px rgba(0,0,0,0.2);
}
.card .icon { font-size: 34px; text-align: center; margin: 4px 0 6px; }
.card h2 { font-size: 17px; color: #123c6e; text-align: center; margin-bottom: 6px; }
.card p { font-size: 13px; line-height: 1.4; color: #42536a; text-align: center; }
.card.scan { border-color: #7fb3e0; background: #f0f7ff; }
.card.read { border-color: #7fb3e0; background: #f0f7ff; }
.card.lib { border-color: #8fd0a8; background: #f1faf4; }
.card.link { border-color: #8fd0a8; background: #f1faf4; }
.card.det { border-color: #f2b879; background: #fff8ef; }
.card.spec { border-color: #f2b879; background: #fff8ef; }
.card.brain { border-color: #c39bd3; background: #f9f3fc; }
.card.human { border-color: #e58f8f; background: #fdf1f1; }
.arrow {
display: flex; align-items: center; justify-content: center;
color: #123c6e; font-size: 30px; font-weight: bold;
width: 44px; flex-shrink: 0;
}
.connector-down {
text-align: center; color: #123c6e; font-size: 30px;
font-weight: bold; line-height: 1; padding: 6px 0;
}
.finish {
margin: 22px auto 0;
width: 560px;
background: #123c6e; color: #ffffff;
border-radius: 14px; padding: 18px 24px; text-align: center;
box-shadow: 0 4px 10px rgba(18,60,110,0.3);
}
.finish .big { font-size: 20px; font-weight: 700; }
.finish .small { font-size: 14px; margin-top: 6px; color: #cfe0f4; }
footer {
margin-top: 26px; text-align: center;
font-size: 13px; color: #7a8aa0;
}
.note {
margin: 18px auto 0; width: 900px; font-size: 13.5px; color: #42536a;
background: #ffffff; border-left: 4px solid #7fb3e0; border-radius: 6px;
padding: 10px 16px; line-height: 1.5;
}
</style>
</head>
<body>
<header>
<h1>🔍 CONFLICT CHECKER</h1>
<div class="subtitle">How your construction plans get reviewed — a team of AI assistants, each with one job, passing notes down the line.</div>
</header>
<div class="blueprint">
<!-- Row 1 -->
<div class="row">
<div class="card scan">
<div class="num">1</div>
<div class="icon">📄</div>
<h2>The Scanner</h2>
<p>Turns every page of your PDF blueprints into a picture the AI can read.</p>
</div>
<div class="arrow">→</div>
<div class="card read">
<div class="num">2</div>
<div class="icon">👓</div>
<h2>The Readers</h2>
<p>One assistant per page, all working at once. Each writes down every fact: dimensions, notes, materials, callouts.</p>
</div>
<div class="arrow">→</div>
<div class="card lib">
<div class="num">3</div>
<div class="icon">📚</div>
<h2>Librarian &amp; Code Scout</h2>
<p>Builds the table of contents (electrical, plumbing, structural…) and figures out <b>where</b> the project is, so the right building codes apply.</p>
</div>
<div class="arrow">→</div>
<div class="card link">
<div class="num">4</div>
<div class="icon">🔗</div>
<h2>The Connector</h2>
<p>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.</p>
</div>
</div>
<div class="connector-down">↓</div>
<!-- Row 2 -->
<div class="row">
<div class="card det">
<div class="num">5</div>
<div class="icon">🕵️</div>
<h2>The Detectives</h2>
<p>One per topic pile. Compares sheets that should agree and hunts for contradictions: "wall shown here, but not on the structural plan."</p>
</div>
<div class="arrow">→</div>
<div class="card spec">
<div class="num">6</div>
<div class="icon">👷</div>
<h2>The Specialists</h2>
<p>Three experts at once: a <b>code inspector</b>, a veteran <b>builder</b> ("can this actually be built?"), and a <b>checklist keeper</b> ("is anything missing?").</p>
</div>
<div class="arrow">→</div>
<div class="card brain">
<div class="num">7</div>
<div class="icon">🧠</div>
<h2>The Brain</h2>
<p>The senior reviewer. Collects every finding, merges duplicates, discards weak ones, and ranks the rest by how much trouble they'd cause.</p>
</div>
<div class="arrow">→</div>
<div class="card human">
<div class="num">8</div>
<div class="icon">✅</div>
<h2>Human Review</h2>
<p>The important and uncertain findings land on <b>your</b> desk. You confirm, reject, or mark unsure — nothing goes out unapproved.</p>
</div>
</div>
<div class="connector-down">↓</div>
<div class="finish">
<div class="big">📋 Final Report + ✉️ Draft RFIs</div>
<div class="small">A prioritized list of every problem found — plus ready-to-send "please clarify" letters (Requests For Information) for the design team.</div>
</div>
<div class="note">
<b>Good to know:</b> 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.
</div>
</div>
<footer>Conflict Checker · conchecker.scoutitsystems.com · Review your plans before they cost you money in the field.</footer>
</body>
</html>
docs/pipeline-infographic.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 184 KiB

docs/pipeline-overview.md
+174
View File
@@ -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`.*