Metadata-Version: 2.4
Name: devagent-physical-engine
Version: 0.11.6
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.
- **Fail-closed visualization** — DevAgent never substitutes a canned motion and labels it as the requested 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 +   6.84s] INTERPRETER  validated request_id=REQ-...
[DevAgent +   6.84s] PLANNER      revision=0 generating high-level task graph
[DevAgent +  12.21s] CRITIC       revision=0 reviewing verified plan
[DevAgent +  15.77s] SIMULATION   running deterministic model execution
[DevAgent +  15.78s] COMPLETE     ready_for_twin_simulation=true
```

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

## Visual simulation

There are two deliberately different visualization modes.

To prove that the workstation can launch Gazebo / MoveIt and visibly move a UR5e, use the explicit visual demo:

```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` runs the packaged UR5e motion smoke through the ROS simulation stack. It is intentionally reported as `task_specific=false`; it proves the visualization/motion stack is working, not that the exact BOX task has been physically planned.

To request visualization of the **exact engineering 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> \
  --visualize
```

Task-specific visualization fails closed until the runtime has enough physical evidence to construct the exact scene and compile an exact `PhysicalMotionPlan`. Required evidence includes robot/source/destination poses, collision geometry, workpiece geometry, tool/TCP information, and the compiled physical motion. DevAgent will not display an unrelated canned movement and call it the requested task.

## 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
EXACT PHYSICAL MOTION CONTRACT
                |
                v
GAZEBO / MOVEIT MATERIALIZATION + READ-BACK
                |
                v
COLLISION / CLEARANCE / 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.

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

For production-candidate UR5e simulation, the stronger verifier can use MoveIt PlanningScene read-back, runtime-owned tool collision binding, runtime-owned workpiece attach/detach transitions, measured collision distance, conservative continuous-path clearance proof, measured joint states, and MoveIt FK evidence.

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. Current production-candidate physical-runtime work is centered on the UR5e ROS 2 / Gazebo / MoveIt path; 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
```

For the stronger production-candidate target 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.

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:

- [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.11.6 — Beta software / evidence-gated physical runtime.**

The software and release pipeline are production-oriented, but physical readiness is scope-specific and evidence-driven. The UR5e physical simulation path remains experimental until its exact target-stack qualification campaign passes. 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.
