devagent-physical-engine 0.11.4__tar.gz → 0.11.6__tar.gz

devagent_physical_engine-0.11.6/PKG-INFO

@@ -0,0 +1,375 @@
+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.