Metadata-Version: 2.4
Name: devagent-physical-engine
Version: 1.2.0
Summary: Production-grade verification-first robotics evidence runtime with customer Twin lineage, measured physical verification, deterministic 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,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: customer Twin import, deterministic verification, measured physical evidence, replayable evidence lineage, change-impact regression, and auditable FAT evidence.**

> **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 one practical question before engineers travel onsite:

> **What can be proven about this robot cell, what failed, what changed, and what evidence supports the conclusion?**

## What v1.2.0 is

DevAgent Physical Engine `v1.2.0` is a Production/Stable **bounded software workflow** for:

- durable customer `Project / Site / Workcell` identity;
- explicit customer Twin evidence and immutable Twin revisions;
- deterministic structural and measured physical requirement checks;
- nominal, boundary, pairwise-boundary, and fault verification-plan generation;
- exact-Twin physical measurement artifacts;
- canonical physical-motion evidence and runtime measurement binding;
- immutable evidence bundles with artifact IDs, SHA-256 hashes, and Twin scope;
- fail-closed replay reconstruction of stored run/case/seed/reset-state/motion lineage;
- a read-only local/static Evidence Viewer for customer inspection;
- change-impact and baseline/current regression analysis;
- FAT evidence in Markdown, HTML, and JSON;
- content-addressed project evidence and release artifacts.

It does **not** claim that a customer robot cell is commissioned, functionally safe, or authorized for production execution.

```text
customer_review_ready
production_engineering_ready
physical_qualification = false
site_qualification = false
real_execution_allowed = false
```

`production_engineering_ready=true` means the supported engineering-evidence chain is complete. It is **not** a safety certificate or permission to command a production robot.

## Product workflow

```text
CUSTOMER PROJECT / SITE / WORKCELL
                |
                v
CUSTOMER ASSETS + EXPLICIT TWIN EVIDENCE
                |
                v
IMMUTABLE TWIN REVISION
                |
                v
REQUIREMENTS
                |
                v
VERIFICATION PLAN
 nominal / boundary / pairwise / faults
                |
                v
QUALIFIED SIMULATION / SHADOW EXECUTION
                |
                v
MEASURED PHYSICAL EVIDENCE
 cycle / clearance / TCP / tracking / collision
                |
                v
DETERMINISTIC VERDICTS
 PASS / FAIL / NOT_TESTED
                |
                v
EVIDENCE BUNDLE + REPLAY RECONSTRUCTION
 requirement / Twin / run / case / motion / hashes
                |
                v
CHANGE IMPACT + REGRESSION
                |
                v
FAT REPORT + READ-ONLY EVIDENCE VIEWER
```

A generated verification plan is **not execution evidence**. Planned cases remain `planned_not_executed` until a runtime actually produces measured evidence.

A replay reconstruction is also **not re-execution**. `devagent-commercial replay` proves that DevAgent can reconstruct and verify the exact persisted physical case/motion lineage; a separately qualified simulation adapter must perform any actual rerun and create new evidence.

Unknown facts remain unknown. Unsupported requirements remain `NOT_TESTED`. A CAD, URDF, or mesh file does not prove pose, scale, TCP, calibration, collision geometry, or physics simply because the file exists.

## Install

Python 3.11+ is required.

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

Verify the installed version:

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

Expected:

```text
1.2.0
```

The package installs three CLIs:

```text
devagent-commercial   customer project / Twin / requirements / evidence / replay / FAT workflow
devagent-physical     deterministic core, project inspection, ROS setup/qualification
devagent-physical-ai  provider-backed natural-language engineering front end
```

`pip install` does **not** install ROS 2, Gazebo, MoveIt, OEM drivers, or privileged operating-system packages.

### Optional AI providers

```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 all supported provider SDKs
python -m pip install "devagent-physical-engine[ai]"
```

Typical credential variables:

```bash
export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."
export GEMINI_API_KEY="..."   # GOOGLE_API_KEY is also accepted for Gemini
```

Check SDK and credential availability without a provider network call:

```bash
devagent-physical-ai doctor --provider openai
```

A live provider qualification uses provider API credits:

```bash
devagent-physical-ai qualify \
  --provider openai \
  --model YOUR_MODEL
```

# Commercial workflow: end to end

The default SQLite project/evidence database is:

```text
~/.devagent/projects.db
```

To use a dedicated database, put `--db` immediately after `devagent-commercial`:

```bash
devagent-commercial --db ./customer-projects.db status warehouse-cnc-04
```

The same project database can be inspected with:

```bash
devagent-physical project --db ./customer-projects.db show warehouse-cnc-04
```

## 1. Create the customer project

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

Keep the same project ID when the cell changes. New evidence creates new immutable Twin revisions instead of overwriting history.

## 2. Prepare customer Twin evidence

A customer folder can contain engineering assets plus exactly one DevAgent Twin manifest:

```text
customer-cell/
├── devagent-twin.yaml
├── robot.urdf
├── robot.srdf
├── gripper.step
├── fixture.stl
└── calibration.csv
```

Supported inventory suffixes include:

```text
.urdf .xacro .srdf .stl .dae .obj .step .stp .iges .igs
.yaml .yml .json .csv
```

Customer assets are SHA-256 fingerprinted with bounded streaming I/O and may be up to 512 MiB per file. Symlinks and ambiguous multiple root `devagent-twin.*` manifests are rejected. Structured manifest input is intentionally subject to a smaller bounded text limit.

Physical facts are promoted only through one explicit manifest:

```text
devagent-twin.yaml
devagent-twin.yml
devagent-twin.json
```

Start from the template:

- [examples/commercial/devagent-twin.yaml](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/devagent-twin.yaml)

**Do not use the template values as customer evidence.** Replace geometry, pose, TCP, payload, frames, physics values, and `source_ref` with actual customer/imported/measured evidence.

Minimal pattern:

```yaml
schema_version: 1
length_unit: mm
angle_unit: deg

engineering_request:
  robot: ur5e
  operation: load
  object_id: BOX_101
  source: conveyor_a
  destination: cnc_04
  tool: parallel_gripper
  payload_kg: 1.5
  purpose: simulate

robot_base_pose:
  x: 0
  y: 0
  z: 0
  roll: 0
  pitch: 0
  yaw: 0
  origin: measured
  source_ref: SITE_SURVEY_2026_09_01
```

DevAgent does not silently promote `estimated` or `default` values into customer evidence.

## 3. Import the Twin and resolve missing information

```bash
devagent-commercial import-twin warehouse-cnc-04 ./customer-cell \
  | tee twin-import.json
```

The JSON result includes `twin_revision_id`, `twin_state`, `information_requests`, discovered asset hashes, and an immutable evidence artifact.

If `information_requests` is non-empty, obtain real engineering evidence and import again. Do not guess TCP, robot base, calibration, geometry, or physics values merely to make the Twin pass.

List immutable revisions:

```bash
devagent-physical project revisions warehouse-cnc-04 \
  | tee twin-revisions.json
```

Capture the latest revision ID and exact Twin hash without requiring `jq`:

```bash
TWIN_REVISION=$(python - <<'PY'
import json
p = json.load(open("twin-revisions.json", encoding="utf-8"))
print(p["revisions"][-1]["revision_id"])
PY
)

TWIN_HASH=$(python - <<'PY'
import json
p = json.load(open("twin-revisions.json", encoding="utf-8"))
print(p["revisions"][-1]["twin_hash"])
PY
)

printf 'revision=%s\ntwin_hash=%s\n' "$TWIN_REVISION" "$TWIN_HASH"
```

Never bind measurement evidence from one Twin revision to another Twin revision.

## 4. Define deterministic requirements

Production example:

- [examples/commercial/requirements-production.csv](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/requirements-production.csv)

```csv
requirement_id,text,check,target,expected,severity
REQ-001,Twin shall be physics ready,physics_allowed,,true,must
REQ-101,Cycle time shall be less than or equal to 8 seconds,cycle_time_max_s,8.0,,must
REQ-102,Minimum clearance shall be at least 30 millimeters,minimum_clearance_m,0.03,,must
REQ-103,Final TCP error shall be at most 2 millimeters,final_tcp_error_max_m,0.002,,must
REQ-104,Maximum tracking error shall be at most 0.03 radians,max_tracking_error_rad,0.03,,must
REQ-105,Trajectory shall remain collision free,collision_free,,true,must
REQ-106,Physical task shall complete,physical_completed,,true,must
```

Record the requirement set:

```bash
devagent-commercial requirements warehouse-cnc-04 \
  examples/commercial/requirements-production.csv \
  | tee requirement-artifact.json
```

Unsupported prose remains `NOT_TESTED`; an LLM cannot auto-pass it.

## 5. Generate a bounded verification plan

Example:

- [examples/commercial/verification-plan.yaml](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/verification-plan.yaml)

```yaml
max_cases: 128
variation:
  object_x_mm: [-20, 0, 20]
  object_y_mm: [-20, 0, 20]
  payload_kg: [1.0, 3.0, 5.0]
  speed_pct: [70, 85, 100]
faults:
  - missing_part
  - controller_timeout
  - sensor_latency
```

```bash
devagent-commercial verification-plan warehouse-cnc-04 \
  examples/commercial/verification-plan.yaml \
  --revision "$TWIN_REVISION" \
  | tee verification-plan-artifact.json
```

The generator creates bounded nominal, single-parameter boundary, pairwise-boundary, and explicit fault cases. It does **not** claim they were executed.

## 6. Execute the supported scope and record real measurements

A measurement artifact must come from the simulation, hardware-shadow, or site-measurement workflow that actually produced the metrics.

Supported measured fields are:

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

Schema/example:

- [examples/commercial/physical-measurement.json](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/physical-measurement.json)

Replace the example metrics with actual run output and replace `twin_hash` with the exact `$TWIN_HASH` captured above.

```json
{
  "case_id": "nominal-load",
  "backend": "gazebo_moveit",
  "source_kind": "simulation",
  "run_id": "physical-20260901T120000000000Z",
  "qualification_ref": "~/.devagent/physical-qualification/physical-20260901T120000000000Z",
  "twin_hash": "EXACT_TWIN_SHA256",
  "metrics": {
    "cycle_time_s": 7.43,
    "minimum_clearance_m": 0.038,
    "final_tcp_error_m": 0.0016,
    "max_tracking_error_rad": 0.021,
    "collision_free": true,
    "completed": true,
    "sample_count": 264
  }
}
```

Record external measurement evidence against the exact Twin revision:

```bash
devagent-commercial record-measurement warehouse-cnc-04 \
  physical-measurement.json \
  --revision "$TWIN_REVISION" \
  | tee physical-evidence.json
```

Capture the content-addressed artifact ID:

```bash
MEASUREMENT_ARTIFACT=$(python - <<'PY'
import json
p = json.load(open("physical-evidence.json", encoding="utf-8"))
print(p["artifact_id"])
PY
)
```

The recorder rejects malformed/non-finite/negative metrics, exact-Twin hash mismatch, invalid source kinds, and inconsistent positive-clearance/collision claims.

### Preferred typed runtime binding

If the runtime already owns `PhysicalMotionPlan` and `MotionExecutionMetrics`, prefer the typed binding over manually retyping metric JSON. In v1.2 this path also persists the canonical physical motion as immutable project evidence, enabling strong replay lineage.

```python
from devagent_physical_engine import (
    CommercialProjectRepository,
    PhysicalEvidenceRecorder,
)

repository = CommercialProjectRepository("~/.devagent/projects.db")
recorder = PhysicalEvidenceRecorder(repository)

artifact = recorder.record_motion_metrics(
    project_id="warehouse-cnc-04",
    motion=physical_motion_plan,       # PhysicalMotionPlan produced by the runtime
    metrics=motion_execution_metrics,  # MotionExecutionMetrics from execution
    backend="gazebo_moveit",
    run_id="physical-20260901T120000000000Z",
    qualification_ref="~/.devagent/physical-qualification/physical-20260901T120000000000Z",
    revision_id="twin-r0001",
    case_id="case-0001",
)
```

The typed bridge checks the motion/Twin binding and persists:

```text
physical_measurement
physical_motion_plan
runtime_measurement_binding
```

including exact artifact hashes, motion fingerprint, planner identity, metric origin, run ID, and qualification reference.

## 7. Run the requirement campaign

```bash
devagent-commercial campaign warehouse-cnc-04 \
  examples/commercial/requirements-production.csv \
  --revision "$TWIN_REVISION" \
  --measurement "$MEASUREMENT_ARTIFACT" \
  | tee campaign.json
```

Capture the campaign artifact:

```bash
CAMPAIGN_ARTIFACT=$(python - <<'PY'
import json
p = json.load(open("campaign.json", encoding="utf-8"))
print(p["artifact_id"])
PY
)
```

A missing metric or unsupported check yields `NOT_TESTED`, never PASS. Failed/not-tested `must` requirements block bounded release readiness.

## 8. Generate the first FAT evidence report

For the first campaign, no regression baseline exists yet:

```bash
devagent-commercial fat-report warehouse-cnc-04 \
  "$CAMPAIGN_ARTIFACT" \
  --output FAT_REPORT.html \
  | tee fat-artifact.json
```

Supported output extensions are `.md`, `.html`, `.htm`, and `.json`. The immutable `fat_report` artifact stores Markdown, escaped customer-facing HTML, and structured JSON from the same evidence lineage.

## 9. Build the v1.2 evidence bundle

After a campaign exists, bind the exact engineering chain into one immutable trace artifact:

```bash
devagent-commercial evidence-bundle warehouse-cnc-04 \
  "$CAMPAIGN_ARTIFACT" \
  | tee evidence-bundle.json
```

You can bind exact optional artifacts explicitly:

```bash
devagent-commercial evidence-bundle warehouse-cnc-04 \
  "$CAMPAIGN_ARTIFACT" \
  --verification-plan "$PLAN_ARTIFACT" \
  --regression "$REGRESSION_ARTIFACT" \
  --fat-report "$FAT_ARTIFACT" \
  | tee evidence-bundle.json
```

The bundle records exact references containing:

```text
artifact_id
artifact_type
artifact_hash
twin_revision_id
```

and requirement traces containing verdict, observed value, expected threshold, reason, and evidence references.

Capture the bundle ID:

```bash
EVIDENCE_BUNDLE=$(python - <<'PY'
import json
p = json.load(open("evidence-bundle.json", encoding="utf-8"))
print(p["artifact_id"])
PY
)
```

## 10. Verify replay reconstruction

`replay` is intentionally a verification command, not a robot-control command:

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

Before reconstruction, the hardened replay boundary verifies every bundle reference:

```text
artifact ID
artifact type
artifact SHA-256
Twin revision scope
```

It then verifies the persisted physical qualification evidence:

```text
trusted qualification-store root
run_id
Twin SHA-256
case_id
case evidence hash
case fingerprint
seed
reset state
case parameters
canonical motion fingerprint
commercial physical_motion_plan fingerprint
```

Successful output includes:

```text
replayable = true
execution_performed = false
replay_manifest_hash = ...
```

`--record` writes immutable `replay_verification` evidence after successful reconstruction.

**Important:** this does not command Gazebo, MoveIt, a real robot, an OEM controller, a PLC, or a safety PLC. A qualified simulation adapter may consume a verified replay manifest for an actual rerun, and that rerun must create new measured evidence.

If exact lineage cannot be proven, replay fails closed. Exit code `24` means the evidence bundle is not replayable under the supplied qualification store/run evidence.

## 11. Inspect the Evidence Viewer

For customer sharing, generate a self-contained static HTML file:

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

For local inspection:

```bash
devagent-commercial evidence-viewer warehouse-cnc-04 \
  --open-browser
```

Default local URL:

```text
http://127.0.0.1:8765/
```

The built-in viewer is deliberately constrained:

- loopback host only (`127.0.0.1`, `localhost`, or `::1`);
- read-only GET surface;
- no write endpoint;
- no robot-control endpoint;
- customer strings HTML-escaped;
- `Cache-Control: no-store`;
- restrictive Content Security Policy.

It shows:

- project/site/workcell identity;
- customer-review readiness;
- production-engineering evidence readiness;
- explicit physical/site authority boundary;
- requirement verdicts;
- observed and expected values;
- evidence references;
- readiness blockers;
- immutable artifact IDs and SHA-256 hashes;
- exact Twin revision hashes.

Inspect the normalized graph as JSON when integrating another UI or audit tool:

```bash
devagent-commercial evidence-graph warehouse-cnc-04 \
  > evidence-graph.json
```

The graph is derived from the existing immutable project store. It is **not a second source of truth**.

## 12. Create a new Twin revision when the cell changes

When robot base, tool/TCP, fixture, workpiece, controller setting, or other evidence changes, update/import the evidence again instead of overwriting history:

```bash
devagent-commercial import-twin warehouse-cnc-04 ./customer-cell-revision-2
```

Then inspect the new revision:

```bash
devagent-physical project revisions warehouse-cnc-04
```

Compute conservative requirement impact:

```bash
devagent-commercial impact warehouse-cnc-04 \
  twin-r0001 twin-r0002 \
  examples/commercial/requirements-production.csv \
  | tee impact.json
```

Capture its artifact ID:

```bash
IMPACT_ARTIFACT=$(python - <<'PY'
import json
p = json.load(open("impact.json", encoding="utf-8"))
print(p["artifact_id"])
PY
)
```

Run the current campaign on the new Twin/measurement evidence, then compare baseline/current campaign artifacts:

```bash
devagent-commercial regression warehouse-cnc-04 \
  "$BASELINE_CAMPAIGN" "$CURRENT_CAMPAIGN" \
  --impact "$IMPACT_ARTIFACT" \
  | tee regression.json
```

Capture regression evidence:

```bash
REGRESSION_ARTIFACT=$(python - <<'PY'
import json
p = json.load(open("regression.json", encoding="utf-8"))
print(p["artifact_id"])
PY
)
```

A PASS -> non-PASS transition is a regression. Numeric observed values are compared as deltas. Stale evidence cannot preserve current readiness.

Generate the regression-aware FAT report:

```bash
devagent-commercial fat-report warehouse-cnc-04 \
  "$CURRENT_CAMPAIGN" \
  --regression "$REGRESSION_ARTIFACT" \
  --output FAT_REPORT_CURRENT.html
```

Then build a new evidence bundle for the current campaign and inspect/replay that exact lineage.

## 13. Inspect readiness and evidence artifacts

```bash
devagent-commercial status warehouse-cnc-04
devagent-commercial artifacts warehouse-cnc-04
```

Useful artifact filters:

```bash
devagent-commercial artifacts warehouse-cnc-04 --type physical_measurement
devagent-commercial artifacts warehouse-cnc-04 --type physical_motion_plan
devagent-commercial artifacts warehouse-cnc-04 --type runtime_measurement_binding
devagent-commercial artifacts warehouse-cnc-04 --type verification_plan
devagent-commercial artifacts warehouse-cnc-04 --type commercial_campaign
devagent-commercial artifacts warehouse-cnc-04 --type change_impact
devagent-commercial artifacts warehouse-cnc-04 --type commercial_regression
devagent-commercial artifacts warehouse-cnc-04 --type fat_report
devagent-commercial artifacts warehouse-cnc-04 --type evidence_bundle
devagent-commercial artifacts warehouse-cnc-04 --type replay_verification
```

# Evidence origin versus qualification authority

Evidence Trust uses origin labels to tell the reviewer where measurements came from:

```text
MODEL_ONLY
SIMULATION_MEASURED
SHADOW_MEASURED
SITE_MEASURED
```

These labels are **not certification levels** and do not automatically promote physical/site authority.

For example, this is a bounded engineering claim:

```text
REQ-102: modeled clearance >= 30 mm
Observed: 37.2 mm
Verdict: PASS
Origin: SIMULATION_MEASURED
Twin: twin-r0007
Twin SHA-256: ...
Measurement artifact: art-...
Motion artifact: art-...
Replay reconstruction: verified
```

It means the identified Twin/runtime/case evidence satisfied the deterministic modeled requirement. It does **not** mean the real workcell is safe for production.

# Supported deterministic requirement checks

Structural/Twin checks:

- `planning_allowed`
- `physics_allowed`
- `entity_present`
- `validation_issue_absent`
- `twin_state`

Measured physical checks:

- `cycle_time_max_s`
- `minimum_clearance_m`
- `final_tcp_error_max_m`
- `max_tracking_error_rad`
- `collision_free`
- `physical_completed`

A physical requirement without exact-Twin measurement evidence is `NOT_TESTED`.

# CLI exit codes for automation

`devagent-commercial` intentionally returns non-zero for engineering blockers so shell/CI automation does not silently treat a failed verification as success.

| Exit | Meaning |
| ---: | --- |
| `0` | command completed and its verdict/readiness gate passed where applicable |
| `10` | project/input/commercial contract error |
| `12` | imported Twin is invalid |
| `20` | campaign completed but is not release-ready |
| `21` | regression comparison detected a regression |
| `22` | FAT report generated but bounded release-readiness is false |
| `23` | project status is not `commercial_v1_ready` |
| `24` | evidence replay reconstruction is not currently replayable |

Preserve the command JSON output even when the process returns a non-zero engineering verdict.

# AI engineering front end

AI is optional and remains outside deterministic execution authority.

Interpret a natural-language request:

```bash
devagent-physical-ai request \
  "Use a UR5e to load BOX_101 from conveyor_a to cnc_04." \
  --provider openai \
  --model YOUR_MODEL
```

Run the engineering agent:

```bash
devagent-physical-ai engineer \
  "Use a UR5e to load BOX_101 from conveyor_a to cnc_04. Simulate and verify the plan." \
  --provider openai \
  --model YOUR_MODEL
```

Task-specific `--visualize` remains deliberately narrow: v1.2 retains the supported nominal UR5e `load` reference-workcell path and fails closed outside that scope.

```bash
devagent-physical-ai engineer \
  "Use a UR5e to load BOX_101 from conveyor_a to cnc_04. Simulate and verify the plan." \
  --provider openai \
  --model YOUR_MODEL \
  --visualize
```

`--visual-demo` is different: it runs a visual UR5e demo after engineering verification, but it is **not** claimed to be the requested BOX/source/destination task-specific motion.

# Physical simulation setup and qualification

Reference direction:

```text
Ubuntu 24.04
ROS 2 Jazzy
Gazebo Harmonic
gz_ros2_control
Universal Robots ROS 2 driver
ur_simulation_gz
MoveIt 2
```

Preview system changes:

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

Apply the supported setup explicitly:

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

Check and qualify the target runtime:

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

Other reference commands:

```bash
devagent-physical ros launch --dry-run
devagent-physical ros acceptance
devagent-physical ros demo
devagent-physical qualify
```

Hosted Python CI cannot prove graphical Gazebo, MoveIt `move_group`, TF, controller actions, or OEM drivers. Physical-simulation qualification must run on the exact workstation/adapter stack. ABB, FANUC, KUKA, or other registry entries do not imply equal physical qualification.

# Evidence and authority rules

DevAgent is fail-closed by design:

- AI cannot authorize real robot execution.
- Missing customer facts remain unknown.
- Unsupported prose remains `NOT_TESTED`.
- Measurements bind to an immutable Twin revision/hash.
- Non-finite and malformed physical metrics are rejected.
- Stale campaign/regression/FAT evidence cannot preserve current readiness after evidence lineage changes.
- A verification plan is not execution evidence.
- A replay reconstruction is not execution evidence from a new run.
- Evidence bundles are content-addressed and replay validates referenced artifact IDs/types/hashes/Twin scope before reconstruction.
- The Evidence Viewer is read-only and exposes no robot-control endpoint.
- Simulation evidence does not override guarding, risk assessment, safety PLC validation, OEM controller validation, site acceptance, or engineer sign-off.

Readiness concepts remain intentionally separate:

```text
customer_review_ready
    bounded customer requirement/evidence review is complete

production_engineering_ready
    supported physical requirements passed using exact-Twin measured evidence
    with run/qualification provenance

physical_qualification / site_qualification / real_execution_allowed
    false in the v1.2 commercial evidence workflow
```

# Example files

- [Twin manifest template](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/devagent-twin.yaml)
- [Basic structural requirements](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/requirements.csv)
- [Production requirement checks](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/requirements-production.csv)
- [Verification-plan input](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/verification-plan.yaml)
- [Physical-measurement schema/example](https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/physical-measurement.json)

The examples are templates/schema examples; they are not customer-site evidence.

# Release quality

Every PR/main update runs Python 3.11/3.12/3.13 regression, compilation, Ruff checks, branch coverage, a dedicated >=90% production-authority coverage gate, a dedicated >=90% Evidence Trust/replay coverage gate, package build/clean-install smoke, CLI Evidence Trust smoke, and runtime dependency vulnerability audit.

Releases are created only from exact green `main`, rebuilt from the exact tag, clean-installed, supplied with CycloneDX SBOM + SHA-256 checksums, attached to GitHub Release, and published to PyPI through Trusted Publishing with digital attestations.

# Documentation

- [Evidence Trust v1.2](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/EVIDENCE_TRUST_V12.md)
- [Production Grade v1.1](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/PRODUCTION_GRADE_V1_1.md)
- [Production readiness](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/PRODUCTION_READINESS.md)
- [Commercial V1](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMERCIAL_V1.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)
- [Robot platform and Twin](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ROBOT_PLATFORM_AND_TWIN.md)
- [Measured physical runtime](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/MEASURED_PHYSICAL_RUNTIME.md)
- [Qualification](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/QUALIFICATION.md)
- [Optimization](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/OPTIMIZATION.md)
- [AI providers](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/AI_PROVIDERS.md)
- [PyPI release process](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/PYPI_RELEASE.md)

## Project status

**v1.2.0 — Production/Stable software workflow with customer Twin evidence, measured physical requirement verification, immutable evidence bundles, hardened replay reconstruction, read-only Evidence Viewer, change-impact regression, and FAT Markdown/HTML/JSON evidence.**

Production/Stable applies to the bounded software/API/CLI/evidence workflow. Physical qualification remains robot-, adapter-, workstation-, and evidence-specific. Customer-site qualification, functional-safety certification, and production-hardware command authority are not claimed and remain locked by default.

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