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.