Definition and lifecycle
Agent, goal, tools, autonomy, verify, start, stream, replay.
Documentation
Everything needed to run, extend and audit the platform.
Getting started, reference, runbooks, the autonomy model, the CLI and the platform limits. The documentation describes the design; sections marked design preview will change before release.
Illustrative scenario: Line 1 · SAG and ball circuit, rougher bank 2 · copper porphyry blend, one shift, one approval gate
Getting started
First hour
From an empty plant-edge node to a shadow-mode run.
- Install the plant-edge runtime. A Jetson Orin node with the Orebex runtime image, inside the plant network.
- Connect read-only sources. Mill and flotation DCS tags, froth cameras, online XRF and particle-size analyzers, LIMS and MES, all read-only.
- Define the blend. Load the shift plan: blend, P80 target, grade specification, recovery target, energy and water budgets, operating envelope.
- Create an agent at L1. Declare its tools read-only and let it watch and recommend.
- Start a shadow run. Observe the run record, the tool-call stream and the reasoning trace against the live circuit.
Developers
Define an agent, bound it, run it
The Orebex SDK is typed Python. Tools are declared with schemas, limits and the operating envelope for the blend, and the policy engine enforces them at call time, not in a review meeting. This is a design preview; the API will change before release.
What you get
- Typed tool definitions with unit-aware ranges, rate limits and operating envelopes
- Deterministic replay of any historical run against a new model
- Local twin harness so a scheme is simulated before it is shipped
- Autonomy policy as code, versioned and reviewed like any other change
# Design preview. Bound the grind agent to SAG mill SAG-1.
from orebex import Agent, Tool, Limit, Autonomy
feed = Tool(
name="mill.set_feed",
tags=["SAG1.FEED_TPH", "CL1.WATER_M3H"],
limits=[Limit(max_step="3%", per="300s", envelope="blend-B14")],
)
grind = Agent(
id="agent.crush_grind",
goal="P80 150 um +/- 10, least kWh per tonne, throughput inside plan",
tools=[feed, Tool("psa.read_p80", read_only=True)],
# bounded writes on feed and water; reagent scheme stays with a human
autonomy=Autonomy.L3,
# simulate on the twin before every write
verify="twin",
)
run = grind.start(line="L1", blend="B-14")
for step in run.stream():
print(step.name, step.status, step.duration)
Reference
Reference sections
What each section of the reference covers.
Connectors with schemas
Tag naming, units, read_only, Limit(max_step, per, floor, ceiling, envelope).
Autonomy as code
Levels, approval routing, shift, ore-type, interlock and water and tailings conditions, versioning and review.
The run record
Steps, status values (queued, running, waiting, approval, succeeded, failed, blocked), durations, outcomes.
The lot record
Fields, export formats, retention, customer and environmental evidence packets.
Simulation API
twin.simulate, candidates, horizon, ranking objectives, as-run comparison.
Run timeline · scenario
Reading a run record
Every Orebex run is an ordered, inspectable sequence. This is run_4b9e27 on Line 1 · SAG and ball circuit, rougher bank 2 · copper porphyry blend. Scenario completes in 10 steps with one approval gate. P80 held at 148 µm as the blend hardened, froth stability recovered on rougher bank 2 after an air trim, a collector-dose change was approved by the shift metallurgist, predicted recovery held inside the plan, lot C-20931 released with full genealogy.
run_4b9e27
Line 1 · SAG and ball circuit, rougher bank 2 · copper porphyry blend
illustrative scenario
SUCCEEDED
-
01
ingest.shift
SUCCEEDED
0.7 s
Concentrator Orchestrator · Pulled the shift plan from the concentrator MES: copper porphyry blend B-14, P80 target 150 µm, concentrate grade at or above 25% Cu, recovery target per the geometallurgy model, energy and water budgets. Locked the operating envelope for the blend.
-
02
twin.simulate
SUCCEEDED
58 s
Concentrator Twin · Simulated 32 candidate grind, air and reagent schemes on the as-run twin for the hardening blend, ranked on predicted recovery, concentrate grade, kWh per tonne and water per tonne. Two candidates breached the thickener bed limit and were discarded.
-
03
grind.setpoint
SUCCEEDED
3 m 40 s
Crush-and-Grind · SAG-1 feed trimmed 3% and cyclone water raised as load and power signatures read a harder feed. P80 from the particle-size analyzer held at 148 µm against the 150 µm target; mill power stayed inside the energy budget.
-
04
froth.read
SUCCEEDED
continuous
Grade-and-Froth · Twelve froth cameras and the online XRF on rougher bank 2 fused at the edge. Froth stability on cells 3 and 4 fell as the blend hardened; predicted recovery drifted 0.4 points below plan. Early warning published to the control agents.
-
05
approve.human
APPROVAL
1 m 12 s
Concentrator Orchestrator · Scheme #7 raises collector dose 6% on rougher bank 2, above the standing reagent scheme. Reagent-scheme changes stay supervised on this blend, so the step was held for the shift metallurgist and approved at 07:19:44.
-
06
float.dose
SUCCEEDED
2 m 05 s
Float-and-Reagent · Approved collector dose applied with an air trim of 4% down on cells 3 and 4 inside the envelope. Froth stability recovered within eight minutes; predicted recovery returned to plan with concentrate grade read at 25.6% Cu.
-
07
classify.cyclone
SUCCEEDED
42 s
Separate-and-Classify · One cyclone brought online in cluster 1 as feed density rose with the hardness change, holding overflow size and circulating load inside the plan.
-
08
dewater.thickener
SUCCEEDED
continuous
Thicken-and-Dewater · Tailings thickener TH-2 flocculant dose trimmed as bed pressure rose; underflow density held and overflow clarity stayed inside the water-recovery target.
-
09
optimise.targets
SUCCEEDED
18 s
Throughput-and-Recovery · Whole-plant targets recomputed for the hardened blend: feed rate, P80, air and reagent targets handed to the control agents with recovery, grade, energy and water inside the budget. The losing candidates and their scores are in the run record.
-
10
lot.release
SUCCEEDED
1 m 30 s
Quality-and-Conformance · Concentrate lot C-20931 released: genealogy written (blend, grind record, reagent and air moves, froth and grade reads, approvals, dewatering record, assays as they land) and dispositioned against the concentrate spec with cited evidence for the metallurgist's sign-off.
Tool calls · scenario
Reading the tool log
Every tool invocation, argument and result is written to an append-only, human-readable log, and every reasoning step is expandable. Nothing about a run is hidden from the plant.
- 07:00:02mes.read_plan({ line: "L1", blend: "B-14", shift: "day" })
- 07:00:02ok envelope locked · P80 150 µm · grade ≥ 25% Cu · energy and water budgets
- 07:00:03twin.simulate({ candidates: 32, horizon: "1 shift" })
- 07:01:01ok best scheme #7 · recovery on plan · 2 candidates discarded (thickener bed)
- 07:01:02policy.evaluate({ scheme: 7, autonomy: "L2+" })
- 07:01:02ok 8 writes permitted · collector_dose requires human approval
- 07:01:03mill.set_feed({ tag: "SAG1.FEED_TPH", delta: "-3%" })
- 07:04:43ok P80 148 µm · power inside budget · hardness index up
- 07:04:44froth.read_bank({ bank: "R2", cams: 12, xrf: true })
- 07:18:30froth stability falling · R2 cells 3, 4 · predicted recovery −0.4 pt
- 07:18:31approval.request({ action: "collector_dose", bank: "R2", delta: "+6%" })
- 07:19:44ok approved by shift metallurgist · logged
- 07:19:45reagent.set_dose({ bank: "R2", scheme: 7 })
- 07:19:46air.set_rate({ cells: [3, 4], delta: "-4%", within: "envelope" })
- 07:27:50ok froth stability recovered · grade 25.6% Cu · recovery back on plan
- 07:27:51cyclone.set_count({ cluster: "CL-1", online: "+1" })
- 07:28:33ok overflow size held · circulating load inside plan
- 07:28:34flocculant.set_dose({ thickener: "TH-2", delta: "-2%" })
- 07:40:10ok bed pressure steady · overflow clear · water recovery on target
- 07:40:11cuopt.solve_targets({ line: "L1", objective: "recovery, grade, energy, water" })
- 07:40:29ok targets handed to 4 agents · all inside budget
- 07:40:30mes.log_lot({ lot: "C-20931", genealogy: "full" })
- 07:42:00ok scenario complete · 10 steps · lot released
Reasoning trace
Plan, thought, action, observation, exactly as the orchestrator would record it.
GoalRun the day shift on line 1 inside the plan for blend B-14: P8…
Run the day shift on line 1 inside the plan for blend B-14: P80 at 150 µm, concentrate grade at or above 25% Cu, recovery maximised, energy and water inside budget.
PlanSimulate grind, air and reagent schemes on the twin first. Lea…
Simulate grind, air and reagent schemes on the twin first. Lead with the grind so the liberation size is right before flotation sees it, then read the froth, then dose. Hold any reagent-scheme change for a human.
ThoughtThe blend is hardening. Holding feed rate would coarsen P80 an…
The blend is hardening. Holding feed rate would coarsen P80 and under-liberate; the twin predicts a 3% feed trim with more cyclone water holds P80 at the cost of a little throughput, and that protecting liberation is worth more than the tonnes.
Actiontwin.simulate(candidates=32) returns scheme #7: SAG-1 feed dow…
twin.simulate(candidates=32) returns scheme #7: SAG-1 feed down 3%, cyclone water up, collector dose up 6% on rougher bank 2, air down 4% on cells 3 and 4.
ObservationScheme #7 predicts recovery on plan, grade 25.5% Cu and energy…
Scheme #7 predicts recovery on plan, grade 25.5% Cu and energy inside budget. Two candidates with higher predicted recovery pushed the tailings thickener past its bed limit and were discarded.
ActionExecute scheme #7: eight bounded writes permitted on grind, ai…
Execute scheme #7: eight bounded writes permitted on grind, air, cyclones and dewatering; the collector-dose write routed to the shift metallurgist.
ObservationFroth stability fell on cells 3 and 4 at 07:18:30 with predict…
Froth stability fell on cells 3 and 4 at 07:18:30 with predicted recovery 0.4 points under plan. The approved dose and the air trim recovered it within eight minutes; grade read 25.6% Cu.
OutcomeScenario complete. P80 held, grade on spec, recovery on plan, …
Scenario complete. P80 held, grade on spec, recovery on plan, lot C-20931 released with full genealogy.
Operations
Runbooks
What to do when.
| Situation | What happens | What you do |
|---|---|---|
| Edge node offline | Control returns to the APC or DCS last known-good state; interlocks unaffected | Check the node, restore, resume at the current autonomy level |
| Network outage at a remote site | The edge keeps running fail-safe on its last validated models; nothing is promoted | Restore the link; the audit log syncs when it returns |
| Model version fails canary | Automatic fallback to the previous validated version on that circuit | Review the evaluation record before re-promoting |
| Approval not answered | The step waits; the run does not time out into a write | Named approver or delegate decides in the console |
| Deadlock between agents | Escalates to a human rather than resolving by timeout | Decide in the console; the decision is logged |
| Rollback condition met | The tag returns to its previous value | Review the trigger signal and the run record |
Autonomy
Four levels, set per agent and per tag
A concentrator does not go from manual to unattended in one step. Orebex makes the level explicit, auditable and reversible at any time. The first release runs shadow mode, then assist mode, then bounded autonomy on low-risk grinding and flotation loops. Reagent-scheme changes stay supervised until the ore type is characterised.
| Level | What the agent does | What the human does | Where it sits in a pilot |
|---|---|---|---|
| L1 · Shadow | Reads froth, analyzer, particle, mill, flotation, dewatering, robot and MES signals; predicts and recommends; writes nothing | Runs the circuit as today; compares predictions to assays and metallurgist outcomes | Shadow mode, baseline measured first |
| L2 · Assist | Proposes grind, reagent, air, froth and dewatering moves with evidence, confidence, envelope and rollback path | Approves each action in the review console | Assist mode, the remainder of a 90 to 120 day pilot |
| L3 · Bounded | Executes pre-approved low-risk grinding and flotation loop moves: feed, water, air, level, flocculant, cyclones online, inside APC, DCS and envelope limits | Approves reagent-scheme changes and lot release | Graduated autonomy, after audited accuracy and ROI |
| L4 · Constrained auto-control | Supervised reagent-scheme adaptation for characterised ore types, across circuits and sites | Sets the envelope; reviews the shift record and the evaluation results | Planned; after golden-dataset evaluation, twin validation and metallurgist sign-off |
CLI
Start a run from anywhere
The same run engine, the same policy checks, the same audit trail, from the terminal, the review console or the SDK. Design preview.
$ orebex run "day shift, line 1, blend B-14" --autonomy L2+
→ plan composed 10 steps · 1 approval gate
→ twin.simulate 32 candidates · best #7 · recovery on plan
→ policy.evaluate 8 writes permitted · collector_dose held for human
→ executing grind.setpoint ... ok 3m40s
→ executing froth.read ....... ok continuous
! approval required collector_dose R2 +6%
→ approved shift metallurgist · 07:19:44
→ executing float.dose ....... ok 2m05s
→ executing optimise.targets . ok 18s
→ scenario complete grade 25.6% Cu · lot C-20931 released
$ orebex runs show run_4b9e27 --format genealogy
Limits
Platform limits and defaults
Design targets. None is a measured figure.
| Item | Design target | Notes |
|---|---|---|
| Edge inference, froth condition | under 250 ms per stream | Jetson Orin at the bank, TensorRT |
| Control recommendation latency | under 2 s | Low-risk setpoint moves; includes policy evaluation |
| Cameras per flotation bank | 8 to 24 | DeepStream and Holoscan, 15 to 30 FPS each |
| Models served per site | 20 to 60 | Triton and NIM, versioned canaries and rollback |
| Training, first commodity model families | 2,000 to 8,000 GPU-hours each | DGX or HGX, once partner data exists |
| Synthetic scenarios | 50k to 250k per commodity and circuit class | Cosmos and Replicator, validated against real assay distributions |
| Fail-safe through outage | Local operation continues | Edge runs the last validated models; no promotion while offline |
Guardrails
An agent that can move a reagent pump needs a leash
Orebex writes to production equipment. Every capability is scoped, every write is policy-checked against the operating envelope, and every action is written to an append-only audit log the plant owns.
- Bounded action space. Each agent writes only to an explicit tag allow-list, inside per-tag rate and magnitude limits and the operating envelope for the blend.
- Policy engine before every write. Autonomy level, shift, ore type, interlock state, water and tailings constraints and metallurgist policy are evaluated before a setpoint moves.
- Human-in-the-loop gates. Reagent-scheme changes and lot release wait for a named approver. Robotics stays assistive until the site safety case is proven.
- Immutable audit log. Append-only and exportable. Every action records source evidence, the envelope applied, confidence, estimated recovery, grade, energy, water and reagent impact, rollback path, approver and lot scope.
- Hard fallback. Loss of the edge node, the network or a model returns control to the APC or DCS last known-good state. Interlocks are never in Orebex's path, and the edge runs fail-safe through a network outage.
- Tenant and ore-body isolation. Ore-body data, geometallurgy models, reagent schemes and recovery records never cross a customer boundary. On-prem and edge deployment is available for remote sites.
Compliance posture
| Item | Scope | Status |
|---|---|---|
| SOC 2 Type I | Cloud control plane | QUEUED Planned, first 6 months |
| SOC 2 Type II | Cloud control plane | QUEUED Planned, 6 to 12 months |
| SSO and RBAC | Console and approvals | QUEUED Planned, 6 to 12 months |
| Environmental and water assurance packages | Recovery, energy, water and tailings evidence | QUEUED Planned, 6 to 12 months; not a certification claim |
| Standards-cited reasoning | ISO, ICMM, tailings and water governance documents | RUNNING In the design, every answer cites its source |
| Per-tenant and ore-body isolation | Ore data, schemes, models, memory | RUNNING In the design from day one |
| On-prem and plant-edge deployment | Remote and IP-sensitive sites | RUNNING Design option |
FAQ
Straight answers
The questions processing managers, metallurgists and sustainability leads ask in the first meeting.
Yes, but only within an explicit tag allow-list with per-tag rate and magnitude limits, inside the operating envelope for the blend, and only at the autonomy level your plant has set. Design partners start in shadow mode, where Orebex writes nothing. Reagent-scheme changes stay supervised by a named metallurgist until the ore type is characterised.
Control returns to the APC or DCS last known-good state. Orebex is a supervisory layer on top of the control systems and interlocks you already run, never a replacement for them, so an outage degrades the circuit to its current way of running, not to a stop. The edge is designed to run fail-safe through a network outage.
Advisory recommendations start from the twin and the shift plan in the first weeks. Froth, grade, recovery and grind-response prediction improve as circuit history and assay-labelled outcomes accumulate per ore type. The compute plan sizes training at 2,000 to 8,000 GPU-hours per commodity model family once partner data exists, a design target.
Only if you choose cloud training. Ore-body data, geometallurgy models, reagent schemes, process models and recovery records are isolated per tenant and never used to train another customer's models. A fully on-prem deployment at the plant edge is available for remote and IP-sensitive sites, and federated learning across sites is planned and waits on data-rights agreements.
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 evidence, the envelope applied and the human decision.
A paid pilot of 90 to 120 days on one grinding or flotation circuit, scoped to a single wedge with a success metric written into the order form: recovery gain, energy per tonne saved, water reduction or reagent per tonne. The first weeks baseline recovery, energy and water in shadow mode from your own assays and meters.
Get started
Get documentation access
Documentation beyond this page opens with the design-partner cohort.