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 @@ + + + + + +WRPS Plant Assistant — Workflow Map + + + +
+ +

The plant assistant — how a question becomes an answer

+

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.

+ +
+ Running now + Built and tested, not yet switched on + Waiting on someone else + Not started +
+ +

1 · The question’s journey

+

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.

+ +
+ +
+
Ask
+
+

The question box Built, not switched on

+

A web page with a question box and an answer pane, opened in an ordinary browser on the + control-room PC. Nothing to install.

+
Application: ai-web — the operator’s screen
+
+
+
+ +
+
Sort
+
+

What kind of question is this? AI step + Built, not switched on

+

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.

+
Application: ai-api · the classifier, using a small AI model
+
+
+
+ +
+
Translate
+
+

What is “Pump 02”, exactly? Built, not switched on

+

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.

+
Application: ai-api · the name resolver, reading the equipment + and tag list in pg-ai
+
+
+
into one of four lanes — or back to the operator
+ +
+
+

Historical — what happened?

+

“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.

+
Looks in: Cube → the plant historian
+
+
+

Reference — what does this mean?

+

“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.

+
Looks in: document search + the equipment and tag list
+
+
+

Procedural — how do I do it?

+

“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.

+
Looks in: document search, procedures only
+
+
+

Advisory — what should we do?

+

“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.

+
Looks in: Cube and document search together
+
+
+

Unclear — I need more

+

“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.

+
Looks in: nothing — it asks instead
+
+
+
evidence gathered
+ +
+
Word it
+
+

Turn the evidence into a readable answer AI step + Built, not switched on

+

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.

+
Application: ai-api · the answer writer, using the larger AI model
+
+
+
+ +
+
Check
+
+

Is this answer allowed to leave? Built, not switched on

+

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.

+
Application: ai-api · the answer contracts and guardrails
+
+
+
+ +
+
Show
+
+

The answer, and its working Built, not switched on

+

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.

+
Application: ai-web · the “show working” panel
+
+
+
+ +
+
Record
+
+

Everything is written down Running now

+

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.

+
Application: Langfuse — the assistant’s logbook
+
+
+ +
+ +
Why four lanes instead of one clever assistant: the four kinds of +question need different sources, and — more importantly — different limits on what may be said. One +general-purpose pipeline answering all four is the main way a project like this hurts somebody: it +is how a bypass procedure gets reassembled from fragments nobody approved, or a setpoint gets +suggested and typed into a control system. The assistant cannot wander between lanes, because the +lane is fixed before any searching starts.
+ +

2 · The four tools it can reach for

+

The assistant has no free access to anything. These four, and nothing else.

+ +
+
+

Cube — the data translator Waiting on the historian

+

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.

+
Reads: the imh plant historian, read-only. Definitions live in + cube/model/ — alarms, process values, operations, equipment.
+
+ +
+

Document search No documents loaded yet

+

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.

+
Reads: document sections stored in pg-ai
+
+ +
+

The name list Built, loaded

+

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.

+
Reads: the equipment and tag tables in pg-ai
+
+ +
+

The logbook Running now

+

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.

+
Application: Langfuse
+
+
+ +

3 · Where the knowledge comes from

+

Two supply lines feed those tools. Neither is finished.

+ +
+
+

Documents in Not started

+

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.

+
Application: ai-ingest, run by hand when documents change → stored + in pg-ai. Written and tested; no documents loaded onto the host yet.
+
+ +
+

Plant history in Waiting on someone else

+

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.

+
Source: the imh historian. That server is still being built, so a + read-only login and the agreed table names are still outstanding.
+
+
+ +
Worth knowing: until the real historian is available, the data lanes run on +stand-in figures. Every answer produced that way carries a warning label all the way to the +operator’s screen, so it cannot be mistaken for a real plant number.
+ +

4 · What exists, and the order the rest gets built

+

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.

+ +
+ + + + + + + + + + + + +
StepWhat it deliversStatusWhat it needs
1The store — where documents, equipment names and ready-made summaries liveRunning nowDone. Live, checks passed.
2The logbook — recording of every question, put in early on purpose so every later experiment is traceableRunning nowDone. Live.
3The documents — the real procedures and manuals, read in and searchableNext upThe documents themselves, and someone to confirm each one’s revision and date. Needs nothing from the historian — which is why it goes next.
4Access to plant history — a read-only login to the historianBlockedThe historian server, a read-only login and agreed table names. The only true blocker — start that conversation now, alongside step 3.
5Cube — the data translator, with every definition written downBuilt, not switched onStep 4 — though it can be proven on stand-in data first. An engineer must independently confirm its first numbers before anyone trusts them.
6The assistant itself — the sorting step, the four lanes, the answer writer and the rulebookBuilt, not switched onSteps 3 and 5, so that a wrong answer can only be the assistant’s own fault.
7The operator’s screen — the question box, the answer, the workingBuilt, not switched onStep 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.
8The exam — 62 engineer-checked questions run end to end and scoredWritten, not runEverything above. Pass mark: 85% correct overall, 95% on the two dangerous kinds, and zero breaches of the rulebook.
+
+ +

5 · The short version

+ + +

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.

+ +
+ +