DevAgent Smart Physical Engine

Verification-first commercial engineering, customer Twin import, requirement traceability, regression analysis, and FAT evidence for robotic and industrial automation.

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

DevAgent Smart Physical Engine helps an engineer move from a customer workcell definition to evidence-backed engineering review without giving an LLM direct robot-control authority. Commercial V1 adds a durable customer workflow around the existing provider-neutral AI, canonical physical Twin, ROS 2 / Gazebo / MoveIt simulation, deterministic verification, and evidence infrastructure.

Commercial V1 outcome

A customer project can now be handled as one durable evidence chain:

CUSTOMER PROJECT / SITE / WORKCELL
                |
                v
CUSTOMER FILE INVENTORY + devagent-twin MANIFEST
                |
                v
CANONICAL TWIN + IMMUTABLE twin-r000N REVISION
                |
                v
REQUIREMENT SET
                |
                v
DETERMINISTIC REQUIREMENT CAMPAIGN
                |
                v
REGRESSION COMPARISON
                |
                v
CUSTOMER-READY FAT EVIDENCE REPORT

The commercial workflow is intentionally fail-closed. A CAD, URDF, mesh, YAML, or CSV file being present does not prove a robot base pose, TCP, dimension, coordinate frame, collision model, calibration, or physics property. Those facts must be explicitly declared or measured before DevAgent promotes them as engineering evidence.

Install

Python 3.11+ is required.

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]"
# or all supported provider SDKs
python -m pip install "devagent-physical-engine[ai]"

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

Commercial quick start

Create durable customer identity:

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

Import a customer folder:

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

The folder may contain supported engineering assets such as:

customer-cell/
├── devagent-twin.yaml
├── robot.urdf
├── robot.srdf
├── meshes/
│   ├── gripper.stl
│   └── fixture.stl
└── notes-or-export.json

Commercial V1 inventories .urdf, .xacro, .srdf, .stl, .dae, .obj, .step, .stp, .iges, .igs, .yaml, .yml, .json, and .csv files. Customer assets are SHA-256 fingerprinted with bounded streaming I/O; individual inventoried assets are limited to 512 MiB. A devagent-twin.yaml, devagent-twin.yml, or devagent-twin.json manifest is required before file inventory becomes physical Twin evidence.

If the manifest or required physical facts are missing, DevAgent returns needs_information with explicit engineering questions instead of inventing values.

Import requirements:

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

Run deterministic requirement verification against the latest Twin revision:

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

Or bind the campaign to an exact immutable revision:

devagent-commercial campaign warehouse-cnc-04 requirements.csv \
  --revision twin-r0002

Compare a previous campaign with a current campaign:

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

Generate a FAT Markdown report:

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

Inspect commercial readiness and immutable evidence:

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

The default commercial evidence database is:

~/.devagent/projects.db

Customer Twin manifest

Commercial V1 is manifest-driven so engineering facts have explicit provenance. A minimal structure is:

schema_version: 1
length_unit: mm
angle_unit: deg

engineering_request:
  robot: ur5e
  operation: load
  object_id: BOX_101
  source: conveyor_a
  destination: cnc_04
  tool: parallel_gripper
  payload_kg: 1.5
  purpose: simulate

robot_base_pose:
  x: 0
  y: 0
  z: 0
  origin: measured
  source_ref: site-survey

entities:
  - id: conveyor_a
    type: conveyor
    pose: {x: 700, y: 0, z: 850}
    geometry:
      kind: box
      dimensions: [2000, 600, 800]

  - id: cnc_04
    type: machine
    pose: {x: 1200, y: 400, z: 0}
    geometry:
      kind: box
      dimensions: [1400, 1200, 1800]

  - id: BOX_101
    type: workpiece
    pose: {x: 700, y: 0, z: 900}
    geometry:
      kind: box
      dimensions: [200, 100, 50]

tool:
  id: parallel_gripper
  tcp:
    x: 0
    y: 0
    z: 180
    origin: measured
  geometry:
    kind: box
    dimensions: [120, 80, 200]
  max_payload_kg:
    value: 5.0
    origin: imported

A mesh can be referenced by relative asset path, for example:

geometry:
  kind: mesh
  asset: meshes/fixture.stl

The referenced file must have been discovered inside the customer source root. Absolute paths, .. traversal, and symlinked customer assets are rejected.

Requirement traceability

CSV example:

requirement_id,text,check,target,expected,severity
REQ-001,Twin shall be planning ready,planning_allowed,,true,must
REQ-002,Workpiece shall exist,entity_present,BOX_101,true,must
REQ-003,Unit mismatch shall be absent,validation_issue_absent,possible_unit_mismatch,true,must

Commercial V1 deterministic checks are deliberately small and auditable:

• planning_allowed
• physics_allowed
• entity_present
• validation_issue_absent
• twin_state

A prose requirement without a supported deterministic check is reported as NOT_TESTED. It is never auto-passed by an LLM. A required (must) item that fails or remains untested blocks customer-review readiness.

Evidence and regression

Project, Twin, import, campaign, regression, and FAT artifacts are stored with stable identities and content hashes. Twin revisions are monotonic and immutable (twin-r0001, twin-r0002, ...).

Regression analysis explicitly identifies a requirement that changed from PASS in the baseline campaign to any non-pass state in the current campaign. A regression blocks release readiness.

The FAT report includes project/site/workcell identity, exact Twin revision and hash, requirement counts, pass/fail/not-tested results, coverage, regression state, and bounded release readiness.

READY FOR CUSTOMER REVIEW means the declared/imported Twin scope and mapped deterministic requirements passed the commercial evidence gates. It does not mean functional-safety certification, site qualification, commissioning approval, or permission to move a production robot.

AI engineering layer

The runtime remains provider-neutral. OpenAI, Anthropic, and Gemini can be used for interpretation, planning, critique, and recovery while deterministic code owns schema validation, semantic policy, Twin validation, collision/clearance contracts, evidence, qualification, and execution gating.

Check a provider:

devagent-physical-ai doctor --provider openai

Run an engineering request:

devagent-physical-ai engineer \
  "Use a UR5e to load BOX_101 from conveyor_a to cnc_04. Simulate and verify the plan." \
  --provider openai \
  --model <model-id>

Use --quiet for machine-readable JSON without progress messages on stdout.

Physical simulation

The repository retains the evidence-gated ROS 2 / Gazebo / MoveIt physical simulation stack and the packaged UR5e reference workcell. The reference stack target is:

Ubuntu 24.04
ROS 2 Jazzy
Gazebo Harmonic
gz_ros2_control
Universal Robots ROS 2 driver
ur_simulation_gz
MoveIt 2

Useful commands:

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

Hosted Python CI cannot truthfully exercise a graphical Gazebo process, MoveIt move_group, TF, ROS controllers, or Gazebo services. Those paths retain separate executable target qualification. A registry entry for FANUC, KUKA, ABB, or another robot family does not imply identical physical simulation qualification.

Safety and authority boundary

Commercial V1 is an engineering verification product, not a safety controller. It intentionally preserves these boundaries:

AI / COMMERCIAL WORKFLOW
        |
        v
DETERMINISTIC DEVAGENT EVIDENCE
        |
        v
SIMULATION / ENGINEERING REVIEW
        |
        X
NO AUTOMATIC PRODUCTION-HARDWARE AUTHORITY

Simulation success does not override OEM controllers, PLC interlocks, safety PLCs, risk assessments, guarding, functional-safety validation, site commissioning procedures, or engineer approval.

Commercial outputs therefore continue to report:

site_qualification=false
real_execution_allowed=false

unless a separately implemented and evidence-qualified authority path explicitly proves otherwise. Commercial V1 does not add such a path.

Software verification and releases

Repository CI verifies Python 3.11, 3.12, and 3.13, compilation, unit regression, Ruff correctness, branch coverage, package build, clean wheel installation, and runtime dependency vulnerability audit.

A green main release is tied to the exact CI-tested commit. Release artifacts are rebuilt from the exact tag, checked with Twine, clean-installed, accompanied by a CycloneDX runtime SBOM and SHA-256 checksums, attached to the GitHub Release, and published to PyPI through Trusted Publishing with digital attestations.

Documentation

• Commercial V1
• Commercial project spine
• Production readiness
• Architecture
• Agent Core
• AI providers
• Natural-language engineering
• Robot platform and Twin
• Measured physical runtime
• Qualification
• Optimization
• Workstation setup
• PyPI release process

Project status

v1.0.0 — Production/Stable software / commercial engineering workflow with evidence-gated customer Twin import, requirement traceability, regression analysis, and FAT reporting.

Production/Stable describes the shipped software/API/CLI and release process for the bounded V1 scope. Physical and site readiness remain evidence- and adapter-specific. Arbitrary CAD/URDF content is inventoried and fingerprinted but is not semantically trusted merely because a file exists; customer physical facts are promoted only through explicit manifest/evidence contracts. Real robot execution remains locked by default. Functional-safety certification and customer-site commissioning are not claimed.

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.