Metadata-Version: 2.4
Name: devagent-physical-engine
Version: 1.7.0
Summary: Production-grade verification-first robotics evidence runtime with one-command customer intake, validated requirement mapping, industrial Pilz PTP/LIN report-test Gazebo execution, requirement-driven test generation, selective verification, deterministic Twin lineage, measured physical verification, replay inspection, regression, and FAT evidence.
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
    ↓
selective retest / replay
```

> **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: **What can be proven about this cell, what failed, what remains unknown, what changed, and what evidence supports the conclusion?**

---

## Quick start

Python 3.11+ is required.

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

Verify the installed package:

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

Expected:

```text
1.7.0
```

Run the normal customer workflow:

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

Request simulation:

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

Open the Evidence Viewer and retain an interactive engineering session:

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

For machine-readable CI output:

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

Default locations:

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

---

# v1.6 report-test visual execution

v1.6 closes the gap between report test cases and the previously separate ROS/Gazebo reference visualization path.

A physical report test can now follow this bounded chain:

```text
Requirement
    ↓
stable Test identity
    ↓
immutable Requirement → Case mapping
    ↓
exact Verification Plan ID/hash
    ↓
exact Case ID
    ↓
exact Twin revision/hash
    ↓
qualified report execution profile
    ↓
Gazebo + MoveIt visible execution
    ↓
typed physical_measurement artifact
    ↓
deterministic PASS / FAIL / NOT_TESTED
    ↓
refreshed Evidence Viewer
```

Interactive example:

```text
devagent> tests
REQ-PERF-001         TEST-PERF-001        NOT_TESTED  case-0001

devagent> simulate TEST-PERF-001
```

For a supported qualified case, DevAgent materializes the **exact immutable report Twin** in the visual runtime. It does not run a separate demo Twin and relabel that result as customer evidence.

The execution runtime binds measured metrics such as:

```text
cycle_time_s
minimum_clearance_m
final_tcp_error_m
max_tracking_error_rad
collision_free
completed
sample_count
```

The resulting `physical_measurement` remains scoped to the exact Twin revision/hash and case lineage that produced it.

## Qualified scope

The initial packaged visual-execution qualification is intentionally narrow:

```text
robot:       UR5e
operation:   load
profile:     packaged qualified report-execution profile
case scope:  one nominal mapped physical case
runtime:     ROS 2 Jazzy + Gazebo Harmonic + MoveIt 2
```

Unsupported customer Twins, boundary/fault cases, multiple mapped cases, incomplete mappings, ambiguous case IDs, mismatched verification plans, or unqualified execution profiles fail closed.

DevAgent never substitutes:

```text
devagent-physical ros demo
```

for report evidence.

## v1.6.1 support-contact lift hotfix

The qualified reference load profile starts with the workpiece physically resting on its source support. During the first attached-object `lift` preflight, v1.6.1 preserves the complete live MoveIt Allowed Collision Matrix and enables exactly one temporary request-local pair:

```text
attached workpiece ↔ conveyor_a support surface
```

That allowance is scoped to lift departure only. Transfer/place keep normal collision checking, no global PlanningScene collision policy is disabled, and the live ACM is never replaced by a sparse two-object matrix.

## v1.6.2 smooth visual motion hotfix

v1.6.2 makes the packaged UR5e visual task deliberately slower and easier to inspect. The task-specific MoveIt planner defaults are reduced from 25% velocity / 25% acceleration to:

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

This is real trajectory time parameterization through MoveIt and `FollowJointTrajectory`; DevAgent does not fake smoothness with teleports or sleeps. Explicit planner scales remain authoritative. Collision checks, endpoint tolerances, tracking tolerances, Twin lineage, and real-execution authority are unchanged.

The joint-state recorder also rejects duplicate/backward ROS source timestamps before trajectory interpolation while recording the number of dropped samples. This removes the false `trajectory_tracking_time_not_increasing` failure caused by duplicate Gazebo/ros2_control JointState stamps without manufacturing synthetic timestamps.

Because the visual trajectory now executes more slowly, cycle-time requirements are evaluated against the actual slower simulation execution. DevAgent does not normalize the observed duration back to a faster value or claim performance that was not executed.

## v1.7 industrial smooth motion execution

v1.7 replaces the packaged report-test stop/go joint-phase presentation with a bounded industrial motion sequence planned by the running MoveIt **Pilz Industrial Motion Planner**. DevAgent does not stitch trajectories by hand and does not manufacture interpolation points.

The qualified UR5e load sequence is grouped as:

```text
HOME
  ↓  PTP
PRE_PICK
  ↓  LIN
PICK
  ↓  grasp / hard boundary
LIFT
  ↓  LIN support departure / hard boundary
TRANSFER
  ↓  PTP with safe internal blend
PLACE
  ↓  LIN / release hard boundary
RETRACT
  ↓  LIN with safe internal blend
HOME
  ↓  PTP
```

Execution groups are intentionally bounded:

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

Compatible motion inside a group can use a small Pilz blend radius. DevAgent never blends through grasp, the support-contact departure boundary, or release. The simulation profile is deliberately conservative:

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

`LIN` means the Pilz planner owns a Cartesian linear tool path; `PTP` remains collision-aware point-to-point planning. MoveIt/Pilz owns geometry, timestamps, velocity/acceleration time parameterization, collision checking, and the returned blended `RobotTrajectory`.

The source-support exception is also bounded at runtime. During `lift_departure`, DevAgent snapshots the complete live MoveIt Allowed Collision Matrix, enables exactly the attached-workpiece ↔ source-support pair, verifies read-back, executes the lift, restores the exact original matrix, and verifies the restoration before transfer is allowed to continue. No global collision disable is used.

Slower industrial execution is real execution time in simulation, not cosmetic playback. Therefore cycle-time requirements are evaluated against the actual measured slower trajectory.

The v1.7 hosted qualification proves deterministic software contracts and fail-closed routing. Graphical ROS 2 Jazzy + Gazebo Harmonic + MoveIt/Pilz target-stack acceptance still has to run on the intended workstation; hosted Python CI does not pretend to execute that graphical stack.

## Exact lineage hardening

A case ID such as `case-0001` is local to its verification plan. v1.6+ therefore requires the complete lineage:

```text
Requirement
 → mapping artifact
 → exact Verification Plan ID/hash
 → exact Case ID
 → exact Twin revision/hash
 → execution
 → measurement
```

If another plan reuses the same case ID, or the mapping references a different plan, report execution is blocked instead of guessing.

Full `--simulate` also fails closed if any physical requirement lacks an exact case mapping, or if the union of mapped physical cases is outside the currently qualified single-case scope.

---

# Requirement intelligence and test generation

DevAgent maps supported requirement language into deterministic criteria only when the mapping can be validated. Supported measured physical checks include:

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

Supported structural/Twin checks include:

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

Provider-backed OpenAI, Anthropic, or Gemini proposals are advisory. They cannot create physical truth, site qualification, or real-execution authority.

Requirement-driven case generation can derive bounded variations and fault cases from explicit engineering requirements, including payload ranges, TCP offset boundaries, missing-workpiece faults, and grasp-verification failures.

A requirement with no deterministic criterion or required measurement remains:

```text
NOT_TESTED
```

It is never auto-passed from prose, CAD filenames, generated plans, or AI interpretation.

---

# Interactive engineering session

With `--open` in a real TTY, or with explicit `--interactive`, DevAgent keeps a bounded engineering 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` re-evaluates existing immutable evidence and does not command a simulator.

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

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

Selective runs never silently promote full FAT readiness.

---

# 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
├── ur5e.urdf
├── robot.urdf.xacro
├── ur5e_robotiq.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 it does not treat a filename as proof of pose, TCP, calibration, 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 creates:

```text
<customer-project>/devagent-results/QUESTIONS.md
```

Update the original customer engineering information and rerun the same command.

---

# Results and evidence

A normal project can produce:

```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. It exposes requirement verdicts, observed/expected values, blockers, artifact IDs/hashes, Twin revision hashes, selective runs, and measurement lineage.

`RUN.log` is the human progress/debug trace. It does not replace immutable engineering evidence.

Repeat runs on the same project automatically compare the immediately previous campaign with the current campaign before the new FAT artifact is generated.

---

# Authority model

DevAgent separates:

```text
requirement
verification intent
physical execution case
measured evidence
verdict
authority/readiness
```

A plan proves that a test was planned. A mapping proves which case is bound to a requirement. A measurement proves only what was actually measured. A replay proves persisted identity can be reconstructed.

None of those alone equals site commissioning or functional-safety certification.

Current hard boundaries remain:

```text
physical_qualification = false unless separately proven
site_qualification = false
real_execution_allowed = false
```

The operating principle remains:

```text
Agents propose.
Deterministic engines compile and verify.
Qualified simulators measure bounded scopes.
Existing certified controllers execute real equipment.
```

---

# 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
Universal Robots ROS 2 driver
ur_simulation_gz
MoveIt 2 + Pilz Industrial Motion Planner
```

Preview setup:

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

Apply explicitly:

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

Check runtime:

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

Hosted Python CI validates software contracts and deterministic execution boundaries. It does not by itself prove a graphical Gazebo runtime, `move_group`, `/sequence_move_group`, TF, controller actions, OEM drivers, or an arbitrary customer cell. Physical target-stack qualification must run on the intended workstation/adapter stack.

---

# Optional AI providers

AI is optional and remains outside deterministic authority.

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

Or install all provider adapters:

```bash
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 can propose intent or criterion mappings. It cannot grant deterministic safety, physical qualification, site qualification, or real-execution authority.

---

# Installed CLIs

```text
devagent             one-command customer verification + interactive report testing
devagent-commercial  expert 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` | full simulation was requested but the exact execution path is blocked/unqualified |
| `32` | verification completed but full release readiness is false |

---

# Project status

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

v1.7.0 adds industrial smooth report-test execution for the qualified UR5e load profile using MoveIt Pilz `PTP` and `LIN` commands, bounded internal blend radii, conservative real simulation speed/acceleration, a 60 Hz workpiece-follow target, and an exact live-ACM support-contact lease scoped only to lift departure. It retains exact-Twin report execution, immutable Requirement→Mapping→Verification Plan→Case lineage, typed simulation measurements, deterministic verdicts, and fail-closed authority boundaries.

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 → Case provenance
qualified report-test visual execution contract
industrial Pilz PTP / LIN task planning
bounded safe trajectory blending
lift-only support-contact ACM lease + exact restore
Gazebo/MoveIt selected-case visualization
typed physical measurement binding
deterministic full campaigns
repeat-run regression orchestration
professional FAT/Evidence Viewer
terminal progress + RUN.log
interactive engineering session
Requirement → Test selectors
selective deterministic retest
failed / blocked / affected selectors
Evidence Bundle + replay
change impact + regression
provider-neutral optional AI front end
```

Quality gates include Python 3.11/3.12/3.13 regression, compilation, Ruff correctness checks, package build/clean-install, runtime dependency audit, global branch coverage, One-Command coverage, Commercial Intelligence coverage, industrial-motion contract tests, report-test visual execution qualification tests, Selective Verification coverage, Production Authority coverage, and Evidence Trust/Replay coverage.

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. The new graphical Pilz execution path must additionally pass target-stack acceptance on the intended ROS/Gazebo/MoveIt workstation.

---

# Documentation

One-command verification:

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

v1.6 report-test visual execution (lineage and authority foundation retained in v1.7):

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

Commercial workflow:

https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMERCIAL_V1.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.
