Metadata-Version: 2.4
Name: devagent-physical-engine
Version: 0.13.0
Summary: Verification-first agentic engineering, simulation, and 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
Classifier: Development Status :: 4 - Beta
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: Beta](https://img.shields.io/badge/status-beta-blue.svg)](#project-status)

**Verification-first agentic engineering, planning, simulation, optimization, and evidence for robotic and industrial automation.**

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

DevAgent Smart Physical Engine turns an engineering request into a bounded, evidence-backed automation plan without giving an LLM direct robot-control authority. It is designed for engineers who want to reason about robot tasks, generate and critique plans, build a canonical physical Twin, simulate through ROS 2 / Gazebo / MoveIt, measure results, and preserve verification evidence before anything reaches real equipment.

The runtime is provider-neutral. OpenAI, Anthropic, and Gemini can be used for interpretation, planning, critique, and recovery while deterministic code remains responsible for safety boundaries, compilation, verification, physical evidence, qualification, and execution policy.

## Why DevAgent Physical Engine?

Many AI robotics demos stop after producing a plan or showing a robot moving. DevAgent Physical Engine is built around a stricter question:

**Can this robotic engineering claim be supported by deterministic checks and measured evidence for the exact plan and physical model being evaluated?**

Core principles:

- **Evidence before promotion** — missing physical evidence blocks stronger claims instead of being silently assumed.
- **Provider-neutral AI** — model output proposes engineering intent; it does not own collision truth, qualification, or real-hardware authorization.
- **Deterministic verification** — task graphs, motion contracts, collision constraints, scene state, and promotion gates are checked outside the model.
- **Exact Twin binding** — physical motion is bound to a canonical Twin and immutable fingerprints rather than free-form model text.
- **Measured simulation** — supported ROS 2 / Gazebo / MoveIt paths collect runtime evidence instead of treating a generated plan as proof.
- **No fake task visualization** — generic demo motion is never labeled as the requested BOX/source/destination task.
- **Real execution remains locked** — simulation success is not site qualification, functional-safety certification, or permission to run production hardware.

## Install

Python 3.11+ is required.

From PyPI:

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

Install one AI provider:

```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 install all supported provider SDKs:

```bash
python -m pip install "devagent-physical-engine[ai]"
```

For development from source:

```bash
git clone https://github.com/tomha85/devagent-physical-engine.git
cd devagent-physical-engine
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev,ai]"
```

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

## Quick start

Configure the credential for the provider you want to use:

```bash
export OPENAI_API_KEY='...'
# or ANTHROPIC_API_KEY / GEMINI_API_KEY
```

Check the provider locally:

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

While the command runs, stage-by-stage progress is printed to `stderr` and the final machine-readable result remains on `stdout`:

```text
[DevAgent +   0.00s] START        provider=openai model=<model-id>
[DevAgent +   0.00s] INTERPRETER  understanding engineering request
[DevAgent +   4.20s] PLANNER      revision=0 generating high-level task graph
[DevAgent +  10.30s] CRITIC       revision=0 reviewing verified plan
[DevAgent +  13.10s] SIMULATION   deterministic model execution completed
[DevAgent +  13.11s] COMPLETE     ready_for_twin_simulation=true
```

Use `--quiet` when a script or CI job needs JSON without terminal progress.

## Commercial project spine

v0.13 adds durable customer project, site, and workcell identity around the existing verification engine. Project manifests are fingerprinted, Twin builds can be persisted as immutable revisions, and project evidence is stored locally in SQLite with content hashes.

Create and inspect a project:

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

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

The default store is `~/.devagent/projects.db`. This project spine is the durable boundary for upcoming customer Twin import, requirement traceability, physical test campaigns, regression analysis, and FAT reporting. It does not by itself claim customer geometry import, physical qualification, site qualification, or real execution.

## Task-specific visual simulation

For the supported v0.12 UR5e `load` scope, `--visualize` continues from the verified high-level task into a physical simulation path:

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

The current task-specific path uses the packaged `ur5e_reference_load_cell_v1` canonical workcell. The request identities remain exact (`BOX_101`, `conveyor_a`, `cnc_04`), while the reference source/destination poses, primitive geometry, nominal workpiece geometry, and reference tool are deterministic template facts rather than guessed customer-site facts.

The runtime then performs this bounded sequence:

```text
validated AI task graph
        |
        v
packaged canonical UR5e load Twin
        |
        v
Gazebo + MoveIt world materialization and read-back
        |
        v
MoveIt FK cross-check of reference pick/place targets
        |
        v
MoveIt joint-space plan for each physical phase
        |
        v
pre-pick -> pick -> attach BOX -> lift -> transfer -> place
        |
        v
BOX visually follows tool0 while attached in Gazebo
        |
        v
verified destination pose -> detach -> retract -> home
        |
        v
measured motion/evidence report
```

On a successful run, Gazebo / MoveIt remains open by default so the engineer can inspect the final workcell. Add `--close-after` to close it after success.

v0.12.1 hardens the initial ROS joint-state snapshot by parsing `ros2 topic echo --once` output as a YAML document stream. This accepts the normal ROS 2 trailing `---` message separator instead of incorrectly classifying an otherwise valid `/joint_states` sample as `joint_state_snapshot_invalid`.

v0.12.2 additionally hardens Gazebo model-pose read-back across Harmonic CLI renderings. One shared parser now accepts both pipe-delimited and whitespace-delimited finite XYZ/RPY vectors and is used by initial world verification and dynamic workpiece pose read-back, so task simulation does not depend on a single human-readable `gz model --pose` delimiter style.

v0.12.3 hardens MoveIt PlanningScene read-back when MoveIt serializes world collision objects in its own planning/root frame. A different observed frame is never trusted by label alone: DevAgent first proves the observed frame and canonical Twin frame are identity-equivalent through TF, then re-reads the scene and canonicalizes it back to the Twin planning frame before enforcing the exact geometry hash. Non-identity frames and geometry drift remain fail-closed.

v0.12.4 hardens attached-tool collision read-back against equivalent MoveIt `CollisionObject` pose decompositions. DevAgent now composes the object pose with the primitive pose, canonicalizes equivalent quaternion signs before hashing, and still requires the exact attachment link, object frame, shape, dimensions, operation, and effective geometry. Exact probe evidence is preserved beside the tool payload for target diagnostics; representation-only changes no longer create false mismatches, while physical geometry drift remains fail-closed.

The packaged reference workcell is **not customer-site geometry**. Arbitrary plant layouts require an imported or user-declared physical Twin with trusted poses, collision geometry, tool/TCP information, and workpiece properties. DevAgent does not invent those site facts from a natural-language prompt.

The v0.12 implementation remains evidence-gated: source/CI success does not prove the ROS target campaign has passed on a particular workstation. Use the executable qualification below before treating the task-specific path as qualified on that target.

### Visual stack demo

To test only that the workstation can launch Gazebo / MoveIt and visibly move a UR5e, without claiming that motion represents the requested BOX task, use:

```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> \
  --visual-demo
```

`--visual-demo` is explicitly reported as `task_specific=false`.

## How it works

A normal engineering flow is intentionally layered:

```text
NATURAL-LANGUAGE ENGINEERING REQUEST
                |
                v
PROVIDER-NEUTRAL INTERPRETER
                |
                v
PLANNER -> DETERMINISTIC COMPILE / VERIFY <- CRITIC
                |
                v
VERIFIED HIGH-LEVEL TASK GRAPH
                |
                v
CANONICAL PHYSICAL TWIN + IMMUTABLE HASH
                |
                v
MOVEIT-COMPILED PHYSICAL MOTION CONTRACTS
                |
                v
GAZEBO / MOVEIT MATERIALIZATION + READ-BACK
                |
                v
COLLISION / TOOL / WORKPIECE VERIFICATION
                |
                v
ROS 2 SIMULATION + MEASURED RUNTIME EVIDENCE
                |
                v
REPLAYABLE EVIDENCE + PROMOTION GATES
                |
                v
REAL HARDWARE AUTHORIZATION REMAINS SEPARATELY LOCKED
```

The high-level AI task graph and the physical motion plan are not the same artifact. A `pick -> move -> place` graph is engineering intent. Gazebo execution requires a physically grounded Twin and compiled trajectory. This separation prevents an AI-generated task description from becoming an implicit motor command.

For a nominal low-risk `load` simulation, the Critic remains advisory after deterministic compilation and verification. If it repeatedly requests subjective revisions but never rejects the plan, DevAgent may use a bounded deterministic advisory fallback after the revision budget is exhausted. A Critic `REJECT`, deterministic violation, higher-risk qualification/commissioning intent, fault injection, physical variation, or explicit engineering threshold still blocks that fallback.

## General architecture

The architecture has three authority layers:

```text
+--------------------------------------------------------------+
|                    ENGINEER / CUSTOMER                       |
|      requirement, robot, object, source, destination         |
+-------------------------------+------------------------------+
                                |
                                v
+--------------------------------------------------------------+
|                 AI ENGINEERING LAYER                         |
| Interpreter | Planner | Critic | Recovery                    |
| OpenAI / Anthropic / Gemini                                  |
| Proposes intent and candidates; owns no physical authority.  |
+-------------------------------+------------------------------+
                                |
                                v
+--------------------------------------------------------------+
|             DEVAGENT DETERMINISTIC CORE                      |
| Request validation | Compiler | Semantic policy              |
| TwinSpec | Motion contract | Collision / clearance           |
| Tool/workpiece state | Simulation measurement | Evidence     |
| Qualification and promotion gates                            |
+-------------------------------+------------------------------+
                                |
                                v
+--------------------------------------------------------------+
|               PHYSICAL SIMULATION ADAPTERS                   |
| ROS 2 | Gazebo | MoveIt | robot-specific adapters            |
| Scene materialization, trajectory execution, measured state  |
+-------------------------------+------------------------------+
                                |
                                v
+--------------------------------------------------------------+
|             OEM CONTROLLER / PLC / SAFETY                    |
| Remains authoritative for real equipment and safe execution. |
| DevAgent real execution is locked by default.                |
+--------------------------------------------------------------+
```

This plain-text diagram is intentionally used instead of Mermaid so the same README renders correctly on GitHub and PyPI.

## Physical Twin and verification

The canonical Twin records robot identity, frames, source/destination entities, workpiece, tool, geometry, physics evidence, controller metadata, uncertainty, and provenance. Unknown physical information remains unknown rather than being filled with AI guesses.

The UR5e canonical adapter can bind one materialization to Gazebo and MoveIt, verify world/scene read-back, apply a runtime-owned tool collision object, verify workpiece attach/detach transitions, execute compiled joint trajectories, record joint states, and compute MoveIt FK metrics.

The stronger production-candidate verifier can additionally use measured collision distance and conservative continuous-path clearance proof. A stronger pre-execution receipt requires evidence such as:

```text
verified=true
continuous_collision_check=true
clearance_measured=true
minimum_clearance_m > 0
materialization_hash=<exact Twin materialization>
failure_codes=[]
```

The conservative collision-distance bound must be qualified for the exact robot/tool/collision model. DevAgent does not invent that bound.

## Supported robot abstraction

The deterministic robot-profile layer includes abstractions for:

- Universal Robots UR5e
- FANUC CRX family
- KUKA KR family
- ABB IRB family

Physical simulation and qualification are adapter- and vendor-specific. The v0.12 task-specific visible `load` runtime is UR5e-specific. A profile existing in the registry does not imply equivalent physical qualification for every vendor.

## ROS 2 / Gazebo reference target

Reference workstation stack:

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

Setup and diagnostics:

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

Run the v0.12 task-specific target qualification:

```bash
python -m devagent_physical_engine.ros2.qualification_v12
```

This must visibly execute the reference task and produce a passing report before the target workstation's v0.12 task-specific ROS simulation is considered qualified. It still intentionally reports:

```text
physical_qualification=false
commissioning_qualification=false
site_qualification=false
real_execution_allowed=false
```

For the stronger continuous-clearance production-candidate campaign:

```bash
python -m devagent_physical_engine.ros2.qualification_v11 \
  --moveit-params-file /path/to/ur5e_moveit_params.yaml \
  --distance-lipschitz <qualified-m-per-radian-bound> \
  --safety-margin 0.005 \
  --log-dir ~/.devagent/v11-production-candidate-qualification
```

A successful source/workstation campaign can qualify specific simulation evidence. It still does not automatically imply physical commissioning, site qualification, functional-safety certification, or permission to execute on a real robot.

## AI providers

The CLI currently supports OpenAI, Anthropic, and Gemini through one provider-neutral agent contract.

Examples:

```bash
devagent-physical-ai qualify --provider openai --model <model-id>
devagent-physical-ai qualify --provider anthropic --model <model-id>
devagent-physical-ai qualify --provider gemini --model <model-id>
```

Provider qualification uses API credits and verifies the bounded Interpreter / Planner / Critic / Recovery path. Provider success never unlocks real robot execution.

## Software verification and releases

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

ROS/Gazebo/MoveIt executable orchestration is separately target-qualified because hosted Python CI cannot truthfully exercise a graphical Gazebo process, MoveIt `move_group`, TF, ROS controllers, and Gazebo services. Pure reference-workcell contracts and deterministic planning logic remain covered by normal unit/coverage gates.

A green `main` release is tied to the exact CI-tested commit. Release artifacts are rebuilt and verified from the exact tag, checked with Twine, installed into a clean environment, accompanied by SHA256 checksums and an SBOM, attached to the GitHub Release, and published to PyPI through Trusted Publishing.

## Documentation

Detailed engineering documentation lives in the repository:

- [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)
- [Canonical Twin runtime](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/CANONICAL_TWIN_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)
- [Laptop acceptance](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/LAPTOP_ACCEPTANCE.md)
- [PyPI release process](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/PYPI_RELEASE.md)

## Project status

**v0.13.0 — Beta software / commercial project spine + evidence-gated task-specific physical simulation.**

The software and release pipeline are production-oriented, but physical readiness is scope-specific and evidence-driven. v0.13 adds durable project/site/workcell identity, immutable Twin revisions, and content-addressed local evidence; it does not claim arbitrary customer Twin import or customer-site qualification. The UR5e task-specific reference-workcell path must pass the executable v0.12 ROS/Gazebo/MoveIt campaign on the target workstation before that scope is considered simulation-qualified there. Real robot execution remains locked. Functional-safety certification and site qualification 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.
