Runs, steps, agents and tools
The four objects the whole platform is built from, and how a goal becomes an executed step graph.
Documentation
Everything needed to run, extend and audit the platform.
Written for the two people who actually have to live with it: the process engineer who owns the loop and the automation engineer who owns the DCS. No marketing language past this point.
Live example: Grade change PM4 · 135 gsm kraftliner → 110 gsm testliner, no break, ≤14 min off-spec
Getting started
First hour
Enough to have a shadow-mode agent watching a machine.
Appliance and network
Rack, power, network segmentation, camera synchronisation and the OT firewall rules Pulpum needs.
QCS, DCS, MES, vision
Tag mapping, scan alignment, historian backfill and how to validate that time alignment is actually correct.
Watching without writing
Running agents against live data with all writes disabled, and how to review what they would have done.
Advisory in the HMI
Surfacing agent recommendations to the crew and capturing acceptance and rejection as training signal.
Supervised autonomy
Defining the tag allow-list, setting limits, and the approval flow for a supervised write.
Developers
Define an agent, bound it, run it
The Pulpum SDK is typed Python. Tools are declared with schemas and limits; the policy engine enforces them at call time — not in a review meeting.
What you get
- Typed tool definitions with unit-aware ranges and rate limits
- Deterministic replay of any historical run against a new model
- Local twin harness so a recipe is simulated before it is shipped
- Autonomy policy as code, versioned and reviewed like any other change
# Bound the dryer agent to six steam groups on PM4.
from pulpum import Agent, Tool, Limit, Autonomy
steam = Tool(
name="dcs.steam_schedule",
tags=["PM4.DRY.G1..G6.PRESS_SP"],
limits=[Limit(max_step="0.15 bar", per="30s")],
)
dryer = Agent(
id="agent.dry_coat",
goal="reel moisture 7.4% +/-0.5, min steam",
tools=[steam, Tool("qcs.read_moisture", read_only=True)],
# bounded writes; humans still gate ramps
autonomy=Autonomy.L3,
# simulate on the twin before every write
verify="twin",
)
run = dryer.start(machine="PM4", grade="TL-110")
for step in run.stream():
print(step.name, step.status, step.duration)
Reference
Reference sections
The parts you will come back to.
Tool definition reference
Every field of a tool definition: tags, direction, units, magnitude and rate limits, verification strategy and owner.
Agent definition reference
Goal statements, tool binding, autonomy levels, verification modes and escalation behaviour.
Autonomy policy schema
Level definitions, tag classes, approval chains, shift and interlock conditions, and site override rules.
REST and SSE reference
Endpoints, payloads, error codes, idempotency and webhook signature verification.
Simulation reference
Snapshot format, correction cadence, candidate scoring and the risk limits that discard a recipe.
Log format and export
Entry schema, hash chaining, retention configuration and JSON/CSV export.
Reel record schema
Furnish, chemistry, profiles, defect map, agent actions, human approvals and standards mapping.
Versioning and promotion
Pinning, replay diffing, evaluation gates, promotion and one-command rollback.
Command reference
Every command, flag and output format, including genealogy and audit export.
Run timeline
Reading a run record
The documentation uses this same run as its worked example throughout.
run_8f21c4
PM4 · 6.8 m trim · 1,180 m/min
SUCCEEDED
-
01
ingest.grade_target
SUCCEEDED
0.8 s
Mill Orchestrator — Pulled the 110 gsm testliner spec, customer tolerances and the standing energy budget from mill MES; locked the target envelope for the run.
-
02
twin.simulate
SUCCEEDED
34 s
Mill Orchestrator — Simulated 48 candidate transition recipes on the as-run paper-machine twin — forming, press, dryer and calender — and ranked them on off-spec tonnes, break risk and steam.
-
03
stock.refine
SUCCEEDED
2 m 10 s
Pulp-and-Stock — Stepped refiner specific edge load 1.9 → 1.4 Ws/m and pushed freeness toward 412 CSF while consistency held at 3.4%.
-
04
wetend.dose
SUCCEEDED
1 m 26 s
Wetend-and-Chemistry — Retention aid trimmed to 214 g/t and sizing to 1.1 kg/t against live charge and turbidity; first-pass retention recovered to 78% inside 90 seconds.
-
05
form.headbox
SUCCEEDED
1 m 05 s
Form-and-Press — Re-cut the slice profile across 78 actuators and set jet-to-wire to 0.994 to hold formation index through the basis-weight ramp.
-
06
press.nip
SUCCEEDED
48 s
Form-and-Press — Nip load reduced 620 → 540 kN/m to protect the lighter web; post-press dryness landed at 47.1%.
-
07
dry.steam
SUCCEEDED
3 m 18 s
Dry-and-Coat — Re-phased the steam schedule across 6 dryer groups and rebalanced the hood; reel moisture converged to 7.4% ±0.19 2σ at 6.1% less steam than the standing recipe.
-
08
inspect.web
SUCCEEDED
continuous
Defect-and-Inspect — 18 line-scan cameras streaming; two edge-crack precursors detected at the drive side and cleared by a 40 kN/m nip trim before either propagated.
-
09
approve.human
APPROVAL
52 s
Mill Orchestrator — Speed ramp 1,180 → 1,245 m/min exceeded the site autonomy threshold. Held for the machine tender; approved by J. Okonkwo at 04:57:12.
-
10
reel.qualify
SUCCEEDED
1 m 31 s
Quality-and-Conformance — Reel R-24188 released: full genealogy written (furnish, chemistry, CD profiles, defect map, operator actions) and checked against grade spec.
Tool calls
Reading the tool log
Arrow in is a call, arrow out is a result, exclamation is an event that changed the plan.
- 04:51:04mes.read_orders({ machine: "PM4", next_grade: "TL-110" })
- 04:51:04ok spec locked · basis 110 g/m² · moisture 7.4% ±0.5
- 04:51:05twin.simulate({ candidates: 48, horizon: "18 min" })
- 04:51:39ok best recipe #31 · est. off-spec 6.4 t · break risk 0.07
- 04:51:40policy.evaluate({ recipe: 31, autonomy: "L3" })
- 04:51:40ok 9 writes permitted · 1 write requires human approval
- 04:51:41dcs.write_setpoint({ tag: "REF4.SEL", from: 1.9, to: 1.4 })
- 04:53:51ok freeness 388 → 412 CSF · consistency 3.4%
- 04:53:52chem.dose({ retention_aid: "214 g/t", sizing: "1.1 kg/t" })
- 04:55:18ok first-pass retention 71% → 78%
- 04:55:19dcs.slice_profile({ actuators: 78, jet_to_wire: 0.994 })
- 04:56:24ok formation index 84 · CD basis 2σ 1.7 g/m²
- 04:56:25vision.stream({ cameras: 18, model: "webdefect-v7" })
- 04:56:41precursor: edge crack risk 0.62 · drive side · 1,412 mm
- 04:56:42dcs.nip_load({ delta: "-40 kN/m", zone: "press-2" })
- 04:56:58ok edge crack risk 0.62 → 0.09 · web stable
- 04:56:59approval.request({ action: "speed_ramp", to: "1245 m/min" })
- 04:57:12ok approved by J. Okonkwo (machine tender) · logged
- 04:58:44mes.log_reel({ reel: "R-24188", genealogy: "full" })
- 05:02:46ok run complete · 11m42s · off-spec 6.2 t · breaks 0
Reasoning trace
Plan → thought → action → observation, exactly as the orchestrator recorded it.
GoalMove PM4 from 135 gsm kraftliner to 110 gsm testliner with zer…
Move PM4 from 135 gsm kraftliner to 110 gsm testliner with zero breaks and under 14 minutes of off-spec production.
PlanSimulate the transition on the twin first. Lead with stock and…
Simulate the transition on the twin first. Lead with stock and chemistry so the furnish is right before the basis weight ramps, then trim forming and press, then re-phase drying. Watch the web continuously; hold the speed ramp for a human.
ThoughtThe standing recipe drops basis weight and speed together. On …
The standing recipe drops basis weight and speed together. On the twin that produces a 3-minute moisture excursion because the dryer section unloads faster than the steam schedule can follow. Sequencing the steam re-phase ahead of the basis-weight ramp removes it.
Actiontwin.simulate(candidates=48) → recipe #31 re-phases steam 40 s…
twin.simulate(candidates=48) → recipe #31 re-phases steam 40 s before the basis-weight ramp and holds nip load until post-press dryness confirms.
ObservationRecipe #31 estimates 6.4 t off-spec against 9.8 t for the stan…
Recipe #31 estimates 6.4 t off-spec against 9.8 t for the standing recipe, with break risk 0.07. Two candidates scored lower on steam but raised break risk above the 0.15 site limit and were discarded.
ActionExecute recipe #31 under autonomy level L3: nine setpoint writ…
Execute recipe #31 under autonomy level L3: nine setpoint writes permitted, speed ramp routed to the machine tender.
ObservationEdge-crack precursor at 1,412 mm drive side at 04:56:41. Nip t…
Edge-crack precursor at 1,412 mm drive side at 04:56:41. Nip trim of −40 kN/m in press-2 cleared it in 16 s without a break.
OutcomeRun complete in 11 m 42 s. 6.2 t off-spec, zero breaks, 6.1% l…
Run complete in 11 m 42 s. 6.2 t off-spec, zero breaks, 6.1% less dryer steam than the standing recipe. Reel R-24188 released with full genealogy.
Operations
Runbooks
What to do at 03:00 when something is wrong.
Agent stopped writing
Diagnosing a policy refusal, a sensor loss or a confidence collapse, and how to return to advisory cleanly.
Unexpected recommendation
Reading the reasoning trace, finding the input that drove it, and filing it as a training correction.
Edge node failure
Confirming DCS fallback, recovering the local audit buffer and re-syncing without losing reel history.
Model rollback
Pinning the prior version, verifying the scan-cycle takeover and documenting the rollback in the audit log.
Camera or sync fault
Detecting desynchronised line-scan cameras and running with a degraded camera set.
Approval backlog
Clearing pending gates safely when a shift has been overwhelmed, and adjusting thresholds afterwards.
Autonomy
Four levels, set per agent and per tag
A mill does not go from manual to unattended in one step. Pulpum makes the level explicit, auditable and reversible at any time.
| Level | What the agent does | What the human does | Typical time to reach |
|---|---|---|---|
| L1 · Advisory | Recommends setpoints and explains why | Enters every change manually | Week 1 |
| L2 · Supervised | Proposes a write; it executes on approval | Approves each write in the HMI | Week 3–6 |
| L3 · Bounded | Writes inside tag, rate and magnitude limits | Approves ramps and grade releases | Month 2–4 |
| L4 · Unattended | Runs the envelope without prompting | Sets the envelope; reviews the shift record | Month 6+ [ASPIRATIONAL] |
CLI
Start a run from anywhere
The same run engine, the same policy checks, the same audit trail — from the terminal, the HMI or the SDK.
$ pulpum run "grade change PM4 to TL-110" --autonomy L3
→ plan composed 10 steps · 1 approval gate
→ twin.simulate 48 candidates · best #31 · risk 0.07
→ policy.evaluate 9 writes permitted · 1 held for human
→ executing stock.refine ... ok 2m10s
→ executing wetend.dose .... ok 1m26s
→ executing form.headbox ... ok 1m05s
→ executing dry.steam ...... ok 3m18s
! approval required speed_ramp 1180 → 1245 m/min
→ approved J. Okonkwo · machine tender · 04:57:12
→ run complete 11m42s · off-spec 6.2 t · breaks 0
$ pulpum runs show run_8f21c4 --format genealogy
Limits
Platform limits and defaults
The numbers you will need when sizing a deployment.
| Item | Default | Maximum | Notes |
|---|---|---|---|
| Cameras per machine | 12 | 24 | Synchronised line-scan or area |
| Defect classification latency | 82 ms | 100 ms target | At the mill edge |
| Break-risk update interval | 240 ms | 250 ms target | From fused web signals |
| Concurrent model endpoints | 20 | 60 | Per enterprise fleet |
| Twin candidates per change | 48 | 100 | Bounded by a 120 s compute budget |
| Setpoint write rate | per tool | policy-bound | Declared in engineering units |
| Audit retention | 7 years | configurable | On mill-owned storage |
| Local buffer | 72 h | 14 days | Survives network loss |
Guardrails
An agent that can move a nip needs a leash
Pulpum writes to production equipment. Every capability is scoped, every write is policy-checked, and every action is written to an append-only audit log the mill owns.
- Bounded action space. Each agent can only write to an explicit tag allow-list, inside per-tag rate and magnitude limits.
- Policy engine before every write. Autonomy level, shift, grade, interlock state and operator presence are all evaluated before a setpoint moves.
- Human-in-the-loop gates. Anything above the site threshold — speed ramps, grade releases, safety-adjacent moves — waits for a named approver.
- Immutable audit log. Append-only, hash-chained, exportable, and retained on the mill's own storage.
- Hard fallback. Loss of the edge node, the network or the model returns control to the DCS's last known-good state within one scan cycle.
- Tenant and IP isolation. Furnish recipes, grade models and defect libraries never cross a customer boundary. On-prem deployment available.
Compliance posture
| Standard | Scope | Status |
|---|---|---|
| SOC 2 Type II | Cloud control plane | RUNNING In progress [ASPIRATIONAL] |
| ISO 27001 | Company-wide ISMS | QUEUED Planned [ASPIRATIONAL] |
| IEC 62443 | Mill-edge OT security | RUNNING Design-aligned |
| GDPR | Operator data | SUCCEEDED Compliant |
| ISO 9001 / FSC | Quality + chain of custody records | SUCCEEDED Supported |
Integrations
It speaks mill, not cloud
Pulpum reads and writes through the systems already on the floor. No rip-and-replace, no parallel historian, no new HMI to learn.
Valmet IQ, ABB 800xA QCS, Honeywell Experion MX
Profiles, scans, lab results
ABB 800xA, Valmet DNA, Honeywell Experion, Siemens PCS 7
Setpoint reads and guarded writes
WIS/WMS line-scan, IR and transmission cameras
Frames, defect maps, break replays
SAP PP/QM, ABB cpmPlus, custom historians
Orders, grades, reel genealogy
OSIsoft PI, Aspen IP.21, InfluxDB
Time-series backfill and replay
NVIDIA Isaac, winder and wrapper PLCs
Reel, roll and clamp-truck motion
Azure AD, Okta, on-prem LDAP
SSO, RBAC, named approvers
NVIDIA Jetson Orin, IGX, on-prem GPU
Sub-100 ms inference at the machine
FAQ
Straight answers
The questions mill managers and process engineers actually ask in the first meeting.
Yes, but only within an explicit tag allow-list with per-tag rate and magnitude limits, and only at the autonomy level your site has set. Level 1 is advisory-only: Pulpum recommends and a human enters everything. Most mills spend their first weeks there before enabling supervised writes.
Control returns to the DCS last known-good state within one scan cycle. Pulpum is designed as a supervisory layer on top of your existing control system, never as a replacement for it, so a Pulpum outage degrades the mill to its current way of running — not to a stop.
Break prediction and defect classification typically need 8 to 12 weeks of QCS, DCS and inspection history per grade family, plus labelled break events. Advisory recommendations start in week one from the physics-based twin, and improve as mill-specific history accumulates.
Only if you choose cloud training. Recipes, grade models and defect libraries are tenant-isolated and never used to train another customer's models. A fully on-prem deployment with an air-gapped mill edge is available for sensitive producers.
You are, the same as with any control strategy — which is why every write is policy-checked, bounded, logged and reversible, and why anything above your risk threshold waits for a named approver. The audit log records the request, the reasoning, the limits applied and the human decision.
A 90 to 120 day mill-edge deployment on one paper machine, scoped to a single workflow with a pre-agreed baseline [ASPIRATIONAL]. Weeks 1–3 are connection and shadow-mode observation; weeks 4–8 advisory; weeks 9+ supervised or bounded writes if the mill is satisfied with the recommendations.
Get started
Get documentation access
Full documentation, the sandbox mill and the tool reference are available to design partners and evaluating mills.