DevAgent Smart Physical Engine

Verification-first agentic engineering, planning, simulation, optimization, and evidence for robotic and industrial automation.

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

DevAgent Smart Physical Engine turns an engineering request into a bounded, evidence-backed automation plan without giving an LLM direct robot-control authority. It is designed for engineers who want to reason about robot tasks, generate and critique plans, build a canonical physical Twin, simulate through ROS 2 / Gazebo / MoveIt, measure results, and preserve verification evidence before anything reaches real equipment.

The runtime is provider-neutral. OpenAI, Anthropic, and Gemini can be used for interpretation, planning, critique, and recovery while deterministic code remains responsible for safety boundaries, compilation, verification, physical evidence, qualification, and execution policy.

Why DevAgent Physical Engine?

Many AI robotics demos stop after producing a plan or showing a robot moving. DevAgent Physical Engine is built around a stricter question:

Can this robotic engineering claim be supported by deterministic checks and measured evidence for the exact plan and physical model being evaluated?

Core principles:

• Evidence before promotion — missing physical evidence blocks stronger claims instead of being silently assumed.
• Provider-neutral AI — model output proposes engineering intent; it does not own collision truth, qualification, or real-hardware authorization.
• Deterministic verification — task graphs, motion contracts, collision constraints, scene state, and promotion gates are checked outside the model.
• Exact Twin binding — physical motion is bound to a canonical Twin and immutable fingerprints rather than free-form model text.
• Measured simulation — supported ROS 2 / Gazebo / MoveIt paths collect runtime evidence instead of treating a generated plan as proof.
• No fake task visualization — generic demo motion is never labeled as the requested BOX/source/destination task.
• Real execution remains locked — simulation success is not site qualification, functional-safety certification, or permission to run production hardware.

Install

Python 3.11+ is required.

From PyPI:

python -m pip install devagent-physical-engine

Install one AI provider:

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 install all supported provider SDKs:

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

For development from source:

git clone https://github.com/tomha85/devagent-physical-engine.git
cd devagent-physical-engine
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev,ai]"

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

Quick start

Configure the credential for the provider you want to use:

export OPENAI_API_KEY='...'
# or ANTHROPIC_API_KEY / GEMINI_API_KEY

Check the provider locally:

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>

While the command runs, stage-by-stage progress is printed to stderr and the final machine-readable result remains on stdout:

[DevAgent +   0.00s] START        provider=openai model=<model-id>
[DevAgent +   0.00s] INTERPRETER  understanding engineering request
[DevAgent +   4.20s] PLANNER      revision=0 generating high-level task graph
[DevAgent +  10.30s] CRITIC       revision=0 reviewing verified plan
[DevAgent +  13.10s] SIMULATION   deterministic model execution completed
[DevAgent +  13.11s] COMPLETE     ready_for_twin_simulation=true

Use --quiet when a script or CI job needs JSON without terminal progress.

Task-specific visual simulation

For the supported v0.12 UR5e load scope, --visualize continues from the verified high-level task into a physical simulation path:

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> \
  --visualize

The current task-specific path uses the packaged ur5e_reference_load_cell_v1 canonical workcell. The request identities remain exact (BOX_101, conveyor_a, cnc_04), while the reference source/destination poses, primitive geometry, nominal workpiece geometry, and reference tool are deterministic template facts rather than guessed customer-site facts.

The runtime then performs this bounded sequence:

validated AI task graph
        |
        v
packaged canonical UR5e load Twin
        |
        v
Gazebo + MoveIt world materialization and read-back
        |
        v
MoveIt FK cross-check of reference pick/place targets
        |
        v
MoveIt joint-space plan for each physical phase
        |
        v
pre-pick -> pick -> attach BOX -> lift -> transfer -> place
        |
        v
BOX visually follows tool0 while attached in Gazebo
        |
        v
verified destination pose -> detach -> retract -> home
        |
        v
measured motion/evidence report

On a successful run, Gazebo / MoveIt remains open by default so the engineer can inspect the final workcell. Add --close-after to close it after success.

v0.12.1 hardens the initial ROS joint-state snapshot by parsing ros2 topic echo --once output as a YAML document stream. This accepts the normal ROS 2 trailing --- message separator instead of incorrectly classifying an otherwise valid /joint_states sample as joint_state_snapshot_invalid.

v0.12.2 additionally hardens Gazebo model-pose read-back across Harmonic CLI renderings. One shared parser now accepts both pipe-delimited and whitespace-delimited finite XYZ/RPY vectors and is used by initial world verification and dynamic workpiece pose read-back, so task simulation does not depend on a single human-readable gz model --pose delimiter style.

v0.12.3 hardens MoveIt PlanningScene read-back when MoveIt serializes world collision objects in its own planning/root frame. A different observed frame is never trusted by label alone: DevAgent first proves the observed frame and canonical Twin frame are identity-equivalent through TF, then re-reads the scene and canonicalizes it back to the Twin planning frame before enforcing the exact geometry hash. Non-identity frames and geometry drift remain fail-closed.

v0.12.4 hardens attached-tool collision read-back against equivalent MoveIt CollisionObject pose decompositions. DevAgent now composes the object pose with the primitive pose, canonicalizes equivalent quaternion signs before hashing, and still requires the exact attachment link, object frame, shape, dimensions, operation, and effective geometry. Exact probe evidence is preserved beside the tool payload for target diagnostics; representation-only changes no longer create false mismatches, while physical geometry drift remains fail-closed.

The packaged reference workcell is not customer-site geometry. Arbitrary plant layouts require an imported or user-declared physical Twin with trusted poses, collision geometry, tool/TCP information, and workpiece properties. DevAgent does not invent those site facts from a natural-language prompt.

The v0.12 implementation remains evidence-gated: source/CI success does not prove the ROS target campaign has passed on a particular workstation. Use the executable qualification below before treating the task-specific path as qualified on that target.

Visual stack demo

To test only that the workstation can launch Gazebo / MoveIt and visibly move a UR5e, without claiming that motion represents the requested BOX task, use:

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> \
  --visual-demo

--visual-demo is explicitly reported as task_specific=false.

How it works

A normal engineering flow is intentionally layered:

NATURAL-LANGUAGE ENGINEERING REQUEST
                |
                v
PROVIDER-NEUTRAL INTERPRETER
                |
                v
PLANNER -> DETERMINISTIC COMPILE / VERIFY <- CRITIC
                |
                v
VERIFIED HIGH-LEVEL TASK GRAPH
                |
                v
CANONICAL PHYSICAL TWIN + IMMUTABLE HASH
                |
                v
MOVEIT-COMPILED PHYSICAL MOTION CONTRACTS
                |
                v
GAZEBO / MOVEIT MATERIALIZATION + READ-BACK
                |
                v
COLLISION / TOOL / WORKPIECE VERIFICATION
                |
                v
ROS 2 SIMULATION + MEASURED RUNTIME EVIDENCE
                |
                v
REPLAYABLE EVIDENCE + PROMOTION GATES
                |
                v
REAL HARDWARE AUTHORIZATION REMAINS SEPARATELY LOCKED

The high-level AI task graph and the physical motion plan are not the same artifact. A pick -> move -> place graph is engineering intent. Gazebo execution requires a physically grounded Twin and compiled trajectory. This separation prevents an AI-generated task description from becoming an implicit motor command.

For a nominal low-risk load simulation, the Critic remains advisory after deterministic compilation and verification. If it repeatedly requests subjective revisions but never rejects the plan, DevAgent may use a bounded deterministic advisory fallback after the revision budget is exhausted. A Critic REJECT, deterministic violation, higher-risk qualification/commissioning intent, fault injection, physical variation, or explicit engineering threshold still blocks that fallback.

General architecture

The architecture has three authority layers:

+--------------------------------------------------------------+
|                    ENGINEER / CUSTOMER                       |
|      requirement, robot, object, source, destination         |
+-------------------------------+------------------------------+
                                |
                                v
+--------------------------------------------------------------+
|                 AI ENGINEERING LAYER                         |
| Interpreter | Planner | Critic | Recovery                    |
| OpenAI / Anthropic / Gemini                                  |
| Proposes intent and candidates; owns no physical authority.  |
+-------------------------------+------------------------------+
                                |
                                v
+--------------------------------------------------------------+
|             DEVAGENT DETERMINISTIC CORE                      |
| Request validation | Compiler | Semantic policy              |
| TwinSpec | Motion contract | Collision / clearance           |
| Tool/workpiece state | Simulation measurement | Evidence     |
| Qualification and promotion gates                            |
+-------------------------------+------------------------------+
                                |
                                v
+--------------------------------------------------------------+
|               PHYSICAL SIMULATION ADAPTERS                   |
| ROS 2 | Gazebo | MoveIt | robot-specific adapters            |
| Scene materialization, trajectory execution, measured state  |
+-------------------------------+------------------------------+
                                |
                                v
+--------------------------------------------------------------+
|             OEM CONTROLLER / PLC / SAFETY                    |
| Remains authoritative for real equipment and safe execution. |
| DevAgent real execution is locked by default.                |
+--------------------------------------------------------------+

This plain-text diagram is intentionally used instead of Mermaid so the same README renders correctly on GitHub and PyPI.

Physical Twin and verification

The canonical Twin records robot identity, frames, source/destination entities, workpiece, tool, geometry, physics evidence, controller metadata, uncertainty, and provenance. Unknown physical information remains unknown rather than being filled with AI guesses.

The UR5e canonical adapter can bind one materialization to Gazebo and MoveIt, verify world/scene read-back, apply a runtime-owned tool collision object, verify workpiece attach/detach transitions, execute compiled joint trajectories, record joint states, and compute MoveIt FK metrics.

The stronger production-candidate verifier can additionally use measured collision distance and conservative continuous-path clearance proof. A stronger pre-execution receipt requires evidence such as:

verified=true
continuous_collision_check=true
clearance_measured=true
minimum_clearance_m > 0
materialization_hash=<exact Twin materialization>
failure_codes=[]

The conservative collision-distance bound must be qualified for the exact robot/tool/collision model. DevAgent does not invent that bound.

Supported robot abstraction

The deterministic robot-profile layer includes abstractions for:

• Universal Robots UR5e
• FANUC CRX family
• KUKA KR family
• ABB IRB family

Physical simulation and qualification are adapter- and vendor-specific. The v0.12 task-specific visible load runtime is UR5e-specific. A profile existing in the registry does not imply equivalent physical qualification for every vendor.

ROS 2 / Gazebo reference target

Reference workstation stack:

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

Setup and diagnostics:

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

Run the v0.12 task-specific target qualification:

python -m devagent_physical_engine.ros2.qualification_v12

This must visibly execute the reference task and produce a passing report before the target workstation's v0.12 task-specific ROS simulation is considered qualified. It still intentionally reports:

physical_qualification=false
commissioning_qualification=false
site_qualification=false
real_execution_allowed=false

For the stronger continuous-clearance production-candidate campaign:

python -m devagent_physical_engine.ros2.qualification_v11 \
  --moveit-params-file /path/to/ur5e_moveit_params.yaml \
  --distance-lipschitz <qualified-m-per-radian-bound> \
  --safety-margin 0.005 \
  --log-dir ~/.devagent/v11-production-candidate-qualification

A successful source/workstation campaign can qualify specific simulation evidence. It still does not automatically imply physical commissioning, site qualification, functional-safety certification, or permission to execute on a real robot.

AI providers

The CLI currently supports OpenAI, Anthropic, and Gemini through one provider-neutral agent contract.

Examples:

devagent-physical-ai qualify --provider openai --model <model-id>
devagent-physical-ai qualify --provider anthropic --model <model-id>
devagent-physical-ai qualify --provider gemini --model <model-id>

Provider qualification uses API credits and verifies the bounded Interpreter / Planner / Critic / Recovery path. Provider success never unlocks real robot execution.

Software verification and releases

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

ROS/Gazebo/MoveIt executable orchestration is separately target-qualified because hosted Python CI cannot truthfully exercise a graphical Gazebo process, MoveIt move_group, TF, ROS controllers, and Gazebo services. Pure reference-workcell contracts and deterministic planning logic remain covered by normal unit/coverage gates.

A green main release is tied to the exact CI-tested commit. Release artifacts are rebuilt and verified from the exact tag, checked with Twine, installed into a clean environment, accompanied by SHA256 checksums and an SBOM, attached to the GitHub Release, and published to PyPI through Trusted Publishing.

Documentation

Detailed engineering documentation lives in the repository:

• Production readiness
• Architecture
• Agent Core
• AI providers
• Natural-language engineering
• Robot platform and Twin
• Measured physical runtime
• Canonical Twin runtime
• Qualification
• Optimization
• Workstation setup
• Laptop acceptance
• PyPI release process

Project status

v0.12.5 — Beta software / evidence-gated task-specific physical simulation.

The software and release pipeline are production-oriented, but physical readiness is scope-specific and evidence-driven. The UR5e task-specific reference-workcell path must pass the executable v0.12 ROS/Gazebo/MoveIt campaign on the target workstation before that scope is considered simulation-qualified there. Real robot execution remains locked. Functional-safety certification and site qualification 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.