Keys: the full design
This page goes one level deeper than the ten-minute version. The world it runs on is described in docs/world.md; what it does not handle is in known gaps.
Data plane
| Source system | Tables | Freshness |
|---|---|---|
| Property management system | buildings, units, unit_vacancies, rent_bands, tenants, leases, renewal_offers | realtime |
| Rent ledger | rent_ledger, tenant_notices | realtime |
| Maintenance help desk | tickets, ticket_events, vendors | realtime |
| Building management system | assets, alarms | streaming |
| Access control | access_events | streaming |
| Purchase ledger | vendor_invoices | hourly |
| Compliance register | inspections | daily |
The operator owns four more tables: messages (the outbox: drafts a person sends), process_gaps (kinds with no runbook), detector_runs (when each scheduled check last ran) and replay_events (markers for the timeline), plus the ledger's ledger, approvals and ledger_repeats.
Incident taxonomy
| Kind | Definition | Cadence | Runbook (in order) |
|---|---|---|---|
| rent_arrears | oldest unpaid charge 10+ days, next stage not taken | daily 08:00 | send_arrears_reminder (0), serve_legal_notice (2) |
| renewal_not_sent | lease ends within 60 days, no offer, no notice | daily 08:00 | send_renewal_offer (0) |
| renewal_out_of_band | pending offer outside its sending date's band | hourly | reissue_renewal_offer (2) |
| long_vacancy | empty 45+ days, not renovation | daily 08:00 | list_unit (0), offer_rent_concession (2) |
| ticket_sla_breach | no vendor at half the SLA, or no attendance by its end | every step | dispatch_vendor (0), reassign_vendor (1), replace_vendor (2) |
| duplicate_ticket | same fault, same home or hallway, while the first is open | every step | merge_duplicate_ticket (0) |
| invoice_without_ticket | job invoice matching no job of that vendor | hourly | hold_invoice (0) |
| inspection_overdue | statutory check past due, nothing booked | daily 08:00 | book_inspection (0) |
| water_alarm_no_ticket | live leak alarm, no ticket after 10 minutes | every step | open_ticket_from_alarm (0) |
| lift_outage_single | lift fault 5+ minutes, no other lift working | every step | open_ticket_from_alarm (0), then notify_residents (1) |
Decision model
For each incident a worker proposes one action. If the runbook leaves one action at tier 0 or 1, a fixed rule fills it in (keys/agent/rules.py). Where there is a choice, or a person may have to approve, the model is asked with the incident, the definition used and the allowed actions with their arguments; its JSON answer is validated against the policy and falls back to the rule if it is unusable. The controller then decides: execute, queue, wait or decline, each with a plain-English reason.
The ledger row
Incident id (kind, subject, start), kind, subject, evidence (with the money at stake), definition term and version, proposal (rules or model, rationale, confidence), decision (tier, reason, checks, policy version), the call, the result with before and after snapshots, who approved, and the undo. Rows are appended and never edited; an approval, rejection or undo is a new row pointing at its parent. A decline repeated for the same incident is folded into the first row's repeats.
Failure modes
- A definition that fails to evaluate is logged once per window as a detector error; the other detectors keep running.
- A tool that raises leaves the world untouched (the action and its ledger row commit together or not at all).
- An undo that finds the world changed since the action refuses and says what changed.
- The model unavailable or invalid: the rule decides, and the row says so.
Measurement
Recal matches detections to the answer key by kind, by the thing they are about, and by time (20 minutes of slack): precision per detection, recall per planted fault, the share of incidents resolved without a person, reverts, time to resolve and age at detection. The per-day timeline scores only faults that began that day.
Policy in one file
keys/agent/policy.yaml (version 2) holds, for each of the 14 actions: the call it stands for, its tier, the incident kinds it may answer, its arguments and where each must come from (the evidence, the band, the panel), its cooldown, and its undo in words. Around them: the never list (eviction, a rent outside the band, contacting a tenant about a legal matter, waiving arrears, paying an invoice, ending a lease, deleting a record, and anything not listed), budgets per building (six automatic actions an hour), per portfolio (thirty a minute) and for the back office (forty a minute), the dedupe window (fifteen minutes), the cadence of each detector (every step, hourly, daily at 08:00), what happens when a budget is used up (a person decides) or a cooldown is active (declined, with the reason), and when the model is asked (only where the runbook offers more than one action or a tier 2 step is possible; water alarms, duplicates, inspections and invoices are always decided by rules). The controller (keys/agent/controller.py) loads it at start and stamps its version on every decision.
The interface
A FastAPI application (app/) with server-rendered pages and one script for the main screen. It reads the database through app/data.py, the only module that touches DuckDB; one short connection per call, never shared across threads. The visitor's site arm (?v=&p=) is carried on every same-site link, form and redirect by app/arm.py. Responses over 2 KB are compressed.
| Path | Screen | Read from |
|---|---|---|
/ | Buildings: the elevation, the ticket board, the receipts, play mode | /api/stack (below) |
/ledger, /ledger/{id} | every row; one row with evidence, definition, the call, the controller's checks, before and after, undo | ledger, ledger_repeats |
/queue | tier 2 items with approve and reject; the people's latest decisions | ledger, approvals |
/accuracy | headline scores, the weakest detector, day by day, per incident kind | recal over the ledger and incidents_truth |
/definitions, /definitions/{term} | every term; one term evaluated at the window's end, each meaning side by side | the dictionary |
/ask?q= | a question answered through the definitions, both meanings where there are two, nothing where none fits | the dictionary |
/architecture, /architecture/full, /known-gaps | these documents | docs/ |
The building stack payload
GET /api/stack (app/stack.py) returns everything the main screen draws, built once and cached until the ledger changes (an approval or undo on another screen rebuilds it on the next read):
- Geometry. Buildings grouped by city and ordered tallest first; each home as (building, floor, column, label). The browser lays the buildings out in bands, one per city, choosing the largest cell pitch of 8, 7 or 6 px that fits the window (never smaller, so a home stays a visible square; the page scrolls). The clock starts at 06:00, two hours before the busy window, so rent day's morning wave shows: occupied homes turn darker as their rent lands ("rent in today", counted straight from the rent ledger). The Queue also has an as-at view (
/queue?at=...) listing the tier 2 items that were waiting at that moment, with the buttons off because the scripted shift answers them. - Frames. Every ten minutes of the window, the home states from four definitions evaluated at that moment:
occupied,vacant(lettings meaning: on the market, renovation excluded),arrears(credit control meaning: a rent past its due date and unpaid, mapped from lease to home) andopen_ticket. The first frame lists every home; later frames list only the homes that changed. Each frame carries the counters shown in the header, so those numbers are the definitions' own counts. - Tickets. Every ticket alive at some point of the window, with the minute it was opened, dispatched, attended, completed, closed or merged. The tools write these timestamps when they act, so an operator's merge or dispatch moves the card at the minute it happened.
- Receipts. The window's ledger rows, each tied to the home (from the evidence, the lease or the offer), the building and the ticket it touched.
Play mode
The clock runs in the browser at ×120, ×360 or ×720 over 08:00 to 20:00. On every new minute it applies the frames up to that minute, recomputes each ticket's stage, and lands the receipts the clock has passed: an ink ring pulses on the home or above the building, the cell keeps an ink outline for the rest of the day, and a ticket the operator moved carries a stamp linking to its ledger row. Scrubbing backwards rebuilds the state from the first frame. Play replays the recorded run: the operator's decisions as it made them on this world during the replay, at the times it made them. It does not run the operator again in the browser (see known gaps).
Tests
.venv/bin/pytest -q runs the suite on a seed 7 world generated once per session and a short replay on a copy of it: world determinism and incident counts, every definition's tests, the policy file's shape, the controller refusing tier 3 and over-budget actions, the ledger's undo, a replay smoke test, recal, every screen answering 200 with the site arm kept and the synthetic-data label shown once, and the stack payload's counters equal to the dictionary's at the same moment.
Screenshots
scripts/screenshot_all.py starts the app on port 8165 against out/keys-replayed.duckdb, visits every screen at 1440x900 with Playwright (including the main screen while playing and with a home under the pointer), writes the PNGs to out/screens/, fails on any HTTP or browser console error, and stops the server by its port. It presses no approve, reject or undo button, so the database is not changed.