Metadata-Version: 2.4
Name: devagent-physical-engine
Version: 1.0.0
Summary: Verification-first commercial engineering, simulation, traceability, 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 commercial engineering, customer Twin import, requirement traceability, regression analysis, and FAT evidence for robotic and industrial automation.**

> **AI proposes. Deterministic engines validate, compile, verify, simulate, measure, and gate promotion. Existing certified robot controllers, PLCs, and safety systems remain authoritative.**

DevAgent Smart Physical Engine helps an engineer move from a customer workcell definition to evidence-backed engineering review without giving an LLM direct robot-control authority. Commercial V1 adds a durable customer workflow around the existing provider-neutral AI, canonical physical Twin, ROS 2 / Gazebo / MoveIt simulation, deterministic verification, and evidence infrastructure.

## Commercial V1 outcome

A customer project can now be handled as one durable evidence chain:

```text
CUSTOMER PROJECT / SITE / WORKCELL
                |
                v
CUSTOMER FILE INVENTORY + devagent-twin MANIFEST
                |
                v
CANONICAL TWIN + IMMUTABLE twin-r000N REVISION
                |
                v
REQUIREMENT SET
                |
                v
DETERMINISTIC REQUIREMENT CAMPAIGN
                |
                v
REGRESSION COMPARISON
                |
                v
CUSTOMER-READY FAT EVIDENCE REPORT
```

The commercial workflow is intentionally fail-closed. A CAD, URDF, mesh, YAML, or CSV file being present does **not** prove a robot base pose, TCP, dimension, coordinate frame, collision model, calibration, or physics property. Those facts must be explicitly declared or measured before DevAgent promotes them as engineering evidence.

## Install

Python 3.11+ is required.

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

`pip install` does not install ROS, Gazebo, MoveIt, OEM robot drivers, or privileged operating-system dependencies.

## Commercial quick start

Create durable customer identity:

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

Import a customer folder:

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

The folder may contain supported engineering assets such as:

```text
customer-cell/
├── devagent-twin.yaml
├── robot.urdf
├── robot.srdf
├── meshes/
│   ├── gripper.stl
│   └── fixture.stl
└── notes-or-export.json
```

Commercial V1 inventories `.urdf`, `.xacro`, `.srdf`, `.stl`, `.dae`, `.obj`, `.step`, `.stp`, `.iges`, `.igs`, `.yaml`, `.yml`, `.json`, and `.csv` files. Customer assets are SHA-256 fingerprinted with bounded streaming I/O; individual inventoried assets are limited to 512 MiB. A `devagent-twin.yaml`, `devagent-twin.yml`, or `devagent-twin.json` manifest is required before file inventory becomes physical Twin evidence.

If the manifest or required physical facts are missing, DevAgent returns `needs_information` with explicit engineering questions instead of inventing values.

Import requirements:

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

Run deterministic requirement verification against the latest Twin revision:

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

Or bind the campaign to an exact immutable revision:

```bash
devagent-commercial campaign warehouse-cnc-04 requirements.csv \
  --revision twin-r0002
```

Compare a previous campaign with a current campaign:

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

Generate a FAT Markdown report:

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

Inspect commercial readiness and immutable evidence:

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

The default commercial evidence database is:

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

## Customer Twin manifest

Commercial V1 is manifest-driven so engineering facts have explicit provenance. A minimal structure is:

```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
  origin: measured
  source_ref: site-survey

entities:
  - id: conveyor_a
    type: conveyor
    pose: {x: 700, y: 0, z: 850}
    geometry:
      kind: box
      dimensions: [2000, 600, 800]

  - id: cnc_04
    type: machine
    pose: {x: 1200, y: 400, z: 0}
    geometry:
      kind: box
      dimensions: [1400, 1200, 1800]

  - id: BOX_101
    type: workpiece
    pose: {x: 700, y: 0, z: 900}
    geometry:
      kind: box
      dimensions: [200, 100, 50]

tool:
  id: parallel_gripper
  tcp:
    x: 0
    y: 0
    z: 180
    origin: measured
  geometry:
    kind: box
    dimensions: [120, 80, 200]
  max_payload_kg:
    value: 5.0
    origin: imported
```

A mesh can be referenced by relative asset path, for example:

```yaml
geometry:
  kind: mesh
  asset: meshes/fixture.stl
```

The referenced file must have been discovered inside the customer source root. Absolute paths, `..` traversal, and symlinked customer assets are rejected.

## Requirement traceability

CSV example:

```csv
requirement_id,text,check,target,expected,severity
REQ-001,Twin shall be planning ready,planning_allowed,,true,must
REQ-002,Workpiece shall exist,entity_present,BOX_101,true,must
REQ-003,Unit mismatch shall be absent,validation_issue_absent,possible_unit_mismatch,true,must
```

Commercial V1 deterministic checks are deliberately small and auditable:

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

A prose requirement without a supported deterministic check is reported as `NOT_TESTED`. It is never auto-passed by an LLM. A required (`must`) item that fails or remains untested blocks customer-review readiness.

## Evidence and regression

Project, Twin, import, campaign, regression, and FAT artifacts are stored with stable identities and content hashes. Twin revisions are monotonic and immutable (`twin-r0001`, `twin-r0002`, ...).

Regression analysis explicitly identifies a requirement that changed from `PASS` in the baseline campaign to any non-pass state in the current campaign. A regression blocks release readiness.

The FAT report includes project/site/workcell identity, exact Twin revision and hash, requirement counts, pass/fail/not-tested results, coverage, regression state, and bounded release readiness.

`READY FOR CUSTOMER REVIEW` means the declared/imported Twin scope and mapped deterministic requirements passed the commercial evidence gates. It does **not** mean functional-safety certification, site qualification, commissioning approval, or permission to move a production robot.

## AI engineering layer

The runtime remains provider-neutral. OpenAI, Anthropic, and Gemini can be used for interpretation, planning, critique, and recovery while deterministic code owns schema validation, semantic policy, Twin validation, collision/clearance contracts, evidence, qualification, and execution gating.

Check a provider:

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

Run an engineering request:

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

Use `--quiet` for machine-readable JSON without progress messages on stdout.

## Physical simulation

The repository retains the evidence-gated ROS 2 / Gazebo / MoveIt physical simulation stack and the packaged UR5e reference workcell. The reference stack target is:

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

Useful commands:

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

Hosted Python CI cannot truthfully exercise a graphical Gazebo process, MoveIt `move_group`, TF, ROS controllers, or Gazebo services. Those paths retain separate executable target qualification. A registry entry for FANUC, KUKA, ABB, or another robot family does not imply identical physical simulation qualification.

## Safety and authority boundary

Commercial V1 is an engineering verification product, not a safety controller. It intentionally preserves these boundaries:

```text
AI / COMMERCIAL WORKFLOW
        |
        v
DETERMINISTIC DEVAGENT EVIDENCE
        |
        v
SIMULATION / ENGINEERING REVIEW
        |
        X
NO AUTOMATIC PRODUCTION-HARDWARE AUTHORITY
```

Simulation success does not override OEM controllers, PLC interlocks, safety PLCs, risk assessments, guarding, functional-safety validation, site commissioning procedures, or engineer approval.

Commercial outputs therefore continue to report:

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

unless a separately implemented and evidence-qualified authority path explicitly proves otherwise. Commercial V1 does not add such a path.

## Software verification and releases

Repository CI verifies Python 3.11, 3.12, and 3.13, compilation, unit regression, Ruff correctness, branch coverage, package build, clean wheel installation, and runtime dependency vulnerability audit.

A green `main` release is tied to the exact CI-tested commit. Release artifacts are rebuilt from the exact tag, checked with Twine, clean-installed, accompanied by a CycloneDX runtime SBOM and SHA-256 checksums, attached to the GitHub Release, and published to PyPI through Trusted Publishing with digital attestations.

## Documentation

- [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)
- [Production readiness](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/PRODUCTION_READINESS.md)
- [Architecture](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ARCHITECTURE.md)
- [Agent Core](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/AGENT_CORE.md)
- [AI providers](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/AI_PROVIDERS.md)
- [Natural-language engineering](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/NATURAL_LANGUAGE_ENGINEERING.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)
- [Workstation setup](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/SETUP.md)
- [PyPI release process](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/PYPI_RELEASE.md)

## Project status

**v1.0.0 — Production/Stable software / commercial engineering workflow with evidence-gated customer Twin import, requirement traceability, regression analysis, and FAT reporting.**

Production/Stable describes the shipped software/API/CLI and release process for the bounded V1 scope. Physical and site readiness remain evidence- and adapter-specific. Arbitrary CAD/URDF content is inventoried and fingerprinted but is not semantically trusted merely because a file exists; customer physical facts are promoted only through explicit manifest/evidence contracts. Real robot execution remains locked by default. Functional-safety certification and customer-site commissioning are not claimed.

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