DevAgent Smart Physical Engine

Verification-first commissioning engineering: customer Twin import, measured physical evidence, deterministic requirement verification, change-impact regression, and FAT evidence for robotics and industrial automation.

AI proposes. Deterministic engines validate, compile, verify, measure, and gate promotion. OEM robot controllers, PLCs, safety PLCs, and certified safety systems remain authoritative.

DevAgent is designed to answer a commercial engineering question: before engineers travel onsite, what can be proven about this robot cell, what failed, what changed, and what evidence supports the conclusion?

Product workflow

CUSTOMER PROJECT / SITE / WORKCELL
                |
                v
CUSTOMER ASSETS + EXPLICIT TWIN EVIDENCE
                |
                v
IMMUTABLE TWIN REVISION
                |
                v
REQUIREMENTS
                |
                v
VERIFICATION PLAN
 nominal / boundary / pairwise / faults
                |
                v
MEASURED PHYSICAL EVIDENCE
 cycle / clearance / TCP / tracking / collision
                |
                v
DETERMINISTIC VERDICTS
 PASS / FAIL / NOT_TESTED
                |
                v
CHANGE IMPACT + REGRESSION
                |
                v
FAT REPORT
 Markdown / HTML / JSON

Unknown facts stay unknown. Unsupported requirements stay NOT_TESTED. A CAD/URDF/mesh file does not prove its pose, scale, TCP, calibration, or physics merely because the file exists.

Install

Python 3.11+:

python -m pip install devagent-physical-engine

Optional AI providers:

python -m pip install "devagent-physical-engine[openai]"
python -m pip install "devagent-physical-engine[anthropic]"
python -m pip install "devagent-physical-engine[gemini]"
python -m pip install "devagent-physical-engine[ai]"

pip install does not install ROS 2, Gazebo, MoveIt, OEM drivers, or privileged OS packages.

Commercial quick start

Create project identity:

devagent-commercial init warehouse-cnc-04 \
  --name "Warehouse CNC Loading Cell 04" \
  --site atl-01 \
  --workcell cnc-04

Import customer Twin evidence:

devagent-commercial import-twin warehouse-cnc-04 ./customer-cell

Supported inventory includes .urdf, .xacro, .srdf, .stl, .dae, .obj, .step, .stp, .iges, .igs, .yaml, .yml, .json, and .csv. Assets are SHA-256 fingerprinted using bounded streaming I/O. Physical facts are promoted only through an explicit devagent-twin.yaml|yml|json evidence manifest.

Import requirements:

devagent-commercial requirements warehouse-cnc-04 requirements.csv

Generate a deterministic verification plan:

devagent-commercial verification-plan warehouse-cnc-04 verification-plan.yaml \
  --revision twin-r0001

Record measured evidence produced by a simulation/hardware-shadow qualification run:

devagent-commercial record-measurement warehouse-cnc-04 physical-measurement.json \
  --revision twin-r0001

Run requirements against the exact Twin and measurement artifact:

devagent-commercial campaign warehouse-cnc-04 requirements.csv \
  --revision twin-r0001 \
  --measurement art-PHYSICAL

After a Twin revision changes, compute conservative impact:

devagent-commercial impact warehouse-cnc-04 \
  twin-r0001 twin-r0002 requirements.csv

Compare baseline/current campaigns:

devagent-commercial regression warehouse-cnc-04 \
  art-BASELINE art-CURRENT \
  --impact art-IMPACT

Generate customer evidence as Markdown, HTML, or JSON:

devagent-commercial fat-report warehouse-cnc-04 art-CURRENT \
  --regression art-REGRESSION \
  --output FAT_REPORT.html

Inspect readiness and evidence:

devagent-commercial status warehouse-cnc-04
devagent-commercial artifacts warehouse-cnc-04

Default evidence database:

~/.devagent/projects.db

Deterministic requirement checks

Structural/Twin checks:

• planning_allowed
• physics_allowed
• entity_present
• validation_issue_absent
• twin_state

Measured physical checks:

• cycle_time_max_s
• minimum_clearance_m
• final_tcp_error_max_m
• max_tracking_error_rad
• collision_free
• physical_completed

Example:

requirement_id,text,check,target,expected,severity
REQ-001,Twin shall be physics ready,physics_allowed,,true,must
REQ-101,Cycle time shall be <= 8 s,cycle_time_max_s,8.0,,must
REQ-102,Minimum clearance shall be >= 30 mm,minimum_clearance_m,0.03,,must
REQ-103,Final TCP error shall be <= 2 mm,final_tcp_error_max_m,0.002,,must
REQ-104,Trajectory shall be collision free,collision_free,,true,must

A physical requirement without exact-Twin measured evidence is NOT_TESTED; it cannot be promoted by an LLM.

Evidence trust and readiness

DevAgent separates three claims:

• customer_review_ready: the bounded declared/imported scope and mapped requirements passed.
• production_engineering_ready: mapped physical requirements passed with exact-Twin measurement evidence and explicit run/qualification provenance.
• site_qualification / real_execution_allowed: remain false in this release.

production_engineering_ready is engineering evidence readiness, not functional-safety certification or commissioning authorization. Simulation evidence does not override guarding, risk assessment, safety PLC validation, OEM controller validation, site acceptance, or engineer sign-off.

The typed Python API can bind PhysicalMotionPlan + MotionExecutionMetrics directly into project evidence so runtime-owned metrics do not have to be manually retyped into free-form JSON.

Physical simulation

The qualified reference direction remains Ubuntu 24.04 + ROS 2 Jazzy + Gazebo Harmonic + gz_ros2_control + Universal Robots ROS 2 driver + ur_simulation_gz + MoveIt 2.

devagent-physical setup --profile ur5e-sim --dry-run
devagent-physical setup --profile ur5e-sim
devagent-physical ros doctor
devagent-physical ros qualify-trajectory-runtime

Hosted Python CI cannot prove a graphical Gazebo/MoveIt/controller stack. Target physical-simulation qualification must run on the exact workstation/adapter stack. Registry entries for ABB, FANUC, KUKA, or other robots do not imply equal physical qualification.

Release quality

Every PR/main update runs Python 3.11/3.12/3.13 regression, compilation, Ruff correctness checks, branch coverage, package build, clean wheel install, and runtime dependency audit. Production-grade authority contracts also have a dedicated high-coverage gate.

Releases are created only from exact green main, rebuilt from the exact tag, clean-installed, accompanied by CycloneDX SBOM + SHA-256 checksums, attached to GitHub Release, and published to PyPI through Trusted Publishing.

Documentation

• Production Grade v1.1
• Production readiness
• Commercial V1
• Commercial project spine
• Architecture
• Robot platform and Twin
• Measured physical runtime
• Qualification
• Optimization
• AI providers
• PyPI release process

Project status

v1.1.0 — Production/Stable software workflow with measured physical requirement evidence, deterministic verification-plan generation, change-impact regression, and customer FAT Markdown/HTML/JSON reporting.

Production/Stable applies to the bounded software/API/CLI/evidence workflow. Physical qualification remains robot-, adapter-, workstation-, and evidence-specific. Site qualification, functional-safety certification, and production-hardware command authority are not claimed and remain locked by default.

Ownership

DevAgent Smart Physical Engine
Copyright © 2026 Tom Ha
Original creator: Tom Ha
Original project: https://github.com/tomha85/devagent-physical-engine
All rights reserved.