Metadata-Version: 2.4
Name: devagent-physical-engine
Version: 1.7.2
Summary: Production-grade verification-first robotics evidence runtime with one-command customer intake, validated requirement mapping, adaptive industrial Pilz PTP/LIN report-test Gazebo execution, transfer/place segment diagnostics, 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
```

> **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.7.2
```

Verify the installed package:

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

Expected:

```text
1.7.2
```

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

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

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.

## Qualified visual-execution scope

The packaged visual executor 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.

Cross-vendor projects such as ABB may still be imported, normalized, structurally evaluated, and reported, but they do not silently enter the UR5e-only physical executor.

## 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
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 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 customer verification + interactive report testing
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.7.2 — Production/Stable software workflow**

v1.7.2 retains the v1.7 industrial Pilz PTP/LIN execution architecture and v1.7.1 bounded adaptive-blend fallback. If transfer/place still fails at zero blend, v1.7.2 now proves the transfer PTP and place LIN segments independently and records a deterministic diagnostic result while keeping execution blocked. It also retains the cross-vendor profile gate so non-UR5e customer Twins cannot enter the UR5e-only qualified visual executor.

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
qualified report-test visual execution contract
industrial Pilz PTP / LIN planning
adaptive bounded blend selection
plan-only transfer/place segment diagnostics
lift-only support-contact ACM 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.
