Blueprint Risk Engine

Blueprint Risk Engine / diagrams

Five diagrams

The whole system, drawn. Every diagram has numbered points on it and a short explanation for each point underneath. No wall of text.

The first diagram marks which stages run today, which are built but wired to nothing, and which are not built at all. That distinction is the diagram, not a footnote under it.

Standing notice: not yet benchmarked

This engine has never been measured against real outcomes. There is no benchmark dataset, no precision figure, no recall figure, and no accuracy claim anywhere on this site. Nothing on this page, and nothing in any output it describes, may be read as evidence that the engine produces correct output. It may be wrong, and how often it is wrong is currently unknown and unmeasured.

The measurement that would matter is precision and recall of pre-bid flags against the change orders a project actually issued. That measurement does not exist yet. Until it does, read this page as a description of a design, not as a claim about results.

Required by project amendment A-003. This notice is permanent and cannot be dismissed.

01The pipeline

A bid package becomes a risk register, and three stages of it do not run

Left to right: PDFs go in, a ranked register comes out. The label on each arrow is the data structure that crosses it. The fill on each box says whether that stage runs today.

  • runs today
  • built and tested, wired to nothing
  • not built
  • input or data file
The Blueprint Risk Engine pipeline in three lanes. Documents are ingested and scope markers detected, both of which run today. Claim extraction and two-vendor agreement are built but wired to nothing. Plan extraction is not built, so spatial models are hand authored. All inputs merge into the deterministic rule engine, then validators, then the risk register, the report and the plan viewer. LANE A / DOCUMENTS Bid package PDFs specs, addenda, schedules Ingest, CSI segmentation text with page and rectangle Scope marker detection regex, with a known gap Claim extraction the one model call Two-vendor agreement compares, never arbitrates PDF bytes sections section text Claim LANE B / DRAWINGS Drawing sheets the real plan set Plan extraction not built SpatialModel hand authored today Rule packs JSON data, versioned sheets openings DocumentModel Claim, agreed SpatialModel DesignRulesPack LANE C / ENGINE Rule engine loader, expressions, evaluate, joins, seam. Two passes. Validators six checks that print what they computed Risk register plus BOM and rule trace ranked, every line cited EvaluationResult ValidationResult Report markdown and JSON Plan viewer draws precomputed values EngineOutput 1 2 3 4 5 6 7 8

Wide diagram. Drag it sideways on a narrow screen.

  1. Ingest runs on real PDFs. It pulls text out of a package, splits it by CSI MasterFormat section numbering, and keeps the document, page and rectangle for every piece. No model is involved.
  2. Scope marker detection runs too, and its gap is recorded. It finds phrases such as "NIC", "by others" and "furnished by" using patterns, not a model. It misses owner-furnished scope written in ordinary English, and that miss is held open as a backlog item rather than papered over.
  3. Claim extraction is finished and reaches nothing. This is the single sanctioned model call for reading documents. It is written and tested, but no command invokes it, so no package the tool can actually produce today contains claims.
  4. Two-vendor agreement is in the same state. Complete, tested, called by nothing outside its own tests. Diagram 3 is what it does when it is wired.
  5. Plan extraction does not exist. Nothing in the system reads a drawing sheet. Spatial models are written by hand today, which is why lane B is dotted up to that point.
  6. Everything meets here, and this half is deterministic. The rule engine cannot reach a model at all. Not the vendor libraries, not an HTTP client, not even the packages that hold them. Diagram 2 is how that is enforced.
  7. The register is the product. The bill of materials is supporting evidence under it, not the headline, and the rule trace records which rules were suppressed as well as which fired.
  8. The viewer reads the JSON, never the report. It renders values the engine already computed. It performs no geometry and no scoring of its own, so it cannot disguise a missing engine capability.

Two consequences of the marked gaps are worth stating. Because claim extraction is unwired, half of the seam analysis in diagram 4 has nothing to read on any package this tool can produce today. And because there is no benchmark, none of this says the findings are correct.

02The boundary

A model may say what a document says. Only code may say what that means.

One wall, drawn down the middle. The wall is a schema. Nothing downstream of it ever reads model text.

A vertical split. On the left, what a language model is permitted to do: extract, classify, locate, transcribe and match. In the middle, a wall labelled the schema, with a single gate through which only structured facts pass. On the right, what only code may do: compute a quantity, assign a part number, produce a risk score, determine compliance and cite a page. Below, a bar describing the import-graph test that enforces the wall in both directions. The model may Extract pull subject, predicate, object off a line Classify say this reads like a scope assignment Locate say which sentence, so code can go find it Transcribe report it as written, never tidied Match say these two lines look like one opening THE SCHEMA NO MODEL TEXT structured facts only Claim / DocumentModel / SpatialModel Only code may Compute a quantity counts, per-leaf math, totals, capacities Assign a part number device selection comes from a rule pack Produce a risk score severity, exposure band, rank order Determine compliance whether something meets code, or does not Cite a page a citation is a claim about the world Enforced by an import-graph test, not by a review convention The engine, the validators, the scoring and the risk modules may not import a model library, an HTTP client, or the two packages that hold them. The ban runs the other way too, so a chat surface cannot re-run a rule or re-rank a register. That module holds 35 passing tests, and it has been found broken once and repaired. 1 2 3 4 5
  1. Everything on the left is reading. The model finds a sentence, says where it is and what it appears to say. It is used the way you would use a very fast reader with no authority.
  2. The wall is a schema, not a policy. What the model is permitted to return has no page, no rectangle and no section number on it. Those fields do not exist on the record it fills in, so it cannot supply them.
  3. Code opens the gate by finding the quote on the page. It searches the actual page for the exact text the model returned. Found means the rectangle is built from the search result. Not found means the reading is dropped and the quote is counted as a defect, which is what stops invented text from acquiring a citation.
  4. Everything on the right is a determination. A quantity, a part number, a severity, a compliance call, and a citation are all conclusions about the world, so a model may not make any of them. Rules written in versioned data files make them instead.
  5. The wall is checked by machine, because the failure mode is a reasonable person under deadline. Someone will want one model call inside a validator to resolve an ambiguity, and they will be right that it would work. A review convention depends on a reviewer noticing on that day. An import graph does not.

The reason for the split is commercial rather than aesthetic. You bring a flag to a pre-bid review and the engineer whose design you are questioning asks where it came from. A named rule, a quoted sentence and a page number turns that into a discussion about the document, which is the discussion worth having.

03Two readers

Two vendors read the same row, and there is deliberately no tiebreak

Two paths out of one comparison. One of them produces a value. The other produces no value at all, on purpose.

One row of one document is read independently by a model from vendor A and a model from vendor B. Both readings enter a comparator that runs in code. If every field agrees, one agreed row is emitted with confidence equal to the minimum of the two. If any field differs, no value is emitted at all and a vendor disagreement record is filed holding every reading, with no field for a winner. A strip at the bottom lists the tiebreak schemes that were rejected. One row of one document same page, same rectangle Vendor A model reads it independently Vendor B model never sees A's answer reconcile field by field EVERY FIELD AGREES ANY FIELD DIFFERS The value is adopted One agreed row is emitted. Its confidence is the MINIMUM of the two, never a blend and never a lift. Agreement withholds the flag disagreement would have raised. That is all it does. No value is produced Not a value with a warning beside it. None. A disagreement record is filed instead: every reading, each vendor and model, the rectangle, and a review flag that cannot be set to false. There is no field for the winner. Every scheme for picking a winner is arbitration Rejected, each with its own test: majority vote, higher confidence wins, sorting the readings, emitting a value with a flag. 1 2 3 4 5 6
  1. One row, two readers, no contact between them. Neither model is shown the other's answer, because two readers who can see each other are one reader.
  2. A row only one vendor read is a disagreement, not a single-vendor value. The absent reader contributes an explicit "not read" at zero confidence. Skipping it would let a row one model never saw arrive looking like a well-read row.
  3. The comparison is code, and it is held to the engine's standard. No model, no network, no clock. A test parses the comparator and fails if it imports a vendor library, an HTTP client, or anything that could make two runs differ.
  4. Agreement takes the lower confidence, never a higher one. Two readers each eighty percent sure does not become ninety-six percent sure. A formula that lifts them would be a number this system invented about its own reliability. Agreement also does not rescue a bad reading: agreeing on an illegible cell is still agreeing on an illegible cell.
  5. Disagreement emits nothing, and the record has no winner field. Two independent readers diverging on a construction document is evidence about the document, not about the models. It says the passage is genuinely ambiguous, which is exactly what an estimator is paid to know before the bid closes.
  6. Why a tiebreak is the wrong feature. A flag can be ignored by a later step that forgot to check it; an absent value cannot. And a tiebreak shortens the flag list without reducing the ambiguity, so the estimator reads the shorter list as good news about the documents rather than as a change in the software.

A run refuses to start when only one reader is configured. Quietly falling back to a single vendor would report agreement that was never checked, and the register would come out wrong in the direction of false confidence.

04The seam

One door opening, two divisions, and four ways the money goes missing

Door hardware is Division 08, written by the architect. Access control is Division 28, written by the security engineer. The electrified locking device sits on the line between them.

A door opening drawn in plan, with a dashed seam line running down the middle of it. Division 08, the architect, is on the left. Division 28, the security engineer, is on the right. Below the door, four panels show the states that cost money: specified in both divisions, specified in neither, each division pointing at the other in a circle, and not determined at all. A fifth strip shows the settled case, in which no rule fires. DIVISION 08 the architect doors, frames, door hardware DIVISION 28 the security engineer electronic safety and security the locking device, its power and its rough-in sit exactly here three aspects, determined per controlled opening SB-021, or SB-020 if they disagree Specified in BOTH Two divisions carry the same device. Costs money as a duplicate buy, or as an argument at submittal about whose product is the right one. SB-023 Specified in NEITHER Both sections were read. Neither carries it. Costs money because nobody priced it at bid time, and after award somebody eats it. SB-022 Each points at the OTHER Division 08 hands it to 28. Division 28 hands it back. Costs money because both sentences are valid alone and together they assign the work to nobody. SB-024 NOT DETERMINED One side of the seam was never supplied, or the statement names no party. Costs money as lost trust: call it unassigned and the reader stops believing you. Settled: one division carries it, or a third division is named for it No rule fires. Silence is the output, and a test pins the ratio of findings to silences so the rules cannot start firing on the ordinary case. 1 2 3 4 5 6
  1. The seam is where the failure is symmetrical. A sentence reads "by others, by Division 28". The security contractor reads it as somebody else's scope. The door hardware supplier reads the same sentence, agrees the work is Division 28, and neither party prices the rough-in.
  2. Both, and they disagree. Two sections carry the device and want different things from it. That argument happens at submittal, after the price is fixed. If they carry it and agree, it is a duplicate buy instead, which is a different rule and a different pre-bid question.
  3. Neither, and both sections were read. This is only reportable because the engine knows it saw both sides. Saying nobody specified it on a package that never included Division 08 would be a confident answer built on a missing document.
  4. The circular hand-off is its own state, not an error. Computed naively it looks identical to "both divisions carry it", which is the opposite finding and the opposite action. It carries a higher severity and an action that says to quote both sentences side by side in the request for information, because asking with only one attached invites the answer that it is obviously yours.
  5. Not determined is an admission about our reading, not a conclusion about the documents. It exists so that state has somewhere to go. A bidder shown "nobody specifies the rough-in" on a package whose Division 08 section was never supplied will find the assignment themselves and stop believing the register.
  6. The healthy case produces nothing, and that is measured. A Division 08 section handing door contacts to Division 28 is how a well-drafted specification is supposed to read. If the silence ratio ever inverts, the rules have started training their reader to skip the section.

The full seam analysis reads two kinds of evidence: located scope statements, which the ingest lane produces today, and structured claims, which it does not. Until claim extraction is wired, half of this runs on nothing. That is stage 3 in diagram 1.

05One register line

What "every line carries provenance" means, on one line

Demonstration. The line below came out of an engine run against the repository's golden fixture: an invented package for a fictional district. The district, the manual, the page and the sentence are all fabricated for testing. It is here to show the shape of a finding and where each part comes from. It is not evidence that the engine is right, and no accuracy claim is made anywhere on this page.

A single risk register line blown up into eight stacked parts, with a leader line and a numbered marker running from each part to a short label on the right. The parts are the rule and pack, the document and page, the verbatim quoted sentence, the rationale and authority, the recommended pre-bid action, the confidence, the exposure band marked as uncalibrated, and the rule trace recording which rules did not fire. RULE SB-002 severity MEDIUM, category SCOPE GAP pack scope_boundary 0.1.0 WHERE project manual, section 28 13 00, page 8 document, page, and the rectangle on that page WHAT IT SAYS "Rough-in at the exterior openings is by others, by Division 28." WHY A marker naming Division 28 points at our own scope authority: the Division 08 and 28 boundary, and the general conditions clause on reviewing the documents WHAT TO DO Confirm this is carried in the base bid, and price it an action you can take before the bid closes HOW SURE 0.87 extraction confidence above the review threshold, so no manual flag is raised EXPOSURE band withheld from this page an uncalibrated placeholder, not derived from cost history RULE TRACE applied SB-002 suppressed SB-001, same conflict group, and the reason 1 the rule that fired, and the versioned pack it came from 2 the document and the page, not "the specifications" 3 the sentence as written, so you argue with the document 4 plain English, plus the authority the rule leans on 5 a pre-bid action, not an observation 6 the confidence, and whether a person has to confirm it 7 a planning band, marked in the deliverable as uncalibrated 8 the rules that did not fire, recorded rather than dropped
  1. The rule id and its pack are on the line itself. Two runs a month apart can be compared because the rule that fired is named in both, and pack ids are permanent. They are never renumbered.
  2. The citation is looked up by code, not written by a model. A citation is a claim about the world, so the record is unconstructable without at least one locator. A line without provenance is treated as a defect in the software, not a formatting preference.
  3. The sentence is quoted verbatim. A tidied reading is what a reviewer ends up arguing with instead of arguing with the document.
  4. Rationale and authority travel together. Code interpretation varies by jurisdiction, so a rule cites what it leans on and stays overridable on a project. The rationale is written as if the reader is the engineer whose design you just contradicted, because sometimes they are.
  5. The action is phrased for the week before the bid closes. A pre-bid request for information is free. The same question asked after award is a negotiation.
  6. Confidence is carried, never smoothed. Below the threshold the item is flagged for a person. Where the documents do not determine something, the engine emits a flag rather than a guess.
  7. The exposure band is a placeholder and says so. Every band shipped today was chosen so the ranking key has something to sort on, and none is derived from cost history. Rather than print a placeholder in the same typeface as a real figure, every rendering marks it. No figures appear on this site for that reason.
  8. The rules that lost are recorded too. When two rules could apply to one sentence, one wins and the other is kept with its reason, so a reviewer who expected a different finding can read the rule that displaced it instead of guessing. Reporting both would put the same money in the register twice.

A run replays exactly from the same documents, configuration and seed, down to the individual characters of the report. That matters for an ordinary reason and an unusual one. If the register changes, something changed and you can find out what. And a run that cannot be replayed cannot be benchmarked, which is the thing this project does not have yet.

06Next

Where to go from here

/ The overview One finding in full detail, the state of the build component by component, and a longer list of what is not proven. /how-it-works/ The same design, in words The written version of these five diagrams, for reading rather than scanning. Written for estimators and contractors.