Metadata-Version: 2.4
Name: devagent-physical-engine
Version: 2.0.0
Summary: Verification-first robotics commissioning control plane with immutable engineering findings, deterministic pre-site readiness, evidence authority, exact-Twin lineage, selective simulation, regression, replay, and FAT reporting.
Author: Tom Ha
License: All Rights Reserved
Project-URL: Homepage, https://github.com/tomha85/devagent-physical-engine
Project-URL: Repository, https://github.com/tomha85/devagent-physical-engine
Project-URL: Issues, https://github.com/tomha85/devagent-physical-engine/issues
Project-URL: Sponsor, https://github.com/sponsors/tomha85
Keywords: robotics,industrial-automation,agentic-ai,ros2,gazebo,moveit,pilz,verification,selective-testing,digital-twin,fat-testing,regression,evidence,replay
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: NOTICE
Requires-Dist: PyYAML<7,>=6.0
Provides-Extra: openai
Requires-Dist: openai<4,>=3.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic<2,>=1.0; extra == "anthropic"
Provides-Extra: gemini
Requires-Dist: google-genai<3,>=2.0; extra == "gemini"
Provides-Extra: ai
Requires-Dist: openai<4,>=3.0; extra == "ai"
Requires-Dist: anthropic<2,>=1.0; extra == "ai"
Requires-Dist: google-genai<3,>=2.0; extra == "ai"
Provides-Extra: dev
Requires-Dist: build==1.6.0; extra == "dev"
Requires-Dist: twine==7.0.0; extra == "dev"
Requires-Dist: coverage[toml]<8,>=7.6; extra == "dev"
Requires-Dist: ruff<1,>=0.12; extra == "dev"
Requires-Dist: pip-audit<3,>=2.9; extra == "dev"
Dynamic: license-file

# DevAgent Smart Physical Engine

[![PyPI](https://img.shields.io/pypi/v/devagent-physical-engine.svg)](https://pypi.org/project/devagent-physical-engine/)
[![Python](https://img.shields.io/pypi/pyversions/devagent-physical-engine.svg)](https://pypi.org/project/devagent-physical-engine/)
[![Status: Production/Stable](https://img.shields.io/badge/status-production%2Fstable-blue.svg)](#project-status)
[![Sponsor DevAgent Physical Engine](https://img.shields.io/badge/Sponsor-DevAgent%20Physical%20Engine-EA4AAA?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/tomha85)

**Verification-first commissioning engineering for robotics and industrial automation.**

DevAgent turns customer engineering inputs into a bounded, evidence-driven pre-site commissioning workflow. AI may help interpret and propose; deterministic engines validate, compile, execute qualified verification, measure evidence, detect regression, and gate promotion.

> **OEM robot controllers, PLCs, safety PLCs, certified safety systems, and qualified site processes remain authoritative. DevAgent does not convert simulation into site qualification or functional-safety certification.**

## Engine in action

<p align="center">
  <img src="docs/assets/readme/Screenshot%20from%202026-09-02%2015-14-21.png" width="100%" alt="DevAgent Smart Physical Engine exact-Twin UR5e workcell running in Gazebo Harmonic">
</p>

<p align="center">
  <b>Exact-Twin simulation in Gazebo Harmonic</b><br>
  <sub>Real DevAgent engine run with the bounded UR5e workcell, customer-cell entities, physics, and simulation state visible.</sub>
</p>

<table>
  <tr>
    <td width="50%" align="center">
      <img src="docs/assets/readme/Screenshot%20from%202026-09-02%2015-15-17.png" width="100%" alt="DevAgent Smart Physical Engine robot task execution in Gazebo">
      <br><b>Robot task execution</b><br>
      <sub>Gazebo view during the bounded pick–transport–place workflow.</sub>
    </td>
    <td width="50%" align="center">
      <img src="docs/assets/readme/Screenshot%20from%202026-09-02%2015-14-32.png" width="100%" alt="DevAgent Smart Physical Engine MoveIt motion planning scene in RViz">
      <br><b>MoveIt motion planning</b><br>
      <sub>RViz planning-scene view used alongside the qualified ROS 2 / MoveIt execution path.</sub>
    </td>
  </tr>
</table>

<p align="center"><sub><b>Real engine screenshots — not product renders.</b> ROS 2 Jazzy · Gazebo Harmonic · MoveIt 2 · Pilz · UR5e exact-Twin verification.</sub></p>

## v2.0 commissioning verification flow

```text
Customer engineering files
        ↓
Immutable project + Twin revision
        ↓
Engineering review
        ↓
Requirements + findings + risks + changes
        ↓
Deterministic criterion mapping
        ↓
Requirement-driven verification plan
        ↓
Verification-scope authority
        ↓
Deterministic checks + qualified physical evidence
        ↓
Evidence Graph
        ↓
PASS / FAIL / NOT_TESTED
        ↓
Change Impact + Regression
        ↓
FAT Report + Evidence Bundle
        ↓
Immutable pre-site commissioning decision
```

The final bounded decision is one of:

```text
READY_FOR_PRE_SITE_COMMISSIONING
NOT_READY_FOR_PRE_SITE_COMMISSIONING
```

That decision means the declared pre-site engineering scope has complete, current evidence according to DevAgent's installed authority contracts. It does **not** mean the real site is commissioned.

## Quick start

Python 3.11+ is required.

```bash
python -m pip install --upgrade devagent-physical-engine==2.0.0
```

Verify the installed package:

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

Expected:

```text
2.0.0
```

Run the normal customer workflow:

```bash
devagent verify ./customer-project
```

Request qualified simulation where available:

```bash
devagent verify ./customer-project --simulate
```

Open the Evidence Viewer and keep the engineering terminal active:

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

Machine-readable CI output:

```bash
devagent verify ./customer-project --json
```

Default locations:

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

## Commercial commissioning workflow

The normal end-to-end customer path is `devagent verify`. It performs requirement normalization, deterministic mapping, requirement-driven case planning/mapping, verification orchestration, evidence recording, regression, and reporting within the qualified scope.

`devagent-commercial` is the lower-level immutable project/evidence/control-plane interface. It is useful for explicit artifact operations, CI, audit, and commissioning-readiness inspection.

Example low-level operations:

```bash
devagent-commercial --db ~/.devagent/projects.db init CELL-01 \
  --name "Customer Cell" \
  --site SITE-01 \
  --workcell CNC-LOAD

devagent-commercial --db ~/.devagent/projects.db import-twin CELL-01 ./customer-project

devagent-commercial --db ~/.devagent/projects.db requirements CELL-01 requirements.yaml

devagent-commercial --db ~/.devagent/projects.db engineering-review CELL-01 <requirement-set-artifact-id>

devagent-commercial --db ~/.devagent/projects.db verification-plan CELL-01 verification.yaml

devagent-commercial --db ~/.devagent/projects.db campaign CELL-01 requirements.yaml \
  --measurement <physical-measurement-artifact-id>

devagent-commercial --db ~/.devagent/projects.db fat-report CELL-01 <campaign-artifact-id>

devagent-commercial --db ~/.devagent/projects.db evidence-bundle CELL-01 <campaign-artifact-id>

devagent-commercial --db ~/.devagent/projects.db commissioning-readiness CELL-01

devagent-commercial --db ~/.devagent/projects.db commissioning-status CELL-01
```

`verification-plan` records an explicit deterministic plan from the supplied spec. It does **not** invent a requirement→case mapping. Final commissioning readiness requires exact current requirement-to-case lineage; the one-command workflow records that mapping, and low-level/custom integrations must record equivalent immutable lineage instead of bypassing the gate.

Use `finding-disposition` to record an immutable engineering disposition. A blocking finding cannot be resolved without current-Twin evidence.

## What DevAgent proves

DevAgent separates planning, execution, measurement, verdicts, and authority.

```text
Requirement / report test
        ↓
Declarative verification capability
        ↓
Exact Twin revision/hash
        ↓
Exact verification plan + case mapping
        ↓
Qualified evidence reuse or qualified execution
        ↓
Measured evidence
        ↓
Deterministic verdict
        ↓
PASS / FAIL / NOT_TESTED
```

A generated plan is not physical proof. A replay is not a new execution. An AI response is not engineering evidence. A simulation result does not grant site qualification.

## Engineering findings and risk authority

v2.0 records first-class immutable artifacts for:

```text
engineering_finding
engineering_review
engineering_finding_disposition
```

High and critical findings are structurally blocking. AI or a human reviewer may propose findings, but findings do not create PASS authority.

A blocking finding may be marked resolved only when the disposition references evidence bound to the current Twin scope. Acknowledged, deferred, or accepted-risk records remain explicit and do not silently promote readiness.

## Verification-scope authority

A verification plan is not trusted merely because it belongs to the same Twin.

`VerificationScopeAuthority` deterministically reconstructs the expected test space from the exact current campaign requirements and compares the stored plan and requirement-to-case mapping with that expected scope.

If a requirement change alters payload, boundary, or fault coverage but an old plan/map is reused, readiness fails closed.

## Physical evidence authority

### Internal simulation / hardware-shadow evidence

A standalone measurement JSON cannot grant final readiness merely by claiming `gazebo_moveit`, a run ID, and a qualification reference.

Internal evidence must preserve an exact immutable chain:

```text
physical_measurement
        ↓
runtime_measurement_binding
        ↓
physical_motion_plan
        ↓
exact Twin + run + qualification lineage
```

### External simulator evidence

External evidence is imported as candidate evidence and is independently gated by installed provider policy.

Built-in provider identities include:

```text
ABB RobotStudio
FANUC ROBOGUIDE
KUKA.Sim
Visual Components
RoboDK
Siemens Process Simulate
```

These identities do not imply qualification. A provider remains candidate-only unless a code-reviewed policy explicitly qualifies its version/export schema and binds exact source provenance, candidate evidence, Twin hash, metrics, and qualification reference.

## Whole-project staleness

Each pre-site decision records a deterministic readiness-state snapshot hash.

A previous READY result becomes stale when readiness-relevant state changes, including:

```text
Twin revision
requirement set
engineering review
finding / disposition
verification plan
requirement-case mapping
physical measurement / runtime binding
campaign
change impact
regression
FAT report
evidence bundle
```

This also catches same-Twin changes. `commissioning-status` verifies both the decision hash and the current project-state snapshot before reporting READY.

## Evidence Graph and replay

The read-only Evidence Graph links requirements, Twin revisions, campaigns, findings, dispositions, measurements, motion plans, regressions, FAT reports, evidence bundles, and final readiness decisions.

```bash
devagent-commercial --db ~/.devagent/projects.db evidence-graph CELL-01
```

Write a self-contained viewer:

```bash
devagent-commercial --db ~/.devagent/projects.db evidence-viewer CELL-01 \
  --output ./EVIDENCE.html
```

Replay reconstructs persisted evidence identity. It never commands Gazebo, MoveIt, a robot, PLC, or safety PLC.

## Interactive engineering session

Use `--interactive`, or `--open` from a real terminal, to keep a bounded prompt:

```text
status
tests
test SELECTOR
simulate SELECTOR
simulate all
simulate --fresh SELECTOR
simulate --fresh all
rerun SELECTOR
rerun failed
rerun blocked
rerun affected
rerun all
replay
report
log
help
quit
```

`test SELECTOR` evaluates existing evidence without commanding the simulator.

`simulate TEST-X` reuses exact qualified evidence when available and executes only when the mapped physical case is missing.

`simulate --fresh TEST-X` and physical `rerun ...` explicitly request new execution and append new immutable evidence.

Report-wide fresh execution still deduplicates shared physical case IDs.

## Qualified visual-execution scope

Measured report-test execution remains intentionally narrow:

```text
robot:       UR5e
operation:   load
case scope:  qualified mapped physical report cases within the packaged authority
runtime:     Ubuntu 24.04 + ROS 2 Jazzy + Gazebo Harmonic + MoveIt/Pilz
```

The target-proven UR5e path retains controller-manager/action readiness binding, canonical Twin/PlanningScene verification, conservative Pilz PTP/LIN motion, workpiece attach/carry/release semantics, controller-feedback tracking evidence, and post-release settle verification.

Unsupported customer Twins, unqualified robot profiles, boundary/fault cases outside the qualified scope, ambiguous case mappings, or incomplete lineage fail closed.

ABB IRB1200 remains a separate experimental visual simulation path. FANUC/KUKA and other robot/vendor paths retain their truthful support tiers until separately qualified.

Inspect robot support:

```bash
devagent robots
devagent robot doctor abb_irb1200
devagent robot visualize abb_irb1200
```

## Customer input

A customer folder can contain the engineering material the team already has:

```text
ACME_CNC_CELL_TEST/
├── project.yaml
├── requirements.xlsx
├── devagent-twin.yaml
├── robot.urdf
├── robot.urdf.xacro
├── robot.srdf
├── tcp.yaml
├── calibration.yaml
├── layout/
│   ├── cell_layout.yaml
│   └── meshes/
├── robot_program/
│   └── mission.yaml
└── expected/
    └── expected_findings.json
```

Important rule:

```text
file discovered != engineering fact proven
```

DevAgent fingerprints and classifies files, but filenames do not prove poses, TCPs, calibrations, collision geometry, safety behavior, or physical performance.

If critical information is missing or ambiguous, DevAgent asks for information instead of inventing engineering facts.

## Results and evidence

Typical output:

```text
customer-project/
└── devagent-results/
    ├── RUN.log
    ├── SUMMARY.json
    ├── INTAKE.json
    ├── QUESTIONS.md
    ├── normalized/
    │   ├── requirements.csv
    │   └── devagent-twin.yaml
    ├── report-test-visualization/
    ├── FAT_REPORT.html
    └── EVIDENCE.html
```

`EVIDENCE.html` is read-only engineering evidence. `RUN.log` is a human progress/debug trace and does not replace immutable evidence artifacts.

## Physical simulation setup

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

Reference stack:

```text
Ubuntu 24.04
ROS 2 Jazzy
Gazebo Harmonic
gz_ros2_control
MoveIt 2
```

UR5e measured report-test execution additionally uses the Universal Robots ROS 2 driver, `ur_simulation_gz`, and Pilz Industrial Motion Planner.

Preview UR5e setup:

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

Apply explicitly:

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

Check runtime prerequisites:

```bash
devagent-physical ros doctor
devagent robot doctor abb_irb1200
```

Hosted CI validates deterministic software contracts. It does not pretend to execute a graphical ROS/Gazebo/MoveIt target stack. Target-stack acceptance must run on the intended workstation.

## Optional AI providers

AI is optional and advisory.

```bash
python -m pip install "devagent-physical-engine[openai]"
python -m pip install "devagent-physical-engine[anthropic]"
python -m pip install "devagent-physical-engine[gemini]"
python -m pip install "devagent-physical-engine[ai]"
```

Typical credentials:

```bash
export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."
export GEMINI_API_KEY="..."
```

Provider-backed interpretation cannot grant physical truth, site qualification, functional-safety certification, or real-execution authority.

## Installed CLIs

```text
devagent             one-command verification, interactive report testing, robot support/visualization
devagent-commercial  project, evidence, findings, FAT, regression, commissioning-readiness workflow
devagent-physical    deterministic core + ROS/qualification tools
devagent-physical-ai optional provider-backed engineering front end
```

## Simple Mode exit codes

| Exit | Meaning |
| ---: | --- |
| `0` | bounded full verification is release-ready |
| `10` | customer input or operational contract failure |
| `30` | more engineering information is required |
| `31` | requested simulation is blocked/unqualified |
| `32` | verification completed but full release readiness is false |

# Project status

**v2.0.0 — Production/Stable software workflow; commissioning verification control plane with fail-closed pre-site readiness**

v2.0.0 adds immutable engineering findings/dispositions, deterministic verification-scope authority, stronger internal/external evidence authority, commissioning-aware Evidence Graph lineage, whole-project staleness detection, and an immutable pre-site commissioning readiness decision.

Production-oriented software capabilities include:

```text
one-command customer intake
XLSX/CSV/YAML/JSON requirement normalization
immutable project/Twin lineage
engineering review + first-class risk findings
evidence-backed finding dispositions
validated Requirement → Criterion mapping
optional provider-backed advisory criterion proposals
requirement-driven nominal / boundary / fault case generation
verification-scope authority against current requirements
exact Requirement → Mapping → Verification Plan → Case provenance
case-centric qualified evidence reuse
explicit fresh physical execution
verification-owned simulator lifecycle cleanup
mixed deterministic + physical report orchestration
truthful PASS / FAIL / NOT_TESTED
runtime-bound internal physical evidence authority
policy-bound external simulator evidence authority
commissioning-aware Evidence Graph
whole-project readiness staleness detection
change impact + regression
professional FAT report
Evidence Bundle + replay
immutable READY / NOT_READY pre-site commissioning decision
provider-neutral optional AI front end
```

Production/Stable describes the bounded software workflow. The target-proven UR5e claim remains limited to the qualified packaged scope and acceptance environment. v2.0.0 does not claim arbitrary customer cells are physically qualified, site-qualified, functionally safe, commissioned, or authorized for autonomous real execution.

Current hard authority boundaries remain:

```text
site_qualification = false
functional_safety_certification = false
commissioning_completed = false
real_execution_allowed = false
```

unless separately proven by an appropriate qualified process.

## Documentation

v2.0.0 release notes:
https://github.com/tomha85/devagent-physical-engine/blob/main/docs/RELEASE_NOTES_V2_0_0.md

v1.9.1 release notes:
https://github.com/tomha85/devagent-physical-engine/blob/main/docs/RELEASE_NOTES_V1_9_1.md

v1.9.0 release notes:
https://github.com/tomha85/devagent-physical-engine/blob/main/docs/RELEASE_NOTES_V1_9_0.md

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

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

## 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 complete ownership and usage terms.
