Metadata-Version: 2.4
Name: devagent-physical-engine
Version: 1.4.0
Summary: Production-grade verification-first robotics evidence runtime with one-command customer intake, selective verification execution, 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,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 an ordinary customer engineering folder into a bounded verification workflow with immutable Twin lineage, deterministic requirement verdicts, measured evidence, replay inspection, FAT reporting, and selective retesting.

```text
customer files
    ↓
intake + SHA-256 inventory
    ↓
requirements + explicit engineering facts
    ↓
immutable Digital Twin revision
    ↓
deterministic verification plan
    ↓
measured evidence when a qualified execution path exists
    ↓
PASS / FAIL / NOT_TESTED
    ↓
FAT report + Evidence Viewer
    ↓
selective retest / replay / regression
```

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

Verify the package:

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

Expected:

```text
1.4.0
```

Run the normal customer workflow:

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

Request simulation when the exact imported-Twin execution path is qualified:

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

Open the Evidence Viewer and keep a human engineering terminal session:

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

For machine-readable CI output:

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

Simple Mode automatically handles project identity, customer-file inventory, supported XLSX requirement normalization, bounded Twin normalization, deterministic campaign generation, FAT generation, and evidence rendering. The user does not need to manually manage artifact IDs for the normal workflow.

Default locations:

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

---

# Customer input

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

```text
ACME_CNC_CELL_TEST/
├── project.yaml
├── requirements.xlsx
├── ur5e.urdf
├── robot.urdf.xacro
├── ur5e_robotiq.srdf
├── tcp.yaml
├── calibration.yaml
├── layout/
│   ├── cell_layout.yaml
│   └── meshes/
├── robot_program/
│   └── mission.yaml
├── safety_requirements.pdf
└── 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. PDF documents can be inventoried for review, but arbitrary PDF prose is not silently converted into deterministic PASS evidence.

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.

---

# What the terminal shows

Human Simple Mode keeps the terminal as the primary progress surface:

```text
[DevAgent +   0.00s] START         RUNNING    source=ACME_CNC_CELL_TEST
[DevAgent +   0.00s] INTAKE        RUNNING    scanning and classifying customer engineering files
[DevAgent +   0.42s] REQUIREMENTS  READY      customer requirements normalized
[DevAgent +   0.61s] TWIN          NORMALIZED customer Twin draft normalized
[DevAgent +   0.85s] PROJECT       READY      project_id=acme-cell
[DevAgent +   0.91s] PLAN          READY      artifact=...
[DevAgent +   1.02s] SIMULATION    BLOCKED    imported_customer_twin_execution_adapter_not_yet_qualified
[DevAgent +   1.11s] CAMPAIGN      COMPLETE   artifact=...
[DevAgent +   1.18s] FAT           COMPLETE   artifact=...
[DevAgent +   1.24s] EVIDENCE      COMPLETE   bundle=...
[DevAgent +   1.25s] COMPLETE      DONE       state=verification_incomplete release_ready=False real_execution_allowed=False
[DevAgent +   1.25s] REPORT        OPENING    new tab requested; terminal remains active
```

Progress is also persisted to:

```text
<customer-project>/devagent-results/RUN.log
```

If the browser chooses to take focus, the DevAgent process still remains alive in the terminal. Return to the terminal and continue with the interactive session.

Use `--no-progress` to suppress human progress. `--json` remains machine-clean and never enters the interactive prompt.

---

# Interactive engineering session

With `--open` in a real TTY, or with explicit `--interactive`, DevAgent keeps a bounded engineering prompt after the full verification run:

```text
Interactive engineering session
Type 'help' for commands.

devagent>
```

Useful commands:

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

Examples:

```text
devagent> tests
devagent> test REQ-CAL-001
devagent> test TEST-CAL-001
devagent> simulate REQ-FUN-001
devagent> rerun failed
devagent> rerun blocked
devagent> rerun affected
```

Use `--no-interactive` when `--open` should open the report but the CLI should exit afterward.

---

# v1.4 selective verification

Selective verification reduces unnecessary FAT/retest work without changing the authority model.

## Stable Requirement → Test identity

DevAgent derives a stable deterministic test identity from a requirement identity:

```text
REQ-FUN-001 → TEST-FUN-001
REQ-CAL-001 → TEST-CAL-001
```

The mapping identifies the verification criterion. It does **not** by itself authorize a physical simulation case.

## `test SELECTOR`

Example:

```text
devagent> test REQ-CAL-001
```

or:

```text
devagent> test TEST-CAL-001
```

`test` re-evaluates only the selected requirement/test scope using the exact Twin and currently available immutable evidence. It does not launch a robot or simulator.

The result is recorded separately as:

```text
selective_verification_run
```

A selective artifact includes:

```text
requested selector
selector kind
parent campaign ID/hash
Twin revision/hash
resolved requirement IDs
resolved test IDs
verification contracts
dependencies
measurement/evidence references
verdicts
```

Every selective run explicitly preserves:

```text
full_campaign_executed = false
release_ready = false
real_execution_allowed = false
```

A selective PASS is therefore not silently promoted into a full FAT PASS.

## `simulate SELECTOR`

Example:

```text
devagent> simulate REQ-CAL-001
```

Selective physical execution is stricter than deterministic `test`.

The required chain is:

```text
Requirement
    ↓
stable Test contract
    ↓
explicit verification-test mapping
    ↓
exact physical case ID(s)
    ↓
qualified selective execution adapter
    ↓
measured simulation artifact
    ↓
selective verdict
```

DevAgent never guesses a physical case from requirement prose. Requirement/Test → physical case mapping must be explicit engineering provenance.

If no mapping exists:

```text
state  = blocked
reason = requirement_has_no_qualified_physical_test_mapping
execution_performed = false
```

If the mapping exists but the selective executor is not qualified:

```text
state  = blocked
reason = selective_execution_adapter_not_qualified
execution_performed = false
```

Current v1.4 qualification intentionally supports one explicitly mapped physical case per selective execution. Multiple mapped cases remain fail-closed until aggregation semantics are separately qualified:

```text
selective_multi_case_aggregation_not_yet_qualified
```

## Explicit physical test mapping

Expert integrations can use the public API:

```python
from devagent_physical_engine import VerificationTestMappingRecorder

mapping = VerificationTestMappingRecorder(repository).record(
    project_id="acme-cell",
    revision_id="twin-r0001",
    verification_plan_artifact_id="art-plan",
    bindings={
        "REQ-CAL-001": ["case-0001"],
    },
    source_ref="engineering-map.yaml",
)
```

The recorder validates that the requirement is a physical requirement, the plan belongs to the exact Twin revision, and every case ID exists in that immutable verification plan.

The mapping itself has:

```text
execution_authority = false
physical_qualification = false
site_qualification = false
real_execution_allowed = false
```

## Selectors

Supported selectors are:

```text
REQ-...       one requirement
TEST-...      one deterministic test identity
failed        requirements that failed the parent campaign
blocked       NOT_TESTED requirements plus currently blocked selective scope
affected      requirements selected by latest exact-Twin change-impact evidence
all           all requirements in the parent campaign
```

For example:

```text
devagent> rerun failed
```

re-evaluates only the requirements that failed instead of rerunning the entire campaign.

```text
devagent> rerun affected
```

uses change-impact evidence to retest only affected requirements.

A selector is resolved deterministically. Unknown selectors fail closed.

---

# Full simulation vs selective simulation vs replay

These operations are intentionally different:

| Command | Meaning |
| --- | --- |
| `simulate` | rerun the full one-command verification with simulation requested |
| `simulate REQ-X` | request only the explicitly mapped physical selective test |
| `test REQ-X` | re-evaluate one requirement/test using existing immutable evidence; no simulation |
| `replay` | reconstruct/verify persisted case identity; no new simulation |
| `rerun failed` | retest failed requirement subset |
| `rerun affected` | retest change-impact-selected requirement subset |

Replay never commands Gazebo, MoveIt, a robot, PLC, or safety PLC.

Selective verification never upgrades real-execution authority.

---

# Results directory

A normal project can produce:

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

`EVIDENCE.html` is a read-only professional evidence viewer. It shows requirement verdicts, observed/expected values, blockers, artifact IDs/hashes, and Twin revision hashes. The viewer can be refreshed after selective runs so the new immutable selective artifacts are inspectable.

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

---

# Requirement verdict model

Supported deterministic structural/Twin checks include:

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

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

Verdicts remain bounded:

```text
PASS
FAIL
NOT_TESTED
```

A requirement requiring measured physical evidence cannot PASS from prose, a CAD filename, a generated plan, or AI interpretation.

Example:

```text
Requirement: cycle time <= 8.0 s
Measurement available: no
Verdict: NOT_TESTED
```

With exact-Twin measured evidence:

```text
Requirement: cycle time <= 8.0 s
Observed: 7.42 s
Threshold: 8.0 s
Verdict: PASS
Evidence: exact measurement artifact + Twin revision/hash
```

---

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

Selective results are represented by immutable artifacts inside the interactive session; they do not rewrite the full-run exit contract.

---

# Expert Mode

Installed CLIs:

```text
devagent             one-command customer verification + interactive selective retesting
devagent-commercial  expert commercial/evidence workflow
devagent-physical    deterministic core + ROS/qualification tools
devagent-physical-ai optional provider-backed engineering front end
```

Typical Expert Mode flow:

```text
project identity
    ↓
customer Twin import
    ↓
requirements
    ↓
verification plan
    ↓
measured evidence
    ↓
commercial campaign
    ↓
FAT report
    ↓
Evidence Bundle
    ↓
replay / change impact / regression
```

Example commands:

```bash
devagent-commercial init warehouse-cnc-04 \
  --name "Warehouse CNC Loading Cell 04" \
  --site atl-01 \
  --workcell cnc-04

devagent-commercial import-twin warehouse-cnc-04 ./customer-cell

devagent-commercial requirements warehouse-cnc-04 \
  examples/commercial/requirements-production.csv

devagent-commercial verification-plan warehouse-cnc-04 \
  examples/commercial/verification-plan.yaml \
  --revision twin-r0001

devagent-commercial record-measurement warehouse-cnc-04 \
  physical-measurement.json \
  --revision twin-r0001

devagent-commercial campaign warehouse-cnc-04 \
  examples/commercial/requirements-production.csv \
  --revision twin-r0001 \
  --measurement ARTIFACT_ID

devagent-commercial fat-report warehouse-cnc-04 \
  CAMPAIGN_ARTIFACT \
  --output FAT_REPORT.html

devagent-commercial evidence-bundle warehouse-cnc-04 CAMPAIGN_ARTIFACT

devagent-commercial evidence-graph warehouse-cnc-04 > evidence-graph.json

devagent-commercial evidence-viewer warehouse-cnc-04 \
  --output DEVAGENT_EVIDENCE.html

devagent-commercial replay warehouse-cnc-04 EVIDENCE_BUNDLE \
  --qualification-root ~/.devagent/physical-qualification \
  --output replay-manifest.json
```

Replay reconstruction reports `execution_performed=false` and never substitutes for a new simulation run.

---

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

Qualify trajectory runtime:

```bash
devagent-physical ros qualify-trajectory-runtime
```

Hosted Python CI does not prove a graphical Gazebo runtime, `move_group`, TF, controller actions, OEM drivers, or an arbitrary customer cell. Physical qualification must run on the exact 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:

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

---

# Evidence and 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 an engineer bound to a physical 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 boundary remains:

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

Physical qualification is true only when separately qualified evidence explicitly establishes it.

The operating principle remains:

```text
Agents propose.
Deterministic engines compile and verify.
Existing certified controllers execute.
```

---

# Project status

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

v1.4.0 adds selective verification execution while preserving the existing fail-closed authority model.

Production-oriented software capabilities include:

```text
one-command customer intake
XLSX requirement normalization
immutable project/Twin lineage
deterministic full campaigns
measured evidence binding
professional FAT/Evidence Viewer
terminal progress + RUN.log
interactive engineering session
Requirement → Test selectors
selective deterministic retest
selective physical execution contract
explicit Requirement/Test → Case mapping
failed / blocked / affected retest selectors
Evidence Bundle + replay
change impact + regression
provider-neutral optional AI front end
```

Quality gates include Python 3.11/3.12/3.13 regression, package clean-install, dependency audit, global branch coverage, One-Command coverage, **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, or safe for autonomous real execution.

---

# Documentation

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

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.
