Metadata-Version: 2.4
Name: devagent-physical-engine
Version: 1.6.2
Summary: Production-grade verification-first robotics evidence runtime with one-command customer intake, validated requirement mapping, report-test Gazebo visualization, 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,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.6.2
```

Verify the installed package:

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

Expected:

```text
1.6.2
```

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.

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

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`, 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.6.2 — Production/Stable software workflow**

v1.6.2 slows the packaged UR5e task/report visual motion to conservative 12% velocity / 8% acceleration defaults and hardens JointState acquisition against duplicate/backward ROS timestamps. It retains the v1.6.1 lift support-contact fix, exact-Twin report execution, immutable Requirement→Mapping→Verification Plan→Case lineage, typed simulation measurements, 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
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, 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.

---

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

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.
