Metadata-Version: 2.4
Name: devagent-physical-engine
Version: 0.11.2
Summary: Verification-first agentic planning runtime for robotic 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

**Verification-first agentic engineering, planning, optimization, simulation, and evidence runtime 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 adds AI-assisted engineering to existing automation without replacing robot controllers, PLCs, safety controllers, or real-time servo loops. The core is provider-neutral and keeps engineering authority separated from model output.

## Current version

**v0.11.2 — Beta software / evidence-gated physical runtime**

The Python software stack is regression-tested on Python 3.11, 3.12, and 3.13 with separate static/coverage, package-install, and runtime dependency security gates. The UR5e Gazebo/MoveIt path now contains production-candidate continuous-clearance, tool-collision, and workpiece-lifecycle capabilities, but those physical-simulation scopes remain **EXPERIMENTAL until the executable target-workstation v0.11 campaign passes**.

Real robot execution remains locked. Functional-safety certification and site qualification are not claimed.

## v0.11 capability status

| Area | Status |
| --- | --- |
| Provider-neutral Agent Core | Implemented |
| OpenAI / Anthropic / Gemini structured adapters | Implemented |
| Planner / Critic / Recovery | Implemented |
| Natural-language engineering request front door | Implemented |
| Deterministic compiler / semantic / verification gates | Implemented |
| Multi-vendor robot profile registry | Implemented |
| UR5e / FANUC CRX / KUKA KR / ABB IRB abstraction | Implemented; physical qualification is vendor-specific |
| Evidence-aware canonical TwinSpec | Implemented |
| Canonical Twin → Gazebo + MoveIt materialization | Implemented |
| Gazebo / TF / MoveIt world read-back | Implemented |
| Runtime-owned tool collision binding + read-back | Implemented; target qualification required |
| Runtime-owned workpiece attach/detach + read-back | Implemented; target qualification required |
| Discrete MoveIt state-validity precheck | Implemented; simulation/debug only |
| Measured MoveIt collision distance | Implemented in production-candidate verifier |
| Adaptive conservative continuous-path proof | Implemented; qualified bound required |
| Measured minimum clearance + safety margin | Implemented; target qualification required |
| Measured joint-state trajectory runtime | Implemented |
| MoveIt FK TCP path / final TCP error | Implemented |
| Quantitative sim↔real qualification gate | Implemented; measured hardware dataset required |
| Python package/release supply chain | Hardened CI + exact-green-main release + direct `release.yml` PyPI OIDC deployment |
| UR5e production-candidate simulation evidence | **Requires executable v0.11 target campaign** |
| Physical commissioning | **Not qualified by source/CI alone** |
| Site qualification | **Not qualified** |
| Real robot execution | **Locked** |
| Functional-safety certification | Not claimed |

## Trust chain

```mermaid
flowchart TD
    USER[Engineer / customer application] --> REQUEST[Natural-language engineering request]
    REQUEST --> AI[Provider-neutral AI / Planner / Critic / Recovery]
    AI --> COMPILE[Deterministic compile + semantic policy]
    COMPILE --> VERIFY[Verified plan artifact]
    VERIFY --> TWIN[Canonical TwinSpec + SHA256]
    TWIN --> MATERIALIZE[Canonical materialization]
    MATERIALIZE --> GZ[Gazebo world]
    MATERIALIZE --> MOVEIT[MoveIt PlanningScene]
    MATERIALIZE --> TF[TF frames]
    GZ --> READBACK[Backend read-back]
    MOVEIT --> READBACK
    TF --> READBACK
    READBACK --> TOOL[Verified tool collision receipt]
    TOOL --> WORKPIECE[Verified workpiece lifecycle receipt]
    WORKPIECE --> MOTION[Exact PhysicalMotionPlan / Twin binding]
    MOTION --> CLEAR[Measured clearance + continuous proof]
    CLEAR --> SIM[ROS 2 / Gazebo execution]
    SIM --> MEASURE[Measured joint states + MoveIt FK]
    MEASURE --> EVIDENCE[Replayable evidence]
    EVIDENCE --> PROMOTION[Scope-specific promotion gate]
    PROMOTION --> LOCKED[Real execution remains separately locked]
```

The model never owns collision policy, minimum-clearance truth, dynamic scene state, qualification promotion, or real-hardware authorization.

## Continuous collision and clearance semantics

The legacy/discrete verifier remains available for development and simulation but can never produce commissioning-usable evidence.

The v0.11 production-candidate verifier synchronizes the authoritative MoveIt PlanningScene, measures minimum collision distance, and adaptively proves every joint interval using a conservative collision-distance Lipschitz bound. If the proof cannot be established within configured sample/depth limits, it fails closed. There is no automatic downgrade to a sampled “pass.”

A commissioning-usable pre-execution receipt requires all of:

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

The distance Lipschitz bound is itself qualification evidence and must be conservative for the exact robot/tool/collision model.

## Tool and workpiece authority

Customer motion metadata can no longer claim that a tool collision model or workpiece attachment is verified.

`ToolCollisionBinding` is runtime configuration. The tool is applied as a MoveIt attached collision object and verified by geometry/link read-back before a receipt is accepted.

Workpiece state uses verified transitions:

```text
WORLD → ATTACHED → WORLD
```

Attach/detach applies the PlanningScene change and verifies the resulting world/attached state. Missing or inconsistent read-back blocks the motion.

## Installation

Python 3.11+ is required.

From PyPI after the corresponding release is published:

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

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

Optional provider SDKs:

```bash
python -m pip install -e ".[openai]"
python -m pip install -e ".[anthropic]"
python -m pip install -e ".[gemini]"
python -m pip install -e ".[ai]"
```

Development/qualification tooling:

```bash
python -m pip install -e ".[dev]"
```

`pip install` does not install ROS/Gazebo system packages or perform privileged OS changes.

## AI providers

Keep credentials outside WorldState/Twin data:

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

Examples:

```bash
devagent-physical-ai doctor --provider openai
devagent-physical-ai qualify --provider openai --model <model-id>
devagent-physical-ai request \
  "Use a UR5e to move a part from conveyor_a to cnc_04" \
  --provider openai --model <model-id>
devagent-physical-ai engineer \
  "Use a UR5e to move a part from conveyor_a to cnc_04" \
  --provider openai --model <model-id>
```

Equivalent routing supports Anthropic and Gemini. Live AI qualification does not unlock real robot execution.

## Software production gates

Repository CI now requires:

```text
Python 3.11 regression
Python 3.12 regression
Python 3.13 regression
compileall
Ruff correctness checks
branch coverage threshold
wheel + sdist build
twine --strict
clean wheel installation/version smoke
runtime dependency vulnerability audit
```

Critical checkout/setup/artifact GitHub Actions are pinned to exact commits.

A successful `main` CI run drives `release-on-ci.yml`, which validates the package version and creates a normal GitHub Release at the **exact CI-tested SHA**. It then dispatches `release.yml` with `workflow_dispatch` at the exact release tag. Running Trusted Publishing in the directly dispatched `release.yml` is intentional: PyPI binds the OIDC publisher identity to that workflow filename and does not currently support reusable workflows for Trusted Publishing. `release.yml` rebuilds and re-verifies the exact tag, attaches wheel/sdist/SBOM/checksum evidence to the GitHub Release, and publishes through the GitHub `pypi` environment using OIDC.

## UR5e ROS 2 / Gazebo target

Reference target:

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

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

## v0.11 production-candidate executable qualification

The stronger campaign is deliberately separate from ordinary hosted GitHub CI because it requires the exact ROS/Gazebo/MoveIt target stack and qualified robot/tool collision-distance bound:

```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 green campaign requires canonical world read-back, verified tool attachment, verified workpiece attach+detach, synchronized MoveIt scene, conservative continuous collision/clearance proof, minimum clearance above margin, measured joint-state execution, and MoveIt FK evidence.

It may report:

```text
promotion_candidate=true
simulation_commissioning_evidence_qualified=true
continuous_collision_check=true
minimum_clearance_measured=true
```

but still intentionally reports:

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

Physical/site promotion requires measured hardware/shadow evidence.

## Sim↔real qualification

The source now includes an explicit quantitative correlation gate. Default minimum criteria are:

```text
observations >= 30
cycle-time gap p95 <= 10%
TCP error p95 <= 10 mm
behavior agreement >= 0.99
measured origin + dataset reference required
```

Missing evidence never qualifies. Customers may set stricter thresholds.

## Optimization semantics

DevAgent does **not** claim a mathematical global optimum. It selects the best evaluated verified candidate among candidates actually generated, verified, and measured under the configured objective. A hard violation, failed verification/simulation, unknown required metric, or failed quality gate makes the candidate ineligible regardless of weighted score.

## Documentation

- [`docs/PRODUCTION_READINESS.md`](docs/PRODUCTION_READINESS.md) — v0.11 readiness scopes and qualification boundaries.
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — current trust boundaries and runtime architecture.
- [`docs/AGENT_CORE.md`](docs/AGENT_CORE.md) — Agent Core authority model.
- [`docs/AI_PROVIDERS.md`](docs/AI_PROVIDERS.md) — provider installation, credentials, and qualification.
- [`docs/NATURAL_LANGUAGE_ENGINEERING.md`](docs/NATURAL_LANGUAGE_ENGINEERING.md) — natural-language engineering request flow.
- [`docs/ROBOT_PLATFORM_AND_TWIN.md`](docs/ROBOT_PLATFORM_AND_TWIN.md) — robot abstraction and evidence-aware Twin.
- [`docs/MEASURED_PHYSICAL_RUNTIME.md`](docs/MEASURED_PHYSICAL_RUNTIME.md) — motion and measured runtime.
- [`docs/CANONICAL_TWIN_RUNTIME.md`](docs/CANONICAL_TWIN_RUNTIME.md) — canonical scene, continuous clearance, and dynamic scene lifecycle.
- [`docs/QUALIFICATION.md`](docs/QUALIFICATION.md) — qualification/evidence model.
- [`docs/OPTIMIZATION.md`](docs/OPTIMIZATION.md) — search, metrics, Pareto ranking, and evidence.
- [`docs/SETUP.md`](docs/SETUP.md) — explicit workstation bootstrap.
- [`docs/LAPTOP_ACCEPTANCE.md`](docs/LAPTOP_ACCEPTANCE.md) — UR5e workstation acceptance.
- [`docs/PYPI_RELEASE.md`](docs/PYPI_RELEASE.md) — Trusted Publishing release pipeline.

## Release policy

v0.11 is a **Beta software release**, not a declaration that every robot/site is physically commissioned. Capability promotion remains evidence-driven and scope-specific. Simulation evidence cannot silently become hardware/site qualification.

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