Developers

Typed tools. Declared limits. Replayable runs.

The Orebex SDK is a design preview of how an agent is defined, bounded and run: tools with unit-aware ranges, rate limits and operating envelopes, autonomy policy as code, deterministic replay of any historical run against a new model, and a local twin harness. The API will change before release.

Read the docs Ask for early access

Python SDK · design previewCLI · design previewPolicy as code

run_4b9e27 · agent graph · line 1 · scenario 10 nodes · 1 approval gate
01 · orchestrator ingest.shift ✓ SUCCEEDED 02 · oretwin twin.simulate ✓ SUCCEEDED 03 · crush_grind grind.setpoint ✓ SUCCEEDED 04 · grade_froth froth.read ✓ SUCCEEDED 05 · orchestrator approve.human ◆ APPROVAL 06 · float_reagent float.dose ✓ SUCCEEDED 07 · separate_classify classify.cyclone ✓ SUCCEEDED 08 · thicken_dewater dewater.thickener ✓ SUCCEEDED 09 · throughput_recovery optimise.targets ✓ SUCCEEDED 10 · quality_conf lot.release ✓ SUCCEEDED

Illustrative scenario: Line 1 · SAG and ball circuit, rougher bank 2 · copper porphyry blend, one shift, one approval gate

Concepts

Six objects

Everything in the SDK is one of these.

Agent

A goal, tools and an autonomy level

An agent declares what it is for, what it may call and how far it may go without a human. Its runs are typed and logged.

Agent

Tool

A connector call with a schema

Tools name tags, units and whether they are read-only. Write tools carry Limits and an operating envelope.

Toolread_only

Limit

Rate, magnitude, envelope

max_step per period, absolute floors and ceilings, and the envelope per blend or ore type, enforced at call time by the policy engine and again at the OT boundary.

Limitenvelope

Autonomy

L1 to L4

The level the plant has set for this agent, this tag, this shift. Approvals are routed to named humans above the threshold.

Autonomy.L1Autonomy.L3

Run

A shift plan becoming a graph of steps

Start, stream, replay. Every step has an agent, a tool, a duration and a status, and the whole record is kept per circuit and lot.

run.stream()run.replay()

Twin

verify=twin

Simulate a move on the as-run twin before it is written. Required for any agent configured with it.

twin.simulate
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

Read the docs Developer guide

l1_grind_agent.py 
# 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)
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 · cli · scenario 
$ 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
Run timeline · scenario

One scenario run, step by step

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
  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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.

  7. 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.

  8. 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.

  9. 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. 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

The agent shows its work

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.

tool-call stream · run_4b9e27
  1. 07:00:02mes.read_plan({ line: "L1", blend: "B-14", shift: "day" })
  2. 07:00:02ok envelope locked · P80 150 µm · grade ≥ 25% Cu · energy and water budgets
  3. 07:00:03twin.simulate({ candidates: 32, horizon: "1 shift" })
  4. 07:01:01ok best scheme #7 · recovery on plan · 2 candidates discarded (thickener bed)
  5. 07:01:02policy.evaluate({ scheme: 7, autonomy: "L2+" })
  6. 07:01:02ok 8 writes permitted · collector_dose requires human approval
  7. 07:01:03mill.set_feed({ tag: "SAG1.FEED_TPH", delta: "-3%" })
  8. 07:04:43ok P80 148 µm · power inside budget · hardness index up
  9. 07:04:44froth.read_bank({ bank: "R2", cams: 12, xrf: true })
  10. 07:18:30froth stability falling · R2 cells 3, 4 · predicted recovery −0.4 pt
  11. 07:18:31approval.request({ action: "collector_dose", bank: "R2", delta: "+6%" })
  12. 07:19:44ok approved by shift metallurgist · logged
  13. 07:19:45reagent.set_dose({ bank: "R2", scheme: 7 })
  14. 07:19:46air.set_rate({ cells: [3, 4], delta: "-4%", within: "envelope" })
  15. 07:27:50ok froth stability recovered · grade 25.6% Cu · recovery back on plan
  16. 07:27:51cyclone.set_count({ cluster: "CL-1", online: "+1" })
  17. 07:28:33ok overflow size held · circulating load inside plan
  18. 07:28:34flocculant.set_dose({ thickener: "TH-2", delta: "-2%" })
  19. 07:40:10ok bed pressure steady · overflow clear · water recovery on target
  20. 07:40:11cuopt.solve_targets({ line: "L1", objective: "recovery, grade, energy, water" })
  21. 07:40:29ok targets handed to 4 agents · all inside budget
  22. 07:40:30mes.log_lot({ lot: "C-20931", genealogy: "full" })
  23. 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.

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.

Autonomy levels and the human role at each
LevelWhat the agent doesWhat the human doesWhere it sits in a pilot
L1 · ShadowReads froth, analyzer, particle, mill, flotation, dewatering, robot and MES signals; predicts and recommends; writes nothingRuns the circuit as today; compares predictions to assays and metallurgist outcomesShadow mode, baseline measured first
L2 · AssistProposes grind, reagent, air, froth and dewatering moves with evidence, confidence, envelope and rollback pathApproves each action in the review consoleAssist mode, the remainder of a 90 to 120 day pilot
L3 · BoundedExecutes pre-approved low-risk grinding and flotation loop moves: feed, water, air, level, flocculant, cyclones online, inside APC, DCS and envelope limitsApproves reagent-scheme changes and lot releaseGraduated autonomy, after audited accuracy and ROI
L4 · Constrained auto-controlSupervised reagent-scheme adaptation for characterised ore types, across circuits and sitesSets the envelope; reviews the shift record and the evaluation resultsPlanned; after golden-dataset evaluation, twin validation and metallurgist sign-off
Accelerated computing

Physical AI, at the bank and the mill

Froth changes in seconds and a shift of feed is gone before the assay lands. Perception has to be local, deterministic and fast, so Orebex runs GPU inference at the plant edge and keeps training, simulation and optimisation in the cloud or on-prem.

Jetson Orin · DeepStream · Holoscan · TensorRT

Edge perception

8 to 24 froth cameras per bank at 15 to 30 FPS plus online XRF, particle-size, pump, level, air, reagent, density and energy streams fused at the plant edge. Sub-250 ms froth inference and local fail-safe through a network outage are the design targets. Jetson Thor is planned.

Triton · NIM

Model serving

Froth, particle and mineralogy, recovery prediction, time-series anomaly and metallurgy retrieval models behind one orchestrator at the plant edge, 20 to 60 per site as a design target, with versioned canaries and rollback.

DGX or HGX · NeMo

Training

Froth segmentation, bubble velocity and stability, grade and recovery prediction, ore hardness, grind-size response, reagent response and metallurgy assistants trained on froth video, analyzer readings, telemetry and metallurgist corrections. 2,000 to 8,000 GPU-hours per commodity model family is the design target once partner data exists.

Omniverse · OVX

Concentrator twin

Grinding, flotation, classification and dewatering simulated as-run against as-designed before the shift. GPU comminution and DEM, flotation and geometallurgy simulation is the workload; physics-informed surrogates with Modulus are planned so schemes rank at production cadence.

Cosmos · Omniverse Replicator

Synthetic data

Rare froth-collapse, feed-upset, mineralogy-shift, equipment-drift and camera-fouling cases generated and validated against real assay distributions before promotion. 50k to 250k scenarios per commodity and circuit class is the design target.

cuOpt

Optimisation

Throughput, energy, water and reagent allocation and the grade and recovery trade-off solved before the shift and during upset recovery, and handed to the control agents as targets.

Isaac Sim · Isaac ROS

Robot sampling and handling

Sampling routes, reagent tote inspection and inspection rovers trained and validated in simulation before they run on site. Assistive until the safety case is proven.

RAPIDS

GPU ETL

Daily features from froth, analyzer, mill, flotation, dewatering and genealogy telemetry for retraining, drift detection and recovery, energy, water and reagent benchmarks.

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

ItemScopeStatus
SOC 2 Type ICloud control plane QUEUED Planned, first 6 months
SOC 2 Type IICloud control plane QUEUED Planned, 6 to 12 months
SSO and RBACConsole and approvals QUEUED Planned, 6 to 12 months
Environmental and water assurance packagesRecovery, energy, water and tailings evidence QUEUED Planned, 6 to 12 months; not a certification claim
Standards-cited reasoningISO, ICMM, tailings and water governance documents RUNNING In the design, every answer cites its source
Per-tenant and ore-body isolationOre data, schemes, models, memory RUNNING In the design from day one
On-prem and plant-edge deploymentRemote and IP-sensitive sites RUNNING Design option

Read the security overview

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.

Get started

Ask for early access

The SDK and CLI are design previews. Tell us what you would build and we will tell you where it stands.

Contact Documentation