AI Playbooks New in 1.0.0
An operator asks "give me a recommendation about pump 2's condition". Without help the assistant improvises: it guesses the question is about tags, searches the namespace for "pump 2", reads whatever comes back, and may or may not think to check the alarms. It answers differently tomorrow.
A playbook is the engineer writing that procedure down once — read these tags, check these alarms, trend this, then present it like this — so every phrasing of the question gets the same complete answer.
What it is, and what it is not
A playbook is rendered into the assistant's instructions and followed by the model. It is deliberately not a pipeline: the operator's question is open-ended, and a fixed execution path cannot answer "why is it drifting" or "should I be worried".
So a playbook promises influence, not enforcement, and it is worth being blunt about that:
It cannot widen or narrow what an assistant may reach. The fences are the tag scope, the connection fence and the endpoint fence, enforced by the server on every call. → Skills & fences
An instruction in a playbook to read a tag outside the fence is not a hole — it is a step that fails. Which is why the playbook is reduced to the steps its instance can actually take before it is used, silently: an order to read something the fence will refuse cannot be recovered from, because the same instructions have just forbidden searching for an alternative.
For a figure that must be right every time there is a better tool — a compute specialist, which works its numbers out on the server. Playbooks are for the conversational middle.
Where the exact paths earn their place
The assistant is forbidden from guessing a tag path: it must search first and use what comes back verbatim, because a namespace may hold hundreds of thousands of tags and the obvious folder is usually the wrong one.
A playbook is the one place a path can be stated safely — an engineer picked it from the tag browser, so it is known-good. That makes the common questions both faster (no search round-trip) and more accurate (no near-miss tag).
Writing one
Playbooks are authored in the Designer and the pipeline editor, in their own pane, and saved with the project like any other resource.
| Field | What it is for |
|---|---|
| Name | What the model matches a question against. Write it like the question: Pump condition, not pump_pb_v2. |
| Asks | Alternative phrasings. The model generalises from them — two or three cover a question better than ten near-duplicates. |
| Roles | The runtime roles this procedure is for. Empty means everyone. |
| Steps | The procedure, in order. |
| Guidance | What to make of what the steps fetched, in your own words. |
| Answer as | How to present it. |
Roles are applicability, not permission
Naming a role hands that operator the procedure. It grants nothing — reach still comes from the role ceiling and the fences. So one pump screen can carry Pump condition for operators and Pump teardown for maintenance, and each person's assistant is given only the one that is theirs, instead of every procedure on the screen competing to match their question.
These are runtime roles from the project's bound user database — the same names a widget's required-roles list uses. A name no longer in that database simply never matches, which costs one procedure rather than the whole turn.
Steps
| Step | Fetches |
|---|---|
| Read tags | Exact tags, by path. Picked here, so the assistant never has to search. |
| Check alarms | What is alarming under a namespace path, right now. |
| Alarm history | What alarmed under a path over a window, and when. |
| Read relationships | The stored cause→consequence links around a tag. |
| Trend | One tag over a window, so the answer can say which way it is moving. |
| Read variables 1.0.8 | Gateway variables by exact name — a running counter, the current batch, a KPI — picked from the live store, up to 50. One that is not set is reported as not set, never guessed. |
| Search manuals | Look the topic up in the ingested documents, and cite it. |
| Run saved query | A saved query an engineer already wrote. Only read queries are listed. |
| Call external system | One named operation on a connected system — an ERP, a CMMS. |
| Read a file | One stored document — a spec sheet, a commissioning record, a CSV of setpoints. |
| Hand to a specialist | Give this part of the question to a saved specialist and use the answer it returns. For a figure the server must work out exactly, hand it to a compute specialist — see below. |
Alarm history and relationships are what make root-cause questions writable. The assistant's method for those is four steps — the alarms, the timeline ordered by raise time, the stored relationships, then the trends — and until those two step kinds existed, a playbook could express only the last of them and half of the first.
Relationships are ground truth an engineer rationalized, not an inference from timing, and the assistant is told to prefer them over anything it infers, and to mark a claim they support as fact rather than likely.
Every step carries a name, never a request. A step naming a query nobody saved, an operation nobody opened, or a specialist nobody created does not become a call — it becomes a step that is refused. And a file's contents are still treated as untrusted reference data, however the file is phrased.
Steps that run together New in 1.0.8
From the second step on, Together with step N marks a step as independent of the one above it. The two are then written as one numbered step — "do these together, in ONE turn" — so the assistant asks for both at once and they run in parallel, instead of costing a model round trip each. Use it for steps that do not need each other's answer, such as two specialists that each work from their own data.
Binding a query's parameters
A Run saved query or Call external system step can fill each declared parameter four ways:
| Mode | Where the value comes from |
|---|---|
| Fixed | A value you chose. |
| From the question | The operator's own words, resolved through the plant vocabulary by the parameter's declared meaning. |
| Window | A relative window the server computes — date arithmetic is the one thing a model must not do. |
| Ask | Tell the assistant to ask the operator rather than guess. |
From the question is named as a resolution, not "use what the user said": passing an operator's own words into a database filter is exactly the failure the plant vocabulary exists to prevent. An exact match is the answer; a probable or ambiguous one is a question to put back to the operator.
A binding left half-filled is dropped, not sent as an empty value — a query whose filter silently disappeared returns a superset that reads exactly like the answer.
Guidance
The steps say what to read; nothing else says what it means. 1180 is not an answer — "the
setpoint is 1150, and sustained drift above it risks coating" is. That judgement is the part an
engineer knows and a model guesses at.
Guidance is free text, unlike the steps, and deliberately so: a step has to be unambiguous enough to render as a tool call, whereas this is the sentence you would say to a new colleague.
It steers the answer and grants nothing. An instruction here to go and read another tag is a silent no-op, because no fence ever sees this text. Anything to fetch is a step.
Answer as
| Option | Renders |
|---|---|
| Short answer (default) | Plain prose stating the values read and where they came from. |
| Dashboard | An inline dashboard of stats, charts and tables. |
| Root cause | A causal graph, with each claim marked fact or likely. |
Exact figures — hand them to a compute specialist Changed in 1.0.8
Arithmetic is where a model's judgement is worth nothing and its reliability is worst: it eyeballs a series and does mental maths, and an alarm count it got wrong reads exactly like one it got right. So a figure an operator acts on should be calculated on the server and handed to the model to explain.
That is a compute specialist: named inputs — a tag, a trend, alarms, the alarm journal, a saved query, an external operation, stored relationships, a manual search, a stored file or a gateway variable — and a short Python function the server runs over them. A playbook reaches it with a Hand to a specialist step. The model can name the specialist and nothing else: its inputs and its code are loaded server-side, and every input is re-read with the same permissions and fences as if the assistant had read it by hand. → AI specialists
Naming a specialist in a step does not select it: each screen or AI node that follows the playbook must also have that specialist ticked. The playbook picker warns when a step names one that screen has not selected.
Removed in 1.0.8 Earlier versions had a Calculate a check step that worked a figure out from an expression, with its own Calculate playbook checks capability and Playbook Checks skill. All three are gone, and a converted check returns no figure until someone writes it again in Python.
When QUBIQ starts after the upgrade — and after a backup from an older version is restored — every saved check is converted into a draft compute specialist with the same inputs, carrying the original expression as a comment, and its step becomes a Hand to a specialist step in the same place. Nothing is dropped, and an input whose name cannot be a Python parameter is renamed. A draft is never offered to an assistant, so until it is finished that step cannot run. To finish one: write its calculation, test it, tick Available to assistants, and tick it on every screen and AI node that follows the playbook.
The originals and a conversion report, which names those screens and nodes, are kept in the project
beside the playbooks, in AIPlaybooks/.check-conversion-<time>.json. A Designer tab opened before
the conversion cannot save the old checks back over it. A step that is still a retired check shows
as Retired check in the editor and cannot be edited or added.
Worked example — pump condition
Name: Pump condition
Asks: how is pump 2 doing · should I be worried about P-102 · pump 2 condition
Roles: (empty — everyone)
Steps
1 Read tags Plant/Area2/PMP02/Amps
Plant/Area2/PMP02/SuctionPressure
Plant/Area2/PMP02/DischargePressure
2 Trend Plant/Area2/PMP02/Amps, the last 8 hours
3 Check alarms Plant/Area2/PMP02
4 Alarm history Plant/Area2, the last 24 hours
5 Hand to a specialist "pump-drift"
a compute specialist: amps = Trend Plant/Area2/PMP02/Amps,
last 8 hours; returns the average and whether it is above 41.5
Guidance
Nameplate is 40 A. Above 42 A sustained means the impeller is wearing or the
discharge is partly blocked — check the strainer before scheduling anything.
Suction below 0.8 bar with normal discharge is cavitation, which is a different
fault and more urgent.
Answer as: Short answer
The operator asks "how is pump 2 doing". The assistant reads three tags it never had to search for, trends one, checks what is alarming, looks at last night's journal, is handed one exact average by the specialist, and answers with the engineer's own interpretation attached.
Gotchas
- A name that reads like a filename never matches. The model matches questions against the name; write it as the question.
- Steps outside the fence vanish silently. Deliberately — naming a cut step would write an out-of-fence tag path into the assistant's instructions. If a playbook seems to be doing less than it says, check the instance's fences first.
- Guidance cannot fetch. If it says "also check the seal temperature", add a step.
- A specialist step cannot nest. A specialist reached this way cannot itself run a specialist.
- Only read queries are offered, and a mislabelled one is still refused at execution: the statement is validated, not the metadata's claim about it.