This project starts with process rules supplied by a manufacturing expert, turns those rules into consistent synthetic records, and gives an agent a small set of read-only calculation tools. The language model may decide what to inspect. It never owns the math, SQL permissions, charts, or production actions.
Quick start
- Pick a production day in the scope bar (3 August – 30 September 2026; the ‹ › steppers skip weekends) and leave Agent mode on Offline / free for deterministic analysis.
- For a daily investigation, set Period to Day, pick Shift 1, 2 or 3 and use an example question from the Speed, Downtime, Waste, Compare or Orders group. Choose All shifts before asking for a comparison between shifts.
- Read the scope sentence under the bar: it says exactly which window, which shifts and which comparison the next question will use, and when a comparison is withheld because nothing earlier exists.
- For a calendar, set Period to Week, Month or 4-4-5 and build the report. September 29 demonstrates a partially available accounting period.
- Read the KPI tile strip: each delta chip is colored by the tool's own better / worse / same / neutral label and reads "withheld" when the comparison is incomplete. Then hover, focus or click a numbered day for its evidence. A click shows details; it does not open a daily investigation.
- Open the tool trail ("How the agent got here" or "How these tiles were produced"): one row per tool call with arguments, row count, coverage and timing, and the exact SQL with bound values behind it. The bad-trim toggle sits under Advanced. All records are synthetic.
How this is built
The full walkthrough, in pipeline order, is How this is built in the repository. The pipeline in five steps:
- Records from a seed. One seed produces two months (August and September 2026) of four record families shaped like a corrugator's own records: dry-end setups, wet ends, shifts and stops. Same seed, byte-identical files, one content hash. Three stories are planted; their answer keys are read by the generator only.
- Invariants, each with a test. Gross area equals lineal feet times web width; knives share travel; wet-end and shift totals are exact sums of their setups; setups tile every shift with no gap; stops sit inside one setup and never overlap.
- A store and bounded tools. The records load once into an in-memory database. Nine daily tools and six period tools answer fixed, parameterized queries; every percentage is a ratio of sums over the window, never an average of averages, and each tile says which direction is better.
- A planner that only chooses. The offline rule-based planner, or Anthropic with the server's key, or your OpenAI key, picks the next permitted tool. Application code validates every call, owns the math, bounds calls, time and spend, and keeps the trail.
- A golden set that owns the truth. Expected numbers are computed a second way, by plain sums over the record families, and stamped with the dataset hash; investigation cases find the seeded stories and may not assert a cause the evidence lacks.
1. Define the process before the prompt
A production day runs from 07:00 to 07:00. Each shift lasts 480 minutes. A dry-end setup changes when either knife's order combination changes. A paper change is the same thing as a wet-end run and can contain one or more dry-end setups. The fixture varies that relationship; it does not force every paper run to contain two setups.
Targets are explicit simulation settings. Speed is measured over elapsed time, including downtime. Maintenance and operator downtime are each compared with a 2.5% shift target. Trim above 3.25% per setup and dry-end waste above 1% are flags. Recorded reasons and notes are observations, not proof of a mechanical cause.
2. Make records reconcile
Each synthetic setup has timestamps, a wet-end ID, grade, paper width, one or two active knife assignments, lineal travel, gross square feet, and recorded waste. Both knives must reconcile to the same machine travel. Rejected sheets convert to area as sheets x width x length / 144. Invalid values remain visible as data-quality errors and are excluded instead of silently corrected.
Mock sheet widths span 12–60 inches and lengths 20–92 inches. Demand determines cuts, outs and shared travel; speed and stops determine elapsed time. Orders + quantities shows requested/planned demand, produced sheets, surplus and remaining quantities. Continuing orders keep their grade and dimensions across shifts. Produced sheets include rejects, so this is not an accepted-delivery ledger.
3. Give the agent bounded tools
| Tool | Purpose |
|---|---|
| Shift KPIs | Output, grade-weighted speed attainment, downtime, waste, throughput, setup count and paper-change count. |
| Downtime breakdown | Group recorded stops by approved kind, place or reason. |
| Wet-end performance | Compare every paper run with its grade target using elapsed time. |
| Setup matrix | Show start/end, grade, stops and interval-allocated downtime for each setup. |
| Rankings and notes | Rank one named measure at a time and expose reported context without treating text as an instruction. |
The application exposes fixed, parameterized database queries. There is no arbitrary SQL, shell, file browser, email, or machine-control tool.
4. Run the loop
- The user chooses a production day, a period and a shift (or All shifts) in the scope bar; the scope sentence reads it back.
- The planner requests one permitted tool.
- Application code validates the tool, arguments, scope, time, and call budget.
- The tool calculates structured evidence and source IDs.
- The planner may request another tool or finish with successful evidence IDs.
- Trusted application code formats the numbers and renders charts from the same rows.
The Shift selection is authoritative. A prompt or model call cannot silently query another shift. Offline mode demonstrates the loop without API cost. OpenAI and Anthropic modes may choose tools, but they cannot alter calculations. Every tool call appears as a row in the trail with its arguments, row count, coverage and timing.
“How can we be better?” needs a measurable goal
An OpenAI key helps choose which evidence to inspect. It does not add missing plant knowledge. Daily OpenAI mode selects tools and adds a short model interpretation above the calculated evidence. It labels findings, hypotheses, checks and limitations. Referenced values are inserted by application code. Reference checks do not prove that the interpretation is correct. Summary + charts covers speed, downtime and waste, with three supporting charts per included shift. Start with a selected day and shift, then ask which downtime reasons took the most minutes, which runs missed their grade targets, or which reject reasons contributed the most square feet. The example buttons support these investigations in free offline mode.
Read results as a recorded finding, a question to investigate, and something a person must verify. A large knife-jam total suggests reviewing those events with the crew; it does not prove a worn part or justify changing machine settings. Notes describe reported observations. Target gaps are not guaranteed recoverable output. Costs, profitability, intervention outcomes and live machine state are unavailable, so this tool cannot establish the best plant-wide improvement or promise savings.
If an answer is unavailable or misses your intent, narrow the question and inspect the evidence trace. “Complete” means the investigation finished, not that it proved a cause. Model tool selection can still be unhelpful; live question quality has not yet been validated with a real key.
5. Read periods and the heatmap
Check the scope: Shift 1, 2 or 3 means eight hours per date; All shifts means 24 hours. The KPI tile strip shows the window's tiles against the previous window; a chip reading "withheld" means a window is incomplete or unavailable, never that the value is zero. The quantity-driven fixture averages about 181 setup records per day across the demo month. A continuing setup appears in both shift records when it crosses a boundary. At a fixed 98-inch width, 1.8 million gross square feet corresponds to about 220,408 lineal feet; estimated-good output additionally deducts waste. Do not interpret a selected-shift cell as a full-day total.
The period report aggregates daily validated results. Calendar month follows ordinary month boundaries. The 4-4-5 view uses repeating 4-week, 4-week, and 5-week accounting periods. This demo assumes the accounting year begins September 1, 2026; a real deployment must replace that with the plant's confirmed fiscal anchor.
Heatmap density represents estimated good square feet: gross area minus recorded trim, shear, and dry-end rejects. It is useful for comparing days, but it is not a customer-acceptance claim. Hover or keyboard-focus a day to read gross and estimated-good output, speed attainment, downtime, waste, paper changes, setup count, and the largest recorded downtime contributor. Missing days are hatched and never treated as zero.
Colors scale from the lowest to highest estimated-good output among available days in this report. The same shade can mean different output in another report. Darker means more output, not better efficiency or proven improvement. Equal-output days intentionally have equal shading.
6. Understand the safety boundary
All displayed production data is synthetic. Notes are escaped as text and cannot expand permissions. Reports are generated from retained evidence, not visitor HTML. The local server accepts bounded JSON, limits requests, validates origin and session tokens, and keeps model spending bounded. These controls teach the right architecture; public deployment still needs real identity, durable rate limits, centralized budgets, monitoring, and a production-grade web server.
7. Evaluate it
Known-answer tests verify area math, speed weighting, stop overlap, setup/paper-run counts, ranking direction, bad-value exclusion, scope escapes, week comparisons, period boundaries, PDF access, and chart data. A useful agent is one whose answer can be traced to evidence and whose unavailable data stays unavailable.
Limits and recovery
- If the model narrative fails or exhausts its budget, the calculated evidence and charts remain available. Repeating a live request can incur another charge.
- Complete means evidence retrieval ended; it does not certify the model’s interpretation or prove a cause. Unsupported profitability, savings and optimal-intervention questions still require additional evidence.
- Order sampling, exact cutoff alignment and reject replacement behavior remain simulation limitations. Days are independent scenarios; unfinished quantities carry across shifts within a day.
- Period PDFs now export successfully in regression tests. They contain summary evidence tables; full visual layout review is still pending. Save text preserves narrative sections.
The repository README links how this is built, detailed how-to instructions, calculation formulas, troubleshooting, testing, the review findings and deployment requirements. The implementation follow-up records completed repairs and remaining calibration and live-evaluation work.
Current limitation: the demo contains August and September 2026 of one synthetic machine, Monday to Friday. The 4-4-5 start date, plant timezone, daylight-saving behavior, and synthetic scenario mix still require owner confirmation or broader calibration before this represents a real plant.