DevAgent Smart Physical Engine

Verification-first agentic engineering, planning, optimization, simulation, and evidence runtime 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 adds AI-assisted engineering to existing automation without replacing robot controllers, PLCs, safety controllers, or real-time servo loops. The core is provider-neutral and keeps engineering authority separated from model output.

Current version

v0.11.5 — Beta software / evidence-gated physical runtime

The Python software stack is regression-tested on Python 3.11, 3.12, and 3.13 with separate static/coverage, package-install, and runtime dependency security gates. The UR5e Gazebo/MoveIt path now contains production-candidate continuous-clearance, tool-collision, and workpiece-lifecycle capabilities, but those physical-simulation scopes remain EXPERIMENTAL until the executable target-workstation v0.11 campaign passes.

v0.11.3 normalized provider-neutral agent schemas at the OpenAI transport boundary so strict Structured Outputs can represent DevAgent optional fields without changing Anthropic/Gemini or deterministic core semantics. v0.11.4 added live terminal progress tracing for AI request, engineering, and provider-qualification workflows. v0.11.5 adds explicit visualization modes: --visualize requests exact task-specific visualization and fails closed until an exact physical Twin plus compiled PhysicalMotionPlan exist; --visual-demo launches the UR5e Gazebo/MoveIt motion demo without misrepresenting that generic motion as the requested BOX/source/destination task.

Real robot execution remains locked. Functional-safety certification and site qualification are not claimed.

v0.11 capability status

Trust chain

flowchart TD
    USER[Engineer / customer application] --> REQUEST[Natural-language engineering request]
    REQUEST --> AI[Provider-neutral AI / Planner / Critic / Recovery]
    AI --> COMPILE[Deterministic compile + semantic policy]
    COMPILE --> VERIFY[Verified plan artifact]
    VERIFY --> TWIN[Canonical TwinSpec + SHA256]
    TWIN --> MATERIALIZE[Canonical materialization]
    MATERIALIZE --> GZ[Gazebo world]
    MATERIALIZE --> MOVEIT[MoveIt PlanningScene]
    MATERIALIZE --> TF[TF frames]
    GZ --> READBACK[Backend read-back]
    MOVEIT --> READBACK
    TF --> READBACK
    READBACK --> TOOL[Verified tool collision receipt]
    TOOL --> WORKPIECE[Verified workpiece lifecycle receipt]
    WORKPIECE --> MOTION[Exact PhysicalMotionPlan / Twin binding]
    MOTION --> CLEAR[Measured clearance + continuous proof]
    CLEAR --> SIM[ROS 2 / Gazebo execution]
    SIM --> MEASURE[Measured joint states + MoveIt FK]
    MEASURE --> EVIDENCE[Replayable evidence]
    EVIDENCE --> PROMOTION[Scope-specific promotion gate]
    PROMOTION --> LOCKED[Real execution remains separately locked]

The model never owns collision policy, minimum-clearance truth, dynamic scene state, qualification promotion, or real-hardware authorization.

Continuous collision and clearance semantics

The legacy/discrete verifier remains available for development and simulation but can never produce commissioning-usable evidence.

The v0.11 production-candidate verifier synchronizes the authoritative MoveIt PlanningScene, measures minimum collision distance, and adaptively proves every joint interval using a conservative collision-distance Lipschitz bound. If the proof cannot be established within configured sample/depth limits, it fails closed. There is no automatic downgrade to a sampled “pass.”

A commissioning-usable pre-execution receipt requires all of:

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

The distance Lipschitz bound is itself qualification evidence and must be conservative for the exact robot/tool/collision model.

Tool and workpiece authority

Customer motion metadata can no longer claim that a tool collision model or workpiece attachment is verified.

ToolCollisionBinding is runtime configuration. The tool is applied as a MoveIt attached collision object and verified by geometry/link read-back before a receipt is accepted.

Workpiece state uses verified transitions:

WORLD → ATTACHED → WORLD

Attach/detach applies the PlanningScene change and verifies the resulting world/attached state. Missing or inconsistent read-back blocks the motion.

Installation

Python 3.11+ is required.

From PyPI after the corresponding release is published:

python -m pip install devagent-physical-engine

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 .

Optional provider SDKs:

python -m pip install -e ".[openai]"
python -m pip install -e ".[anthropic]"
python -m pip install -e ".[gemini]"
python -m pip install -e ".[ai]"

Development/qualification tooling:

python -m pip install -e ".[dev]"

pip install does not install ROS/Gazebo system packages or perform privileged OS changes.

AI providers

Keep credentials outside WorldState/Twin data:

export OPENAI_API_KEY='...'
export ANTHROPIC_API_KEY='...'
export GEMINI_API_KEY='...'

Examples use the currently supported deterministic goal action load:

devagent-physical-ai doctor --provider openai
devagent-physical-ai qualify --provider openai --model <model-id>
devagent-physical-ai request \
  "Use a UR5e to load BOX_101 from conveyor_a to cnc_04. Simulate and verify the plan." \
  --provider openai --model <model-id>
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>

Live commands show stage-by-stage progress while they are running, for example:

[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] REASONING    risk_score=1 max_revisions=1 critic_threshold=0.70
[DevAgent +   6.84s] PLANNER      revision=0 generating high-level task graph
[DevAgent +  12.21s] PLANNER      revision=0 proposal compiled and deterministically verified
[DevAgent +  12.21s] CRITIC       revision=0 reviewing verified plan
[DevAgent +  15.77s] CRITIC       revision=0 decision=accept score=0.91
[DevAgent +  15.77s] PLANNING     verified plan accepted after revision=0
[DevAgent +  15.77s] SIMULATION   running deterministic model execution
[DevAgent +  15.78s] SIMULATION   deterministic model execution completed
[DevAgent +  15.78s] COMPLETE     ready_for_twin_simulation=true

Progress logs are emitted to stderr, so piping stdout still produces clean JSON. For CI or scripts that do not want terminal progress, add --quiet.

Visualization semantics

--visualize means visualize the exact engineering task, not merely make a robot move. Therefore it fails closed until the request has enough physical evidence to build the exact scene and a compiled physical trajectory:

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

Until the task-specific physical bridge is complete, the result reports task_visualization_requires_physical_twin_motion_plan and lists required evidence such as robot/source/destination poses, collision geometry, workpiece/tool geometry, and a compiled PhysicalMotionPlan. DevAgent intentionally does not substitute a canned motion and claim it is the requested BOX task.

To verify that the workstation can actually launch Gazebo/MoveIt and visibly move a UR5e now, use the explicit demo mode:

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

The visual demo uses the packaged UR simulation motion smoke, records an acceptance report under ~/.devagent/ai-visual, and leaves Gazebo/MoveIt open after success unless --close-after is supplied. Its JSON explicitly reports task_specific=false and motion_source=ur_robot_driver/example_move.py.

Equivalent routing supports Anthropic and Gemini. Live AI qualification does not unlock real robot execution.

Software production gates

Repository CI now requires:

Python 3.11 regression
Python 3.12 regression
Python 3.13 regression
compileall
Ruff correctness checks
branch coverage threshold
wheel + sdist build
twine --strict
clean wheel installation/version smoke
runtime dependency vulnerability audit

Critical checkout/setup/artifact GitHub Actions are pinned to exact commits.

A successful main CI run drives release-on-ci.yml, which validates the package version and creates a normal GitHub Release at the exact CI-tested SHA. It then dispatches release.yml with workflow_dispatch at the exact release tag. Running Trusted Publishing in the directly dispatched release.yml is intentional: PyPI binds the OIDC publisher identity to that workflow filename and does not currently support reusable workflows for Trusted Publishing. release.yml rebuilds and re-verifies the exact tag, attaches wheel/sdist/SBOM/checksum evidence to the GitHub Release, and publishes through the GitHub pypi environment using OIDC.

UR5e ROS 2 / Gazebo target

Reference target:

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

Setup/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

v0.11 production-candidate executable qualification

The stronger campaign is deliberately separate from ordinary hosted GitHub CI because it requires the exact ROS/Gazebo/MoveIt target stack and qualified robot/tool collision-distance bound:

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 green campaign requires canonical world read-back, verified tool attachment, verified workpiece attach+detach, synchronized MoveIt scene, conservative continuous collision/clearance proof, minimum clearance above margin, measured joint-state execution, and MoveIt FK evidence.

It may report:

promotion_candidate=true
simulation_commissioning_evidence_qualified=true
continuous_collision_check=true
minimum_clearance_measured=true

but still intentionally reports:

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

Physical/site promotion requires measured hardware/shadow evidence.

Sim↔real qualification

The source now includes an explicit quantitative correlation gate. Default minimum criteria are:

observations >= 30
cycle-time gap p95 <= 10%
TCP error p95 <= 10 mm
behavior agreement >= 0.99
measured origin + dataset reference required

Missing evidence never qualifies. Customers may set stricter thresholds.

Optimization semantics

DevAgent does not claim a mathematical global optimum. It selects the best evaluated verified candidate among candidates actually generated, verified, and measured under the configured objective. A hard violation, failed verification/simulation, unknown required metric, or failed quality gate makes the candidate ineligible regardless of weighted score.

Documentation

• docs/PRODUCTION_READINESS.md — v0.11 readiness scopes and qualification boundaries.
• docs/ARCHITECTURE.md — current trust boundaries and runtime architecture.
• docs/AGENT_CORE.md — Agent Core authority model.
• docs/AI_PROVIDERS.md — provider installation, credentials, and qualification.
• docs/NATURAL_LANGUAGE_ENGINEERING.md — natural-language engineering request flow.
• docs/ROBOT_PLATFORM_AND_TWIN.md — robot abstraction and evidence-aware Twin.
• docs/MEASURED_PHYSICAL_RUNTIME.md — motion and measured runtime.
• docs/CANONICAL_TWIN_RUNTIME.md — canonical scene, continuous clearance, and dynamic scene lifecycle.
• docs/QUALIFICATION.md — qualification/evidence model.
• docs/OPTIMIZATION.md — search, metrics, Pareto ranking, and evidence.
• docs/SETUP.md — explicit workstation bootstrap.
• docs/LAPTOP_ACCEPTANCE.md — UR5e workstation acceptance.
• docs/PYPI_RELEASE.md — Trusted Publishing release pipeline.

Release policy

v0.11 is a Beta software release, not a declaration that every robot/site is physically commissioned. Capability promotion remains evidence-driven and scope-specific. Simulation evidence cannot silently become hardware/site qualification.

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.