Metadata-Version: 2.4
Name: devagent-physical-engine
Version: 2.10.0
Summary: Verification-first multi-vendor commissioning control plane with flexible guided customer-file intake, deterministic source/evidence authority, exact-Twin lineage, regression, FAT reporting, and pre-site readiness.
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
Project-URL: Sponsor, https://github.com/sponsors/tomha85
Keywords: robotics,industrial-automation,agentic-ai,ros2,gazebo,moveit,pilz,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
Requires-Dist: uv<1,>=0.11
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: numpy<3,>=1.26; 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)
[![Sponsor DevAgent Physical Engine](https://img.shields.io/badge/Sponsor-DevAgent%20Physical%20Engine-EA4AAA?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/tomha85)

**Verification-first commissioning engineering for robotics and industrial automation.**

DevAgent turns customer engineering files into a bounded pre-site verification workflow: it discovers what is available, normalizes engineering inputs, maps requirements to deterministic checks, runs only qualified verification paths, records evidence, detects regression, and produces FAT/readiness artifacts.

> **Safety boundary:** DevAgent does not turn simulation, AI output, or a generated report into site qualification, functional-safety certification, or permission for real robot motion. OEM controllers, PLCs, safety PLCs, qualified site processes, live interlocks, and measured physical evidence remain authoritative.

## 30-second overview

If you are new to DevAgent, remember this flow:

```text
customer engineering files
        ↓
devagent verify ./customer-project
        ↓
normalize source + Twin + requirements
        ↓
deterministic checks / qualified simulation when available
        ↓
measured evidence + PASS / FAIL / NOT_TESTED
        ↓
regression + FAT + pre-site readiness
```

The normal customer entry point is intentionally simple:

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

DevAgent is designed to fail closed. Missing information becomes a question, `NOT_TESTED`, or a blocked capability. It does not invent a PASS just to complete a workflow.

## Two product front doors

DevAgent v2.10.0 exposes two product identities on the same deterministic authority/evidence core:

> **DevAgent Community — Connect AI to your robot.**
>
> **DevAgent Enterprise — Verify AI and automation before it reaches production.**

Community users can inspect the AI-to-robot surface with:

```bash
devagent community --help
```

Enterprise/customer verification continues to start with `devagent verify ./customer-project`. Neither front door bypasses physical qualification, interlocks, exact identity, or operator approval.

## Install in 2–5 minutes

Python 3.11+ is required. A virtual environment is recommended:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --upgrade devagent-physical-engine==2.10.0
```

Verify exactly what was installed:

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

Expected package version:

```text
2.10.0
```

The base install does **not** require ROS 2, Gazebo, MoveIt, CUDA, robot hardware, or an AI-provider API key.

## First safe result in under 10 minutes

Start with a no-motion runtime inspection:

```bash
devagent engine status
```

Then inspect discovered robot/adaptor authority:

```bash
devagent discover
```

These commands do not command a robot. They show the installed control plane and what is or is not currently qualified. Real execution remains disabled by default.

For machine-readable inspection:

```bash
devagent engine status --json
devagent discover --json
```

## Verify a customer project

You do not need to convert a customer project into a special DevAgent repository first. Put the engineering material you already have into one folder:

```text
customer-project/
├── requirements.xlsx
├── PLC/
├── Robot/
├── cell.step
├── FAT_results.xlsx
├── calibration/
├── drawings.pdf
└── other customer engineering files
```

Run the normal workflow:

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

Request qualified simulation where the exact execution path exists:

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

Open the generated Evidence Viewer after verification:

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

For CI or automation:

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

Default locations:

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

A first project does not need to be complete. Missing evidence remains `NOT_TESTED`, reduces scope, or produces explicit information requests. Generated `devagent-results/` files do not become customer-source authority on the next run.

## What gets installed — and what does not

| Layer | How it arrives | What it includes | Required for the first safe result? |
| --- | --- | --- | --- |
| **pip-installed** | `pip install devagent-physical-engine` | DevAgent Python package, base runtime dependencies, CLI entry points, deterministic control/evidence logic | **Yes** |
| **optional AI extras** | `pip install "devagent-physical-engine[openai]"` etc. | Provider SDKs for advisory interpretation/planning | No |
| **DevAgent-managed humanoid runtime** | `devagent robot setup unitree_g1_29dof --managed` | Exact qualified GR00T/SONIC runtime materialized in user storage and attested before authority | No |
| **external system/runtime stack** | Installed by the engineer/OEM/platform owner | ROS 2, Gazebo, MoveIt, CUDA/runtime drivers, OEM robot drivers, firmware, privileged OS packages | No for base verification; yes for the corresponding simulation/physical capability |
| **physical authority** | Never installed as a shortcut | Measured campaign evidence, exact identity, external admission, live interlocks, explicit approval | Never implicit |

The base Python package currently declares only normal Python runtime dependencies. Physical simulation and robot execution intentionally remain separate from `pip install`.

### Humanoid setup system prerequisites

The DevAgent-managed Unitree G1 setup can manage the qualified user-space runtime, but it does not silently install privileged OS packages. Its setup doctor checks system tools such as:

```text
git
git-lfs
bash
cmake
cc
make
tmux
```

Preview setup without installing anything:

```bash
devagent robot setup unitree_g1_29dof --dry-run
```

Inspect an existing runtime without changing it:

```bash
devagent robot setup unitree_g1_29dof --doctor --json
```

## Safe progression from inspection to execution

Use DevAgent in increasing levels of authority:

```text
1. inspect
   devagent engine status / devagent discover

2. verify customer engineering
   devagent verify ./customer-project

3. request qualified simulation
   devagent verify ./customer-project --simulate

4. review evidence / regression / FAT
   devagent-results/

5. physical execution
   only through separately qualified adapters, measured evidence,
   live interlocks, exact identity, and explicit operator approval
```

A simulation result never grants physical authority by itself.

## Engine in action

<p align="center">
  <img src="docs/assets/readme/Screenshot%20from%202026-09-02%2015-14-21.png" width="100%" alt="DevAgent Smart Physical Engine exact-Twin UR5e workcell running in Gazebo Harmonic">
</p>

<p align="center">
  <b>Exact-Twin simulation in Gazebo Harmonic</b><br>
  <sub>Real DevAgent engine run with the bounded UR5e workcell, customer-cell entities, physics, and simulation state visible.</sub>
</p>

<table>
  <tr>
    <td width="50%" align="center">
      <img src="docs/assets/readme/Screenshot%20from%202026-09-02%2015-15-17.png" width="100%" alt="DevAgent Smart Physical Engine robot task execution in Gazebo">
      <br><b>Robot task execution</b><br>
      <sub>Gazebo view during the bounded pick-transport-place workflow.</sub>
    </td>
    <td width="50%" align="center">
      <img src="docs/assets/readme/Screenshot%20from%202026-09-02%2015-14-32.png" width="100%" alt="DevAgent Smart Physical Engine MoveIt motion planning scene in RViz">
      <br><b>MoveIt motion planning</b><br>
      <sub>RViz planning-scene view used alongside the qualified ROS 2 / MoveIt execution path.</sub>
    </td>
  </tr>
</table>

<p align="center"><sub><b>Real engine screenshots — not product renders.</b> ROS 2 Jazzy · Gazebo Harmonic · MoveIt 2 · Pilz · exact-Twin verification.</sub></p>

## Commissioning verification flow

```text
Customer engineering files
        ↓
Immutable project + Twin revision
        ↓
Engineering review
        ↓
Requirements + findings + risks + changes
        ↓
Deterministic criterion mapping
        ↓
Requirement-driven verification plan
        ↓
Verification-scope authority
        ↓
Deterministic checks + qualified execution/evidence
        ↓
Evidence Graph
        ↓
PASS / FAIL / NOT_TESTED
        ↓
Change Impact + Regression
        ↓
FAT Report + Evidence Bundle
        ↓
Immutable pre-site commissioning decision
```

The bounded readiness decision is one of:

```text
READY_FOR_PRE_SITE_COMMISSIONING
NOT_READY_FOR_PRE_SITE_COMMISSIONING
```

This means the declared pre-site engineering scope has complete, current evidence according to installed DevAgent authority contracts. It does **not** mean the real site is commissioned.

## Evidence and generated outputs

DevAgent records lineage for requirements, Twin revisions, verification plans, requirement-to-case mappings, findings, evidence, campaigns, regressions, FAT reports, and readiness decisions.

A previous READY decision becomes stale when readiness-relevant state changes. Change impact and regression are therefore first-class rather than optional post-processing.

Typical outputs:

```text
customer-project/
└── devagent-results/
    ├── RUN.log
    ├── SOURCE_MANIFEST.json
    ├── INTAKE_READINESS.json
    ├── SUMMARY.json
    ├── PRE_SITE_READINESS.json
    ├── FAT_REPORT.html
    └── EVIDENCE.html
```

## Industrial robot support

The verification engine retains bounded industrial robot workflows, including the target-proven UR5e path and exact simulation-supported ABB IRB1200, FANUC CRX-10iA, and KUKA KR6 R900-2 profiles within their declared qualification scopes.

Inspect available robot profiles and doctors:

```bash
devagent robots
devagent robot doctor abb_irb1200
devagent robot doctor fanuc_crx10ia
devagent robot doctor kuka_kr6_r900_2
```

Generic family profiles and arbitrary customer workcells do not inherit measured authority from a reference workcell.

## Unitree G1 bounded natural-language workflow

The humanoid product path separates natural-language intent from low-level authority:

```text
natural-language task
        ↓
bounded deterministic task graph
        ↓
GEAR-SONIC locomotion / stable hold
        ↓
measured distance + balance gates
        ↓
qualified GR00T policy selection
        ↓
measured manipulation evidence
        ↓
verification / replay
```

Install or adopt the exact managed runtime only when you need this capability:

```bash
devagent robot setup unitree_g1_29dof --managed
```

Re-check readiness without motion:

```bash
devagent robot setup unitree_g1_29dof --doctor --json
```

Compile a bounded task without motion:

```bash
devagent robot execute unitree_g1_29dof \
  --task "Walk to the box, grasp it with both hands, and lift it." \
  --dry-run
```

A visualization/simulation request can then be made only in an environment with the qualified runtime:

```bash
devagent robot execute unitree_g1_29dof \
  --task "Walk to the box, grasp it with both hands, and lift it." \
  --visualize
```

Supported scene/task contracts remain bounded. Placement into bins, stacking, sorting, or other destination tasks are not silently approximated unless a separately qualified capability implements them.

Training output is a candidate, not motion authority. Qualification binds the exact checkpoint and execution evidence before activation can change the active registry.

## Physical simulation prerequisites

`pip install` does not install ROS 2, Gazebo, MoveIt, OEM drivers, CUDA runtimes, robot firmware, or privileged operating-system packages.

Reference industrial simulation stack:

```text
Ubuntu 24.04
ROS 2 Jazzy
Gazebo Harmonic
gz_ros2_control
MoveIt 2
```

Target-stack acceptance must run on the intended workstation. Hosted software CI must not pretend that graphical ROS/Gazebo/MoveIt or GPU humanoid execution was physically exercised when it was not.

## Optional AI providers

AI is optional and advisory. Install only the provider SDK you need:

```bash
python -m pip install "devagent-physical-engine[openai]==2.10.0"
python -m pip install "devagent-physical-engine[anthropic]==2.10.0"
python -m pip install "devagent-physical-engine[gemini]==2.10.0"
python -m pip install "devagent-physical-engine[ai]==2.10.0"
```

Typical credentials:

```bash
export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."
export GEMINI_API_KEY="..."
```

Provider-backed interpretation cannot grant physical truth, site qualification, functional-safety certification, or real-execution authority.

## Installed CLIs

```text
devagent             customer onboarding, verification, AI/agent workflows, robot setup/execution
devagent-commercial  project/evidence/FAT/regression/readiness control plane
devagent-physical    deterministic core + ROS/qualification tools
devagent-physical-ai optional provider-backed engineering front end
```

New users should start with `devagent`. The other entry points expose deeper engineering/control-plane functionality and are not required for the first successful onboarding path.

## Architecture — learn this after the first result

DevAgent separates proposal from proof:

```text
AI / natural language / customer intent
        ↓
proposal + interpretation
        ↓
deterministic capability / task / verification contracts
        ↓
exact source + Twin + model + adapter identity
        ↓
qualified simulation / measured execution
        ↓
evidence
        ↓
deterministic verdict
        ↓
authority gate
```

The important rule is simple:

```text
AI may propose.
Deterministic contracts decide what can be attempted.
Measured evidence decides what can be claimed.
Authority gates decide what may execute.
```

A generated plan is not physical proof. A replay is not a new execution. An AI answer is not engineering evidence. A simulation result does not grant site qualification.

## v2.10.0 / V59 drawing-to-simulation release scope

**v2.10.0 — Production/Stable software**

v2.10.0 adds a fail-closed Drawing-to-Simulation setup path for bounded industrial workcells. `devagent robot setup-from-drawing ...` lets an AI provider identify semantic entities and explicit dimension callouts from a drawing while deterministic DevAgent geometry remains the only metric authority. AI-derived or visually scaled dimensions are rejected, and missing authoritative dimensions return `drawing_setup_needs_input` until a named user-verified value is supplied.

The generated Twin, runtime configuration, and fixed-camera contract pass through the existing Setup Qualification authority before simulation. The new `devagent robot setup-camera-verify ...` gate performs a no-motion render-alignment verification: it launches the simulation scene, captures the fixed camera, obtains only a semantic image-region hypothesis from the AI provider, reads exact Gazebo geometry, and compares deterministic projection/inverse-projection results against the bounded localization authority. Camera-guided execution remains blocked unless this alignment is verified.

v2.10.0 also corrects the Gazebo camera projection contract so custom `fx`, `fy`, `cx`, and `cy` live under the SDFormat lens intrinsics block and an explicit horizontal FOV is emitted. A regression check prevents silent fallback to the Gazebo default projection from drifting the rendered image away from deterministic camera geometry.

The existing V58 setup qualification progression (`blocked -> geometric -> physical -> reality_calibrated`), V52 industrial-arm AI + vision execution authority, V51 Community surface, and V50 verification-first core remain intact. The qualified industrial motion acceptance remains unchanged: deterministic collision/preexecution checks, controller/FK readback, 2 mm TCP position acceptance, 0.5° orientation acceptance, and exact evidence identity remain authoritative. AI has no joint, trajectory, metric, or physical-execution authority.

The production release remains fail-closed on exact target-workstation campaign evidence for declared industrial robot configurations. Software CI, generated plans, single-run simulation, drawing completeness, setup completeness, camera alignment, or AI output alone cannot satisfy physical qualification or grant motion authority.

Physical authority remains conservative by construction: compatibility and simulation do not grant motion; hardware and site evidence cannot be skipped; external admission is required; exact identity drift invalidates qualification; and site-qualified evidence does not bypass the independent runtime approval and live-interlock gates.

Real hardware execution and measured FAT promotion remain disabled until their separate physical campaigns satisfy the required evidence contracts.

## Exit codes

| Exit | Meaning |
| ---: | --- |
| `0` | deterministic current project state is `READY_FOR_PRE_SITE_COMMISSIONING` |
| `10` | customer input or operational contract failure |
| `30` | more engineering information is required |
| `31` | requested simulation is blocked/unqualified |
| `32` | verification completed but full release readiness is false |

# Project status

**v2.10.0 — Production/Stable software; V59 drawing-to-simulation and camera render-alignment on the V58 setup-qualification, V52 industrial AI + vision, V51 Community, and V50 verification-first core**

Production/Stable describes the bounded software workflow and runtime authority contracts. It does not claim arbitrary customer workcells, functional safety, site commissioning, real hardware manipulation, or unqualified robot/model/camera combinations are automatically qualified.

Current hard authority boundaries remain:

```text
site_qualification = false
functional_safety_certification = false
commissioning_completed = false
real_execution_allowed = false
```

unless separately proven by the appropriate qualified process.

## Documentation

- [v2.7.0 Release Notes](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/RELEASE_NOTES_V2_7_0.md)
- [Community Production V51](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMUNITY_PRODUCTION_V51.md)
- [Flexible Guided Intake](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/FLEXIBLE_GUIDED_INTAKE_V23.md)
- [Commissioning Agent Orchestrator](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMISSIONING_AGENT_ORCHESTRATOR_V1.md)
- [Humanoid Pip-First Setup](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/HUMANOID_PIP_FIRST_V32.md)
- [Humanoid GR00T Manipulation](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/HUMANOID_GROOT_MANIPULATION_V27.md)
- [Humanoid Task Orchestrator](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/HUMANOID_TASK_ORCHESTRATOR_V28.md)
- [Humanoid High-Quality Demonstrations](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/HUMANOID_HIGH_QUALITY_DEMONSTRATIONS_V31.md)
- [Physical AI Runtime V40](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/PHYSICAL_AI_RUNTIME_V40.md)
- [V40 Production Gate](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/V40_PRODUCTION_GATE.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)
- [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)
- [Laptop Acceptance](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/LAPTOP_ACCEPTANCE.md)

Release history is available from the GitHub Releases page and versioned release-note documents in `docs/`.

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