devagent-physical-engine 1.7.0__tar.gz → 1.7.2__tar.gz

devagent_physical_engine-1.7.2/PKG-INFO

@@ -0,0 +1,584 @@
+Metadata-Version: 2.4
+Name: devagent-physical-engine
+Version: 1.7.2
+Summary: Production-grade verification-first robotics evidence runtime with one-command customer intake, validated requirement mapping, adaptive industrial Pilz PTP/LIN report-test Gazebo execution, transfer/place segment diagnostics, requirement-driven test generation, selective verification, deterministic Twin lineage, measured physical verification, replay inspection, regression, and FAT evidence.
+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,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)
+
+**Verification-first commissioning engineering for robotics and industrial automation.**
+
+DevAgent turns a customer engineering folder into a bounded verification workflow with immutable Digital Twin lineage, deterministic requirement verdicts, requirement-driven test cases, exact-Twin measured simulation evidence, regression analysis, FAT reporting, replay inspection, and selective retesting.
+
+```text
+customer engineering files
+    ↓
+intake + SHA-256 inventory
+    ↓
+validated Requirement → Criterion mapping
+    ↓
+immutable Digital Twin revision
+    ↓
+requirement-driven nominal / boundary / fault cases
+    ↓
+qualified exact-Twin simulation when supported
+    ↓
+measured evidence
+    ↓
+PASS / FAIL / NOT_TESTED
+    ↓
+regression + FAT report + Evidence Viewer
+```
+
+> **AI proposes. Deterministic engines validate, compile, verify, measure, and gate promotion. OEM robot controllers, PLCs, safety PLCs, and certified safety systems remain authoritative.**
+
+## Quick start
+
+Python 3.11+ is required.
+
+```bash
+python -m pip install --upgrade devagent-physical-engine==1.7.2
+```
+
+Verify the installed package:
+
+```bash
+python -c "import devagent_physical_engine as d; print(d.__version__)"
+```
+
+Expected:
+
+```text
+1.7.2
+```
+
+Run the normal customer workflow:
+
+```bash
+devagent verify ./customer-project
+```
+
+Request simulation:
+
+```bash
+devagent verify ./customer-project --simulate
+```
+
+Open the Evidence Viewer and keep the engineering terminal active:
+
+```bash
+devagent verify ./customer-project --simulate --open
+```
+
+For machine-readable CI output:
+
+```bash
+devagent verify ./customer-project --json
+```
+
+Default locations:
+
+```text
+Evidence database: ~/.devagent/projects.db
+Results:           <customer-project>/devagent-results/
+```
+
+## What DevAgent proves
+
+DevAgent separates planning, execution, measurement, verdicts, and authority.
+
+```text
+requirement
+  ↓
+verification criterion
+  ↓
+verification case
+  ↓
+exact Twin revision/hash
+  ↓
+qualified simulation when available
+  ↓
+measured evidence
+  ↓
+PASS / FAIL / NOT_TESTED
+```
+
+A generated plan is not physical proof. A replay is not a new execution. A simulation result does not grant site qualification or real-robot authority.
+
+Current hard boundaries remain:
+
+```text
+site_qualification = false
+real_execution_allowed = false
+```
+
+unless separately proven by an appropriate qualified process.
+
+## v1.6 report-test visual execution foundation
+
+v1.6 connected report tests to the exact stored Twin instead of a separate demo scene.
+
+A supported physical report test follows:
+
+```text
+Requirement
+  → stable Test ID
+  → immutable Requirement → Case mapping
+  → exact Verification Plan ID/hash
+  → exact Case ID
+  → exact Twin revision/hash
+  → qualified Gazebo/MoveIt execution
+  → typed physical_measurement artifact
+  → deterministic verdict
+```
+
+Interactive example:
+
+```text
+devagent> tests
+devagent> simulate TEST-PERF-001
+```
+
+Measured physical criteria include:
+
+```text
+cycle_time_max_s
+minimum_clearance_m
+final_tcp_error_max_m
+max_tracking_error_rad
+collision_free
+physical_completed
+```
+
+Structural/Twin criteria include:
+
+```text
+planning_allowed
+physics_allowed
+entity_present
+validation_issue_absent
+twin_state
+```
+
+A requirement without deterministic evidence remains `NOT_TESTED`; it is never auto-passed from prose or AI interpretation.
+
+## v1.6.1 support-contact lift hotfix
+
+The packaged UR5e reference load starts with the workpiece resting on its source support. During attached-object lift departure, DevAgent preserves the complete live MoveIt Allowed Collision Matrix and temporarily enables exactly the attached-workpiece ↔ source-support pair.
+
+That allowance is scoped only to lift departure. Transfer/place keep normal collision checking. DevAgent does not globally disable collision checking or replace the live matrix with an unsafe sparse matrix.
+
+## v1.6.2 slower measured visual execution
+
+The packaged visual task uses conservative MoveIt scaling so motion is inspectable while remaining real trajectory execution:
+
+```text
+velocity scale:      12%
+acceleration scale:   8%
+```
+
+The joint-state recorder also rejects duplicate/backward ROS timestamps instead of manufacturing synthetic time. Collision, endpoint, tracking, Twin-lineage, and authority checks remain fail-closed.
+
+## v1.7 industrial PTP/LIN execution
+
+v1.7 moves the qualified UR5e report test to the MoveIt Pilz Industrial Motion Planner rather than hand-building interpolation.
+
+The bounded task sequence is:
+
+```text
+HOME
+  ↓ PTP
+PRE_PICK
+  ↓ LIN
+PICK
+  ↓ grasp hard boundary
+LIFT
+  ↓ LIN support departure hard boundary
+TRANSFER
+  ↓ PTP
+PLACE
+  ↓ LIN release hard boundary
+RETRACT
+  ↓ LIN
+HOME
+  ↓ PTP
+```
+
+Execution groups:
+
+```text
+approach_pick    PTP → LIN
+lift_departure   LIN
+transfer_place   PTP → LIN
+retreat_home     LIN → PTP
+```
+
+Conservative limits:
+
+```text
+PTP velocity scale:       10%
+PTP acceleration scale:    6%
+LIN velocity scale:        6%
+LIN acceleration scale:    4%
+requested blend radius:   12 mm
+workpiece follow target:   60 Hz
+```
+
+MoveIt/Pilz owns geometry, timestamps, collision checking, velocity/acceleration time parameterization, and the returned `RobotTrajectory`. DevAgent does not fake smoothness with teleports or sleeps.
+
+## v1.7.1 adaptive Pilz blend hotfix
+
+A real ROS 2 Jazzy + Gazebo Harmonic + MoveIt/Pilz target-stack run showed:
+
+```text
+approach_pick    PASS
+lift_departure   PASS
+transfer_place   Pilz FAILURE(99999)
+execution        NOT STARTED
+```
+
+Pilz can reject a sequence when a requested blend sphere is not feasible for that specific geometry. v1.7.1 therefore keeps the same PTP/LIN targets, attached/world scene contract, collision policy, velocity/acceleration limits, and execution authority while retrying only the internal blend radius:
+
+```text
+12 mm
+  ↓ if Pilz returns pilz_sequence_planning_failed
+6 mm
+  ↓
+3 mm
+  ↓
+0 mm
+```
+
+Every candidate is still planned and collision-checked by MoveIt/Pilz. DevAgent selects the largest candidate Pilz actually accepts. If the zero-blend candidate fails, execution remains blocked.
+
+The fallback is intentionally narrow:
+
+```text
+no target modification
+no planner-type substitution
+no collision disable
+no speed increase
+no hand-built interpolation
+no fake PASS
+no fallback to an unqualified simulator or robot
+```
+
+The selected blend radii and every planning attempt receipt remain attached to motion metadata for auditability.
+
+## v1.7.2 transfer/place diagnostic hotfix
+
+A target-stack qualification run proved that `transfer_place` still returned Pilz `FAILURE(99999)` for every v1.7.1 blend candidate, including zero blend. v1.7.2 therefore does not keep guessing at blend values. When that exact bounded failure occurs, DevAgent remains fail-closed and runs two independent **plan-only** probes against the same attached-workpiece PlanningScene:
+
+```text
+lift target
+   ↓
+transfer PTP probe
+   ↓ independent start at transfer target
+place LIN probe
+```
+
+The result is classified deterministically as one of:
+
+```text
+pilz_transfer_segment_planning_failed
+pilz_place_segment_planning_failed
+pilz_transfer_and_place_segment_planning_failed
+pilz_transfer_place_sequence_composition_failed
+```
+
+Each probe writes its own request/receipt plus a `transfer-place-diagnostic.json` summary. These probes never execute motion and never relax targets, planner types, collision policy, attached-workpiece scene state, velocity/acceleration limits, Twin lineage, or real-execution authority. Their purpose is to identify the exact target-stack defect before changing physical execution semantics.
+
+## Qualified visual-execution scope
+
+The packaged visual executor remains intentionally narrow:
+
+```text
+robot:       UR5e
+operation:   load
+case scope:  one nominal mapped physical report case
+runtime:     Ubuntu 24.04 + ROS 2 Jazzy + Gazebo Harmonic + MoveIt/Pilz
+```
+
+Unsupported customer Twins, unqualified robot profiles, boundary/fault cases outside the qualified scope, ambiguous case mappings, or incomplete lineage fail closed.
+
+Cross-vendor projects such as ABB may still be imported, normalized, structurally evaluated, and reported, but they do not silently enter the UR5e-only physical executor.
+
+## Interactive engineering session
+
+Use `--interactive`, or `--open` from a real terminal, to keep a bounded prompt:
+
+```text
+status
+tests
+test SELECTOR
+simulate [SELECTOR]
+rerun [SELECTOR]
+rerun failed
+rerun blocked
+rerun affected
+replay
+report
+log
+help
+quit
+```
+
+Selectors can be requirement IDs, test IDs, or bounded groups:
+
+```text
+REQ-PERF-001
+TEST-PERF-001
+failed
+blocked
+affected
+all
+```
+
+`test SELECTOR` evaluates deterministic/evidence checks without commanding the simulator.
+
+`simulate TEST-X` requests qualified execution of the selected mapped physical report case.
+
+`replay` reconstructs persisted evidence identity; it never commands Gazebo, MoveIt, a robot, PLC, or safety PLC.
+
+## 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.
+
+The root `expected/` folder is test-oracle material and is never promoted as engineering authority.
+
+If critical information is missing or ambiguous, DevAgent writes questions into the project results instead of guessing.
+
+## 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 debug/progress trace and does not replace immutable evidence artifacts.
+
+Repeat runs compare the immediately previous campaign with the current campaign before a new FAT artifact is finalized.
+
+## 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
+Universal Robots ROS 2 driver
+ur_simulation_gz
+MoveIt 2 + Pilz Industrial Motion Planner
+```
+
+Preview setup:
+
+```bash
+devagent-physical setup --profile ur5e-sim --dry-run
+```
+
+Apply explicitly:
+
+```bash
+devagent-physical setup --profile ur5e-sim --yes
+```
+
+Check runtime:
+
+```bash
+devagent-physical ros doctor
+```
+
+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 customer verification + interactive report testing
+devagent-commercial  commercial/evidence 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
+
+**v1.7.2 — Production/Stable software workflow**
+
+v1.7.2 retains the v1.7 industrial Pilz PTP/LIN execution architecture and v1.7.1 bounded adaptive-blend fallback. If transfer/place still fails at zero blend, v1.7.2 now proves the transfer PTP and place LIN segments independently and records a deterministic diagnostic result while keeping execution blocked. It also retains the cross-vendor profile gate so non-UR5e customer Twins cannot enter the UR5e-only qualified visual executor.
+
+Production-oriented software capabilities include:
+
+```text
+one-command customer intake
+XLSX requirement normalization
+validated Requirement → Criterion mapping
+optional provider-backed advisory criterion proposals
+requirement-driven nominal / boundary / fault case generation
+immutable project/Twin lineage
+exact Requirement → Mapping → Verification Plan → Case provenance
+qualified report-test visual execution contract
+industrial Pilz PTP / LIN planning
+adaptive bounded blend selection
+plan-only transfer/place segment diagnostics
+lift-only support-contact ACM lease + exact restore
+Gazebo/MoveIt selected-case visualization
+typed physical measurement binding
+deterministic campaigns
+repeat-run regression
+professional FAT / Evidence Viewer
+interactive selective verification
+Evidence Bundle + replay
+change impact + regression
+provider-neutral optional AI front end
+```
+
+Production/Stable describes the bounded software workflow. It does not claim arbitrary customer cells are physically qualified, site-qualified, functionally safe, or authorized for autonomous real execution.
+
+## Documentation
+
+One-command verification:
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ONE_COMMAND_VERIFY_V13.md
+
+Report-test visual execution foundation:
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/REPORT_TEST_VISUAL_EXECUTION_V16.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.