devagent-physical-engine 1.4.1__tar.gz → 1.6.0__tar.gz

devagent_physical_engine-1.6.0/PKG-INFO

@@ -0,0 +1,589 @@
+Metadata-Version: 2.4
+Name: devagent-physical-engine
+Version: 1.6.0
+Summary: Production-grade verification-first robotics evidence runtime with one-command customer intake, validated requirement mapping, report-test Gazebo visualization, 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,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
+    ↓
+selective retest / replay
+```
+
+> **AI proposes. Deterministic engines validate, compile, verify, measure, and gate promotion. OEM robot controllers, PLCs, safety PLCs, and certified safety systems remain authoritative.**
+
+DevAgent is designed to answer: **What can be proven about this cell, what failed, what remains unknown, what changed, and what evidence supports the conclusion?**
+
+---
+
+## Quick start
+
+Python 3.11+ is required.
+
+```bash
+python -m pip install --upgrade devagent-physical-engine==1.6.0
+```
+
+Verify the installed package:
+
+```bash
+python -c "import devagent_physical_engine as d; print(d.__version__)"
+```
+
+Expected:
+
+```text
+1.6.0
+```
+
+Run the normal customer workflow:
+
+```bash
+devagent verify ./customer-project
+```
+
+Request simulation:
+
+```bash
+devagent verify ./customer-project --simulate
+```
+
+Open the Evidence Viewer and retain an interactive engineering session:
+
+```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/
+```
+
+---
+
+# v1.6 report-test visual execution
+
+v1.6 closes the gap between report test cases and the previously separate ROS/Gazebo reference visualization path.
+
+A physical report test can now follow this bounded chain:
+
+```text
+Requirement
+    ↓
+stable Test identity
+    ↓
+immutable Requirement → Case mapping
+    ↓
+exact Verification Plan ID/hash
+    ↓
+exact Case ID
+    ↓
+exact Twin revision/hash
+    ↓
+qualified report execution profile
+    ↓
+Gazebo + MoveIt visible execution
+    ↓
+typed physical_measurement artifact
+    ↓
+deterministic PASS / FAIL / NOT_TESTED
+    ↓
+refreshed Evidence Viewer
+```
+
+Interactive example:
+
+```text
+devagent> tests
+REQ-PERF-001         TEST-PERF-001        NOT_TESTED  case-0001
+
+devagent> simulate TEST-PERF-001
+```
+
+For a supported qualified case, DevAgent materializes the **exact immutable report Twin** in the visual runtime. It does not run a separate demo Twin and relabel that result as customer evidence.
+
+The execution runtime binds measured metrics such as:
+
+```text
+cycle_time_s
+minimum_clearance_m
+final_tcp_error_m
+max_tracking_error_rad
+collision_free
+completed
+sample_count
+```
+
+The resulting `physical_measurement` remains scoped to the exact Twin revision/hash and case lineage that produced it.
+
+## Qualified scope
+
+The initial packaged visual-execution qualification is intentionally narrow:
+
+```text
+robot:       UR5e
+operation:   load
+profile:     packaged qualified report-execution profile
+case scope:  one nominal mapped physical case
+runtime:     ROS 2 Jazzy + Gazebo Harmonic + MoveIt 2
+```
+
+Unsupported customer Twins, boundary/fault cases, multiple mapped cases, incomplete mappings, ambiguous case IDs, mismatched verification plans, or unqualified execution profiles fail closed.
+
+DevAgent never substitutes:
+
+```text
+devagent-physical ros demo
+```
+
+for report evidence.
+
+## Exact lineage hardening
+
+A case ID such as `case-0001` is local to its verification plan. v1.6 therefore requires the complete lineage:
+
+```text
+Requirement
+ → mapping artifact
+ → exact Verification Plan ID/hash
+ → exact Case ID
+ → exact Twin revision/hash
+ → execution
+ → measurement
+```
+
+If another plan reuses the same case ID, or the mapping references a different plan, report execution is blocked instead of guessing.
+
+Full `--simulate` also fails closed if any physical requirement lacks an exact case mapping, or if the union of mapped physical cases is outside the currently qualified single-case scope.
+
+---
+
+# Requirement intelligence and test generation
+
+DevAgent maps supported requirement language into deterministic criteria only when the mapping can be validated. Supported measured physical checks include:
+
+```text
+cycle_time_max_s
+minimum_clearance_m
+final_tcp_error_max_m
+max_tracking_error_rad
+collision_free
+physical_completed
+```
+
+Supported structural/Twin checks include:
+
+```text
+planning_allowed
+physics_allowed
+entity_present
+validation_issue_absent
+twin_state
+```
+
+Provider-backed OpenAI, Anthropic, or Gemini proposals are advisory. They cannot create physical truth, site qualification, or real-execution authority.
+
+Requirement-driven case generation can derive bounded variations and fault cases from explicit engineering requirements, including payload ranges, TCP offset boundaries, missing-workpiece faults, and grasp-verification failures.
+
+A requirement with no deterministic criterion or required measurement remains:
+
+```text
+NOT_TESTED
+```
+
+It is never auto-passed from prose, CAD filenames, generated plans, or AI interpretation.
+
+---
+
+# Interactive engineering session
+
+With `--open` in a real TTY, or with explicit `--interactive`, DevAgent keeps a bounded engineering 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` re-evaluates existing immutable evidence and does not command a simulator.
+
+`simulate TEST-X` requests qualified execution of the selected mapped physical report case.
+
+`replay` reconstructs and verifies persisted identity only; it never commands Gazebo, MoveIt, a robot, PLC, or safety PLC.
+
+Selective runs never silently promote full FAT readiness.
+
+---
+
+# 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
+├── ur5e.urdf
+├── robot.urdf.xacro
+├── ur5e_robotiq.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 it does not treat a filename as proof of pose, TCP, calibration, 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 creates:
+
+```text
+<customer-project>/devagent-results/QUESTIONS.md
+```
+
+Update the original customer engineering information and rerun the same command.
+
+---
+
+# Results and evidence
+
+A normal project can produce:
+
+```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. It exposes requirement verdicts, observed/expected values, blockers, artifact IDs/hashes, Twin revision hashes, selective runs, and measurement lineage.
+
+`RUN.log` is the human progress/debug trace. It does not replace immutable engineering evidence.
+
+Repeat runs on the same project automatically compare the immediately previous campaign with the current campaign before the new FAT artifact is generated.
+
+---
+
+# Authority model
+
+DevAgent separates:
+
+```text
+requirement
+verification intent
+physical execution case
+measured evidence
+verdict
+authority/readiness
+```
+
+A plan proves that a test was planned. A mapping proves which case is bound to a requirement. A measurement proves only what was actually measured. A replay proves persisted identity can be reconstructed.
+
+None of those alone equals site commissioning or functional-safety certification.
+
+Current hard boundaries remain:
+
+```text
+physical_qualification = false unless separately proven
+site_qualification = false
+real_execution_allowed = false
+```
+
+The operating principle remains:
+
+```text
+Agents propose.
+Deterministic engines compile and verify.
+Qualified simulators measure bounded scopes.
+Existing certified controllers execute real equipment.
+```
+
+---
+
+# 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
+```
+
+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 Python CI validates software contracts and deterministic execution boundaries. It does not by itself prove a graphical Gazebo runtime, `move_group`, TF, controller actions, OEM drivers, or an arbitrary customer cell. Physical target-stack qualification must run on the intended workstation/adapter stack.
+
+---
+
+# Optional AI providers
+
+AI is optional and remains outside deterministic authority.
+
+```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 provider adapters:
+
+```bash
+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 can propose intent or criterion mappings. It cannot grant deterministic safety, physical qualification, site qualification, or real-execution authority.
+
+---
+
+# Installed CLIs
+
+```text
+devagent             one-command customer verification + interactive report testing
+devagent-commercial  expert 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` | full simulation was requested but the exact execution path is blocked/unqualified |
+| `32` | verification completed but full release readiness is false |
+
+---
+
+# Project status
+
+**v1.6.0 — Production/Stable software workflow**
+
+v1.6.0 adds exact-Twin report-test visual execution, immutable Requirement→Mapping→Verification Plan→Case lineage validation, qualified Gazebo/MoveIt execution for the packaged UR5e nominal report profile, typed simulation measurement binding, interactive report-case visualization, and fail-closed handling for unsupported or ambiguous execution scopes.
+
+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 → Case provenance
+qualified report-test visual execution contract
+Gazebo/MoveIt selected-case visualization
+typed physical measurement binding
+deterministic full campaigns
+repeat-run regression orchestration
+professional FAT/Evidence Viewer
+terminal progress + RUN.log
+interactive engineering session
+Requirement → Test selectors
+selective deterministic retest
+failed / blocked / affected selectors
+Evidence Bundle + replay
+change impact + regression
+provider-neutral optional AI front end
+```
+
+Quality gates include Python 3.11/3.12/3.13 regression, compilation, Ruff correctness checks, package build/clean-install, runtime dependency audit, global branch coverage, One-Command coverage, Commercial Intelligence coverage, report-test visual execution qualification tests, Selective Verification coverage, Production Authority coverage, and Evidence Trust/Replay coverage.
+
+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
+
+v1.6 report-test visual execution:
+
+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
+
+Commercial workflow:
+
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMERCIAL_V1.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.