devagent-physical-engine 0.11.5__tar.gz → 0.12.0__tar.gz

devagent_physical_engine-0.12.0/PKG-INFO

@@ -0,0 +1,429 @@
+Metadata-Version: 2.4
+Name: devagent-physical-engine
+Version: 0.12.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.
+
+## 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.
+
+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:
+
+- [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.12.0 — Beta software / evidence-gated task-specific physical simulation.**
+
+The software and release pipeline are production-oriented, but physical readiness is scope-specific and evidence-driven. The new 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.