DevAgent Smart Physical Engine

Verification-first commissioning engineering for robotics and industrial automation.

DevAgent turns an ordinary customer engineering folder into a bounded, traceable verification workflow:

customer files
    ↓
intake + SHA-256 inventory
    ↓
requirements + explicit engineering facts
    ↓
immutable Digital Twin revision
    ↓
deterministic verification plan
    ↓
measured evidence when a qualified execution path exists
    ↓
PASS / FAIL / NOT_TESTED
    ↓
FAT report + Evidence Viewer + replayable lineage

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

DevAgent is designed to answer a practical commissioning question before engineers travel onsite:

What can be proven about this cell, what failed, what is still unknown, what changed, and what evidence supports the conclusion?

---

Quick start

Python 3.11+ is required.

Install:

python -m pip install --upgrade devagent-physical-engine==1.3.0

Verify the installed version:

python -c "import devagent_physical_engine as d; print(d.__version__)"

Expected:

1.3.0

Run DevAgent on the customer project folder:

devagent verify ./customer-project

That is the normal starting point.

You do not need to manually initialize a DevAgent project, choose artifact IDs, convert an XLSX sheet to CSV, or understand the internal evidence database before using Simple Mode.

If you also want physical simulation when an exact qualified execution path exists:

devagent verify ./customer-project --simulate

If you want DevAgent to open the generated Evidence Viewer:

devagent verify ./customer-project --simulate --open

For machine-readable output:

devagent verify ./customer-project --json

Use a dedicated evidence database and results directory when required:

devagent verify ./customer-project \
  --db ./customer-projects.db \
  --output ./verification-results \
  --json

Default locations:

Evidence database: ~/.devagent/projects.db
Results:           <customer-project>/devagent-results/

---

How to use the engine

1. Give DevAgent the engineering folder you already have

A typical project may look like this:

ACME_CNC_CELL_TEST/
├── project.yaml
├── requirements.xlsx
├── ur5e.urdf
├── tcp.yaml
├── layout.yaml
├── robot_program/
│   └── mission.yaml
├── drawings.step
├── safety_requirements.pdf
└── expected/
    └── expected_findings.json

The filenames do not all have to match this example. DevAgent inventories the source tree, fingerprints files with SHA-256, assigns bounded roles, and normalizes supported structured evidence.

Important rule:

file discovered != engineering fact proven

A URDF, Xacro, STEP, STL, PDF, YAML, or JSON file does not automatically prove pose, TCP, calibration, collision geometry, physics, safety, or production readiness.

What DevAgent does during intake

CUSTOMER FOLDER
      |
      v
FILE INVENTORY + SHA-256
      |
      v
ROLE CLASSIFICATION
      |
      +--> expected/ test data -> NEVER engineering authority
      |
      v
REQUIREMENT NORMALIZATION
      |
      v
EXPLICIT FACT EXTRACTION
      |
      v
PROPOSED TWIN NORMALIZATION
      |
      v
DETERMINISTIC TWIN VALIDATION
      |
      +--> missing or ambiguous facts -> QUESTIONS.md
      |
      v
VERIFICATION PLAN / CAMPAIGN / FAT
      |
      v
EVIDENCE VIEWER

Unknown facts remain unknown. DevAgent does not fill engineering gaps with guesses.

---

2. First-run example: incomplete customer information

Assume the customer provides this project.yaml:

project_id: acme-cell
name: ACME Cell
site_id: atl-01
workcell_id: cell-01

and also provides robot/layout/TCP/requirements files, but does not say exactly what task the robot must perform.

Run:

devagent verify ./ACME_CNC_CELL_TEST

DevAgent creates the project automatically and may return:

State: needs_information

Typical questions may include:

engineering_request_operation_missing
engineering_request_object_id_missing
engineering_request_source_missing
engineering_request_destination_missing

The questions are also written to:

ACME_CNC_CELL_TEST/devagent-results/QUESTIONS.md

This is expected fail-closed behavior. DevAgent will not invent the operation, workpiece, source, or destination simply to produce a green report.

Typical first-run output:

ACME_CNC_CELL_TEST/
└── devagent-results/
    ├── SUMMARY.json
    ├── INTAKE.json
    ├── QUESTIONS.md
    └── normalized/
        └── requirements.csv

Fix the source engineering information, then run the same command again.

---

3. Complete ACME example

The following example uses the same input shape exercised by the v1.3 one-command acceptance tests.

project.yaml

project_id: acme-cell
name: ACME Cell
site_id: atl-01
workcell_id: cell-01

robot_base_pose:
  x: 0
  y: 0
  z: 0
  roll: 0
  pitch: 0
  yaw: 0

engineering_request:
  robot: ur5e
  operation: load
  object_id: BOX_101
  source: conveyor_a
  destination: cnc_04
  tool: gripper
  payload_kg: 1.5

tcp.yaml

tcp:
  x: 0
  y: 0
  z: 180
  roll: 0
  pitch: 0
  yaw: 0

layout.yaml

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]

ur5e.urdf

Use the customer's real robot model. A minimal test fixture can look like:

<robot name="ur5e"/>

Do not treat a placeholder URDF as production geometry evidence.

requirements.xlsx

A conventional first worksheet can contain columns such as:

requirement_id	text	check	target	expected	severity
REQ-101	Cycle time <= 8 s	cycle_time_max_s	8.0	true	must
REQ-102	E-stop accessible			true	must

Simple Mode can normalize common requirement ID, text, check, threshold/target, expected-value, and severity/criticality column names without requiring OpenPyXL at runtime.

If the spreadsheet columns are ambiguous, DevAgent asks for clarification rather than guessing which column is authoritative.

Run:

devagent verify ./ACME_CNC_CELL_TEST

When enough explicit evidence exists to build the Twin and deterministic campaign, the results directory can expand to:

ACME_CNC_CELL_TEST/
└── devagent-results/
    ├── SUMMARY.json
    ├── INTAKE.json
    ├── QUESTIONS.md
    ├── normalized/
    │   ├── requirements.csv
    │   └── devagent-twin.yaml
    ├── FAT_REPORT.html
    └── EVIDENCE.html

normalized/devagent-twin.yaml is generated evidence mapping. It is not an independent source of truth and does not bypass Twin validation.

---

4. Request simulation

Run:

devagent verify ./ACME_CNC_CELL_TEST --simulate

--simulate means:

request measured physical simulation if the exact imported-Twin execution path is qualified

It does not mean:

run any available demo and label it customer evidence

The current one-command safety boundary is:

IMPORTED CUSTOMER TWIN
        |
        v
EXACT QUALIFIED EXECUTION ADAPTER?
        |
   +----+----+
   |         |
  YES        NO
   |         |
execute     simulation_state=blocked
measure     exit 31 when --simulate was requested
record      no fake measurement

For example, the repository contains a UR5e reference simulation stack, but:

reference UR5e demo != customer imported Twin evidence

If the exact imported-customer execution adapter is not qualified, DevAgent reports a bounded reason such as:

imported_customer_twin_execution_adapter_not_yet_qualified

or:

twin_not_ready_for_physics

That is intentional. A blocked simulation is more trustworthy than a visually impressive but unrelated demo.

---

5. Open the Evidence Viewer

When evidence lineage can be rendered:

devagent verify ./ACME_CNC_CELL_TEST --open

or:

devagent verify ./ACME_CNC_CELL_TEST --simulate --open

The viewer is read-only and is intended to answer:

• Which requirement was evaluated?
• What was the verdict?
• What value was observed?
• What threshold or expected value was used?
• Which Twin revision was evaluated?
• Which evidence artifact supports the result?
• Which SHA-256 hashes bind the evidence?
• What is still blocked or not tested?

The trust principle is simple:

Do not trust a PASS label by itself. Inspect the evidence behind it.

---

Understanding the results

SUMMARY.json

This is the primary machine-readable result of Simple Mode.

Important fields include:

project_id
state
twin_revision_id
twin_state
requirements_file
verification_plan_artifact_id
campaign_artifact_id
fat_artifact_id
evidence_bundle_artifact_id
evidence_viewer
simulation_requested
simulation_state
simulation_reason
release_ready
real_execution_allowed
questions

A green software workflow never changes this hard safety boundary by itself:

real_execution_allowed = false

INTAKE.json

Records the source-file inventory and SHA-256 fingerprints so the customer can see exactly what DevAgent inspected.

Each discovered file is associated with a bounded role and authority decision.

Examples:

requirements.xlsx      -> requirements
layout.yaml            -> engineering_data
ur5e.urdf              -> robot_model
safety_requirements.pdf -> manual engineering document
expected/...           -> test_oracle, used_for_authority=false

QUESTIONS.md

Contains missing or ambiguous engineering facts that prevented deterministic promotion.

Use it as an engineering punch list, update the original customer files, and rerun:

devagent verify ./ACME_CNC_CELL_TEST

FAT_REPORT.html

Customer-readable verification report generated when a campaign can be built.

A missing metric or unsupported requirement is not silently changed to PASS. It remains NOT_TESTED or otherwise blocks readiness.

EVIDENCE.html

Read-only evidence view of requirement/Twin/artifact lineage.

---

Requirements and verdicts

Supported deterministic structural/Twin checks include:

planning_allowed
physics_allowed
entity_present
validation_issue_absent
twin_state

Measured physical checks include:

cycle_time_max_s
minimum_clearance_m
final_tcp_error_max_m
max_tracking_error_rad
collision_free
physical_completed

The verdict model is intentionally bounded:

PASS
FAIL
NOT_TESTED

A requirement that needs measured physical evidence cannot PASS from prose, a CAD filename, or a generated verification plan.

Example:

Requirement: cycle time <= 8.0 s
Measurement available: no
Verdict: NOT_TESTED

When exact-Twin measured evidence exists:

Requirement: cycle time <= 8.0 s
Observed: 7.42 s
Threshold: 8.0 s
Verdict: PASS
Evidence: exact measurement artifact + Twin revision/hash

---

XLSX, PDF, and expected-data policies

XLSX requirements

Simple Mode supports conventional requirements.xlsx first-worksheet normalization.

Common semantic columns include:

requirement ID
requirement text / description
check / metric
target / threshold
expected value
severity / criticality / priority

If multiple requirement sources are present and authority becomes ambiguous, DevAgent fails closed rather than silently merging them.

PDF documents

PDFs are inventoried and fingerprinted for review.

v1.3 does not silently OCR arbitrary safety PDFs and convert extracted prose into deterministic PASS evidence.

A safety requirement without a supported deterministic check remains manual/NOT_TESTED until appropriate evidence exists.

expected/ folders

A root expected/ folder is treated as test-fixture oracle data:

expected/
  -> inventoried
  -> SHA-256 recorded
  -> role = test_oracle
  -> used_for_authority = false

This prevents a fixture from proving its own expected answer.

---

Simple Mode exit codes

Exit	Meaning
0	bounded verification is release-ready
10	customer input or operational contract failure
30	more engineering information is required
31	simulation was requested but the exact execution path is blocked/unqualified
32	verification completed but release readiness is still false

Non-zero engineering exits are intentional and machine-friendly.

Example CI use:

devagent verify ./customer-project --json > devagent-result.json
rc=$?

case "$rc" in
  0)  echo "bounded verification ready" ;;
  30) echo "customer information required" ;;
  31) echo "simulation path blocked" ;;
  32) echo "verification complete but not release-ready" ;;
  *)  echo "input or operational failure" ;;
esac

---

When to use Simple Mode vs Expert Mode

Use Simple Mode for the normal customer workflow:

devagent verify ./customer-project

Use Expert Mode when you need explicit control over:

• project identity;
• immutable Twin revisions;
• explicit requirement artifacts;
• measurement binding;
• campaign artifact IDs;
• regression baselines;
• Evidence Bundle generation;
• replay reconstruction;
• external CI/orchestration;
• qualification workflows.

Installed CLIs:

devagent             one-command customer verification
devagent-commercial  expert commercial/evidence workflow
devagent-physical    deterministic core + ROS/qualification tools
devagent-physical-ai optional provider-backed engineering front end

---

Expert Mode example

The default project/evidence database is:

~/.devagent/projects.db

1. Create project identity

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

2. Import explicit customer Twin evidence

devagent-commercial import-twin warehouse-cnc-04 ./customer-cell \
  | tee twin-import.json

List immutable revisions:

devagent-physical project \
  --db ~/.devagent/projects.db \
  revisions warehouse-cnc-04

Twin manifest example:

https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/devagent-twin.yaml

Do not use template values as customer evidence.

3. Load requirements

devagent-commercial requirements warehouse-cnc-04 \
  examples/commercial/requirements-production.csv

Example requirements file:

https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/requirements-production.csv

4. Generate verification plan

devagent-commercial verification-plan warehouse-cnc-04 \
  examples/commercial/verification-plan.yaml \
  --revision twin-r0001

Planning creates bounded test intent. It is not execution evidence.

5. Record measured evidence

devagent-commercial record-measurement warehouse-cnc-04 \
  physical-measurement.json \
  --revision twin-r0001

Example schema:

https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/physical-measurement.json

Preferred integrations use the typed PhysicalEvidenceRecorder.record_motion_metrics(...) path so measurement, canonical motion, planner/source graph, qualification reference, and Twin hash remain bound together.

6. Run deterministic campaign

devagent-commercial campaign warehouse-cnc-04 \
  examples/commercial/requirements-production.csv \
  --revision twin-r0001 \
  --measurement ARTIFACT_ID

7. Generate FAT report

devagent-commercial fat-report warehouse-cnc-04 \
  CAMPAIGN_ARTIFACT \
  --output FAT_REPORT.html

8. Build Evidence Bundle

devagent-commercial evidence-bundle \
  warehouse-cnc-04 \
  CAMPAIGN_ARTIFACT

The bundle binds requirement results to exact artifact IDs, artifact hashes, Twin revision, and Twin hash.

9. Inspect evidence graph

devagent-commercial evidence-graph warehouse-cnc-04 \
  > evidence-graph.json

10. Generate static Evidence Viewer

devagent-commercial evidence-viewer warehouse-cnc-04 \
  --output DEVAGENT_EVIDENCE.html

11. Replay persisted lineage

devagent-commercial replay \
  warehouse-cnc-04 \
  EVIDENCE_BUNDLE \
  --qualification-root ~/.devagent/physical-qualification \
  --output replay-manifest.json \
  --record

Replay verifies persisted identity before reconstruction:

artifact ID
artifact type
artifact SHA-256
Twin revision/hash
run_id
case_id
case evidence hash
seed
reset state
parameters
canonical motion fingerprint

A successful replay inspection reports:

replayable = true
execution_performed = false

Replay reconstruction does not command Gazebo, MoveIt, a robot, PLC, or safety PLC.

12. Change impact

After importing a new Twin revision:

devagent-commercial impact warehouse-cnc-04 \
  twin-r0001 twin-r0002 \
  examples/commercial/requirements-production.csv

13. Regression

devagent-commercial regression warehouse-cnc-04 \
  BASELINE_CAMPAIGN CURRENT_CAMPAIGN \
  --impact CHANGE_IMPACT_ARTIFACT

A previous PASS does not remain authoritative after a changed Twin unless the required evidence chain remains valid for the new revision.

14. Project status

devagent-commercial status warehouse-cnc-04

Inspect artifacts:

devagent-commercial artifacts warehouse-cnc-04

Useful artifact types include:

customer_twin_import
one_command_twin_normalization
requirement_set
verification_plan
physical_measurement
physical_motion_plan
runtime_measurement_binding
commercial_campaign
change_impact
commercial_regression
fat_report
evidence_bundle
replay_verification

---

Physical simulation setup

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

Reference stack:

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

Preview setup changes:

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

Apply explicitly:

devagent-physical setup --profile ur5e-sim --yes

Check runtime readiness:

devagent-physical ros doctor

Qualify trajectory runtime:

devagent-physical ros qualify-trajectory-runtime

Other reference commands:

devagent-physical ros launch --dry-run
devagent-physical ros acceptance
devagent-physical ros demo
devagent-physical qualify

Hosted Python CI cannot prove a graphical Gazebo runtime, MoveIt move_group, TF, controller actions, OEM drivers, or an arbitrary imported workcell. Physical qualification must run on the exact workstation/adapter stack.

---

Optional AI providers

AI is optional and remains outside deterministic authority.

Install one 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 all provider SDKs:

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

Typical credentials:

export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."
export GEMINI_API_KEY="..."

Check provider setup without using the provider as physical authority:

devagent-physical-ai doctor --provider openai

Example natural-language 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 YOUR_MODEL

The model can help interpret and propose engineering intent. It cannot grant deterministic safety, physical qualification, site qualification, or real-execution authority.

---

Evidence and authority model

DevAgent deliberately separates four things that are often incorrectly mixed together:

1. requirement
2. test intent
3. measured evidence
4. authority/readiness

A verification plan proves only that a test was planned.

A model-only result proves only the model-level property that was actually evaluated.

A physical requirement requires physical measurement evidence.

A replay reconstruction proves persisted evidence lineage can be reconstructed; it is not a new simulation run.

A simulation PASS does not equal site commissioning.

A complete customer FAT report does not equal functional-safety certification.

Current hard boundary:

physical_qualification = false unless separately qualified evidence says otherwise
site_qualification = false
real_execution_allowed = false

This architecture is intentional:

Agents propose.
Deterministic engines compile and verify.
Existing certified controllers execute.

---

What DevAgent should be used for

DevAgent is designed to help engineering teams:

• reduce FAT preparation and verification effort;
• discover missing engineering information before travel;
• identify requirement failures before onsite commissioning;
• create repeatable deterministic test plans;
• bind physical measurements to exact Twin revisions;
• detect regression after engineering changes;
• preserve evidence provenance;
• produce customer-readable FAT evidence;
• reduce dependence on manual artifact bookkeeping;
• make verification results inspectable rather than opaque.

It is not a replacement for:

• OEM robot controllers;
• PLC logic authority;
• safety PLCs;
• certified safety functions;
• site acceptance responsibility;
• functional-safety engineering;
• real-world commissioning judgment.

---

Project status

v1.3.0 — Production/Stable software workflow

The bounded software/evidence workflow is production-oriented and continuously tested across Python 3.11, 3.12, and 3.13.

The v1.3 release candidate includes:

one-command customer intake
XLSX requirement normalization
immutable project/Twin lineage
deterministic verification campaigns
measured evidence binding
FAT generation
Evidence Bundle
Evidence Viewer
replay reconstruction
change impact
regression
provider-neutral optional AI front end

Software quality gates include dedicated coverage thresholds for:

One-Command customer workflow
Production Authority
Evidence Trust / Replay

Production/Stable describes the bounded software workflow. It does not claim arbitrary customer cells are physically or site qualified.

---

Documentation

One-command verification:

https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ONE_COMMAND_VERIFY_V13.md

Evidence Trust / replay / viewer:

https://github.com/tomha85/devagent-physical-engine/blob/main/docs/EVIDENCE_TRUST_V12.md

Measured physical runtime:

https://github.com/tomha85/devagent-physical-engine/blob/main/docs/MEASURED_PHYSICAL_RUNTIME.md

Commercial project spine:

https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMERCIAL_PROJECT_SPINE.md

Commercial workflow:

https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMERCIAL_V1.md

Natural-language engineering:

https://github.com/tomha85/devagent-physical-engine/blob/main/docs/NATURAL_LANGUAGE_ENGINEERING.md

AI providers:

https://github.com/tomha85/devagent-physical-engine/blob/main/docs/AI_PROVIDERS.md

Architecture:

https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ARCHITECTURE.md

Canonical Twin runtime:

https://github.com/tomha85/devagent-physical-engine/blob/main/docs/CANONICAL_TWIN_RUNTIME.md

Laptop acceptance:

https://github.com/tomha85/devagent-physical-engine/blob/main/docs/LAPTOP_ACCEPTANCE.md

Optimization:

https://github.com/tomha85/devagent-physical-engine/blob/main/docs/OPTIMIZATION.md

---

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.

See repository LICENSE, NOTICE, and COPYRIGHT for the complete ownership and usage terms.