devagent-physical-engine 1.9.1__tar.gz → 2.0.0__tar.gz

devagent_physical_engine-2.0.0/PKG-INFO

@@ -0,0 +1,609 @@
+Metadata-Version: 2.4
+Name: devagent-physical-engine
+Version: 2.0.0
+Summary: Verification-first robotics commissioning control plane with immutable engineering findings, deterministic pre-site readiness, evidence authority, exact-Twin lineage, selective simulation, regression, replay, and FAT reporting.
+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
+Project-URL: Sponsor, https://github.com/sponsors/tomha85
+Keywords: robotics,industrial-automation,agentic-ai,ros2,gazebo,moveit,pilz,verification,selective-testing,digital-twin,fat-testing,regression,evidence,replay
+Classifier: Development Status :: 5 - Production/Stable
+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: Production/Stable](https://img.shields.io/badge/status-production%2Fstable-blue.svg)](#project-status)
+[![Sponsor DevAgent Physical Engine](https://img.shields.io/badge/Sponsor-DevAgent%20Physical%20Engine-EA4AAA?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/tomha85)
+
+**Verification-first commissioning engineering for robotics and industrial automation.**
+
+DevAgent turns customer engineering inputs into a bounded, evidence-driven pre-site commissioning workflow. AI may help interpret and propose; deterministic engines validate, compile, execute qualified verification, measure evidence, detect regression, and gate promotion.
+
+> **OEM robot controllers, PLCs, safety PLCs, certified safety systems, and qualified site processes remain authoritative. DevAgent does not convert simulation into site qualification or functional-safety certification.**
+
+## Engine in action
+
+<p align="center">
+  <img src="docs/assets/readme/Screenshot%20from%202026-09-02%2015-14-21.png" width="100%" alt="DevAgent Smart Physical Engine exact-Twin UR5e workcell running in Gazebo Harmonic">
+</p>
+
+<p align="center">
+  <b>Exact-Twin simulation in Gazebo Harmonic</b><br>
+  <sub>Real DevAgent engine run with the bounded UR5e workcell, customer-cell entities, physics, and simulation state visible.</sub>
+</p>
+
+<table>
+  <tr>
+    <td width="50%" align="center">
+      <img src="docs/assets/readme/Screenshot%20from%202026-09-02%2015-15-17.png" width="100%" alt="DevAgent Smart Physical Engine robot task execution in Gazebo">
+      <br><b>Robot task execution</b><br>
+      <sub>Gazebo view during the bounded pick–transport–place workflow.</sub>
+    </td>
+    <td width="50%" align="center">
+      <img src="docs/assets/readme/Screenshot%20from%202026-09-02%2015-14-32.png" width="100%" alt="DevAgent Smart Physical Engine MoveIt motion planning scene in RViz">
+      <br><b>MoveIt motion planning</b><br>
+      <sub>RViz planning-scene view used alongside the qualified ROS 2 / MoveIt execution path.</sub>
+    </td>
+  </tr>
+</table>
+
+<p align="center"><sub><b>Real engine screenshots — not product renders.</b> ROS 2 Jazzy · Gazebo Harmonic · MoveIt 2 · Pilz · UR5e exact-Twin verification.</sub></p>
+
+## v2.0 commissioning verification flow
+
+```text
+Customer engineering files
+        ↓
+Immutable project + Twin revision
+        ↓
+Engineering review
+        ↓
+Requirements + findings + risks + changes
+        ↓
+Deterministic criterion mapping
+        ↓
+Requirement-driven verification plan
+        ↓
+Verification-scope authority
+        ↓
+Deterministic checks + qualified physical evidence
+        ↓
+Evidence Graph
+        ↓
+PASS / FAIL / NOT_TESTED
+        ↓
+Change Impact + Regression
+        ↓
+FAT Report + Evidence Bundle
+        ↓
+Immutable pre-site commissioning decision
+```
+
+The final bounded decision is one of:
+
+```text
+READY_FOR_PRE_SITE_COMMISSIONING
+NOT_READY_FOR_PRE_SITE_COMMISSIONING
+```
+
+That decision means the declared pre-site engineering scope has complete, current evidence according to DevAgent's installed authority contracts. It does **not** mean the real site is commissioned.
+
+## Quick start
+
+Python 3.11+ is required.
+
+```bash
+python -m pip install --upgrade devagent-physical-engine==2.0.0
+```
+
+Verify the installed package:
+
+```bash
+python -c "import devagent_physical_engine as d; print(d.__version__)"
+```
+
+Expected:
+
+```text
+2.0.0
+```
+
+Run the normal customer workflow:
+
+```bash
+devagent verify ./customer-project
+```
+
+Request qualified simulation where available:
+
+```bash
+devagent verify ./customer-project --simulate
+```
+
+Open the Evidence Viewer and keep the engineering terminal active:
+
+```bash
+devagent verify ./customer-project --simulate --open
+```
+
+Machine-readable CI output:
+
+```bash
+devagent verify ./customer-project --json
+```
+
+Default locations:
+
+```text
+Evidence database: ~/.devagent/projects.db
+Results:           <customer-project>/devagent-results/
+```
+
+## Commercial commissioning workflow
+
+The normal end-to-end customer path is `devagent verify`. It performs requirement normalization, deterministic mapping, requirement-driven case planning/mapping, verification orchestration, evidence recording, regression, and reporting within the qualified scope.
+
+`devagent-commercial` is the lower-level immutable project/evidence/control-plane interface. It is useful for explicit artifact operations, CI, audit, and commissioning-readiness inspection.
+
+Example low-level operations:
+
+```bash
+devagent-commercial --db ~/.devagent/projects.db init CELL-01 \
+  --name "Customer Cell" \
+  --site SITE-01 \
+  --workcell CNC-LOAD
+
+devagent-commercial --db ~/.devagent/projects.db import-twin CELL-01 ./customer-project
+
+devagent-commercial --db ~/.devagent/projects.db requirements CELL-01 requirements.yaml
+
+devagent-commercial --db ~/.devagent/projects.db engineering-review CELL-01 <requirement-set-artifact-id>
+
+devagent-commercial --db ~/.devagent/projects.db verification-plan CELL-01 verification.yaml
+
+devagent-commercial --db ~/.devagent/projects.db campaign CELL-01 requirements.yaml \
+  --measurement <physical-measurement-artifact-id>
+
+devagent-commercial --db ~/.devagent/projects.db fat-report CELL-01 <campaign-artifact-id>
+
+devagent-commercial --db ~/.devagent/projects.db evidence-bundle CELL-01 <campaign-artifact-id>
+
+devagent-commercial --db ~/.devagent/projects.db commissioning-readiness CELL-01
+
+devagent-commercial --db ~/.devagent/projects.db commissioning-status CELL-01
+```
+
+`verification-plan` records an explicit deterministic plan from the supplied spec. It does **not** invent a requirement→case mapping. Final commissioning readiness requires exact current requirement-to-case lineage; the one-command workflow records that mapping, and low-level/custom integrations must record equivalent immutable lineage instead of bypassing the gate.
+
+Use `finding-disposition` to record an immutable engineering disposition. A blocking finding cannot be resolved without current-Twin evidence.
+
+## What DevAgent proves
+
+DevAgent separates planning, execution, measurement, verdicts, and authority.
+
+```text
+Requirement / report test
+        ↓
+Declarative verification capability
+        ↓
+Exact Twin revision/hash
+        ↓
+Exact verification plan + case mapping
+        ↓
+Qualified evidence reuse or qualified execution
+        ↓
+Measured evidence
+        ↓
+Deterministic verdict
+        ↓
+PASS / FAIL / NOT_TESTED
+```
+
+A generated plan is not physical proof. A replay is not a new execution. An AI response is not engineering evidence. A simulation result does not grant site qualification.
+
+## Engineering findings and risk authority
+
+v2.0 records first-class immutable artifacts for:
+
+```text
+engineering_finding
+engineering_review
+engineering_finding_disposition
+```
+
+High and critical findings are structurally blocking. AI or a human reviewer may propose findings, but findings do not create PASS authority.
+
+A blocking finding may be marked resolved only when the disposition references evidence bound to the current Twin scope. Acknowledged, deferred, or accepted-risk records remain explicit and do not silently promote readiness.
+
+## Verification-scope authority
+
+A verification plan is not trusted merely because it belongs to the same Twin.
+
+`VerificationScopeAuthority` deterministically reconstructs the expected test space from the exact current campaign requirements and compares the stored plan and requirement-to-case mapping with that expected scope.
+
+If a requirement change alters payload, boundary, or fault coverage but an old plan/map is reused, readiness fails closed.
+
+## Physical evidence authority
+
+### Internal simulation / hardware-shadow evidence
+
+A standalone measurement JSON cannot grant final readiness merely by claiming `gazebo_moveit`, a run ID, and a qualification reference.
+
+Internal evidence must preserve an exact immutable chain:
+
+```text
+physical_measurement
+        ↓
+runtime_measurement_binding
+        ↓
+physical_motion_plan
+        ↓
+exact Twin + run + qualification lineage
+```
+
+### External simulator evidence
+
+External evidence is imported as candidate evidence and is independently gated by installed provider policy.
+
+Built-in provider identities include:
+
+```text
+ABB RobotStudio
+FANUC ROBOGUIDE
+KUKA.Sim
+Visual Components
+RoboDK
+Siemens Process Simulate
+```
+
+These identities do not imply qualification. A provider remains candidate-only unless a code-reviewed policy explicitly qualifies its version/export schema and binds exact source provenance, candidate evidence, Twin hash, metrics, and qualification reference.
+
+## Whole-project staleness
+
+Each pre-site decision records a deterministic readiness-state snapshot hash.
+
+A previous READY result becomes stale when readiness-relevant state changes, including:
+
+```text
+Twin revision
+requirement set
+engineering review
+finding / disposition
+verification plan
+requirement-case mapping
+physical measurement / runtime binding
+campaign
+change impact
+regression
+FAT report
+evidence bundle
+```
+
+This also catches same-Twin changes. `commissioning-status` verifies both the decision hash and the current project-state snapshot before reporting READY.
+
+## Evidence Graph and replay
+
+The read-only Evidence Graph links requirements, Twin revisions, campaigns, findings, dispositions, measurements, motion plans, regressions, FAT reports, evidence bundles, and final readiness decisions.
+
+```bash
+devagent-commercial --db ~/.devagent/projects.db evidence-graph CELL-01
+```
+
+Write a self-contained viewer:
+
+```bash
+devagent-commercial --db ~/.devagent/projects.db evidence-viewer CELL-01 \
+  --output ./EVIDENCE.html
+```
+
+Replay reconstructs persisted evidence identity. It never commands Gazebo, MoveIt, a robot, PLC, or safety PLC.
+
+## Interactive engineering session
+
+Use `--interactive`, or `--open` from a real terminal, to keep a bounded prompt:
+
+```text
+status
+tests
+test SELECTOR
+simulate SELECTOR
+simulate all
+simulate --fresh SELECTOR
+simulate --fresh all
+rerun SELECTOR
+rerun failed
+rerun blocked
+rerun affected
+rerun all
+replay
+report
+log
+help
+quit
+```
+
+`test SELECTOR` evaluates existing evidence without commanding the simulator.
+
+`simulate TEST-X` reuses exact qualified evidence when available and executes only when the mapped physical case is missing.
+
+`simulate --fresh TEST-X` and physical `rerun ...` explicitly request new execution and append new immutable evidence.
+
+Report-wide fresh execution still deduplicates shared physical case IDs.
+
+## Qualified visual-execution scope
+
+Measured report-test execution remains intentionally narrow:
+
+```text
+robot:       UR5e
+operation:   load
+case scope:  qualified mapped physical report cases within the packaged authority
+runtime:     Ubuntu 24.04 + ROS 2 Jazzy + Gazebo Harmonic + MoveIt/Pilz
+```
+
+The target-proven UR5e path retains controller-manager/action readiness binding, canonical Twin/PlanningScene verification, conservative Pilz PTP/LIN motion, workpiece attach/carry/release semantics, controller-feedback tracking evidence, and post-release settle verification.
+
+Unsupported customer Twins, unqualified robot profiles, boundary/fault cases outside the qualified scope, ambiguous case mappings, or incomplete lineage fail closed.
+
+ABB IRB1200 remains a separate experimental visual simulation path. FANUC/KUKA and other robot/vendor paths retain their truthful support tiers until separately qualified.
+
+Inspect robot support:
+
+```bash
+devagent robots
+devagent robot doctor abb_irb1200
+devagent robot visualize abb_irb1200
+```
+
+## Customer input
+
+A customer folder can contain the engineering material the team already has:
+
+```text
+ACME_CNC_CELL_TEST/
+├── project.yaml
+├── requirements.xlsx
+├── devagent-twin.yaml
+├── robot.urdf
+├── robot.urdf.xacro
+├── robot.srdf
+├── tcp.yaml
+├── calibration.yaml
+├── layout/
+│   ├── cell_layout.yaml
+│   └── meshes/
+├── robot_program/
+│   └── mission.yaml
+└── expected/
+    └── expected_findings.json
+```
+
+Important rule:
+
+```text
+file discovered != engineering fact proven
+```
+
+DevAgent fingerprints and classifies files, but filenames do not prove poses, TCPs, calibrations, collision geometry, safety behavior, or physical performance.
+
+If critical information is missing or ambiguous, DevAgent asks for information instead of inventing engineering facts.
+
+## Results and evidence
+
+Typical output:
+
+```text
+customer-project/
+└── devagent-results/
+    ├── RUN.log
+    ├── SUMMARY.json
+    ├── INTAKE.json
+    ├── QUESTIONS.md
+    ├── normalized/
+    │   ├── requirements.csv
+    │   └── devagent-twin.yaml
+    ├── report-test-visualization/
+    ├── FAT_REPORT.html
+    └── EVIDENCE.html
+```
+
+`EVIDENCE.html` is read-only engineering evidence. `RUN.log` is a human progress/debug trace and does not replace immutable evidence artifacts.
+
+## Physical simulation setup
+
+`pip install` does not install ROS 2, Gazebo, MoveIt, OEM drivers, or privileged operating-system packages.
+
+Reference stack:
+
+```text
+Ubuntu 24.04
+ROS 2 Jazzy
+Gazebo Harmonic
+gz_ros2_control
+MoveIt 2
+```
+
+UR5e measured report-test execution additionally uses the Universal Robots ROS 2 driver, `ur_simulation_gz`, and Pilz Industrial Motion Planner.
+
+Preview UR5e setup:
+
+```bash
+devagent-physical setup --profile ur5e-sim --dry-run
+```
+
+Apply explicitly:
+
+```bash
+devagent-physical setup --profile ur5e-sim --yes
+```
+
+Check runtime prerequisites:
+
+```bash
+devagent-physical ros doctor
+devagent robot doctor abb_irb1200
+```
+
+Hosted CI validates deterministic software contracts. It does not pretend to execute a graphical ROS/Gazebo/MoveIt target stack. Target-stack acceptance must run on the intended workstation.
+
+## Optional AI providers
+
+AI is optional and advisory.
+
+```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]"
+python -m pip install "devagent-physical-engine[ai]"
+```
+
+Typical credentials:
+
+```bash
+export OPENAI_API_KEY="..."
+export ANTHROPIC_API_KEY="..."
+export GEMINI_API_KEY="..."
+```
+
+Provider-backed interpretation cannot grant physical truth, site qualification, functional-safety certification, or real-execution authority.
+
+## Installed CLIs
+
+```text
+devagent             one-command verification, interactive report testing, robot support/visualization
+devagent-commercial  project, evidence, findings, FAT, regression, commissioning-readiness workflow
+devagent-physical    deterministic core + ROS/qualification tools
+devagent-physical-ai optional provider-backed engineering front end
+```
+
+## Simple Mode exit codes
+
+| Exit | Meaning |
+| ---: | --- |
+| `0` | bounded full verification is release-ready |
+| `10` | customer input or operational contract failure |
+| `30` | more engineering information is required |
+| `31` | requested simulation is blocked/unqualified |
+| `32` | verification completed but full release readiness is false |
+
+# Project status
+
+**v2.0.0 — Production/Stable software workflow; commissioning verification control plane with fail-closed pre-site readiness**
+
+v2.0.0 adds immutable engineering findings/dispositions, deterministic verification-scope authority, stronger internal/external evidence authority, commissioning-aware Evidence Graph lineage, whole-project staleness detection, and an immutable pre-site commissioning readiness decision.
+
+Production-oriented software capabilities include:
+
+```text
+one-command customer intake
+XLSX/CSV/YAML/JSON requirement normalization
+immutable project/Twin lineage
+engineering review + first-class risk findings
+evidence-backed finding dispositions
+validated Requirement → Criterion mapping
+optional provider-backed advisory criterion proposals
+requirement-driven nominal / boundary / fault case generation
+verification-scope authority against current requirements
+exact Requirement → Mapping → Verification Plan → Case provenance
+case-centric qualified evidence reuse
+explicit fresh physical execution
+verification-owned simulator lifecycle cleanup
+mixed deterministic + physical report orchestration
+truthful PASS / FAIL / NOT_TESTED
+runtime-bound internal physical evidence authority
+policy-bound external simulator evidence authority
+commissioning-aware Evidence Graph
+whole-project readiness staleness detection
+change impact + regression
+professional FAT report
+Evidence Bundle + replay
+immutable READY / NOT_READY pre-site commissioning decision
+provider-neutral optional AI front end
+```
+
+Production/Stable describes the bounded software workflow. The target-proven UR5e claim remains limited to the qualified packaged scope and acceptance environment. v2.0.0 does not claim arbitrary customer cells are physically qualified, site-qualified, functionally safe, commissioned, or authorized for autonomous real execution.
+
+Current hard authority boundaries remain:
+
+```text
+site_qualification = false
+functional_safety_certification = false
+commissioning_completed = false
+real_execution_allowed = false
+```
+
+unless separately proven by an appropriate qualified process.
+
+## Documentation
+
+v2.0.0 release notes:
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/RELEASE_NOTES_V2_0_0.md
+
+v1.9.1 release notes:
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/RELEASE_NOTES_V1_9_1.md
+
+v1.9.0 release notes:
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/RELEASE_NOTES_V1_9_0.md
+
+One-command verification:
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ONE_COMMAND_VERIFY_V13.md
+
+Evidence Trust / replay / viewer:
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/EVIDENCE_TRUST_V12.md
+
+Measured physical runtime:
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/MEASURED_PHYSICAL_RUNTIME.md
+
+Commercial project spine:
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMERCIAL_PROJECT_SPINE.md
+
+Architecture:
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ARCHITECTURE.md
+
+Canonical Twin runtime:
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/CANONICAL_TWIN_RUNTIME.md
+
+Laptop acceptance:
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/LAPTOP_ACCEPTANCE.md
+
+## 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.
+
+See repository `LICENSE`, `NOTICE`, and `COPYRIGHT` for complete ownership and usage terms.