This page puts the example of the whole site in one place. Every chapter used a piece of it; here it runs end to end. If you arrived here first, the Start page explains the idea in five minutes and each section below links to the chapter that explains its part.
An honest boundary first. This is an illustrative reconstruction for teaching. The insurer, the broker, the cases, the rules, the 63 fields, the roof-data provider and every number are invented. The roof thresholds are synthetic, not insurance practice. Nothing here reports the quality of a real system or model: the model here is a scripted stand-in, so these results show how the mechanism works, not how good any model is. The model recommends; a person decides.
The situation#
An insurer sells commercial property insurance through brokers. A broker sends a quote request by email. In our main case the email is for SUB-1004, a masonry office:
From: broker@brokerage.example
To: submissions@insurer.example
Subject: Quote request SUB-1004
Please quote property cover for Example Holdings LLC (synthetic), a masonry office, built 2001, floor area 1,858 square metres, sprinklered. Building value about 2.4 million dollars. The owner says the roof was replaced 9 years ago. Wind zone C. No losses, 0 claims in five years.
That is the version of the email in case UW-S18; the series' shared case UW-004 has the same facts with the area already in square feet. Three agents and one person handle it:
| Actor | Does | Contract it produces |
|---|---|---|
| the intake agent (a model) | turns the email into a submission | submission.v1, 63 fields with provenance |
| the assessment agent | gets the roof assessment from the roof-data provider and hands it on | handoff.v1 around roof_assessment.v1 |
| the underwriting agent (a model) | reads everything, runs the rules, writes a recommendation | recommendation.v1 (or v2 with evidence ids) |
| the workflow (code) | validates at every boundary, repairs within bounds, stamps identifiers, stores the record | recommendation_record.v1 |
| the underwriter (a person) | decides in the underwriter cockpit | human_decision |
The policy fixture, UW-GUIDE version 2026.2 (illustrative), has five rules. The one that matters for SUB-1004 is R-ROOF-03: when the roof age on the application and from the provider differ by more than 5 years, escalate to a senior underwriter. Here they differ by 13 (9 against 22).
Diagram: SUB-1004 from email to decision · who produces, who checks
Each lane is one actor. Read left to right. Payloads cross from a producer lane to a consumer lane, and the workflow checks every crossing before the next actor uses it. Only the underwriter decides.
- Intake agent (model)
- Submission: Read from the broker's email, each value with a quote.
- Assessment agent
- Roof assessment: From the roof-data provider, checked before use.
- Underwriting agent (model)
- Recommendation: escalate, citing R-ROOF-03.
- Workflow (code)
- Intake check: Catches the phrase and the square metres.
- Handoff check: Ties the result to SUB-1004 and run-7f3a.
- Four stages, record: Validates, repairs within 3 attempts, writes the record.
- Underwriter (person)
- Decision: A person decides; the cockpit writes human_decision.
Step by step through the contracts#
The example walks the whole path with one command, run_contracts.py --path. Real output, from a scratch copy:
intake intake agent (model) ok
tool input underwriting agent (model) ok
tool input (a bad call) underwriting agent (model) REJECTED
/submission_id: "1004" does not match ^SUB-[0-9]{4}$
tool result roof-data provider (stand-in) ok
agent handoff assessment agent ok
final response underwriting agent (model) ok
stored record the workflow (code) ok
Each line is one contract checked by the side that receives it (boundaries explains why the receiver checks). The lab below lets you click each point and see the payload, the producer, the validator, and what would break if nobody checked it.
| Boundary | What crosses it for SUB-1004 | Checked by | Chapter |
|---|---|---|---|
| Intake | the submission: area_sq_ft 20000 (converted, declared), roof_age_years 9, building_value_usd 2400000 | the workflow, with submission.v1 and provenance | schema design |
| Tool input | {"submission_id": "SUB-1004"} | the tool runner, before the call | boundaries |
| Tool result | status ok, roof_age_years 22, evidence_id EV-ROOF-0412 | the workflow, before the model sees it | boundaries |
| Handoff | an envelope for SUB-1004, run-7f3a, payload type roof_assessment.v1 | the underwriting agent's code | boundaries |
| Final response | escalate, citing R-ROOF-03, requires_human true | the workflow: four stages | validation |
1. Intake: 63 fields, and where each came from#
The intake agent fills the submission. Its contract is the largest: 63 fields from the catalog, 16 of them required, each with a source (44 from the email, 11 from providers, 5 stamped by code, 3 derived by code). Search them here:
| What to look for | Field | Why |
|---|---|---|
| required and nullable | roof_age_years | the producer must say whether it knows; null is "nobody said", never 0 |
| unit in the name | area_sq_ft, building_value_usd | a number without a unit is half a fact |
| stamped by code | submission_id, intake_run_id, source_email_id | the model must not write identifiers |
| from a provider | provider_roof_age_years, roof_evidence_id | tool results, with evidence ids |
On SUB-1004 the intake agent took three attempts (case UW-S18): a phrase where a number belongs, then square metres in a square-foot field, then the declared conversion. The second attempt was schema-valid and wrong by a factor of almost eleven; only provenance caught it.
2. Tool input and tool result#
The underwriting agent calls get_roof_assessment with {"submission_id": "SUB-1004"}. The tool runner checks the arguments before the call; the bad call in the output above ("1004") never reaches the provider. The provider answers with a roof age of 22 years and the evidence id EV-ROOF-0412. The workflow checks the result against roof_assessment.v1 before it enters the model's context. On another day (case UW-S20) the provider answers status: "partial"; the workflow rejects the unknown value, counts it as drift and degrades the run to request_info.
3. The final response, through four stages#
The underwriting agent writes its recommendation. In case UW-S01 the first attempt is a fluent paragraph instead of JSON; the parse stage stops it, the re-ask carries the error, and attempt 2 is:
{"recommendation": "escalate", "reasons": ["The application says the roof is 9 years old; the roof-data provider says 22 years.", "The two ages differ by 13 years, more than the 5 years rule R-ROOF-03 allows, so a senior underwriter should look."], "citations": ["R-ROOF-03"], "missing": [], "stated_confidence": 0.62, "requires_human": true, "policy_version": "2026.2"}
It parses, has the agreed shape, agrees with itself (an escalation cites a rule), and is true for this run (the rule check also gives escalate under R-ROOF-03). Switch stages off in the explorer to see what each case would do to the underwriter if a stage were missing:
| Stage | Question | Catches, among this site's cases |
|---|---|---|
| parse | is it JSON? | UW-S01 prose, UW-S02 fence, UW-S03 cut off |
| schema | the agreed shape? | UW-S04 to UW-S07, UW-S16 |
| cross_field | agrees with itself? | UW-S08, UW-S09 |
| domain | true for this run? | UW-S10 to UW-S14 |
| none | (passes every stage) | UW-S15: a valid string carrying markup and an instruction |
4. Repair within bounds#
Every failure goes to whoever can fix it without changing its meaning: code unwraps a fence, the model gets a re-ask with the errors, and after 3 attempts the workflow falls back. Step through any case:
| Outcome | Cases |
|---|---|
| accepted after deterministic repair | UW-S02 |
| accepted after a re-ask | UW-S01, UW-S03 to UW-S12, UW-S14, UW-S17, UW-S18 (3 attempts) |
| fallback: no valid recommendation | UW-S13 (requires_human false three times), UW-S16 (ambiguous three times) |
| accepted, flagged untrusted | UW-S15 |
| upcast | UW-S19 |
| degraded to request_info | UW-S20 |
5. The record code writes, and the person who decides#
Code wraps the accepted recommendation in a record and stamps every identifier. The record of UW-S01 (the recommendation itself left out here):
{
"schema_version": 1,
"submission_id": "SUB-1004",
"run_id": "run-7f01",
"attempt_number": 2,
"trace_id": "41f93ea7fa4048728e1f5d184202311e",
"policy_version": "2026.2",
"evidence_ids": ["EV-EMAIL-1004", "EV-ROOF-0412", "EV-GUIDE-0031"],
"status": "recommendation_ready",
"validation": ["parse", "schema", "cross_field", "domain"],
"requires_human": true,
"human_decision": null
}
attempt_number 2 says a re-ask happened. human_decision is null: nobody has decided yet. The underwriter cockpit is the web app where the underwriter sees the submission, the evidence and this record, and decides. When they do, the cockpit, not the model, writes the decision. The series' shared case UW-009 shows one: the agent recommended approve, and the underwriter declined.
{"decided_by": "underwriter", "decision": "decline", "override": true, "reason": "The broker's loss run shows an open water damage claim that is not on the application."}
Plain English. An override is a human decision that differs from the agent's recommendation. For example: approve recommended, decline decided. override is computed by code from the two values, and the reason is required, so that every override can be counted and read later.
Diagram: Who writes which part of the stored record
Read left to right. The model writes only the recommendation inside the record. Code writes every identifier and the validation result. Only the cockpit, on a person's action, writes the decision.
- The model
- recommendation: The object that passed all four stages, nothing else.
- The workflow (code)
- Identifiers: submission_id, run_id, attempt_number, trace_id, policy_version, evidence_ids.
- status, validation: recommendation_ready with four stages, or no_valid_recommendation with the errors.
- The underwriter cockpit
- human_decision: decided_by, decision, override, reason; null until someone decides.
All twenty cases at once#
The example runs every case of this site with run_contracts.py. Real output:
case boundary first failure outcome attempts
UW-S01 final parse accepted_after_reask 2
UW-S02 final parse accepted_after_repair 1
UW-S03 final parse accepted_after_reask 2
UW-S04 final schema accepted_after_reask 2
UW-S05 final schema accepted_after_reask 2
UW-S06 final schema accepted_after_reask 2
UW-S07 final schema accepted_after_reask 2
UW-S08 final cross_field accepted_after_reask 2
UW-S09 final cross_field accepted_after_reask 2
UW-S10 final domain accepted_after_reask 2
UW-S11 final domain accepted_after_reask 2
UW-S12 final domain accepted_after_reask 2
UW-S13 final domain fallback 3
UW-S14 final domain accepted_after_reask 2
UW-S15 final - accepted_flagged_untrusted 1
UW-S16 final schema fallback 3
UW-S17 intake domain accepted_after_reask 2
UW-S18 intake schema accepted_after_reask 3
UW-S19 evolution schema upcast 0
UW-S20 tool_result schema degraded 0
| Case | Built on | The raw output | Chapter that explains it |
|---|---|---|---|
UW-S01 | UW-004 | a fluent paragraph, no JSON | four layers, repair |
UW-S02 | UW-004 | correct JSON in a code fence | repair |
UW-S03 | UW-004 | JSON cut off by the output limit | repair, advanced |
UW-S04 | UW-004 | "approved" | JSON Schema |
UW-S05 | UW-004 | policy_version absent | repair |
UW-S06 | UW-004 | "stated_confidence": "high" | typed models |
UW-S07 | UW-004 | extra field premium_usd | schema design |
UW-S08 | UW-003 | request_info with nothing missing | validation |
UW-S09 | UW-001 | decline with no citation | validation |
UW-S10 | UW-002 | a rule that does not apply | validation |
UW-S11 | UW-004 | a rule the fixture does not contain | validation |
UW-S12 | UW-007 | an old policy version | validation |
UW-S13 | UW-004 | requires_human: false | repair |
UW-S14 | UW-004 | evidence never gathered | schema design |
UW-S15 | UW-005 | markup and an instruction in a valid string | security |
UW-S16 | UW-004 | an ambiguous word, three times | repair |
UW-S17 | UW-003 | a roof age of 0 with no source | schema design |
UW-S18 | UW-004 | a phrase for a number; square metres | schema design |
UW-S19 | UW-004 | version 1 read by a version 2 reader | evolution |
UW-S20 | UW-004 | an unknown status from the provider | boundaries, observability |
Run it yourself#
Everything above comes from examples/uw-contracts/ in this site's repository: standard-library Python 3, no key, no network, no model call. Copy the folder and run:
cd examples/uw-contracts
python3 run_contracts.py # the twenty cases, a summary, files in out/
python3 run_contracts.py --case UW-S18 # one case, every attempt and error
python3 run_contracts.py --path # SUB-1004 across every boundary
python3 -m unittest # 43 tests
The folder's README lists every file and maps each concept to a function. The labs on this site run the same functions, ported to JavaScript and checked against the Python results row by row (1,290 rows on the day this was written). The Pydantic and Java comparison lives in examples/uw-contracts/twins/: a recorded run of real libraries, explained on typed models.
What this is not. Measuring how often the agent's recommendations are right, over many runs and with graders, is eval.sammuthu.com, which uses the same insurer and the shared casesUW-001toUW-010. The runtime that would host these agents is harness.sammuthu.com.
For a coding agent. The same machinery fits a coding agent that reports its work as achange_reportfor CI:schemas/change_report.v1.jsonin the example, with one valid and one invalid sample checked by a test. Review and CI for coding agents are on diff-to-deploy.sammuthu.com.
Checklist#
- Write the path down: every boundary, its producer, its consumer, its schema, its owner.
- Give the intake contract a field catalog with a source for every field, and provenance for every value read from a document.
- Check tool arguments before the call and tool results before the model sees them.
- Run the four stages on every final output, in order; repair within a small bound; fall back to a person.
- Let code stamp every identifier and write the record; let only the cockpit write the human decision.
- Keep the cases as files and run them all on every change, with the expected outcome of each.
What this example leaves outOn purpose, to stay readable
There is no real model, no real provider, no database and no web app: the underwriter cockpit is a role in the text and a lab on this page. The validator implements only the part of JSON Schema the site teaches. The repair loop is synchronous. Production systems add a queue for the human step, storage with access control for raw outputs, tracing through a real library, and the reliability concerns of retries and timeouts (see reliable.sammuthu.com). The contracts, the stage order, the bounds and the record shape carry over unchanged.
In one breath#
One quote request crosses five contracts on its way to a person: the intake agent's 63-field submission with provenance, the tool's arguments, the provider's result, the handoff envelope and the final recommendation, and each is checked by the side that depends on it. Failures go to whoever can fix them without changing their meaning, within three attempts, and code writes a record with stamped identifiers whether a valid recommendation exists or not. The underwriter decides, and the cockpit records it.
This is the end of the path. The glossary has every term in one place, and about lists the sources, the sister sites and what is original here.