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.
• Fail-closed visualization — DevAgent never substitutes a canned motion and labels it as the requested 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 +   6.84s] INTERPRETER  validated request_id=REQ-...
[DevAgent +   6.84s] PLANNER      revision=0 generating high-level task graph
[DevAgent +  12.21s] CRITIC       revision=0 reviewing verified plan
[DevAgent +  15.77s] SIMULATION   running deterministic model execution
[DevAgent +  15.78s] COMPLETE     ready_for_twin_simulation=true

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

Visual simulation

There are two deliberately different visualization modes.

To prove that the workstation can launch Gazebo / MoveIt and visibly move a UR5e, use the explicit visual demo:

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 runs the packaged UR5e motion smoke through the ROS simulation stack. It is intentionally reported as task_specific=false; it proves the visualization/motion stack is working, not that the exact BOX task has been physically planned.

To request visualization of the exact engineering 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> \
  --visualize

Task-specific visualization fails closed until the runtime has enough physical evidence to construct the exact scene and compile an exact PhysicalMotionPlan. Required evidence includes robot/source/destination poses, collision geometry, workpiece geometry, tool/TCP information, and the compiled physical motion. DevAgent will not display an unrelated canned movement and call it the requested task.

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
EXACT PHYSICAL MOTION CONTRACT
                |
                v
GAZEBO / MOVEIT MATERIALIZATION + READ-BACK
                |
                v
COLLISION / CLEARANCE / 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.

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.

For production-candidate UR5e simulation, the stronger verifier can use MoveIt PlanningScene read-back, runtime-owned tool collision binding, runtime-owned workpiece attach/detach transitions, measured collision distance, conservative continuous-path clearance proof, measured joint states, and MoveIt FK evidence.

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. Current production-candidate physical-runtime work is centered on the UR5e ROS 2 / Gazebo / MoveIt path; 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

For the stronger production-candidate target 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.

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.11.6 — Beta software / evidence-gated physical runtime.

The software and release pipeline are production-oriented, but physical readiness is scope-specific and evidence-driven. The UR5e physical simulation path remains experimental until its exact target-stack qualification campaign passes. 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.