cnx_vinyl/docs/plant-assistant.md

# Plant Assistant: Ask the Plant

Decided (Alexander, 26 October 2026): **the plant gets an agent that
management and operators can ask**, which reads the plant's knowledge
base and its data and gives insight into the process. This document plans
it on the systems of the [digital factory](digital-factory.md): ERPNext as
the system of record, the machine-data store, the factory application and
the NixOS fleet. It is a planning position; every figure without a source
is an estimate.

## In one paragraph

One assistant for the whole plant, asked in Thai or English at a press
kiosk, at a desk or on a phone. It answers from two places: **the
knowledge base** (procedures, vendor manuals, safety rules, this planning
repository) and **the records and data** (ERPNext documents, press cycles,
inspection results, time series, alarms). Every answer names its sources;
every number comes from a query it shows. It sees only what the person
asking may see, it can draft but never submit a record, and it never
touches a machine. It runs on site on an open-weights model, so it works
when the internet does not.

## Who asks what

| Who | Typical questions | What it uses | Where |
|---|---|---|---|
| Press operator | "What is the band for the mould temperature at 180 g on the Classic?" "Non-fill rejects since 14:00, what changed?" "Show me the stamper change steps for the HRP 12." "Is compound lot L-0412 released?" | Quality Procedures (the SOPs), the recipe and inspection templates, the press's cycle rows and zone environment, the lot's Quality Inspection | press kiosk, Thai first, the station and job card already known |
| Shift lead | "Handover: what happened on the last shift?" "Which stampers are near retirement?" "Downtime by reason this week." | job cards, downtime entries, stamper serial numbers and play counts, open holds, alarms | kiosk, office |
| QC engineer | "Trace the record with this sleeve code." "Compare today's run of this title with the last repress." "Audio score against play count for stamper S-1187." | the record key's chain (cycle, stamper, mother, lot, environment) per [traceability](traceability.md), inspection results, audio scores | office |
| Maintenance | "Alarm history of boiler B-1 this month." "Hours since the last oil change on the Duplex hydraulics?" "Page of the manual for the chiller's low-pressure fault." "Is the seal kit in stock?" | alarm history, run hours, ERPNext Asset Maintenance and stock, the vendor manuals attached to the Asset | workshop kiosk, phone |
| Cutting and galvanics | "Current density in cell 2 over the last father." "Which mothers of POY013 have sets left?" | rectifier and bath series, metal-part serial numbers | room kiosks |
| Management | "Yield and effectiveness per press this week, and why the Classic dropped." "Energy per record against the plan." "Orders at risk of missing their date." "Which gates are waiting on customers?" | ERPNext reports, the machine-data store, the design figures in this repository | office, phone |
| Customer service | "Where is order SO-0231, and when will it ship?" | the same records the customer portal shows | office |
| New staff and trainees | "Why must labels be dried before pressing?" | procedures and the training material, never live customer data | training mode |

## What it knows

### The knowledge base: what should happen, and why

| Source | Where it lives | Notes |
|---|---|---|
| Procedures and work instructions (SOPs), safety procedures, emergency steps | ERPNext **Quality Procedure** documents: structured, nested steps, versioned; a **Non Conformance** links to the procedure it breaks and a **Quality Action** carries the fix ([ERPNext docs](https://docs.frappe.io/erpnext/user/manual/en/non-conformance)) | the SOPs are written into ERPNext during commissioning, not kept as loose files |
| Vendor manuals, datasheets, site requirements | attached to the ERPNext **Asset** (each press, boiler, chiller, lathe, cell) and Item | the vendor PDFs already filed under `docs/equipment/` are the first ones |
| Recipes and limits | Item, BOM and Quality Inspection Templates (parameters and limits from [quality automation](quality-automation.md)) | |
| Why the plant is built as it is | this planning repository, indexed from git | utility sizing, the metal archive, the QC layers, the decisions and their dates |
| Lessons learned | Non Conformance and Quality Review records with their actions | |
| Thai and English terms | a glossary document (stamper, mother, non-fill, flash, run-out) | keeps the Thai answers consistent |

Only **approved, current** versions are indexed. Superseded versions stay
available for "what did the procedure say on 3 March?", marked as
superseded.

**Tacit knowledge is the part worth catching.** P-Vine's pressing staff
describe a room that changes every day with the weather despite air
conditioning, so the settings (boiler temperature, a few seconds more or
less of press time) are adjusted daily by feel
([ele-king, VGAP interview](https://www.ele-king.net/vga/vga_column/011864/);
[BRUTUS](https://brutus.jp/en/post-430468/)). Here every adjustment is a
logged event next to the zone environment, so the assistant can answer
"last time the press hall was this humid, what did the operator change,
and did the rejects fall?" from the data, and a question nobody could
answer goes to the shift lead as an ERPNext ToDo; the expert's answer,
once approved, becomes a procedure note. The knowledge base grows from
the floor's own questions.

### The records and data: what did happen

- **ERPNext**: work orders, job cards, batches, quality inspections,
  metal-part serial numbers and their genealogy, downtime entries, stock,
  sales orders, gates, deliveries, assets and maintenance
  ([who owns what](digital-factory.md#who-owns-what)).
- **Machine-data store**: press cycles, per-record optical results, audio
  scores, packaging scans and the hash-chained event log in PostgreSQL;
  1 Hz machine tags, zone environment, energy and water in VictoriaMetrics
  ([design decision 2](digital-factory.md#design-decisions)).
- **Alarms**: vmalert and Alertmanager history.

## What it does with it

1. **Answers with sources**: the procedure step and its version, the
   ERPNext document names, the query and time window behind a number.
2. **Explains a number**: yield down this week is broken down by press,
   title, stamper, compound lot, shift and zone environment. What moves
   together is reported as a correlation, never as the cause.
3. **Traces**: from a sleeve code or a complaint back through cycle,
   stamper, mother, lot and environment, in one answer.
4. **Summarises**: a handover note at each shift start (open holds,
   stampers near the end of their life, lots on hold, excursions,
   downtime), a daily plant note and a weekly management note.
5. **Adds context to alerts**: when vmalert fires, the alert still goes
   out through Alertmanager unchanged; the assistant follows it with what
   changed in the half hour before (lot start, stamper change, humidity,
   a neighbouring alarm).
6. **Compares against the plan**: actual cycle times, steam and energy per
   record, reject rates and repress lead times against the figures in
   this repository ([scale](scale.md),
   [production timeline](production-timeline.md)), so the plan learns
   from the plant.
7. **Drafts records**: a Non Conformance, a maintenance request, a
   ToDo, a revision of a Quality Procedure. A person reviews and submits.

## What it never does

- **Touches a machine.** No writes to a PLC, an instrument, a recipe or a
  setpoint; the data platform is read-only toward machines
  ([design decision 4](digital-factory.md#design-decisions)).
- **Submits a record.** Drafts only; the person asking submits.
- **Improvises on safety.** For lockout, steam and boilers, hydraulics,
  galvanics chemistry, the crane and electrical work it quotes the
  approved procedure word for word with its version and names the
  responsible person. With no approved procedure it says so and stops. It
  is not an alarm and not an emergency channel
  ([worker safety](worker-safety.md)).
- **Sees more than the asker.** Every tool call runs with the asker's
  ERPNext role: an operator sees the job, not the customer's price;
  customer service sees orders, not payroll. The client audio vault and
  customers' artwork are never indexed. Questions that must be refused
  are part of the test set below.
- **Answers from memory.** A figure without a query or a document behind
  it is not given; missing data is said to be missing.
- **Rates people.** Operators' questions are logged to improve the
  answers and the procedures, not to assess the operator; that goes into
  the staff policy, and the logs are kept for a limited time (staff are
  data subjects under the PDPA).
- **Needs the internet.** Model, index and tools all run on site
  ([design decision 8](digital-factory.md#design-decisions)).

## How it is built

- **Model.** Open weights, Thai and English, **self-hosted on premises**
  (decided October 2026; no hosted AI service). The first
  candidate is **Typhoon 2.5** from SCB 10X, a Thai fine-tune of
  Qwen3-30B-A3B for Thai and English with a 256K context, Apache-2.0
  ([model card](https://huggingface.co/typhoon-ai/typhoon2.5-qwen3-30b-a3b),
  checked October 2026), with a 4B sibling for quick kiosk answers. It
  is a mixture-of-experts model with about 3B parameters active per
  token, so it may run usefully on a CPU server before any GPU is bought
  (to be measured). The choice is made on our own test set, not on
  published benchmarks.
- **Serving.** llama.cpp or vLLM as a NixOS service on the clan, like
  every other plant service.
- **Speech, optional.** **Typhoon ASR Real-time**: open-source streaming
  Thai speech recognition that runs on CPUs, Apache-2.0
  ([model](https://huggingface.co/typhoon-ai/typhoon-asr-realtime),
  [code](https://github.com/scb-10x/typhoon-asr)). Its authors name
  background noise and Thai-English code-switching as weaknesses, both of
  which the press hall has, so push-to-talk with a headset and a test on
  the floor come before any promise.
- **Retrieval.** Document chunks with embeddings in PostgreSQL with
  pgvector on `vinyl-core`, rebuilt from the sources (Quality Procedures
  and attachments in ERPNext, the repository). Derived and rebuildable;
  no business records.
- **Tools.** Exposed to the model over the Model Context Protocol, each
  a thin wrapper in `cnx-factory`:
  - ERPNext through the existing integration client, read as the asker,
    create drafts only;
  - SQL on the machine-data store through the **PostgreSQL streaming
    replica on `vinyl-backup`**, read-only with row and time limits, so a
    heavy question never slows the floor;
  - PromQL on VictoriaMetrics' read API;
  - document search, the event log and alarm history.

  An open-source MCP app for ERPNext exists (Frappe Assistant Core,
  AGPL-3.0); it runs inside Frappe as a second way into ERPNext, which the
  rule of one integration layer
  ([how every tool interacts](digital-factory.md#how-every-tool-interacts-with-it))
  does not allow, so its ideas are reused and the tools stay in
  `cnx-factory`.
- **Front ends.** An "Ask" panel in the factory application: on the
  station kiosks with the station, job card and the operator's language
  filled in, on office desktops, and on phones over the mesh. Same badge
  and sign-on identity as everything else.
- **Machine.** `vinyl-ai` in the IT room: one server with a 32 GB GPU.
  An RTX 5090 32 GB sells in Thailand for about 203,000 to 209,000 THB
  ([Advice](https://www.advice.co.th/product/graphic-card-vga-/nvidia-5000-series/vga-asus-geforce-rtx-5090-rog-astral-gaming-32gb-gddr7);
  JIB via [BigGo](https://biggo.co.th/s/rtx%205090%2032gb); October 2026), so the server is roughly 250,000
  to 300,000 THB (~7,500 to 9,000 USD, estimate). The cheaper start is
  CPU-only on the dev trio and then on `vinyl-core`, with the GPU bought
  only if answers are too slow for the kiosks.

## Keeping it right

- **A test set per role**, in Thai and English: questions with known
  answers from the procedures and from recorded history, plus questions
  it must refuse (another customer's order, payroll, a safety step with
  no approved procedure). It runs on every change of model, index or
  tool, and nothing is deployed that fails it, the same rule as an
  ERPNext upgrade.
- **Feedback** on every answer; wrong answers are reviewed weekly by the
  QC lead, and the fix goes into the source (the procedure, the glossary,
  the data), not into a prompt.
- **Measures**: share of answers with a source, share of questions it
  could not answer, time to answer, use per role, incidents where it was
  wrong.
- **Owners**: the automation and IT engineer the digital factory plan
  adds to the headcount runs it; the QC lead owns the content.

## Phasing

| Roadmap phase | Step |
|---|---|
| 0 to 1, now | Prototype on the dev trio over this planning repository: the team asks the plan ("how much steam does the launch plant need, and why?") in Thai and English, CPU-only; the test-set habit starts here |
| 3, build | SOPs written as Quality Procedures during commissioning (vendor training sessions recorded and transcribed into procedures), manuals attached to the Assets; assistant v1 on documents and ERPNext records; `vinyl-ai` installed if the CPU trial says so |
| 4, launch | "Ask" on the kiosks with station context; machine-data and alarm tools; shift handover notes; alert context |
| 5, expand | Voice at the presses if the floor test passes; galvanics and audio QC data; the same software as the catalogue company's advisor, its own instance on its own hardware ([own catalogue](catalogue-intelligence.md)); offered with the open plant stack to other plants ([digital factory](digital-factory.md#open-source-throughout-and-working-with-other-plants)) |

## Rough cost (estimates)

| Item | Estimate |
|---|---|
| `vinyl-ai` server with one 32 GB GPU | 250,000 to 300,000 THB (~7,500 to 9,000 USD); none while CPU-only |
| Tools, retrieval and the "Ask" panel in `cnx-factory` | 2 to 3 person-months |
| Test set and evaluation harness | 0.5 person-month, then part of the IT role |
| Speech at the kiosks | 0.5 person-month plus headsets |
| Writing the SOPs into ERPNext | part of commissioning and training, not IT time |

Not in the [digital factory](digital-factory.md#rough-cost) hardware total
or in the [total investment](finance/total-investment.md).

## Risks

- **A confident wrong answer.** Sources on every answer, no source no
  answer, and the safety quoting rule carry most of it; the test set
  catches the rest before a release.
- **Stale procedures.** Only approved versions are indexed, and every
  answer shows the version and date.
- **Training replaced by asking.** It supports training; training and
  sign-off stay with the supervisors and the safety programme.
- **Noise and gloves.** Voice is optional and tested on the floor first;
  the touch panel always works.
- **Leaks across customers.** Permissions per asker, refusals in the test
  set, and no customer audio or artwork in the index.

## Open decisions

1. **Model**: Typhoon 2.5 or another open model, chosen on the test set.
2. **Hardware**: CPU first and a GPU only if needed (recommended), or
   `vinyl-ai` from the build.
3. **Voice** at the presses, after a floor test.
4. **Web search** for management questions through a fleet-hosted search,
   or none: the assistant stays on plant data and the repository.
5. **Log retention** for questions and answers.
6. **Name** on the kiosks.