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.

First hour Developer guide

Getting startedReferenceRunbooks

run_7c2e41 · agent graph · cell F-2 · scenario 10 nodes · 1 approval gate
01 · orchestrator ingest.order ✓ SUCCEEDED 02 · forgetwin twin.simulate ✓ SUCCEEDED 03 · heat_billet heat.soak ✓ SUCCEEDED 04 · die_lube die.spray ✓ SUCCEEDED 05 · orchestrator approve.human ◆ APPROVAL 06 · forge_press forge.stroke ✓ SUCCEEDED 07 · defect_inspect inspect.fuse ✓ SUCCEEDED 08 · robot_handling handle.transfer ✓ SUCCEEDED 09 · trim_heat heat.treat ✓ SUCCEEDED 10 · quality_conf lot.release ✓ SUCCEEDED

Illustrative scenario: Cell F-2 · 2,500 t closed-die press · 42CrMo4 connecting rod, one lot, one approval gate

Getting started

First hour

From an empty plant-edge node to a shadow-mode run.

  1. Install the plant-edge runtime. A Jetson Orin node with the Forgiron runtime image, inside the plant network.
  2. Connect read-only sources. Induction and press PLC tags, die thermal cameras, ultrasonic and MPI events, cameras and MES, all read-only.
  3. Define the part family. Load the part spec: alloy, forging window, stroke schedule, die, hardness target, qualified envelope.
  4. Create an agent at L1. Declare its tools read-only and let it watch and recommend.
  5. Start a shadow run. Observe the run record, the tool-call stream and the reasoning trace against the live cell.
Developers

Define an agent, bound it, run it

The Forgiron SDK is typed Python. Tools are declared with schemas, limits and the qualified process envelope, 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 process envelopes
  • 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

Read the docs Developer guide

f2_heating_agent.py 
# Design preview. Bound the heating agent to induction heater IH-2.
from forgiron import Agent, Tool, Limit, Autonomy

power = Tool(
    name="induction.set_power",
    tags=["IH2.STAGE3_KW", "IH2.SOAK_S"],
    limits=[Limit(max_step="4%", per="60s", envelope="42CrMo4-CR118")],
)

heat = Agent(
    id="agent.heat_billet",
    goal="surface 1180 to 1230 C, core-to-surface spread <= 20 C, least kWh",
    tools=[power, Tool("pyro.read_surface", read_only=True)],
    # bounded writes on heating; press schedule stays with a human
    autonomy=Autonomy.L3,
    # simulate on the twin before every write
    verify="twin",
)

run = heat.start(cell="F-2", part="CR-42CrMo4-118")
for step in run.stream():
    print(step.name, step.status, step.duration)
Reference

Reference sections

What each section of the reference covers.

Agents

Definition and lifecycle

Agent, goal, tools, autonomy, verify, start, stream, replay.

Tools and limits

Connectors with schemas

Tag naming, units, read_only, Limit(max_step, per, floor, ceiling, envelope).

Policy

Autonomy as code

Levels, approval routing, shift, part-family and interlock conditions, versioning and review.

Runs

The run record

Steps, status values (queued, running, waiting, approval, succeeded, failed, blocked), durations, outcomes.

Genealogy

The forging record

Fields, export formats, retention, customer, first-article and qualification evidence packets.

Twin

Simulation API

twin.simulate, candidates, horizon, ranking objectives, as-forged comparison.

Run timeline · scenario

Reading a run record

Every Forgiron run is an ordered, inspectable sequence. This is run_7c2e41 on Cell F-2 · 2,500 t closed-die press · 42CrMo4 connecting rod. Scenario completes in 10 steps with one approval gate. Surface temperature held at 1,205 °C with a 14 °C core-to-surface spread, fill predicted and confirmed complete, one lap precursor at the flash land cleared by a blow-energy trim, lot L-80412 released with full genealogy.

run_7c2e41 Cell F-2 · 2,500 t closed-die press · 42CrMo4 connecting rod illustrative scenario SUCCEEDED
  1. 01 ingest.order SUCCEEDED 0.6 s

    Plant Orchestrator · Pulled the part spec for the 42CrMo4 connecting rod from MES: forging window 1,180 to 1,230 °C, two-blow closed-die schedule, flash land 2.4 mm, temper to 28 to 32 HRC, 1,200 pieces. Locked the qualified process envelope.

  2. 02 twin.simulate SUCCEEDED 52 s

    Forge Twin · Simulated 24 candidate heat-and-stroke recipes on the as-forged twin for soak time, blow energy and spray timing, ranked on predicted fill, lap risk at the flash land, die load and kWh per piece.

  3. 03 heat.soak SUCCEEDED 2 m 10 s

    Heat-and-Billet · Induction power on IH-2 stepped down 4% in the final soak stage as the pyrometer read 1,205 °C at the surface. Core-to-surface spread estimated at 14 °C against a 20 °C limit, no overheat, scale growth inside the window.

  4. 04 die.spray SUCCEEDED 48 s

    Die-and-Lube · Lower-die spray dose raised 6% and cooling extended 0.3 s as die surface temperature climbed through 240 °C. Heat-check growth on cavity 2 flagged at 0.31 of the die-change threshold.

  5. 05 approve.human APPROVAL 46 s

    Plant Orchestrator · Recipe #9 moves second-blow energy 3% below the standing schedule. Press-schedule changes stay supervised on this part family, so the step was held for the shift forging engineer and approved at 05:47:31.

  6. 06 forge.stroke SUCCEEDED 1 m 36 s

    Forge-and-Press · Two-blow schedule executed with the approved energy. High-speed vision and force curves confirmed complete fill on the first ten pieces; predicted lap risk at the flash land fell from 0.27 to 0.08.

  7. 07 inspect.fuse SUCCEEDED continuous

    Defect-and-Inspect · Eight cameras, two thermal cameras and the ultrasonic station fused at the edge. One lap precursor at the flash land on piece 212 flagged and cleared by a 1.5% blow-energy trim inside the approved envelope; the piece was routed to MPI and passed.

  8. 08 handle.transfer SUCCEEDED continuous

    Robot-and-Handling · Press-to-trim transfer planned and executed by the handling robot at 11 s per piece, temperature loss in transfer 38 °C against a 60 °C limit, interlock zones clear throughout.

  9. 09 heat.treat SUCCEEDED continuous

    Trim-and-Heat · Temper furnace HT-1 zone 2 trimmed 5 °C against the predicted hardness from the recorded heat and stroke history. First hardness checks read 30 HRC, inside 28 to 32.

  10. 10 lot.release SUCCEEDED 1 m 20 s

    Quality-and-Conformance · Lot L-80412 released: genealogy written (billet lot, heat curve, stroke record, die cycles, inspection map, approvals, temper record) and dispositioned against IATF 16949 criteria with cited evidence for the quality engineer'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 forge.

tool-call stream · run_7c2e41
  1. 05:40:02mes.read_order({ cell: "F-2", part: "CR-42CrMo4-118", qty: 1200 })
  2. 05:40:02ok envelope locked · 1,180 to 1,230 °C · 2 blows · 28 to 32 HRC
  3. 05:40:03twin.simulate({ candidates: 24, horizon: "1 lot" })
  4. 05:40:55ok best recipe #9 · fill 1.00 · lap risk 0.08 · 1.9 kWh/pc
  5. 05:40:56policy.evaluate({ recipe: 9, autonomy: "L2+" })
  6. 05:40:56ok 7 writes permitted · press_schedule requires human approval
  7. 05:40:57induction.set_power({ tag: "IH2.STAGE3_KW", delta: "-4%" })
  8. 05:43:07ok surface 1,205 °C · core-to-surface spread 14 °C · no overheat
  9. 05:43:08spray.set_dose({ die: "F2.LOWER", dose: "+6%", cool: "+0.3 s" })
  10. 05:43:56ok die surface 240 °C · heat-check index 0.31
  11. 05:43:57approval.request({ action: "press_schedule", blow2: "-3%" })
  12. 05:47:31ok approved by shift forging engineer · logged
  13. 05:47:32press.set_schedule({ press: "F-2", recipe: 9 })
  14. 05:49:08ok fill complete on 10 pieces · lap risk 0.27 → 0.08
  15. 05:49:09sensors.fuse({ cams: 8, thermal: 2, ut: true })
  16. 06:21:40precursor: lap risk 0.52 · flash land · piece 212
  17. 06:21:41press.set_schedule({ press: "F-2", blow2: "-1.5%", within: "approved envelope" })
  18. 06:21:58ok lap risk 0.52 → 0.07 · piece 212 routed to MPI · passed
  19. 06:22:00isaac.plan_path({ task: "press_to_trim", cell: "F-2" })
  20. 06:22:11ok 11 s per piece · transfer loss 38 °C · zones clear
  21. 06:22:12furnace.set_zone({ furnace: "HT-1", zone: 2, delta: "-5 °C" })
  22. 06:58:40ok first hardness 30 HRC · inside 28 to 32
  23. 06:58:41mes.log_forging({ lot: "L-80412", genealogy: "full" })
  24. 07:00:01ok scenario complete · 10 steps · 0 laps escaped · released

Reasoning trace

Plan, thought, action, observation, exactly as the orchestrator would record it.

GoalRun the 42CrMo4 connecting-rod lot on cell F-2 inside the qual…

Run the 42CrMo4 connecting-rod lot on cell F-2 inside the qualified window, hold full fill with zero laps at the flash land, and land hardness between 28 and 32 HRC.

PlanSimulate heat-and-stroke recipes on the twin first. Lead with …

Simulate heat-and-stroke recipes on the twin first. Lead with heating so the billet state is right before the stroke, then set spray against die temperature, then execute the approved press schedule. Fuse inspection continuously. Hold any press-schedule change for a human.

ThoughtThe standing schedule runs the second blow hot enough to guara…

The standing schedule runs the second blow hot enough to guarantee fill on a cold billet. With the induction soak held at 1,205 °C the twin predicts the same fill at 3% less energy and lower flash-land lap risk, because the metal arrives more uniform.

Actiontwin.simulate(candidates=24) returns recipe #9: stage-3 induct…

twin.simulate(candidates=24) returns recipe #9: stage-3 induction power down 4%, lower-die spray up 6%, second-blow energy down 3%.

ObservationRecipe #9 predicts fill 1.00, lap risk 0.08 and 1.9 kWh per pi…

Recipe #9 predicts fill 1.00, lap risk 0.08 and 1.9 kWh per piece. Two candidates scored lower on energy but pushed predicted die load past the cavity-2 limit and were discarded.

ActionExecute recipe #9: seven bounded writes permitted on heating, …

Execute recipe #9: seven bounded writes permitted on heating, spray, handling and heat-treat; the press-schedule write routed to the shift forging engineer.

ObservationLap precursor at the flash land on piece 212 at 06:21:40. A 1.…

Lap precursor at the flash land on piece 212 at 06:21:40. A 1.5% blow-energy trim inside the approved envelope cleared it in 17 s; the piece was routed to MPI and passed.

OutcomeScenario complete. Fill confirmed, no laps escaped, hardness 3…

Scenario complete. Fill confirmed, no laps escaped, hardness 30 HRC. Lot L-80412 released with full genealogy.

Operations

Runbooks

What to do when.

Runbooks
SituationWhat happensWhat you do
Edge node offlineControl returns to the controller's last known-good state; interlocks unaffectedCheck the node, restore, resume at the current autonomy level
Model version fails canaryAutomatic fallback to the previous validated version on that cellReview the evaluation record before re-promoting
Approval not answeredThe step waits; the run does not time out into a writeNamed approver or delegate decides in the console
Deadlock between agentsEscalates to a human rather than resolving by timeoutDecide in the console; the decision is logged
Rollback condition metThe tag returns to its previous valueReview the trigger signal and the run record
Autonomy

Four levels, set per agent and per tag

A forge does not go from manual to unattended in one step. Forgiron 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 actions. Press control stays supervised until the part family is qualified.

Autonomy levels and the human role at each
LevelWhat the agent doesWhat the human doesWhere it sits in a pilot
L1 · ShadowReads thermal, vision, ultrasonic, MPI, press, die, robot and MES signals; predicts and recommends; writes nothingRuns the cell as today; compares predictions to inspection and engineer outcomesShadow mode, baseline 30 to 60 days
L2 · AssistProposes heating, press, die-lube, routing and handling actions with evidence, confidence, envelope and rollback pathApproves each action in the review consoleAssist mode, the remainder of a 90 to 180 day pilot
L3 · BoundedExecutes pre-approved low-risk actions: inspection routing, lube timing, heating and soak adjustments, robot path variants, inside PLC and safety limitsApproves press-schedule changes, die changes and lot releaseGraduated autonomy, after audited accuracy and ROI
L4 · ScaledSupervised press-schedule adaptation for qualified part families, across cells and sitesSets the envelope; reviews the shift record and the evaluation resultsPlanned; after golden-dataset evaluation, simulation validation and quality 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.

forgiron · cli · scenario 
$ forgiron run "lot CR-42CrMo4-118 on F-2" --autonomy L2+

→ plan composed          10 steps · 1 approval gate
→ twin.simulate          24 candidates · best #9 · lap risk 0.08
→ policy.evaluate        7 writes permitted · press_schedule held for human
→ executing              heat.soak ........ ok   2m10s
→ executing              die.spray ........ ok   48s
! approval required      press_schedule blow2 −3%
→ approved               shift forging engineer · 05:47:31
→ executing              forge.stroke ..... ok   1m36s
→ executing              inspect.fuse ..... ok   continuous
→ scenario complete      laps escaped 0 · lot L-80412 released

$ forgiron runs show run_7c2e41 --format genealogy
Limits

Platform limits and defaults

Design targets. None is a measured figure.

Platform limits and defaults
ItemDesign targetNotes
Edge inference, visual defect alertsunder 100 msJetson Orin at the cell, TensorRT
Decision latency, process recommendationsunder 500 msNon-emergency; includes policy evaluation
Cameras per line8 to 24DeepStream and Holoscan
Thermal streams10 to 50 HzBillet and die thermal cameras
Press, ram and force telemetry100 to 1,000 HzTime-series fusion
Training set, first models2 M labelled frames and signals20,000 heat and press cycles, 10,000 die-life events, 5,000 inspected defects per cohort
Synthetic scenarios100,000 per priority part familyOmniverse Replicator or Cosmos, validated against real distributions
Models served per plantRouted by latency, tenant, sensitivity and costTriton and NIM, canary by cell
Guardrails

An agent that can move a press schedule needs a leash

Forgiron writes to production equipment. Every capability is scoped, every write is policy-checked against the qualified envelope, and every action is written to an append-only audit log the forge owns.

  • Bounded action space. Each agent writes only to an explicit tag allow-list, inside per-tag rate and magnitude limits and the qualified process envelope for the part family.
  • Policy engine before every write. Autonomy level, shift, part family, interlock state and operator presence are evaluated before a setpoint moves.
  • Human-in-the-loop gates. Press-schedule changes, die changes and lot release wait for a named approver. Safety-critical press control stays guarded by PLC interlocks and engineer approval until qualification evidence supports more.
  • Immutable audit log. Append-only and exportable. Every action records source evidence, the approved process envelope, confidence, estimated yield, scrap, die-life and energy impact, rollback path, approver and lot scope.
  • Hard fallback. Loss of the edge node, the network or a model returns control to the furnace, press or die controller's last known-good state. Interlocks are never in Forgiron's path.
  • Tenant and die-IP isolation. Die designs, part drawings, alloy recipes and quality records never cross a customer boundary. On-prem deployment is available for sensitive producers.

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
AS9100 and NADCAP assurance packagesDisposition and genealogy evidence QUEUED Planned, 6 to 12 months; not a certification claim
Standards-cited reasoningAS9100, IATF 16949, NADCAP, ASTM documents RUNNING In the design, every answer cites its source
Per-tenant and die-IP isolationRecipes, die designs, models, memory RUNNING In the design from day one
On-prem and plant-edge deploymentSensitive producers RUNNING Design option

Read the security overview

FAQ

Straight answers

The questions plant directors, forging engineers and quality engineers ask in the first meeting.

Yes, but only within an explicit tag allow-list with per-tag rate and magnitude limits, inside the qualified process envelope, and only at the autonomy level your plant has set. Design partners start in shadow mode, where Forgiron writes nothing. Press-schedule changes stay supervised by a named forging engineer until the part family is qualified.

Get started

Get documentation access

Documentation beyond this page opens with the design-partner cohort.

Contact Developers