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 is designed to add 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.10.0 — Alpha

The Python software stack is regression-tested in GitHub Actions on Python 3.11, 3.12, and 3.13. The UR5e Gazebo/MoveIt canonical physical-simulation runtime is implemented but remains EXPERIMENTAL until executable target-workstation qualification promotes its individual scopes.

Real robot execution remains locked. Functional-safety certification is not claimed.

What v0.10.0 includes

Trust chain

flowchart TD
    USER[Engineer / customer application] --> REQUEST[Natural-language engineering request]
    REQUEST --> INTERPRETER[Requirement Interpreter]

    INTERPRETER --> OAI[OpenAI]
    INTERPRETER --> CLAUDE[Anthropic]
    INTERPRETER --> GEMINI[Gemini]

    OAI --> AGENTS[Planner / Critic / Recovery]
    CLAUDE --> AGENTS
    GEMINI --> AGENTS

    AGENTS --> COMPILE[Deterministic compile + 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 / frame model]

    GZ --> READBACK[Backend read-back verification]
    MOVEIT --> READBACK
    TF --> READBACK

    READBACK --> PRECHECK[Pre-execution verification]
    PRECHECK --> MOTION[Exact PhysicalMotionPlan]
    MOTION --> SIM[Gazebo / ROS 2 execution]
    SIM --> MEASURE[Measured joint states + MoveIt FK]
    MEASURE --> EVIDENCE[Replayable evidence]
    EVIDENCE --> PROMOTION[Evidence-driven promotion gate]

    PROMOTION --> LOCKED[Real execution remains locked]

The v0.10 architecture is specifically designed to prevent DevAgent from validating one Twin while MoveIt plans against a different scene and Gazebo executes a different world. One canonical Twin fingerprint is carried through materialization, backend read-back, pre-execution verification, motion execution, and evidence.

Safety and qualification boundary

A successful software test or simulation run does not automatically create a commissioning or real-hardware claim.

The v0.10 canonical qualification report deliberately keeps:

physical_qualification      = false
commissioning_qualification = false
continuous_collision_check  = false
minimum_clearance_measured  = false
real_execution_allowed      = false
site_qualification          = false

A reference campaign can produce promotion-candidate evidence for an experimental scope, but promotion remains evidence-driven and scope-specific.

Installation from source

Python 3.11+ is required.

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

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

AI providers

Credentials stay outside the world model:

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

Check a provider without making a network qualification call:

devagent-physical-ai doctor --provider openai

Run live provider qualification:

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

Interpret an engineering request:

devagent-physical-ai request \
  "Use a UR5e to move a part from conveyor_a to cnc_04" \
  --provider openai \
  --model <model-id>

Run the natural-language engineering pipeline:

devagent-physical-ai engineer \
  "Use a UR5e to move a part from conveyor_a to cnc_04" \
  --provider openai \
  --model <model-id>

Equivalent provider commands support Anthropic and Gemini. Live AI routing is simulation-only and does not unlock real execution.

See docs/AI_PROVIDERS.md and docs/NATURAL_LANGUAGE_ENGINEERING.md.

Deterministic verification

Core checks:

python -m compileall -q src tests
python -m unittest discover -s tests -v
devagent-physical doctor
devagent-physical qualify
devagent-physical simulate --robot fanuc_crx --inject-collision

The repository CI performs editable installation, compileall, and the full unittest regression matrix on Python 3.11 / 3.12 / 3.13.

UR5e ROS 2 / Gazebo target stack

Current reference target:

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

Inspect workstation changes without modifying the system:

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

Explicitly install/verify the supported workstation profile:

devagent-physical setup --profile ur5e-sim

Then run:

devagent-physical ros doctor
devagent-physical ros demo

The visual demo launches the official UR5e Gazebo + MoveIt/RViz stack, waits for controller readiness and /joint_states, performs a motion smoke, verifies measured joint-state movement, and records evidence.

Trajectory-runtime-only qualification is also available:

devagent-physical ros qualify-trajectory-runtime

That command qualifies only its defined scope and does not promote commissioning or real-hardware execution.

v0.10 canonical Twin qualification

The executable reference campaign is intentionally separate from ordinary GitHub CI because it requires the ROS/Gazebo/MoveIt target stack:

python -m devagent_physical_engine.ros2.qualification_v10 \
  --log-dir ~/.devagent/v10-canonical-qualification

The campaign requires canonical Gazebo/MoveIt materialization, TF alignment, backend scene read-back, sampled pre-execution validity, measured joint-state motion, and MoveIt FK evidence across the reference trajectories.

Even a green reference campaign remains an experimental-scope promotion candidate until the missing commissioning gates—such as continuous collision checking and qualified minimum-clearance measurement—are implemented and evidenced.

See docs/CANONICAL_TWIN_RUNTIME.md and docs/MEASURED_PHYSICAL_RUNTIME.md.

Optimization semantics

DevAgent does not claim a mathematical global optimum. It selects the best evaluated verified candidate among the candidates and motion variants that were actually generated, verified, and measured under the configured objective profile.

A candidate is ineligible when deterministic verification/simulation fails, a hard violation is reported, required metrics are unknown, or configured quality gates fail. Weighted scoring cannot make an unsafe or unverified plan acceptable.

See docs/OPTIMIZATION.md.

Documentation

• docs/ARCHITECTURE.md — trust boundaries and runtime architecture.
• docs/AGENT_CORE.md — Agent Core design.
• 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 — multi-vendor robot platform and evidence-aware Twin.
• docs/MEASURED_PHYSICAL_RUNTIME.md — physical motion and measured qualification runtime.
• docs/CANONICAL_TWIN_RUNTIME.md — canonical Gazebo/MoveIt/TF materialization and verification.
• docs/QUALIFICATION.md — qualification and evidence model.
• docs/OPTIMIZATION.md — search, metrics, Pareto ranking, and evidence.
• docs/SETUP.md — explicit workstation bootstrap.
• docs/LAPTOP_ACCEPTANCE.md — UR5e visual workstation acceptance.

Release policy

v0.10.0 is the first tagged GitHub release of this repository. It is an alpha engineering release, not a declaration of functional-safety certification, site qualification, or authorization for autonomous real-robot execution.

Future capability promotion must remain evidence-driven and must not silently upgrade experimental simulator results into commissioning claims.

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.