diff --git a/BUILD-AI-CONTAINERS.md b/BUILD-AI-CONTAINERS.md index d13357d..d03c45a 100644 --- a/BUILD-AI-CONTAINERS.md +++ b/BUILD-AI-CONTAINERS.md @@ -239,6 +239,8 @@ Project lives in Forgejo (`git.yokogawa.tech`). Compose files stay in `~` per ho . ├── BUILD-AI-CONTAINERS.md # this file ├── CLAUDE.md # symlink or copy of the host onboarding brief +├── workflow-map.html # the plain-language explainer, for people who are +│ # not going to read this file ├── README.md # rebuild-from-zero ├── compose/ │ ├── ai-compose.yml # deployed to ~/ai-compose.yml diff --git a/README.md b/README.md index 6e7b8a7..50df30c 100644 --- a/README.md +++ b/README.md @@ -343,6 +343,8 @@ pytest api/tests # contracts, classifier rules, SQL allow-list. No netw ``` CLAUDE.md short rules — what Claude Code keeps front of mind +workflow-map.html the non-technical explainer — how a question becomes + an answer, and what is built. Open it in a browser BUILD-AI-CONTAINERS.md the build spec YAU_Linux_Host_Onboarding.md the host brief (reference; wins on conflict) compose/ deployed to ~/ai-compose.yml and ~/langfuse-compose.yml diff --git a/workflow-map.html b/workflow-map.html new file mode 100644 index 0000000..689d8a5 --- /dev/null +++ b/workflow-map.html @@ -0,0 +1,381 @@ + + +
+ + +Waterloo Road Pump Station. An operator types a question in plain English; the +assistant answers it from plant records and controlled documents, and shows its evidence. This page +follows one question through the assistant, names the piece of software doing each job, and marks +what already exists.
+Status as observed on the live host, 21 August 2026.
+ +Seven stages. The important thing to notice: the assistant decides what kind of +question it is before it looks anything up, and that decision fixes both which sources it may +use and what it is allowed to say.
+ +A web page with a question box and an answer pane, opened in an ordinary browser on the + control-room PC. Nothing to install.
+A small, fast AI model reads the question and labels it as one of four kinds — or says it is + unsure. It does no answering; it only labels. This is the most safety-relevant step in the + whole assistant, because the label decides everything downstream.
+Two rules are built in: if it is not confident, it asks the operator to rephrase rather than + guessing; and if two labels are close, it takes the more cautious one — a question that is + partly advice is treated as advice.
+Operators say “Pump 02” or “the wet well”. The plant records call + those PU-302 and WW-101. This step converts everyday names into the plant’s official + ones by looking them up in a list — no AI, no guessing. When it gets a name wrong, the fix is + to add the nickname to the list.
+“How many high level alarms last week?”
+Counts and measurements taken from the plant’s recorded history. If there are no + records, the answer says so — it never estimates a figure.
+“What does the level fault alarm mean?”
+Explains a signal, alarm or piece of equipment from the manuals and alarm records, quoting + the document it came from.
+“How do I lift the interlock on Pump 02?”
+Finds the approved procedure and identifies it — document number, revision, date — and + quotes its prerequisites word for word. It never writes the steps itself.
+“What discharge rate avoids a spill?”
+Shows what has been run before, what happened when, and the documented limits — then hands + the decision back to a competent person. It never gives a number as the answer.
+“Is the pump alright?”
+When the sorting step is not confident, the assistant stops and asks a clarifying question. + No sources are searched and no answer is drafted.
+The larger AI model is used here and only here: to put the gathered evidence into plain + English. It cannot go looking for anything else — it only sees what its lane collected. It + supplies wording, not facts.
+Every draft is checked against a fixed rulebook before the operator sees it: no invented + steps for safety-critical work, no recommended setpoint, nothing beyond the evidence actually + found, and every claim carrying its citation. A draft that fails is rewritten once and then + refused — it is never shown.
+These are ordinary software checks written in code, not instructions given to the AI. That + distinction is the point: an AI can be talked out of an instruction, and cannot be talked out + of a check.
+Beside the answer the operator sees how it was reached: which kind of question it was judged + to be, what data was counted and over what period, how many records were found, and which + documents were cited with their revision and date. Procedural and advisory answers carry a + visible banner stating plainly what the assistant did not do.
+Each question, the kind it was judged to be, the sources used, the rulebook result and how + long it took are all recorded, so any answer can be reviewed afterwards and any mistake traced + to the step that caused it.
+The assistant has no free access to anything. These four, and nothing else.
+ +Turns “high level alarms last week” into an exact query over the plant’s + recorded history. The definitions that make an answer right — what counts as an alarm, what + “last week” means, what counts as a fill — are written down in files an engineer can + read and check, instead of being invented per question. It also keeps ready-made summaries so + common questions never hammer the live historian.
+The assistant never writes database code itself. It fills in a request form; Cube does the + rest.
+Searches the controlled documents by meaning rather than keyword, so “lift the + interlock” finds the right procedure even when the document says “interlock + override”. Two rules are permanently on: withdrawn revisions are never returned, and every + result carries its document number, revision, date, page and section — a passage that cannot be + cited cannot be used.
+Every piece of equipment and every measurement point, with the everyday names operators + actually use. Deliberately a plain list rather than something the AI works out, so it behaves the + same way every time and can be corrected by editing one row.
+Not a source of answers — the record of them. Every question and every step it took is stored + so the assistant’s behaviour can be audited and improved from evidence rather than + impressions.
+Two supply lines feed those tools. Neither is finished.
+ +Procedures, manuals, alarm rationalisation and design documents are read, split into sections, + and converted into a searchable form. Three habits matter: a numbered step sequence is never cut + in half; the document’s type comes from the folder it was filed in, not from a guess; and + a person confirms the document number, revision and date before anything is stored. A wrong + revision on a procedure is a safety problem, not a tidiness one.
+The station’s control system records levels, pump runs and alarms into the plant + historian. The assistant reads that history through Cube — read-only, never writing to it, and + never touching the control system itself.
+Each step ends in a check that must pass before the next begins — so that when an +answer comes out wrong, there is one place to look, not four.
+ +| Step | What it delivers | Status | What it needs |
|---|---|---|---|
| 1 | The store — where documents, equipment names and ready-made summaries live | Running now | Done. Live, checks passed. |
| 2 | The logbook — recording of every question, put in early on purpose so every later experiment is traceable | Running now | Done. Live. |
| 3 | The documents — the real procedures and manuals, read in and searchable | Next up | The documents themselves, and someone to confirm each one’s revision and date. Needs nothing from the historian — which is why it goes next. |
| 4 | Access to plant history — a read-only login to the historian | Blocked | The historian server, a read-only login and agreed table names. The only true blocker — start that conversation now, alongside step 3. |
| 5 | Cube — the data translator, with every definition written down | Built, not switched on | Step 4 — though it can be proven on stand-in data first. An engineer must independently confirm its first numbers before anyone trusts them. |
| 6 | The assistant itself — the sorting step, the four lanes, the answer writer and the rulebook | Built, not switched on | Steps 3 and 5, so that a wrong answer can only be the assistant’s own fault. |
| 7 | The operator’s screen — the question box, the answer, the working | Built, not switched on | Step 6, plus one network name record so control-room PCs can reach it — ask for that early, it depends on someone else and will not surface as a problem until the day it is tried. |
| 8 | The exam — 62 engineer-checked questions run end to end and scored | Written, not run | Everything above. Pass mark: 85% correct overall, 95% on the two dangerous kinds, and zero breaches of the rulebook. |
Sign-in, network routing and hosting are handled by platform services already running +on the demo host. They are deliberately left off this map — they protect the assistant, but they are +not part of how it answers a question.
+ +