Metadata-Version: 2.4
Name: devagent-physical-engine
Version: 1.1.0
Summary: Production-grade verification-first customer Twin, measured physical evidence, change-impact regression, and FAT evidence runtime for robotics and industrial automation.
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
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: customer Twin import, measured physical evidence, deterministic requirement verification, change-impact regression, and FAT evidence for robotics and industrial automation.**

> **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 a commercial engineering question: **before engineers travel onsite, what can be proven about this robot cell, what failed, what changed, and what evidence supports the conclusion?**

## 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
MEASURED PHYSICAL EVIDENCE
 cycle / clearance / TCP / tracking / collision
                |
                v
DETERMINISTIC VERDICTS
 PASS / FAIL / NOT_TESTED
                |
                v
CHANGE IMPACT + REGRESSION
                |
                v
FAT REPORT
 Markdown / HTML / JSON
```

Unknown facts stay unknown. Unsupported requirements stay `NOT_TESTED`. A CAD/URDF/mesh file does not prove its pose, scale, TCP, calibration, or physics merely because the file exists.

## Install

Python 3.11+:

```bash
python -m pip install devagent-physical-engine
```

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

`pip install` does not install ROS 2, Gazebo, MoveIt, OEM drivers, or privileged OS packages.

## Commercial quick start

Create project identity:

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

Import customer Twin evidence:

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

Supported inventory includes `.urdf`, `.xacro`, `.srdf`, `.stl`, `.dae`, `.obj`, `.step`, `.stp`, `.iges`, `.igs`, `.yaml`, `.yml`, `.json`, and `.csv`. Assets are SHA-256 fingerprinted using bounded streaming I/O. Physical facts are promoted only through an explicit `devagent-twin.yaml|yml|json` evidence manifest.

Import requirements:

```bash
devagent-commercial requirements warehouse-cnc-04 requirements.csv
```

Generate a deterministic verification plan:

```bash
devagent-commercial verification-plan warehouse-cnc-04 verification-plan.yaml \
  --revision twin-r0001
```

Record measured evidence produced by a simulation/hardware-shadow qualification run:

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

Run requirements against the exact Twin and measurement artifact:

```bash
devagent-commercial campaign warehouse-cnc-04 requirements.csv \
  --revision twin-r0001 \
  --measurement art-PHYSICAL
```

After a Twin revision changes, compute conservative impact:

```bash
devagent-commercial impact warehouse-cnc-04 \
  twin-r0001 twin-r0002 requirements.csv
```

Compare baseline/current campaigns:

```bash
devagent-commercial regression warehouse-cnc-04 \
  art-BASELINE art-CURRENT \
  --impact art-IMPACT
```

Generate customer evidence as Markdown, HTML, or JSON:

```bash
devagent-commercial fat-report warehouse-cnc-04 art-CURRENT \
  --regression art-REGRESSION \
  --output FAT_REPORT.html
```

Inspect readiness and evidence:

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

Default evidence database:

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

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

Example:

```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 <= 8 s,cycle_time_max_s,8.0,,must
REQ-102,Minimum clearance shall be >= 30 mm,minimum_clearance_m,0.03,,must
REQ-103,Final TCP error shall be <= 2 mm,final_tcp_error_max_m,0.002,,must
REQ-104,Trajectory shall be collision free,collision_free,,true,must
```

A physical requirement without exact-Twin measured evidence is `NOT_TESTED`; it cannot be promoted by an LLM.

## Evidence trust and readiness

DevAgent separates three claims:

- `customer_review_ready`: the bounded declared/imported scope and mapped requirements passed.
- `production_engineering_ready`: mapped physical requirements passed with exact-Twin measurement evidence and explicit run/qualification provenance.
- `site_qualification` / `real_execution_allowed`: **remain false** in this release.

`production_engineering_ready` is engineering evidence readiness, not functional-safety certification or commissioning authorization. Simulation evidence does not override guarding, risk assessment, safety PLC validation, OEM controller validation, site acceptance, or engineer sign-off.

The typed Python API can bind `PhysicalMotionPlan` + `MotionExecutionMetrics` directly into project evidence so runtime-owned metrics do not have to be manually retyped into free-form JSON.

## Physical simulation

The qualified reference direction remains Ubuntu 24.04 + ROS 2 Jazzy + Gazebo Harmonic + `gz_ros2_control` + Universal Robots ROS 2 driver + `ur_simulation_gz` + MoveIt 2.

```bash
devagent-physical setup --profile ur5e-sim --dry-run
devagent-physical setup --profile ur5e-sim
devagent-physical ros doctor
devagent-physical ros qualify-trajectory-runtime
```

Hosted Python CI cannot prove a graphical Gazebo/MoveIt/controller stack. Target physical-simulation qualification must run on the exact workstation/adapter stack. Registry entries for ABB, FANUC, KUKA, or other robots do not imply equal physical qualification.

## Release quality

Every PR/main update runs Python 3.11/3.12/3.13 regression, compilation, Ruff correctness checks, branch coverage, package build, clean wheel install, and runtime dependency audit. Production-grade authority contracts also have a dedicated high-coverage gate.

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

## Documentation

- [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.1.0 — Production/Stable software workflow with measured physical requirement evidence, deterministic verification-plan generation, change-impact regression, and customer FAT Markdown/HTML/JSON reporting.**

Production/Stable applies to the bounded software/API/CLI/evidence workflow. Physical qualification remains robot-, adapter-, workstation-, and evidence-specific. 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.
