Rounds in full
The complete design, module by module. The ten-minute version is architecture.md; the world is described in world.md; what Rounds does not do is in known gaps.
1. Shape of the system
┌────────────────────── policy.yaml (written authority) ─────────────────────┐
│ │
world (DuckDB) ──► detectors ──► dedupe ──► workers ──► controller ──► tools ──► world │
▲ (dictionary (ledger (rules or (tier, budget, (FHIR-style │
│ definitions) lookups) model) cooldown) calls + undo) │
│ │ │
│ └──► sign-off queue ──► people (tier 2) │
│ │
└──────────── action record (append-only ledger) ◄── every decision, refusal and undo ──────┘
│
├──► scoring against incidents_truth (rounds/recal)
└──► screens (app/)
There is one process per run. The runner owns its own database connection; the screens open one connection per request. All time is logical: everything that asks "what time is it" asks a Clock, never the wall. That is what lets a replay run a week in about two minutes and lets play mode run the busiest window at 120 times real speed.
2. The world (rounds/world/)
generate.py writes one DuckDB file from a seed in about five seconds, deterministic per seed. It builds the group (people.py: regions, clinics, specialties, clinicians, rooms, patients), the diary (diary.py: weekly half-day lists, absences, bookings, cancellations, arrivals, no-shows), the care around it (care.py: referrals, discharges, lab orders, results, authorisations, consents, waitlist, messages), and then plants faults (faults_diary.py, faults_results.py, faults_admin.py) and decoys. Names come from word lists in names.py.
Every row carries its own event times. Status columns record how things stood at the world's end, and are never read by a definition; definitions read times, so any question can be asked "as of" any moment. The day-board relies on this: it draws a booking only once booked_at has passed, a cancellation only once cancelled_at has.
incidents_truth is the answer key: kind, clinic, subject, patient, when the problem became visible, when (if ever) it was put right, the root cause, the correct handling and the severity. No part of the operator reads it.
3. The dictionary (rounds/dictionary/)
Each term is a YAML file in definitions/: a title, a description, parameters (for example abnormal_hours: 24, critical_hours: 4), and one or more variants. A variant has an owner, a department, a version, a change note, a history of earlier versions, SQL with placeholders ({now}, {period_start}, parameters), and tests.
store.pyanddictionary.pyload and validate the files.execute.pyprepares a variant's SQL for a moment and a period and runs it, returning aResultwith the rows, the SQL that ran, the version and the parameters.testing.pyruns each variant's expectations and checks every detector returns the shape the operator needs (an incident id, a subject, a start time, a clinic and evidence).period.pyresolves "last week", "today", "this month" into half-open windows in world time.
There are sixteen terms: ten detector definitions and six shared words. Five of the shared words have two meanings, owned by different departments: no-show (operations; the health-fund contract), late cancellation (operations; the patient charter), acknowledged (results inbox; clinical governance), overdue follow-up (booking team; clinical), active patient (registration; clinical). Abnormal result has one.
4. The operator (rounds/agent/)
Detectors and cadence
detectors.py turns each detector definition into Incidents, calling only the dictionary; it holds no SQL of its own. A definition that fails to evaluate becomes a detector_error row in the record (a blind spot is visible). cadence.py decides which detectors are due on this tick: realtime ones every tick, hourly ones on the hour, the daily one at 07:00. Last runs are stored in detector_runs, so a restart does not repeat a daily check.
Runner
runner.py runs one pass per tick: due detectors, then anything waiting on the group rate limit, then new incidents in order of severity and start time. new_incidents drops duplicates: anything handled inside the fifteen-minute dedupe window, anything already in the queue, anything a person turned down or undid, anything whose action is marked once-per-incident and already ran, and anything inside its action's cooldown. start_background runs the loop on its own thread and connection, which is what live play mode uses.
Workers and the model
rules.py has one small function per incident kind that reads only the evidence and returns an action, its arguments and a reason. llm.py is an OpenAI-compatible client configured only from the environment (ROUNDS_LLM_BASE_URL, ROUNDS_LLM_API_KEY, ROUNDS_LLM_MODEL, ROUNDS_LLM_FALLBACKS). The policy says when it is asked: only when the runbook leaves a real choice, and always when a tier-2 action is possible. Four kinds are decided by rules alone. If the model is missing, slow, or returns something unusable, the rules decide and the record notes it. parallel.py asks for proposals in parallel and caches identical ones within a run; decisions and writes stay on the runner's thread, in order, because budgets depend on what was just done.
Controller
controller.py is the only component that can authorise execution. For every proposal it checks, in order: the action exists in the policy; it is allowed for this kind of incident; its arguments are the ones the policy names and take allowed values; the targets are the ones the evidence names; the written conditions hold (ask_first_when, for example a re-file where only the family name matches, or more than sixteen patients to move); cooldowns; per-clinic, group and admin budgets. The result is a Decision with a tier and a plain-English reason. when_a_limit_is_hit says what happens at each limit: a used-up clinic budget goes to a person, the group's per-minute limit waits for the next minute, a cooldown or a false condition is declined with the reason.
Tools
tools/ holds eleven tools named after FHIR-style calls (endpoints.py renders each as one line): offer waitlist slots, send a booking offer, send a reminder, move a booking to a free room or colleague, move a sick clinician's list, cancel a clinic, re-file a result, request consent, request an authorisation renewal, escalate to the on-call doctor, merge patient records. Each tool re-checks the world itself, never trusting the evidence to still be true, and returns the before and after rows it touched and the name of its rollback. slots.py finds free slots and only offers ones the recorded diary leaves free. A runbook can chain: after a failed move, if_it_fails sends the patient a new-slot offer.
Handling and shadow mode
handling.py runs propose, decide, execute or queue or decline, and writes the record row with the evidence, the definition and version, the proposal, the decision, the call, the result and what is at stake (stakes.py: the patients and bookings affected, never a claim about what was saved). With ROUNDS_SHADOW=1, every tier 0 and 1 action becomes a "shadow" row naming the call it would have made, and the world is left untouched.
Process gaps
gaps.py: an incident kind with no runbook in the policy gets no action (no runbook means no authority). One backlog row is filed per kind, and when people have handled similar incidents through the queue, a draft runbook is written from what they approved and rejected. A person turns the draft into policy.
Scripted staff
humans.py reads humans.yaml: five synthetic roles with working hours, response delays on the logical clock and rules (sign off an abnormal-result escalation; turn down a merge when phone and postcode both differ; turn down a re-file when the request came from outside the group; undo a move into the treatment room). A backlog sweep decides tier-2 items older than two hours by the same kind of rules; that is how a list cancellation proposed too late gets turned down. Their decisions are ordinary approvals, rejections and rollbacks in the record, labelled as scripted. Anything no rule covers stays in the queue for a person.
5. The action record (rounds/ledger/)
Two tables and a side table. ledger holds one row per decision: time, incident, kind, subject, proposal, decision, action, arguments, tier, result (with before and after), evidence, definition and version, model, tokens, cost, status, the person, a note, the parent row and the call. approvals holds who decided a tier-2 item and when. ledger_repeats folds repeats of the same decline into the row they repeat, so the record stays readable.
The API has no update and no delete. A sign-off, a refusal or an undo is a new row whose parent_id points at the row it acts on. Undo (Ledger.rollback, with the tool's rollback from tools.run_undo) runs the stored rollback through worldops.plan_restore, which restores a row only if nobody changed it since the action; any conflict is reported and nothing is half-restored.
Statuses: auto_done, escalated, approved, rejected, declined, rolled_back, failed, shadow.
6. Replay and scoring
scripts/replay_window.py replays on a copy of a world; it refuses a file under data/ and a database whose record is not empty. With --history-days, the days before the window run on coarse steps so the record holds the whole week; then the window runs on fine steps (Monday 08:00 to 13:00 at 30 seconds by default). Scripted staff answer the queue throughout. The report, out/replay-<label>.json, holds the run's parts and wall times, the queue at the end, model usage, and the scoring.
rounds/recal/ scores the record against incidents_truth. matching.py matches a finding to a planted incident by kind, subject and overlapping time. metrics.py computes, for the replayed week and per kind: findings, true findings, precision, planted incidents, recall, the share handled without a person, actions undone, queue left at the end, mean time from visible to resolved, and the weakest detector. drift.py watches whether the model becomes less sure, more often invalid or more often undone.
scripts/sweep_detectors.py runs every detector over the week without the operator and scores it. It is the tuning tool, used on seeds 7 and 11; seed 23 is kept for the headline run.
7. Ask (rounds/ask/)
resolve.py maps a question to a term by name, synonyms and simple time phrases (timephrases.py), and to a department's variant if one is named. answer.py runs the definition and returns the number with its lineage: term, variant, version, owner, period, SQL and tables. A term with two meanings and no canonical one returns both, side by side; nothing picks between them. A question that matches no term is refused with suggestions. An optional model may map an unmatched question to a term name, and nothing more. what_changes.py previews which rows a parameter change would add or drop before anyone commits it.
8. The screens (app/)
A FastAPI app with Jinja templates and one small script. app/data.py is the only place the screens read: the world, the record, the dictionary and the replay report. app/board.py builds the day-board as of one moment.
- Day board (
/): one region's clinics as columns, 08:00 to 18:00 as rows. Each booking is a block placed in its clinic and hour and coloured by its state at that moment: booked, arrived, seen, no-show, cancelled late or early, filled from the waitlist today, or touched by the operator. Across the top, the results lane shows each clinic's abnormal and critical results still waiting for acknowledgement, with their age against the rule, a ring where the operator has handed one to the on-call doctor, and the count of specimens still in the lab. Receipts land in the clinic's column at the hour they were written; the rail lists the whole group's receipts and the group's numbers for the day. The region strip shows how many actions each region has had. - Play mode (
app/play.py,app/replay.py,static/board.js): the window is Monday 08:00 to 13:00. When the database holds a recorded run for the window, a replay clock runs over it at 20, 60 or 120 times real speed and the board reveals everything at its own time. On a fresh world, Play starts the operator on its own thread and connection, and its actions land as it takes them; a world insidedata/is never run live. The script polls the board while the clock runs and highlights receipts as they land. Clicking the timeline moves the clock. - Action record (
/ledger,/ledger/{id}): every row up to the play clock, filterable by kind and status, and one row in full with its evidence, call, tier, controller reason, sign-off and before-and-after. - Sign-off (
/queue): tier-2 items waiting for a person, with sign-off and turn-down buttons. - Accuracy (
/accuracy): the replay report's scoring and the answer key's counts in this database. - Definitions (
/definitions,/definitions/{term}): every term with its meanings, and the policy's actions. - Ask (
/ask): questions answered through the dictionary, both meanings shown where there are two. - Architecture, Known gaps and World: these documents.
The visitor's site arm (v, p) rides every same-site link, form and redirect (app/arm.py).
9. Running it
.venv/bin/python -m rounds.world.generate --seed 23 --out data/rounds-seed23.duckdb
cp data/rounds-seed23.duckdb out/rounds-seed23-replayed.duckdb
.venv/bin/python scripts/replay_window.py --db out/rounds-seed23-replayed.duckdb --history-days 6 \
--history-tick 300 --tick 30 --seed-label seed23
ROUNDS_DB=out/rounds-seed23-replayed.duckdb ROUNDS_REPLAY_JSON=out/replay-seed23.json \
.venv/bin/uvicorn app.main:app --port 8162
For live play, point ROUNDS_DB at a fresh copy of a world outside data/ and press Play on the day board. scripts/screenshot_all.py starts the app on port 8162, photographs every screen at 1440x900 into out/screens/ and stops it. pytest -q runs the tests: world determinism and incident counts, the controller refusing tier 3 and over-budget actions, undo, a replay on a short window, and every screen answering.