DevAgent Smart Physical Engine

Verification-first commissioning engineering for robotics and industrial automation.

DevAgent turns a customer engineering folder into a bounded verification workflow with immutable Digital Twin lineage, deterministic requirement verdicts, requirement-driven test cases, exact-Twin measured simulation evidence, regression analysis, FAT reporting, replay inspection, and selective retesting.

customer engineering files
    ↓
intake + SHA-256 inventory
    ↓
validated Requirement → Criterion mapping
    ↓
immutable Digital Twin revision
    ↓
requirement-driven nominal / boundary / fault cases
    ↓
qualified exact-Twin simulation when supported
    ↓
measured evidence
    ↓
PASS / FAIL / NOT_TESTED
    ↓
regression + FAT report + Evidence Viewer

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

Quick start

Python 3.11+ is required.

python -m pip install --upgrade devagent-physical-engine==1.7.1

Verify the installed package:

python -c "import devagent_physical_engine as d; print(d.__version__)"

Expected:

1.7.1

Run the normal customer workflow:

devagent verify ./customer-project

Request simulation:

devagent verify ./customer-project --simulate

Open the Evidence Viewer and keep the engineering terminal active:

devagent verify ./customer-project --simulate --open

For machine-readable CI output:

devagent verify ./customer-project --json

Default locations:

Evidence database: ~/.devagent/projects.db
Results:           <customer-project>/devagent-results/

What DevAgent proves

DevAgent separates planning, execution, measurement, verdicts, and authority.

requirement
  ↓
verification criterion
  ↓
verification case
  ↓
exact Twin revision/hash
  ↓
qualified simulation when available
  ↓
measured evidence
  ↓
PASS / FAIL / NOT_TESTED

A generated plan is not physical proof. A replay is not a new execution. A simulation result does not grant site qualification or real-robot authority.

Current hard boundaries remain:

site_qualification = false
real_execution_allowed = false

unless separately proven by an appropriate qualified process.

v1.6 report-test visual execution foundation

v1.6 connected report tests to the exact stored Twin instead of a separate demo scene.

A supported physical report test follows:

Requirement
  → stable Test ID
  → immutable Requirement → Case mapping
  → exact Verification Plan ID/hash
  → exact Case ID
  → exact Twin revision/hash
  → qualified Gazebo/MoveIt execution
  → typed physical_measurement artifact
  → deterministic verdict

Interactive example:

devagent> tests
devagent> simulate TEST-PERF-001

Measured physical criteria include:

cycle_time_max_s
minimum_clearance_m
final_tcp_error_max_m
max_tracking_error_rad
collision_free
physical_completed

Structural/Twin criteria include:

planning_allowed
physics_allowed
entity_present
validation_issue_absent
twin_state

A requirement without deterministic evidence remains NOT_TESTED; it is never auto-passed from prose or AI interpretation.

v1.6.1 support-contact lift hotfix

The packaged UR5e reference load starts with the workpiece resting on its source support. During attached-object lift departure, DevAgent preserves the complete live MoveIt Allowed Collision Matrix and temporarily enables exactly the attached-workpiece ↔ source-support pair.

That allowance is scoped only to lift departure. Transfer/place keep normal collision checking. DevAgent does not globally disable collision checking or replace the live matrix with an unsafe sparse matrix.

v1.6.2 slower measured visual execution

The packaged visual task uses conservative MoveIt scaling so motion is inspectable while remaining real trajectory execution:

velocity scale:      12%
acceleration scale:   8%

The joint-state recorder also rejects duplicate/backward ROS timestamps instead of manufacturing synthetic time. Collision, endpoint, tracking, Twin-lineage, and authority checks remain fail-closed.

v1.7 industrial PTP/LIN execution

v1.7 moves the qualified UR5e report test to the MoveIt Pilz Industrial Motion Planner rather than hand-building interpolation.

The bounded task sequence is:

HOME
  ↓ PTP
PRE_PICK
  ↓ LIN
PICK
  ↓ grasp hard boundary
LIFT
  ↓ LIN support departure hard boundary
TRANSFER
  ↓ PTP
PLACE
  ↓ LIN release hard boundary
RETRACT
  ↓ LIN
HOME
  ↓ PTP

Execution groups:

approach_pick    PTP → LIN
lift_departure   LIN
transfer_place   PTP → LIN
retreat_home     LIN → PTP

Conservative limits:

PTP velocity scale:       10%
PTP acceleration scale:    6%
LIN velocity scale:        6%
LIN acceleration scale:    4%
requested blend radius:   12 mm
workpiece follow target:   60 Hz

MoveIt/Pilz owns geometry, timestamps, collision checking, velocity/acceleration time parameterization, and the returned RobotTrajectory. DevAgent does not fake smoothness with teleports or sleeps.

v1.7.1 adaptive Pilz blend hotfix

A real ROS 2 Jazzy + Gazebo Harmonic + MoveIt/Pilz target-stack run showed:

approach_pick    PASS
lift_departure   PASS
transfer_place   Pilz FAILURE(99999)
execution        NOT STARTED

Pilz can reject a sequence when a requested blend sphere is not feasible for that specific geometry. v1.7.1 therefore keeps the same PTP/LIN targets, attached/world scene contract, collision policy, velocity/acceleration limits, and execution authority while retrying only the internal blend radius:

12 mm
  ↓ if Pilz returns pilz_sequence_planning_failed
6 mm
  ↓
3 mm
  ↓
0 mm

Every candidate is still planned and collision-checked by MoveIt/Pilz. DevAgent selects the largest candidate Pilz actually accepts. If the zero-blend candidate fails, execution remains blocked.

The fallback is intentionally narrow:

no target modification
no planner-type substitution
no collision disable
no speed increase
no hand-built interpolation
no fake PASS
no fallback to an unqualified simulator or robot

The selected blend radii and every planning attempt receipt remain attached to motion metadata for auditability.

Qualified visual-execution scope

The packaged visual executor remains intentionally narrow:

robot:       UR5e
operation:   load
case scope:  one nominal mapped physical report case
runtime:     Ubuntu 24.04 + ROS 2 Jazzy + Gazebo Harmonic + MoveIt/Pilz

Unsupported customer Twins, unqualified robot profiles, boundary/fault cases outside the qualified scope, ambiguous case mappings, or incomplete lineage fail closed.

Cross-vendor projects such as ABB may still be imported, normalized, structurally evaluated, and reported, but they do not silently enter the UR5e-only physical executor.

Interactive engineering session

Use --interactive, or --open from a real terminal, to keep a bounded prompt:

status
tests
test SELECTOR
simulate [SELECTOR]
rerun [SELECTOR]
rerun failed
rerun blocked
rerun affected
replay
report
log
help
quit

Selectors can be requirement IDs, test IDs, or bounded groups:

REQ-PERF-001
TEST-PERF-001
failed
blocked
affected
all

test SELECTOR evaluates deterministic/evidence checks without commanding the simulator.

simulate TEST-X requests qualified execution of the selected mapped physical report case.

replay reconstructs persisted evidence identity; it never commands Gazebo, MoveIt, a robot, PLC, or safety PLC.

Customer input

A customer folder can contain the engineering material the team already has:

ACME_CNC_CELL_TEST/
├── project.yaml
├── requirements.xlsx
├── devagent-twin.yaml
├── robot.urdf
├── robot.urdf.xacro
├── robot.srdf
├── tcp.yaml
├── calibration.yaml
├── layout/
│   ├── cell_layout.yaml
│   └── meshes/
├── robot_program/
│   └── mission.yaml
└── expected/
    └── expected_findings.json

Important rule:

file discovered != engineering fact proven

DevAgent fingerprints and classifies files, but filenames do not prove poses, TCPs, calibrations, collision geometry, safety behavior, or physical performance.

The root expected/ folder is test-oracle material and is never promoted as engineering authority.

If critical information is missing or ambiguous, DevAgent writes questions into the project results instead of guessing.

Results and evidence

Typical output:

customer-project/
└── devagent-results/
    ├── RUN.log
    ├── SUMMARY.json
    ├── INTAKE.json
    ├── QUESTIONS.md
    ├── normalized/
    │   ├── requirements.csv
    │   └── devagent-twin.yaml
    ├── report-test-visualization/
    ├── FAT_REPORT.html
    └── EVIDENCE.html

EVIDENCE.html is read-only engineering evidence. RUN.log is a human debug/progress trace and does not replace immutable evidence artifacts.

Repeat runs compare the immediately previous campaign with the current campaign before a new FAT artifact is finalized.

Physical simulation setup

pip install does not install ROS 2, Gazebo, MoveIt, OEM drivers, or privileged operating-system packages.

Reference stack:

Ubuntu 24.04
ROS 2 Jazzy
Gazebo Harmonic
gz_ros2_control
Universal Robots ROS 2 driver
ur_simulation_gz
MoveIt 2 + Pilz Industrial Motion Planner

Preview setup:

devagent-physical setup --profile ur5e-sim --dry-run

Apply explicitly:

devagent-physical setup --profile ur5e-sim --yes

Check runtime:

devagent-physical ros doctor

Hosted CI validates deterministic software contracts. It does not pretend to execute a graphical ROS/Gazebo/MoveIt target stack. Target-stack acceptance must run on the intended workstation.

Optional AI providers

AI is optional and advisory.

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]"

Typical credentials:

export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."
export GEMINI_API_KEY="..."

Provider-backed interpretation cannot grant physical truth, site qualification, functional-safety certification, or real-execution authority.

Installed CLIs

devagent             one-command customer verification + interactive report testing
devagent-commercial  commercial/evidence workflow
devagent-physical    deterministic core + ROS/qualification tools
devagent-physical-ai optional provider-backed engineering front end

Simple Mode exit codes

Project status

v1.7.1 — Production/Stable software workflow

v1.7.1 retains the v1.7 industrial Pilz PTP/LIN execution architecture and adds fail-closed adaptive blend selection for geometry-specific Pilz sequence failures. It also retains the cross-vendor profile gate so non-UR5e customer Twins cannot enter the UR5e-only qualified visual executor.

Production-oriented software capabilities include:

one-command customer intake
XLSX requirement normalization
validated Requirement → Criterion mapping
optional provider-backed advisory criterion proposals
requirement-driven nominal / boundary / fault case generation
immutable project/Twin lineage
exact Requirement → Mapping → Verification Plan → Case provenance
qualified report-test visual execution contract
industrial Pilz PTP / LIN planning
adaptive bounded blend selection
lift-only support-contact ACM lease + exact restore
Gazebo/MoveIt selected-case visualization
typed physical measurement binding
deterministic campaigns
repeat-run regression
professional FAT / Evidence Viewer
interactive selective verification
Evidence Bundle + replay
change impact + regression
provider-neutral optional AI front end

Production/Stable describes the bounded software workflow. It does not claim arbitrary customer cells are physically qualified, site-qualified, functionally safe, or authorized for autonomous real execution.

Documentation

One-command verification: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ONE_COMMAND_VERIFY_V13.md

Report-test visual execution foundation: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/REPORT_TEST_VISUAL_EXECUTION_V16.md

Evidence Trust / replay / viewer: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/EVIDENCE_TRUST_V12.md

Measured physical runtime: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/MEASURED_PHYSICAL_RUNTIME.md

Commercial project spine: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMERCIAL_PROJECT_SPINE.md

Architecture: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ARCHITECTURE.md

Canonical Twin runtime: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/CANONICAL_TWIN_RUNTIME.md

Laptop acceptance: https://github.com/tomha85/devagent-physical-engine/blob/main/docs/LAPTOP_ACCEPTANCE.md

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.

See repository LICENSE, NOTICE, and COPYRIGHT for complete ownership and usage terms.