Metadata-Version: 2.4
Name: devagent-physical-engine
Version: 0.10.0
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 :: 3 - Alpha
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"
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 is designed to add 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.10.0 — Alpha**

The Python software stack is regression-tested in GitHub Actions on Python 3.11, 3.12, and 3.13. The UR5e Gazebo/MoveIt canonical physical-simulation runtime is implemented but remains **EXPERIMENTAL** until executable target-workstation qualification promotes its individual scopes.

Real robot execution remains locked. Functional-safety certification is not claimed.

## What v0.10.0 includes

| Area | Status |
| --- | --- |
| Provider-neutral Agent Core | Implemented |
| OpenAI structured provider adapter | Implemented |
| Anthropic structured provider adapter | Implemented |
| Gemini structured provider adapter | Implemented |
| Planner / Critic / Recovery | Implemented |
| Natural-language engineering request front door | Implemented |
| Deterministic request/compiler/policy gates | Implemented |
| Multi-vendor robot profile registry | Implemented |
| UR5e / FANUC CRX / KUKA KR / ABB IRB profile abstraction | Implemented |
| Evidence-aware canonical TwinSpec | Implemented |
| Deterministic Twin validation and confidence levels | Implemented |
| Bounded candidate generation and Pareto optimization | Implemented |
| Replayable qualification/evidence primitives | Implemented |
| Canonical physical motion contract | Implemented |
| Measured joint-state trajectory runtime | Implemented |
| Canonical Twin -> Gazebo + MoveIt materialization | Implemented |
| Gazebo / TF / MoveIt backend read-back verification | Implemented |
| Sampled MoveIt pre-execution state-validity checks | Implemented, **discrete only** |
| Measured motion duration / joint travel | Implemented |
| MoveIt FK TCP path length / final TCP error | Implemented |
| UR5e canonical Gazebo/MoveIt adapter | **EXPERIMENTAL** |
| Continuous collision checking qualification | **Not qualified** |
| Minimum-clearance measurement | **Not qualified** |
| Sim-real correlation | **Not qualified** |
| 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 --> INTERPRETER[Requirement Interpreter]

    INTERPRETER --> OAI[OpenAI]
    INTERPRETER --> CLAUDE[Anthropic]
    INTERPRETER --> GEMINI[Gemini]

    OAI --> AGENTS[Planner / Critic / Recovery]
    CLAUDE --> AGENTS
    GEMINI --> AGENTS

    AGENTS --> COMPILE[Deterministic compile + 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 / frame model]

    GZ --> READBACK[Backend read-back verification]
    MOVEIT --> READBACK
    TF --> READBACK

    READBACK --> PRECHECK[Pre-execution verification]
    PRECHECK --> MOTION[Exact PhysicalMotionPlan]
    MOTION --> SIM[Gazebo / ROS 2 execution]
    SIM --> MEASURE[Measured joint states + MoveIt FK]
    MEASURE --> EVIDENCE[Replayable evidence]
    EVIDENCE --> PROMOTION[Evidence-driven promotion gate]

    PROMOTION --> LOCKED[Real execution remains locked]
```

The v0.10 architecture is specifically designed to prevent DevAgent from validating one Twin while MoveIt plans against a different scene and Gazebo executes a different world. One canonical Twin fingerprint is carried through materialization, backend read-back, pre-execution verification, motion execution, and evidence.

## Safety and qualification boundary

A successful software test or simulation run does **not** automatically create a commissioning or real-hardware claim.

The v0.10 canonical qualification report deliberately keeps:

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

A reference campaign can produce promotion-candidate evidence for an experimental scope, but promotion remains evidence-driven and scope-specific.

## Installation from source

Python 3.11+ is required.

```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 AI 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]"
```

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

## AI providers

Credentials stay outside the world model:

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

Check a provider without making a network qualification call:

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

Run live provider qualification:

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

Interpret an engineering request:

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

Run the natural-language engineering pipeline:

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

Equivalent provider commands support Anthropic and Gemini. Live AI routing is simulation-only and does not unlock real execution.

See [`docs/AI_PROVIDERS.md`](docs/AI_PROVIDERS.md) and [`docs/NATURAL_LANGUAGE_ENGINEERING.md`](docs/NATURAL_LANGUAGE_ENGINEERING.md).

## Deterministic verification

Core checks:

```bash
python -m compileall -q src tests
python -m unittest discover -s tests -v
devagent-physical doctor
devagent-physical qualify
devagent-physical simulate --robot fanuc_crx --inject-collision
```

The repository CI performs editable installation, `compileall`, and the full `unittest` regression matrix on Python 3.11 / 3.12 / 3.13.

## UR5e ROS 2 / Gazebo target stack

Current reference target:

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

Inspect workstation changes without modifying the system:

```bash
devagent-physical setup --profile ur5e-sim --dry-run
```

Explicitly install/verify the supported workstation profile:

```bash
devagent-physical setup --profile ur5e-sim
```

Then run:

```bash
devagent-physical ros doctor
devagent-physical ros demo
```

The visual demo launches the official UR5e Gazebo + MoveIt/RViz stack, waits for controller readiness and `/joint_states`, performs a motion smoke, verifies measured joint-state movement, and records evidence.

Trajectory-runtime-only qualification is also available:

```bash
devagent-physical ros qualify-trajectory-runtime
```

That command qualifies only its defined scope and does not promote commissioning or real-hardware execution.

## v0.10 canonical Twin qualification

The executable reference campaign is intentionally separate from ordinary GitHub CI because it requires the ROS/Gazebo/MoveIt target stack:

```bash
python -m devagent_physical_engine.ros2.qualification_v10 \
  --log-dir ~/.devagent/v10-canonical-qualification
```

The campaign requires canonical Gazebo/MoveIt materialization, TF alignment, backend scene read-back, sampled pre-execution validity, measured joint-state motion, and MoveIt FK evidence across the reference trajectories.

Even a green reference campaign remains an experimental-scope promotion candidate until the missing commissioning gates—such as continuous collision checking and qualified minimum-clearance measurement—are implemented and evidenced.

See [`docs/CANONICAL_TWIN_RUNTIME.md`](docs/CANONICAL_TWIN_RUNTIME.md) and [`docs/MEASURED_PHYSICAL_RUNTIME.md`](docs/MEASURED_PHYSICAL_RUNTIME.md).

## Optimization semantics

DevAgent does **not** claim a mathematical global optimum. It selects the **best evaluated verified candidate** among the candidates and motion variants that were actually generated, verified, and measured under the configured objective profile.

A candidate is ineligible when deterministic verification/simulation fails, a hard violation is reported, required metrics are unknown, or configured quality gates fail. Weighted scoring cannot make an unsafe or unverified plan acceptable.

See [`docs/OPTIMIZATION.md`](docs/OPTIMIZATION.md).

## Documentation

- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — trust boundaries and runtime architecture.
- [`docs/AGENT_CORE.md`](docs/AGENT_CORE.md) — Agent Core design.
- [`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) — multi-vendor robot platform and evidence-aware Twin.
- [`docs/MEASURED_PHYSICAL_RUNTIME.md`](docs/MEASURED_PHYSICAL_RUNTIME.md) — physical motion and measured qualification runtime.
- [`docs/CANONICAL_TWIN_RUNTIME.md`](docs/CANONICAL_TWIN_RUNTIME.md) — canonical Gazebo/MoveIt/TF materialization and verification.
- [`docs/QUALIFICATION.md`](docs/QUALIFICATION.md) — qualification and 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 visual workstation acceptance.

## Release policy

`v0.10.0` is the first tagged GitHub release of this repository. It is an **alpha engineering release**, not a declaration of functional-safety certification, site qualification, or authorization for autonomous real-robot execution.

Future capability promotion must remain evidence-driven and must not silently upgrade experimental simulator results into commissioning claims.

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