devagent-physical-engine 1.3.0__tar.gz → 1.4.0__tar.gz

devagent_physical_engine-1.4.0/PKG-INFO

@@ -0,0 +1,798 @@
+Metadata-Version: 2.4
+Name: devagent-physical-engine
+Version: 1.4.0
+Summary: Production-grade verification-first robotics evidence runtime with one-command customer intake, selective verification execution, 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,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 an ordinary customer engineering folder into a bounded verification workflow with immutable Twin lineage, deterministic requirement verdicts, measured evidence, replay inspection, FAT reporting, and selective retesting.
+
+```text
+customer files
+    ↓
+intake + SHA-256 inventory
+    ↓
+requirements + explicit engineering facts
+    ↓
+immutable Digital Twin revision
+    ↓
+deterministic verification plan
+    ↓
+measured evidence when a qualified execution path exists
+    ↓
+PASS / FAIL / NOT_TESTED
+    ↓
+FAT report + Evidence Viewer
+    ↓
+selective retest / replay / regression
+```
+
+> **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.4.0
+```
+
+Verify the package:
+
+```bash
+python -c "import devagent_physical_engine as d; print(d.__version__)"
+```
+
+Expected:
+
+```text
+1.4.0
+```
+
+Run the normal customer workflow:
+
+```bash
+devagent verify ./customer-project
+```
+
+Request simulation when the exact imported-Twin execution path is qualified:
+
+```bash
+devagent verify ./customer-project --simulate
+```
+
+Open the Evidence Viewer and keep a human engineering terminal session:
+
+```bash
+devagent verify ./customer-project --simulate --open
+```
+
+For machine-readable CI output:
+
+```bash
+devagent verify ./customer-project --json
+```
+
+Simple Mode automatically handles project identity, customer-file inventory, supported XLSX requirement normalization, bounded Twin normalization, deterministic campaign generation, FAT generation, and evidence rendering. The user does not need to manually manage artifact IDs for the normal workflow.
+
+Default locations:
+
+```text
+Evidence database: ~/.devagent/projects.db
+Results:           <customer-project>/devagent-results/
+```
+
+---
+
+# Customer input
+
+A customer folder can contain the engineering material the team already has:
+
+```text
+ACME_CNC_CELL_TEST/
+├── project.yaml
+├── requirements.xlsx
+├── ur5e.urdf
+├── robot.urdf.xacro
+├── ur5e_robotiq.srdf
+├── tcp.yaml
+├── calibration.yaml
+├── layout/
+│   ├── cell_layout.yaml
+│   └── meshes/
+├── robot_program/
+│   └── mission.yaml
+├── safety_requirements.pdf
+└── 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. PDF documents can be inventoried for review, but arbitrary PDF prose is not silently converted into deterministic PASS evidence.
+
+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.
+
+---
+
+# What the terminal shows
+
+Human Simple Mode keeps the terminal as the primary progress surface:
+
+```text
+[DevAgent +   0.00s] START         RUNNING    source=ACME_CNC_CELL_TEST
+[DevAgent +   0.00s] INTAKE        RUNNING    scanning and classifying customer engineering files
+[DevAgent +   0.42s] REQUIREMENTS  READY      customer requirements normalized
+[DevAgent +   0.61s] TWIN          NORMALIZED customer Twin draft normalized
+[DevAgent +   0.85s] PROJECT       READY      project_id=acme-cell
+[DevAgent +   0.91s] PLAN          READY      artifact=...
+[DevAgent +   1.02s] SIMULATION    BLOCKED    imported_customer_twin_execution_adapter_not_yet_qualified
+[DevAgent +   1.11s] CAMPAIGN      COMPLETE   artifact=...
+[DevAgent +   1.18s] FAT           COMPLETE   artifact=...
+[DevAgent +   1.24s] EVIDENCE      COMPLETE   bundle=...
+[DevAgent +   1.25s] COMPLETE      DONE       state=verification_incomplete release_ready=False real_execution_allowed=False
+[DevAgent +   1.25s] REPORT        OPENING    new tab requested; terminal remains active
+```
+
+Progress is also persisted to:
+
+```text
+<customer-project>/devagent-results/RUN.log
+```
+
+If the browser chooses to take focus, the DevAgent process still remains alive in the terminal. Return to the terminal and continue with the interactive session.
+
+Use `--no-progress` to suppress human progress. `--json` remains machine-clean and never enters the interactive prompt.
+
+---
+
+# Interactive engineering session
+
+With `--open` in a real TTY, or with explicit `--interactive`, DevAgent keeps a bounded engineering prompt after the full verification run:
+
+```text
+Interactive engineering session
+Type 'help' for commands.
+
+devagent>
+```
+
+Useful commands:
+
+```text
+status
+ tests
+ test SELECTOR
+ simulate [SELECTOR]
+ rerun [SELECTOR]
+ rerun failed
+ rerun blocked
+ rerun affected
+ replay
+ report
+ log
+ help
+ quit
+```
+
+Examples:
+
+```text
+devagent> tests
+devagent> test REQ-CAL-001
+devagent> test TEST-CAL-001
+devagent> simulate REQ-FUN-001
+devagent> rerun failed
+devagent> rerun blocked
+devagent> rerun affected
+```
+
+Use `--no-interactive` when `--open` should open the report but the CLI should exit afterward.
+
+---
+
+# v1.4 selective verification
+
+Selective verification reduces unnecessary FAT/retest work without changing the authority model.
+
+## Stable Requirement → Test identity
+
+DevAgent derives a stable deterministic test identity from a requirement identity:
+
+```text
+REQ-FUN-001 → TEST-FUN-001
+REQ-CAL-001 → TEST-CAL-001
+```
+
+The mapping identifies the verification criterion. It does **not** by itself authorize a physical simulation case.
+
+## `test SELECTOR`
+
+Example:
+
+```text
+devagent> test REQ-CAL-001
+```
+
+or:
+
+```text
+devagent> test TEST-CAL-001
+```
+
+`test` re-evaluates only the selected requirement/test scope using the exact Twin and currently available immutable evidence. It does not launch a robot or simulator.
+
+The result is recorded separately as:
+
+```text
+selective_verification_run
+```
+
+A selective artifact includes:
+
+```text
+requested selector
+selector kind
+parent campaign ID/hash
+Twin revision/hash
+resolved requirement IDs
+resolved test IDs
+verification contracts
+dependencies
+measurement/evidence references
+verdicts
+```
+
+Every selective run explicitly preserves:
+
+```text
+full_campaign_executed = false
+release_ready = false
+real_execution_allowed = false
+```
+
+A selective PASS is therefore not silently promoted into a full FAT PASS.
+
+## `simulate SELECTOR`
+
+Example:
+
+```text
+devagent> simulate REQ-CAL-001
+```
+
+Selective physical execution is stricter than deterministic `test`.
+
+The required chain is:
+
+```text
+Requirement
+    ↓
+stable Test contract
+    ↓
+explicit verification-test mapping
+    ↓
+exact physical case ID(s)
+    ↓
+qualified selective execution adapter
+    ↓
+measured simulation artifact
+    ↓
+selective verdict
+```
+
+DevAgent never guesses a physical case from requirement prose. Requirement/Test → physical case mapping must be explicit engineering provenance.
+
+If no mapping exists:
+
+```text
+state  = blocked
+reason = requirement_has_no_qualified_physical_test_mapping
+execution_performed = false
+```
+
+If the mapping exists but the selective executor is not qualified:
+
+```text
+state  = blocked
+reason = selective_execution_adapter_not_qualified
+execution_performed = false
+```
+
+Current v1.4 qualification intentionally supports one explicitly mapped physical case per selective execution. Multiple mapped cases remain fail-closed until aggregation semantics are separately qualified:
+
+```text
+selective_multi_case_aggregation_not_yet_qualified
+```
+
+## Explicit physical test mapping
+
+Expert integrations can use the public API:
+
+```python
+from devagent_physical_engine import VerificationTestMappingRecorder
+
+mapping = VerificationTestMappingRecorder(repository).record(
+    project_id="acme-cell",
+    revision_id="twin-r0001",
+    verification_plan_artifact_id="art-plan",
+    bindings={
+        "REQ-CAL-001": ["case-0001"],
+    },
+    source_ref="engineering-map.yaml",
+)
+```
+
+The recorder validates that the requirement is a physical requirement, the plan belongs to the exact Twin revision, and every case ID exists in that immutable verification plan.
+
+The mapping itself has:
+
+```text
+execution_authority = false
+physical_qualification = false
+site_qualification = false
+real_execution_allowed = false
+```
+
+## Selectors
+
+Supported selectors are:
+
+```text
+REQ-...       one requirement
+TEST-...      one deterministic test identity
+failed        requirements that failed the parent campaign
+blocked       NOT_TESTED requirements plus currently blocked selective scope
+affected      requirements selected by latest exact-Twin change-impact evidence
+all           all requirements in the parent campaign
+```
+
+For example:
+
+```text
+devagent> rerun failed
+```
+
+re-evaluates only the requirements that failed instead of rerunning the entire campaign.
+
+```text
+devagent> rerun affected
+```
+
+uses change-impact evidence to retest only affected requirements.
+
+A selector is resolved deterministically. Unknown selectors fail closed.
+
+---
+
+# Full simulation vs selective simulation vs replay
+
+These operations are intentionally different:
+
+| Command | Meaning |
+| --- | --- |
+| `simulate` | rerun the full one-command verification with simulation requested |
+| `simulate REQ-X` | request only the explicitly mapped physical selective test |
+| `test REQ-X` | re-evaluate one requirement/test using existing immutable evidence; no simulation |
+| `replay` | reconstruct/verify persisted case identity; no new simulation |
+| `rerun failed` | retest failed requirement subset |
+| `rerun affected` | retest change-impact-selected requirement subset |
+
+Replay never commands Gazebo, MoveIt, a robot, PLC, or safety PLC.
+
+Selective verification never upgrades real-execution authority.
+
+---
+
+# Results directory
+
+A normal project can produce:
+
+```text
+customer-project/
+└── devagent-results/
+    ├── RUN.log
+    ├── SUMMARY.json
+    ├── INTAKE.json
+    ├── QUESTIONS.md
+    ├── normalized/
+    │   ├── requirements.csv
+    │   └── devagent-twin.yaml
+    ├── FAT_REPORT.html
+    └── EVIDENCE.html
+```
+
+`EVIDENCE.html` is a read-only professional evidence viewer. It shows requirement verdicts, observed/expected values, blockers, artifact IDs/hashes, and Twin revision hashes. The viewer can be refreshed after selective runs so the new immutable selective artifacts are inspectable.
+
+`RUN.log` is the human progress/debug trace. It does not replace immutable engineering evidence.
+
+---
+
+# Requirement verdict model
+
+Supported deterministic structural/Twin checks include:
+
+```text
+planning_allowed
+physics_allowed
+entity_present
+validation_issue_absent
+twin_state
+```
+
+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
+```
+
+Verdicts remain bounded:
+
+```text
+PASS
+FAIL
+NOT_TESTED
+```
+
+A requirement requiring measured physical evidence cannot PASS from prose, a CAD filename, a generated plan, or AI interpretation.
+
+Example:
+
+```text
+Requirement: cycle time <= 8.0 s
+Measurement available: no
+Verdict: NOT_TESTED
+```
+
+With exact-Twin measured evidence:
+
+```text
+Requirement: cycle time <= 8.0 s
+Observed: 7.42 s
+Threshold: 8.0 s
+Verdict: PASS
+Evidence: exact measurement artifact + Twin revision/hash
+```
+
+---
+
+# 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 |
+
+Selective results are represented by immutable artifacts inside the interactive session; they do not rewrite the full-run exit contract.
+
+---
+
+# Expert Mode
+
+Installed CLIs:
+
+```text
+devagent             one-command customer verification + interactive selective retesting
+devagent-commercial  expert commercial/evidence workflow
+devagent-physical    deterministic core + ROS/qualification tools
+devagent-physical-ai optional provider-backed engineering front end
+```
+
+Typical Expert Mode flow:
+
+```text
+project identity
+    ↓
+customer Twin import
+    ↓
+requirements
+    ↓
+verification plan
+    ↓
+measured evidence
+    ↓
+commercial campaign
+    ↓
+FAT report
+    ↓
+Evidence Bundle
+    ↓
+replay / change impact / regression
+```
+
+Example commands:
+
+```bash
+devagent-commercial init warehouse-cnc-04 \
+  --name "Warehouse CNC Loading Cell 04" \
+  --site atl-01 \
+  --workcell cnc-04
+
+devagent-commercial import-twin warehouse-cnc-04 ./customer-cell
+
+devagent-commercial requirements warehouse-cnc-04 \
+  examples/commercial/requirements-production.csv
+
+devagent-commercial verification-plan warehouse-cnc-04 \
+  examples/commercial/verification-plan.yaml \
+  --revision twin-r0001
+
+devagent-commercial record-measurement warehouse-cnc-04 \
+  physical-measurement.json \
+  --revision twin-r0001
+
+devagent-commercial campaign warehouse-cnc-04 \
+  examples/commercial/requirements-production.csv \
+  --revision twin-r0001 \
+  --measurement ARTIFACT_ID
+
+devagent-commercial fat-report warehouse-cnc-04 \
+  CAMPAIGN_ARTIFACT \
+  --output FAT_REPORT.html
+
+devagent-commercial evidence-bundle warehouse-cnc-04 CAMPAIGN_ARTIFACT
+
+devagent-commercial evidence-graph warehouse-cnc-04 > evidence-graph.json
+
+devagent-commercial evidence-viewer warehouse-cnc-04 \
+  --output DEVAGENT_EVIDENCE.html
+
+devagent-commercial replay warehouse-cnc-04 EVIDENCE_BUNDLE \
+  --qualification-root ~/.devagent/physical-qualification \
+  --output replay-manifest.json
+```
+
+Replay reconstruction reports `execution_performed=false` and never substitutes for a new simulation run.
+
+---
+
+# 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
+```
+
+Qualify trajectory runtime:
+
+```bash
+devagent-physical ros qualify-trajectory-runtime
+```
+
+Hosted Python CI does not prove a graphical Gazebo runtime, `move_group`, TF, controller actions, OEM drivers, or an arbitrary customer cell. Physical qualification must run on the exact 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:
+
+```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 engineering interpretation can propose intent and mappings. It cannot grant deterministic safety, physical qualification, site qualification, or real-execution authority.
+
+---
+
+# Evidence and 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 an engineer bound to a physical 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 boundary remains:
+
+```text
+site_qualification = false
+real_execution_allowed = false
+```
+
+Physical qualification is true only when separately qualified evidence explicitly establishes it.
+
+The operating principle remains:
+
+```text
+Agents propose.
+Deterministic engines compile and verify.
+Existing certified controllers execute.
+```
+
+---
+
+# Project status
+
+**v1.4.0 — Production/Stable software workflow**
+
+v1.4.0 adds selective verification execution while preserving the existing fail-closed authority model.
+
+Production-oriented software capabilities include:
+
+```text
+one-command customer intake
+XLSX requirement normalization
+immutable project/Twin lineage
+deterministic full campaigns
+measured evidence binding
+professional FAT/Evidence Viewer
+terminal progress + RUN.log
+interactive engineering session
+Requirement → Test selectors
+selective deterministic retest
+selective physical execution contract
+explicit Requirement/Test → Case mapping
+failed / blocked / affected retest selectors
+Evidence Bundle + replay
+change impact + regression
+provider-neutral optional AI front end
+```
+
+Quality gates include Python 3.11/3.12/3.13 regression, package clean-install, dependency audit, global branch coverage, One-Command coverage, **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, or safe for autonomous real execution.
+
+---
+
+# Documentation
+
+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
+
+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.