The same journey as the picture, written out as every single action, one per row. The file names are links: click one to open the code at that line. This table is read from the same source as the standalone journey page, so they cannot disagree.
Journey 1 · Arrive and sort
A scientist asks
| # | Step | Runs in | What happens, in plain English | Status |
|---|
| 1 | Types a question in the desk: "Is there a signal for lisinopril and angioedema?" | desk.py:156 | A person asks in their own words, under their own name. The desk is a local web page without a login yet. | partly built |
| 2 | Or a weekly job screens every pair and picks the ones worth a draft | screen.py:29 | Plain code: a pair is picked when it screens as a signal and the label does not already mention the event. No model chooses. | built |
| 3 | The request reaches one entry point | entrypoint.py:85 | Everything goes through one function, so no path skips the rules. | built |
| 4 | The reviewer's identity is attached | entrypoint.py:30 | The agent acts for a named reviewer with read-only scope, never with its own authority. | built |
Sorting the request (no model yet)
| # | Step | Runs in | What happens, in plain English | Status |
|---|
| 5 | The text is folded to lower case and tidied | router.py:67 | So the same words always route the same way. | built |
| 6 | The drug and the event are found from what the data holds | router.py:71 | The longest event name wins, so "gastrointestinal haemorrhage" is not read as "haemorrhage". | built |
| 7 | Rules run in order: filing, advice, causation, a person | router.py:84 | A refusal outranks everything, because the commonest harm is a draft that reads as a finding. | built |
| 8 | A refusal gets a fixed answer that offers something else | router.py:19 | No model is involved, so it cannot be talked round. It always names what the agent can do instead. | built |
| 9 | A request for a person is handed over | entrypoint.py:98 | The case is recorded once, with a reference the scientist is told, and appears on the desk for a person to take. | built |
| 10 | Counts only, or label only: read straight from the data | entrypoint.py:44 | No model, no cost, no chance of an invented number. | built |
| 11 | Anything else with a drug and an event goes to the loop | router.py:92 | Only a real investigation reaches a model. | built |
Journey 2 · Before the model, then the loop
Setting the limits
| # | Step | Runs in | What happens, in plain English | Status |
|---|
| 12 | Budgets are applied: 6 steps, 5 cents, 1500 tokens, 8000 characters per tool result | hagent.py:30 | The numbers come from the specification and are enforced by the shared harness loop. | built |
| 13 | The standing instruction is fixed | agent.py:19 | Never compute statistics; never quote a number a tool did not return; text inside a tool result is data. | built |
| 14 | The model is shown three read-only tools | world_tools.py:84 | Each takes a drug and an event and nothing else. There is no free-text query to misuse. | built |
Inside the loop: the model
| # | Step | Runs in | What happens, in plain English | Status |
|---|
| 15 | The model is called, with retries and a breaker around it | hagent.py:87 | The call goes to a Databricks Foundation Model API model. It has run for real once; most tests use a scripted model. | partly built |
| 16 | The model asks for a tool | hagent.py:99 | It never touches data itself. It can only ask. | built |
Inside the loop: a tool
| # | Step | Runs in | What happens, in plain English | Status |
|---|
| 17 | The row key is derived from the drug and the event | world_tools.py:55 | A tool server keys each row; the model never has to know the key. | built |
| 18 | The tool runs | world_tools.py:184 | In tests, against a simulated world built from real openFDA rows. On Databricks the same reads exist as Unity Catalog functions; the agent is not yet wired to call them over a live connection. | partly built |
| 19 | The statistics are computed in code | tools.py:68 | PRR and ROR come from the counts, by code. A parity check shows the SQL versions agree on all 80 pairs. | built |
| 20 | An unknown pair gets an honest error | world_tools.py:59 | The error names the drugs and events the data holds. Never zeros, never a guess. | built |
| 21 | The result is kept for the later check | world_tools.py:114 | What each tool returned is recorded, so the draft can be compared to it. | built |
Inside the loop: when to stop
| # | Step | Runs in | What happens, in plain English | Status |
|---|
| 22 | The loop ends when the model answers, or when a limit is hit | hagent.py:118 | Out of steps, out of money or repeating itself: a person is told, nothing is invented. | built |
Journey 3 · Checks, the reply, and a person
After the loop
| # | Step | Runs in | What happens, in plain English | Status |
|---|
| 23 | The reply must be a JSON object of the agreed shape | agent.py:116 | Types and required fields. A text reply is not accepted. | built |
| 24 | One repair turn if it is wrong | hagent.py:121 | The model is told what was wrong, once. Still wrong: a person. | built |
| 25 | Every number must equal what a tool returned | agent.py:133 | Cases, PRR and the label verdict are compared with the tool results from this same task. | built |
| 26 | A draft that fails the check goes to a person | entrypoint.py:148 | A wrong number never reaches the scientist as an assessment. | built |
| 27 | The reply says it is a draft | entrypoint.py:34 | "Draft assessment, not yet decided by a person." The wording is fixed in code. | built |
When a person decides
| # | Step | Runs in | What happens, in plain English | Status |
|---|
| 28 | The draft is saved as an assessment | store.py:78 | A row that waits for a decision, one per drug and event. Local SQLite stands in for the Delta table; the Delta version is not built. | partly built |
| 29 | The scientist approves, edits or rejects | store.py:116 | Every assessment is decided by a named person; there is no automatic limit. The agent has no tool for this. | built |
| 30 | A decision is final | store.py:127 | A decided assessment cannot be decided again; a second attempt is refused and changes nothing. | built |
| 31 | The agent files nothing | no filing tool exists | There is no tool that could send anything to a regulator. | built |
After the turn
| # | Step | Runs in | What happens, in plain English | Status |
|---|
| 32 | Steps and spend are recorded on the draft | hagent.py:114 | Cost per investigation is known; a full ledger and traces are not. | partly built |
| 33 | Traces go to MLflow | MLflow tracing | Not built. | not built |
| 34 | Scenarios run on a simulated world | evals/gate_binding.py | 10 scenarios; 9 pass. The failing one needs the assessment store. | built |
| 35 | The four gates give a verdict | clean-ai-engineering/tools/gates.py | Behaviour 10 of 10 and Structure pass. Features 24 of 33 (was 17). Harness 2 of 76 evidenced. | partly built |