Metadata-Version: 2.4
Name: devagent-physical-engine
Version: 1.8.5
Summary: Verification-first robotics commissioning runtime with exact-Twin evidence, qualified UR5e Gazebo/MoveIt report execution, truthful robot support tiers, selective verification, replay, regression, 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
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)

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

DevAgent turns a customer engineering folder into a bounded verification workflow with immutable Digital Twin lineage, deterministic requirement verdicts, requirement-driven test cases, exact-Twin measured simulation evidence, regression analysis, FAT reporting, replay inspection, and selective retesting.

```text
customer engineering files
    ↓
intake + SHA-256 inventory
    ↓
validated Requirement → Criterion mapping
    ↓
immutable Digital Twin revision
    ↓
requirement-driven nominal / boundary / fault cases
    ↓
qualified exact-Twin simulation when supported
    ↓
measured evidence
    ↓
PASS / FAIL / NOT_TESTED
    ↓
regression + FAT report + Evidence Viewer
```

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

## Quick start

Python 3.11+ is required.

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

Verify the installed package:

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

Expected:

```text
1.8.5
```

Run the normal customer workflow:

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

Request simulation:

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

Open the Evidence Viewer and keep the engineering terminal active:

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

For machine-readable CI output:

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

Inspect truthful robot support tiers:

```bash
devagent robots
```

For the exact ABB IRB1200 experimental visual runtime:

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

Default locations:

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

## What DevAgent proves

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

```text
requirement
  ↓
verification criterion
  ↓
verification case
  ↓
exact Twin revision/hash
  ↓
qualified simulation when available
  ↓
measured evidence
  ↓
PASS / FAIL / NOT_TESTED
```

A generated plan is not physical proof. A replay is not a new execution. A simulation result does not grant site qualification or real-robot authority.

Current hard boundaries remain:

```text
site_qualification = false
real_execution_allowed = false
```

unless separately proven by an appropriate qualified process.

## v1.6 report-test visual execution foundation

v1.6 connected report tests to the exact stored Twin instead of a separate demo scene.

A supported physical report test follows:

```text
Requirement
  → stable Test ID
  → immutable Requirement → Case mapping
  → exact Verification Plan ID/hash
  → exact Case ID
  → exact Twin revision/hash
  → qualified Gazebo/MoveIt execution
  → typed physical_measurement artifact
  → deterministic verdict
```

Interactive example:

```text
devagent> tests
devagent> simulate TEST-PERF-001
```

Measured physical criteria include:

```text
cycle_time_max_s
minimum_clearance_m
final_tcp_error_max_m
max_tracking_error_rad
collision_free
physical_completed
```

Structural/Twin criteria include:

```text
planning_allowed
physics_allowed
entity_present
validation_issue_absent
twin_state
```

A requirement without deterministic evidence remains `NOT_TESTED`; it is never auto-passed from prose or AI interpretation.

## v1.6.1 support-contact lift hotfix

The packaged UR5e reference load starts with the workpiece resting on its source support. During attached-object lift departure, DevAgent preserves the complete live MoveIt Allowed Collision Matrix and temporarily enables exactly the attached-workpiece ↔ source-support pair.

That allowance is scoped only to lift departure. Transfer/place keep normal collision checking. DevAgent does not globally disable collision checking or replace the live matrix with an unsafe sparse matrix.

## v1.6.2 slower measured visual execution

The packaged visual task uses conservative MoveIt scaling so motion is inspectable while remaining real trajectory execution:

```text
velocity scale:      12%
acceleration scale:   8%
```

The joint-state recorder also rejects duplicate/backward ROS timestamps instead of manufacturing synthetic time. Collision, endpoint, tracking, Twin-lineage, and authority checks remain fail-closed.

## v1.7 industrial PTP/LIN execution

v1.7 moves the qualified UR5e report test to the MoveIt Pilz Industrial Motion Planner rather than hand-building interpolation.

The bounded task sequence is:

```text
HOME
  ↓ PTP
PRE_PICK
  ↓ LIN
PICK
  ↓ grasp hard boundary
LIFT
  ↓ LIN support departure hard boundary
TRANSFER
  ↓ PTP
PLACE
  ↓ LIN release hard boundary
RETRACT
  ↓ LIN
HOME
  ↓ PTP
```

Original v1.7 execution groups:

```text
approach_pick    PTP → LIN
lift_departure   LIN
transfer_place   PTP → LIN
retreat_home     LIN → PTP
```

Conservative limits:

```text
PTP velocity scale:       10%
PTP acceleration scale:    6%
LIN velocity scale:        6%
LIN acceleration scale:    4%
requested blend radius:   12 mm
workpiece follow target:   60 Hz
```

MoveIt/Pilz owns geometry, timestamps, collision checking, velocity/acceleration time parameterization, and the returned `RobotTrajectory`. DevAgent does not fake smoothness with teleports or sleeps.

## v1.7.1 adaptive Pilz blend hotfix

A real ROS 2 Jazzy + Gazebo Harmonic + MoveIt/Pilz target-stack run showed:

```text
approach_pick    PASS
lift_departure   PASS
transfer_place   Pilz FAILURE(99999)
execution        NOT STARTED
```

Pilz can reject a sequence when a requested blend sphere is not feasible for that specific geometry. v1.7.1 therefore keeps the same PTP/LIN targets, attached/world scene contract, collision policy, velocity/acceleration limits, and execution authority while retrying only the internal blend radius:

```text
12 mm
  ↓ if Pilz returns pilz_sequence_planning_failed
6 mm
  ↓
3 mm
  ↓
0 mm
```

Every candidate is still planned and collision-checked by MoveIt/Pilz. DevAgent selects the largest candidate Pilz actually accepts. If the zero-blend candidate fails, execution remains blocked.

The fallback is intentionally narrow:

```text
no target modification
no planner-type substitution
no collision disable
no speed increase
no hand-built interpolation
no fake PASS
no fallback to an unqualified simulator or robot
```

The selected blend radii and every planning attempt receipt remain attached to motion metadata for auditability.

## v1.7.2 transfer/place diagnostic hotfix

A target-stack qualification run proved that `transfer_place` still returned Pilz `FAILURE(99999)` for every v1.7.1 blend candidate, including zero blend. v1.7.2 therefore does not keep guessing at blend values. When that exact bounded failure occurs, DevAgent remains fail-closed and runs two independent **plan-only** probes against the same attached-workpiece PlanningScene:

```text
lift target
   ↓
transfer PTP probe
   ↓ independent start at transfer target
place LIN probe
```

The result is classified deterministically as one of:

```text
pilz_transfer_segment_planning_failed
pilz_place_segment_planning_failed
pilz_transfer_and_place_segment_planning_failed
pilz_transfer_place_sequence_composition_failed
```

Each probe writes its own request/receipt plus a `transfer-place-diagnostic.json` summary. These probes never execute motion and never relax targets, planner types, collision policy, attached-workpiece scene state, velocity/acceleration limits, Twin lineage, or real-execution authority. Their purpose is to identify the exact target-stack defect before changing physical execution semantics.

## v1.8 truthful robot support + ABB IRB1200 visual runtime

v1.8 makes robot support explicit instead of implying that every built-in robot profile has the same simulator authority.

Support is exposed through:

```bash
devagent robots
devagent robot doctor <robot>
devagent robot visualize <robot>
```

The exact `abb_irb1200` profile adds an experimental visual runtime using Ubuntu 24.04, ROS 2 Jazzy, Gazebo Harmonic, `gz_ros2_control`, upstream ABB IRB1200 geometry, MoveIt, and RViz. Runtime readiness is bounded on controller state, `/joint_states`, FollowJointTrajectory, `move_group`, and RViz availability.

For the Golden ABB cell, DevAgent can load the waypoint seed, pre-plan every phase through MoveIt before sending any simulated trajectory, then execute the preview while Gazebo/RViz remain open for inspection.

This is intentionally **visual simulation availability**, not measured FAT qualification. ABB preview evidence is not promoted to a qualified physical measurement, and `real_execution_allowed` remains false. The normal One-Command ABB FAT path continues to fail closed until an exact-Twin measured ABB execution adapter is separately qualified.

Generic `abb_irb`, FANUC CRX, and KUKA KR profiles remain model-only until equivalent vendor/model visual runtimes are implemented and qualified.

## v1.8.1 direct UR5e controller/action readiness hotfix

A real UR5e target-stack run proved that Gazebo, `gz_ros2_control`, the controller manager, joint-state broadcaster, and `scaled_joint_trajectory_controller` could all initialize successfully while DevAgent remained stuck in startup readiness until the 120-second timeout. The old UR5e readiness gate depended on ROS CLI graph commands and expected the unscaled `/joint_trajectory_controller/follow_joint_trajectory` action even when the active controller was the scaled UR controller.

v1.8.1 makes UR5e readiness and trajectory execution use one controller-binding contract. A short-lived direct `rclpy` probe calls `/controller_manager/list_controllers`, deterministically selects the active trajectory controller, verifies its exact `FollowJointTrajectory` action server, and returns the bound action name. Required UR5e joint-state readiness continues to use the direct machine joint-state probe.

The readiness gate therefore no longer depends on a long-lived `ros2 daemon`, `ros2 node list`, `ros2 topic list`, or `ros2 action list`. It remains fail-closed on missing controller-manager service, no active trajectory controller, ambiguous active controllers, a missing trajectory action server, or missing required UR5e joint state. No collision rule, Pilz target, motion speed, Twin lineage, site-qualification boundary, or real-execution authority is relaxed.

## v1.8.2 scoped destination-support place contact

A clean v1.8.1 UR5e target-stack run reached exact-Twin read-back and independently proved that transfer PTP planning succeeds while the attached-workpiece place LIN segment fails. v1.8.2 converts that evidence into a narrow placement contract rather than disabling collision checking.

The qualified report runtime now uses hard transfer/place boundaries:

```text
approach_pick       PTP → LIN
lift_departure      LIN
transfer_departure  PTP
transfer_place      LIN   # place only
retreat_home        LIN → PTP
```

`transfer_departure` remains normally collision checked. Only the single zero-blend `place` LIN planning request may add one request-local Allowed Collision Matrix pair:

```text
attached workpiece ↔ declared destination support
```

The place probe starts from the complete live MoveIt ACM, preserves every existing entry, enables only that symmetric pair, and applies the matrix only to the request-local PlanningScene diff. The transfer path cannot inherit the allowance. No global/live destination-contact lease remains active after planning.

The v1.8.2 place receipt records the exact destination support id, workpiece id, phase, and contact scope. Missing destination identity, a non-attached scene, a non-LIN place planner, nonzero place blending, malformed support identity, or mismatched receipt fails closed.

The release does **not** change real-execution authority, site qualification, target poses, conservative motion scales, or the rule that every motion group must preflight successfully before execution begins.

## v1.8.3 synchronous verified workpiece attach

A clean v1.8.2 target-stack run proved all five industrial preflight groups and actual `approach_pick` execution, then failed closed at GRASP with `workpiece_lifecycle_failed:apply_planning_scene_rejected`.

The attach request previously combined an `AttachedCollisionObject.ADD` with a redundant same-ID world `CollisionObject.REMOVE`. MoveIt applies attached-object state first, which already transitions the same-ID object out of the world. Processing the later redundant world REMOVE can therefore make synchronous `/apply_planning_scene` report failure even though the attachment transition was already attempted.

v1.8.3 makes the attach transition service-safe and deterministic: the request contains only the authoritative attached-object ADD. DevAgent then synchronously reads the PlanningScene back and requires all of the following before motion may continue:

```text
workpiece absent from world
exactly one attached object with the expected id
attached link == verified tool mount link
attached primitive geometry is valid
attachment pose/geometry hash matches the expected attachment hash
```

Detach semantics remain explicit attached-object REMOVE plus world-object ADD at the verified placement pose. No collision rule, tool/workpiece geometry, TCP, touch link, target pose, motion speed, planner, site-qualification boundary, or real-execution authority is relaxed.

## v1.8.4 PyPI metadata compliance hotfix

v1.8.4 carries the exact v1.8.3 runtime semantics and shortens only the package Core Metadata `Summary` so it satisfies PyPI's 512-character limit. A regression test now parses `pyproject.toml` and rejects an empty or over-limit project description before release.

This metadata hotfix does not change the UR5e attach/detach lifecycle, collision policy, motion planning, Twin lineage, site-qualification boundary, or real-execution authority.

## v1.8.5 quaternion-invariant verified workpiece attach

A clean v1.8.4 UR5e target-stack run proved that synchronous `/apply_planning_scene` attachment now succeeds, world/attached state reaches strict read-back, and the remaining GRASP blocker is `workpiece_attachment_hash_mismatch`.

MoveIt round-trips attached-object rotations through Eigen. Unit quaternions `q` and `-q` represent the same physical rotation, but a raw component hash treats those two equivalent representations as different. v1.8.5 canonicalizes equivalent quaternion signs before workpiece attachment hashing using the same deterministic positive-`w` / first-nonzero-component rule already used by the qualified tool-scene path.

Verification remains strict for attachment identity, link, geometry contract, position, and physical rotation. This is not a tolerance-based PASS and does not change target geometry, TCP, collision policy, planner types, motion speeds, controller binding, Twin lineage, site qualification, or real-execution authority. If a hash mismatch remains, DevAgent records expected and observed hashes plus canonical expected/object/primitive/effective attachment poses for target diagnosis.

## Qualified visual-execution scope

Measured report-test execution remains intentionally narrow:

```text
robot:       UR5e
operation:   load
case scope:  one nominal mapped physical report case
runtime:     Ubuntu 24.04 + ROS 2 Jazzy + Gazebo Harmonic + MoveIt/Pilz
```

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

ABB IRB1200 is separately exposed as `SIMULATION_AVAILABLE_EXPERIMENTAL`: Gazebo/MoveIt/RViz preview is available, but it does not silently enter the UR5e measured FAT executor and cannot promote physical evidence.

## Interactive engineering session

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

```text
status
tests
test SELECTOR
simulate [SELECTOR]
rerun [SELECTOR]
rerun failed
rerun blocked
rerun affected
replay
report
log
help
quit
```

Selectors can be requirement IDs, test IDs, or bounded groups:

```text
REQ-PERF-001
TEST-PERF-001
failed
blocked
affected
all
```

`test SELECTOR` evaluates deterministic/evidence checks without commanding the simulator.

`simulate TEST-X` requests qualified execution of the selected mapped physical report case.

`replay` reconstructs persisted evidence identity; it never commands Gazebo, MoveIt, a robot, PLC, or safety PLC.

## 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.

The root `expected/` folder is test-oracle material and is never promoted as engineering authority.

If critical information is missing or ambiguous, DevAgent writes questions into the project results instead of guessing.

## 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 debug/progress trace and does not replace immutable evidence artifacts.

Repeat runs compare the immediately previous campaign with the current campaign before a new FAT artifact is finalized.

## 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 the UR5e runtime:

```bash
devagent-physical ros doctor
```

Check ABB IRB1200 visual runtime prerequisites:

```bash
devagent robot doctor abb_irb1200
```

Launch ABB IRB1200 Gazebo + MoveIt + RViz preview:

```bash
devagent robot visualize 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  commercial/evidence 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

**v1.8.5 — Production/Stable software workflow**

v1.8.5 retains v1.8.4 PyPI metadata compliance, v1.8.3 synchronous service-safe workpiece attachment, v1.8.2 scoped destination-support place contact, v1.8.1 direct UR5e controller/action binding, truthful robot support tiers, and the ABB IRB1200 experimental visual runtime. It makes strict workpiece attachment verification invariant to the mathematically equivalent quaternion representations `q` and `-q` and persists exact pose/hash diagnostics for any remaining mismatch.

Production-oriented software capabilities include:

```text
one-command customer intake
XLSX requirement normalization
validated Requirement → Criterion mapping
optional provider-backed advisory criterion proposals
requirement-driven nominal / boundary / fault case generation
immutable project/Twin lineage
exact Requirement → Mapping → Verification Plan → Case provenance
truthful robot support tiers
qualified UR5e report-test visual execution contract
direct UR5e controller-manager/action readiness binding
synchronous verified workpiece attach/detach lifecycle
quaternion-invariant strict attachment hashing
scoped destination-support place contact
experimental exact ABB IRB1200 Gazebo/MoveIt/RViz preview
industrial Pilz PTP / LIN planning
adaptive bounded blend selection
plan-only transfer/place segment diagnostics
lift-only source-support contact lease + exact restore
Gazebo/MoveIt selected-case visualization
typed physical measurement binding
deterministic campaigns
repeat-run regression
professional FAT / Evidence Viewer
interactive selective verification
Evidence Bundle + replay
change impact + regression
provider-neutral optional AI front end
```

Production/Stable describes the bounded software workflow. It does not claim arbitrary customer cells are physically qualified, site-qualified, functionally safe, or authorized for autonomous real execution.

## Documentation

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

Report-test visual execution foundation:
https://github.com/tomha85/devagent-physical-engine/blob/main/docs/REPORT_TEST_VISUAL_EXECUTION_V16.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.
