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

devagent_physical_engine-1.3.0/PKG-INFO

@@ -0,0 +1,1181 @@
+Metadata-Version: 2.4
+Name: devagent-physical-engine
+Version: 1.3.0
+Summary: Production-grade verification-first robotics evidence runtime with one-command customer intake, 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,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, traceable verification workflow:
+
+```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 + replayable lineage
+```
+
+> **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 a practical commissioning question before engineers travel onsite:
+
+> **What can be proven about this cell, what failed, what is still unknown, what changed, and what evidence supports the conclusion?**
+
+---
+
+## Quick start
+
+Python 3.11+ is required.
+
+Install:
+
+```bash
+python -m pip install --upgrade devagent-physical-engine==1.3.0
+```
+
+Verify the installed version:
+
+```bash
+python -c "import devagent_physical_engine as d; print(d.__version__)"
+```
+
+Expected:
+
+```text
+1.3.0
+```
+
+Run DevAgent on the customer project folder:
+
+```bash
+devagent verify ./customer-project
+```
+
+That is the normal starting point.
+
+You do **not** need to manually initialize a DevAgent project, choose artifact IDs, convert an XLSX sheet to CSV, or understand the internal evidence database before using Simple Mode.
+
+If you also want physical simulation when an exact qualified execution path exists:
+
+```bash
+devagent verify ./customer-project --simulate
+```
+
+If you want DevAgent to open the generated Evidence Viewer:
+
+```bash
+devagent verify ./customer-project --simulate --open
+```
+
+For machine-readable output:
+
+```bash
+devagent verify ./customer-project --json
+```
+
+Use a dedicated evidence database and results directory when required:
+
+```bash
+devagent verify ./customer-project \
+  --db ./customer-projects.db \
+  --output ./verification-results \
+  --json
+```
+
+Default locations:
+
+```text
+Evidence database: ~/.devagent/projects.db
+Results:           <customer-project>/devagent-results/
+```
+
+---
+
+# How to use the engine
+
+## 1. Give DevAgent the engineering folder you already have
+
+A typical project may look like this:
+
+```text
+ACME_CNC_CELL_TEST/
+├── project.yaml
+├── requirements.xlsx
+├── ur5e.urdf
+├── tcp.yaml
+├── layout.yaml
+├── robot_program/
+│   └── mission.yaml
+├── drawings.step
+├── safety_requirements.pdf
+└── expected/
+    └── expected_findings.json
+```
+
+The filenames do not all have to match this example. DevAgent inventories the source tree, fingerprints files with SHA-256, assigns bounded roles, and normalizes supported structured evidence.
+
+Important rule:
+
+```text
+file discovered != engineering fact proven
+```
+
+A URDF, Xacro, STEP, STL, PDF, YAML, or JSON file does not automatically prove pose, TCP, calibration, collision geometry, physics, safety, or production readiness.
+
+### What DevAgent does during intake
+
+```text
+CUSTOMER FOLDER
+      |
+      v
+FILE INVENTORY + SHA-256
+      |
+      v
+ROLE CLASSIFICATION
+      |
+      +--> expected/ test data -> NEVER engineering authority
+      |
+      v
+REQUIREMENT NORMALIZATION
+      |
+      v
+EXPLICIT FACT EXTRACTION
+      |
+      v
+PROPOSED TWIN NORMALIZATION
+      |
+      v
+DETERMINISTIC TWIN VALIDATION
+      |
+      +--> missing or ambiguous facts -> QUESTIONS.md
+      |
+      v
+VERIFICATION PLAN / CAMPAIGN / FAT
+      |
+      v
+EVIDENCE VIEWER
+```
+
+Unknown facts remain unknown. DevAgent does not fill engineering gaps with guesses.
+
+---
+
+## 2. First-run example: incomplete customer information
+
+Assume the customer provides this `project.yaml`:
+
+```yaml
+project_id: acme-cell
+name: ACME Cell
+site_id: atl-01
+workcell_id: cell-01
+```
+
+and also provides robot/layout/TCP/requirements files, but does not say exactly what task the robot must perform.
+
+Run:
+
+```bash
+devagent verify ./ACME_CNC_CELL_TEST
+```
+
+DevAgent creates the project automatically and may return:
+
+```text
+State: needs_information
+```
+
+Typical questions may include:
+
+```text
+engineering_request_operation_missing
+engineering_request_object_id_missing
+engineering_request_source_missing
+engineering_request_destination_missing
+```
+
+The questions are also written to:
+
+```text
+ACME_CNC_CELL_TEST/devagent-results/QUESTIONS.md
+```
+
+This is expected fail-closed behavior. DevAgent will not invent the operation, workpiece, source, or destination simply to produce a green report.
+
+Typical first-run output:
+
+```text
+ACME_CNC_CELL_TEST/
+└── devagent-results/
+    ├── SUMMARY.json
+    ├── INTAKE.json
+    ├── QUESTIONS.md
+    └── normalized/
+        └── requirements.csv
+```
+
+Fix the source engineering information, then run the same command again.
+
+---
+
+## 3. Complete ACME example
+
+The following example uses the same input shape exercised by the v1.3 one-command acceptance tests.
+
+### `project.yaml`
+
+```yaml
+project_id: acme-cell
+name: ACME Cell
+site_id: atl-01
+workcell_id: cell-01
+
+robot_base_pose:
+  x: 0
+  y: 0
+  z: 0
+  roll: 0
+  pitch: 0
+  yaw: 0
+
+engineering_request:
+  robot: ur5e
+  operation: load
+  object_id: BOX_101
+  source: conveyor_a
+  destination: cnc_04
+  tool: gripper
+  payload_kg: 1.5
+```
+
+### `tcp.yaml`
+
+```yaml
+tcp:
+  x: 0
+  y: 0
+  z: 180
+  roll: 0
+  pitch: 0
+  yaw: 0
+```
+
+### `layout.yaml`
+
+```yaml
+entities:
+  - id: conveyor_a
+    type: conveyor
+    pose:
+      x: 700
+      y: 0
+      z: 850
+    geometry:
+      kind: box
+      dimensions: [2000, 600, 800]
+
+  - id: cnc_04
+    type: machine
+    pose:
+      x: 1200
+      y: 400
+      z: 0
+    geometry:
+      kind: box
+      dimensions: [1400, 1200, 1800]
+
+  - id: BOX_101
+    type: workpiece
+    pose:
+      x: 700
+      y: 0
+      z: 900
+    geometry:
+      kind: box
+      dimensions: [200, 100, 50]
+```
+
+### `ur5e.urdf`
+
+Use the customer's real robot model. A minimal test fixture can look like:
+
+```xml
+<robot name="ur5e"/>
+```
+
+Do not treat a placeholder URDF as production geometry evidence.
+
+### `requirements.xlsx`
+
+A conventional first worksheet can contain columns such as:
+
+| requirement_id | text | check | target | expected | severity |
+| --- | --- | --- | ---: | --- | --- |
+| REQ-101 | Cycle time <= 8 s | cycle_time_max_s | 8.0 | true | must |
+| REQ-102 | E-stop accessible |  |  | true | must |
+
+Simple Mode can normalize common requirement ID, text, check, threshold/target, expected-value, and severity/criticality column names without requiring OpenPyXL at runtime.
+
+If the spreadsheet columns are ambiguous, DevAgent asks for clarification rather than guessing which column is authoritative.
+
+Run:
+
+```bash
+devagent verify ./ACME_CNC_CELL_TEST
+```
+
+When enough explicit evidence exists to build the Twin and deterministic campaign, the results directory can expand to:
+
+```text
+ACME_CNC_CELL_TEST/
+└── devagent-results/
+    ├── SUMMARY.json
+    ├── INTAKE.json
+    ├── QUESTIONS.md
+    ├── normalized/
+    │   ├── requirements.csv
+    │   └── devagent-twin.yaml
+    ├── FAT_REPORT.html
+    └── EVIDENCE.html
+```
+
+`normalized/devagent-twin.yaml` is generated evidence mapping. It is not an independent source of truth and does not bypass Twin validation.
+
+---
+
+## 4. Request simulation
+
+Run:
+
+```bash
+devagent verify ./ACME_CNC_CELL_TEST --simulate
+```
+
+`--simulate` means:
+
+```text
+request measured physical simulation if the exact imported-Twin execution path is qualified
+```
+
+It does **not** mean:
+
+```text
+run any available demo and label it customer evidence
+```
+
+The current one-command safety boundary is:
+
+```text
+IMPORTED CUSTOMER TWIN
+        |
+        v
+EXACT QUALIFIED EXECUTION ADAPTER?
+        |
+   +----+----+
+   |         |
+  YES        NO
+   |         |
+execute     simulation_state=blocked
+measure     exit 31 when --simulate was requested
+record      no fake measurement
+```
+
+For example, the repository contains a UR5e reference simulation stack, but:
+
+```text
+reference UR5e demo != customer imported Twin evidence
+```
+
+If the exact imported-customer execution adapter is not qualified, DevAgent reports a bounded reason such as:
+
+```text
+imported_customer_twin_execution_adapter_not_yet_qualified
+```
+
+or:
+
+```text
+twin_not_ready_for_physics
+```
+
+That is intentional. A blocked simulation is more trustworthy than a visually impressive but unrelated demo.
+
+---
+
+## 5. Open the Evidence Viewer
+
+When evidence lineage can be rendered:
+
+```bash
+devagent verify ./ACME_CNC_CELL_TEST --open
+```
+
+or:
+
+```bash
+devagent verify ./ACME_CNC_CELL_TEST --simulate --open
+```
+
+The viewer is read-only and is intended to answer:
+
+- Which requirement was evaluated?
+- What was the verdict?
+- What value was observed?
+- What threshold or expected value was used?
+- Which Twin revision was evaluated?
+- Which evidence artifact supports the result?
+- Which SHA-256 hashes bind the evidence?
+- What is still blocked or not tested?
+
+The trust principle is simple:
+
+> **Do not trust a PASS label by itself. Inspect the evidence behind it.**
+
+---
+
+# Understanding the results
+
+## `SUMMARY.json`
+
+This is the primary machine-readable result of Simple Mode.
+
+Important fields include:
+
+```text
+project_id
+state
+twin_revision_id
+twin_state
+requirements_file
+verification_plan_artifact_id
+campaign_artifact_id
+fat_artifact_id
+evidence_bundle_artifact_id
+evidence_viewer
+simulation_requested
+simulation_state
+simulation_reason
+release_ready
+real_execution_allowed
+questions
+```
+
+A green software workflow never changes this hard safety boundary by itself:
+
+```text
+real_execution_allowed = false
+```
+
+## `INTAKE.json`
+
+Records the source-file inventory and SHA-256 fingerprints so the customer can see exactly what DevAgent inspected.
+
+Each discovered file is associated with a bounded role and authority decision.
+
+Examples:
+
+```text
+requirements.xlsx      -> requirements
+layout.yaml            -> engineering_data
+ur5e.urdf              -> robot_model
+safety_requirements.pdf -> manual engineering document
+expected/...           -> test_oracle, used_for_authority=false
+```
+
+## `QUESTIONS.md`
+
+Contains missing or ambiguous engineering facts that prevented deterministic promotion.
+
+Use it as an engineering punch list, update the original customer files, and rerun:
+
+```bash
+devagent verify ./ACME_CNC_CELL_TEST
+```
+
+## `FAT_REPORT.html`
+
+Customer-readable verification report generated when a campaign can be built.
+
+A missing metric or unsupported requirement is not silently changed to PASS. It remains `NOT_TESTED` or otherwise blocks readiness.
+
+## `EVIDENCE.html`
+
+Read-only evidence view of requirement/Twin/artifact lineage.
+
+---
+
+# Requirements and verdicts
+
+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
+```
+
+The verdict model is intentionally bounded:
+
+```text
+PASS
+FAIL
+NOT_TESTED
+```
+
+A requirement that needs measured physical evidence cannot PASS from prose, a CAD filename, or a generated verification plan.
+
+Example:
+
+```text
+Requirement: cycle time <= 8.0 s
+Measurement available: no
+Verdict: NOT_TESTED
+```
+
+When exact-Twin measured evidence exists:
+
+```text
+Requirement: cycle time <= 8.0 s
+Observed: 7.42 s
+Threshold: 8.0 s
+Verdict: PASS
+Evidence: exact measurement artifact + Twin revision/hash
+```
+
+---
+
+# XLSX, PDF, and expected-data policies
+
+## XLSX requirements
+
+Simple Mode supports conventional `requirements.xlsx` first-worksheet normalization.
+
+Common semantic columns include:
+
+```text
+requirement ID
+requirement text / description
+check / metric
+target / threshold
+expected value
+severity / criticality / priority
+```
+
+If multiple requirement sources are present and authority becomes ambiguous, DevAgent fails closed rather than silently merging them.
+
+## PDF documents
+
+PDFs are inventoried and fingerprinted for review.
+
+v1.3 does **not** silently OCR arbitrary safety PDFs and convert extracted prose into deterministic PASS evidence.
+
+A safety requirement without a supported deterministic check remains manual/`NOT_TESTED` until appropriate evidence exists.
+
+## `expected/` folders
+
+A root `expected/` folder is treated as test-fixture oracle data:
+
+```text
+expected/
+  -> inventoried
+  -> SHA-256 recorded
+  -> role = test_oracle
+  -> used_for_authority = false
+```
+
+This prevents a fixture from proving its own expected answer.
+
+---
+
+# Simple Mode exit codes
+
+| Exit | Meaning |
+| ---: | --- |
+| `0` | bounded verification is release-ready |
+| `10` | customer input or operational contract failure |
+| `30` | more engineering information is required |
+| `31` | simulation was requested but the exact execution path is blocked/unqualified |
+| `32` | verification completed but release readiness is still false |
+
+Non-zero engineering exits are intentional and machine-friendly.
+
+Example CI use:
+
+```bash
+devagent verify ./customer-project --json > devagent-result.json
+rc=$?
+
+case "$rc" in
+  0)  echo "bounded verification ready" ;;
+  30) echo "customer information required" ;;
+  31) echo "simulation path blocked" ;;
+  32) echo "verification complete but not release-ready" ;;
+  *)  echo "input or operational failure" ;;
+esac
+```
+
+---
+
+# When to use Simple Mode vs Expert Mode
+
+Use **Simple Mode** for the normal customer workflow:
+
+```bash
+devagent verify ./customer-project
+```
+
+Use **Expert Mode** when you need explicit control over:
+
+- project identity;
+- immutable Twin revisions;
+- explicit requirement artifacts;
+- measurement binding;
+- campaign artifact IDs;
+- regression baselines;
+- Evidence Bundle generation;
+- replay reconstruction;
+- external CI/orchestration;
+- qualification workflows.
+
+Installed CLIs:
+
+```text
+devagent             one-command customer verification
+devagent-commercial  expert commercial/evidence workflow
+devagent-physical    deterministic core + ROS/qualification tools
+devagent-physical-ai optional provider-backed engineering front end
+```
+
+---
+
+# Expert Mode example
+
+The default project/evidence database is:
+
+```text
+~/.devagent/projects.db
+```
+
+## 1. Create project identity
+
+```bash
+devagent-commercial init warehouse-cnc-04 \
+  --name "Warehouse CNC Loading Cell 04" \
+  --site atl-01 \
+  --workcell cnc-04
+```
+
+## 2. Import explicit customer Twin evidence
+
+```bash
+devagent-commercial import-twin warehouse-cnc-04 ./customer-cell \
+  | tee twin-import.json
+```
+
+List immutable revisions:
+
+```bash
+devagent-physical project \
+  --db ~/.devagent/projects.db \
+  revisions warehouse-cnc-04
+```
+
+Twin manifest example:
+
+https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/devagent-twin.yaml
+
+Do not use template values as customer evidence.
+
+## 3. Load requirements
+
+```bash
+devagent-commercial requirements warehouse-cnc-04 \
+  examples/commercial/requirements-production.csv
+```
+
+Example requirements file:
+
+https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/requirements-production.csv
+
+## 4. Generate verification plan
+
+```bash
+devagent-commercial verification-plan warehouse-cnc-04 \
+  examples/commercial/verification-plan.yaml \
+  --revision twin-r0001
+```
+
+Planning creates bounded test intent. It is not execution evidence.
+
+## 5. Record measured evidence
+
+```bash
+devagent-commercial record-measurement warehouse-cnc-04 \
+  physical-measurement.json \
+  --revision twin-r0001
+```
+
+Example schema:
+
+https://github.com/tomha85/devagent-physical-engine/blob/main/examples/commercial/physical-measurement.json
+
+Preferred integrations use the typed `PhysicalEvidenceRecorder.record_motion_metrics(...)` path so measurement, canonical motion, planner/source graph, qualification reference, and Twin hash remain bound together.
+
+## 6. Run deterministic campaign
+
+```bash
+devagent-commercial campaign warehouse-cnc-04 \
+  examples/commercial/requirements-production.csv \
+  --revision twin-r0001 \
+  --measurement ARTIFACT_ID
+```
+
+## 7. Generate FAT report
+
+```bash
+devagent-commercial fat-report warehouse-cnc-04 \
+  CAMPAIGN_ARTIFACT \
+  --output FAT_REPORT.html
+```
+
+## 8. Build Evidence Bundle
+
+```bash
+devagent-commercial evidence-bundle \
+  warehouse-cnc-04 \
+  CAMPAIGN_ARTIFACT
+```
+
+The bundle binds requirement results to exact artifact IDs, artifact hashes, Twin revision, and Twin hash.
+
+## 9. Inspect evidence graph
+
+```bash
+devagent-commercial evidence-graph warehouse-cnc-04 \
+  > evidence-graph.json
+```
+
+## 10. Generate static Evidence Viewer
+
+```bash
+devagent-commercial evidence-viewer warehouse-cnc-04 \
+  --output DEVAGENT_EVIDENCE.html
+```
+
+## 11. Replay persisted lineage
+
+```bash
+devagent-commercial replay \
+  warehouse-cnc-04 \
+  EVIDENCE_BUNDLE \
+  --qualification-root ~/.devagent/physical-qualification \
+  --output replay-manifest.json \
+  --record
+```
+
+Replay verifies persisted identity before reconstruction:
+
+```text
+artifact ID
+artifact type
+artifact SHA-256
+Twin revision/hash
+run_id
+case_id
+case evidence hash
+seed
+reset state
+parameters
+canonical motion fingerprint
+```
+
+A successful replay inspection reports:
+
+```text
+replayable = true
+execution_performed = false
+```
+
+Replay reconstruction does not command Gazebo, MoveIt, a robot, PLC, or safety PLC.
+
+## 12. Change impact
+
+After importing a new Twin revision:
+
+```bash
+devagent-commercial impact warehouse-cnc-04 \
+  twin-r0001 twin-r0002 \
+  examples/commercial/requirements-production.csv
+```
+
+## 13. Regression
+
+```bash
+devagent-commercial regression warehouse-cnc-04 \
+  BASELINE_CAMPAIGN CURRENT_CAMPAIGN \
+  --impact CHANGE_IMPACT_ARTIFACT
+```
+
+A previous PASS does not remain authoritative after a changed Twin unless the required evidence chain remains valid for the new revision.
+
+## 14. Project status
+
+```bash
+devagent-commercial status warehouse-cnc-04
+```
+
+Inspect artifacts:
+
+```bash
+devagent-commercial artifacts warehouse-cnc-04
+```
+
+Useful artifact types include:
+
+```text
+customer_twin_import
+one_command_twin_normalization
+requirement_set
+verification_plan
+physical_measurement
+physical_motion_plan
+runtime_measurement_binding
+commercial_campaign
+change_impact
+commercial_regression
+fat_report
+evidence_bundle
+replay_verification
+```
+
+---
+
+# 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 changes:
+
+```bash
+devagent-physical setup --profile ur5e-sim --dry-run
+```
+
+Apply explicitly:
+
+```bash
+devagent-physical setup --profile ur5e-sim --yes
+```
+
+Check runtime readiness:
+
+```bash
+devagent-physical ros doctor
+```
+
+Qualify trajectory runtime:
+
+```bash
+devagent-physical ros qualify-trajectory-runtime
+```
+
+Other reference commands:
+
+```bash
+devagent-physical ros launch --dry-run
+devagent-physical ros acceptance
+devagent-physical ros demo
+devagent-physical qualify
+```
+
+Hosted Python CI cannot prove a graphical Gazebo runtime, MoveIt `move_group`, TF, controller actions, OEM drivers, or an arbitrary imported workcell. Physical qualification must run on the exact workstation/adapter stack.
+
+---
+
+# Optional AI providers
+
+AI is optional and remains outside deterministic authority.
+
+Install one provider:
+
+```bash
+python -m pip install "devagent-physical-engine[openai]"
+```
+
+```bash
+python -m pip install "devagent-physical-engine[anthropic]"
+```
+
+```bash
+python -m pip install "devagent-physical-engine[gemini]"
+```
+
+Or all provider SDKs:
+
+```bash
+python -m pip install "devagent-physical-engine[ai]"
+```
+
+Typical credentials:
+
+```bash
+export OPENAI_API_KEY="..."
+export ANTHROPIC_API_KEY="..."
+export GEMINI_API_KEY="..."
+```
+
+Check provider setup without using the provider as physical authority:
+
+```bash
+devagent-physical-ai doctor --provider openai
+```
+
+Example natural-language 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 YOUR_MODEL
+```
+
+The model can help interpret and propose engineering intent. It cannot grant deterministic safety, physical qualification, site qualification, or real-execution authority.
+
+---
+
+# Evidence and authority model
+
+DevAgent deliberately separates four things that are often incorrectly mixed together:
+
+```text
+1. requirement
+2. test intent
+3. measured evidence
+4. authority/readiness
+```
+
+A verification plan proves only that a test was planned.
+
+A model-only result proves only the model-level property that was actually evaluated.
+
+A physical requirement requires physical measurement evidence.
+
+A replay reconstruction proves persisted evidence lineage can be reconstructed; it is not a new simulation run.
+
+A simulation PASS does not equal site commissioning.
+
+A complete customer FAT report does not equal functional-safety certification.
+
+Current hard boundary:
+
+```text
+physical_qualification = false unless separately qualified evidence says otherwise
+site_qualification = false
+real_execution_allowed = false
+```
+
+This architecture is intentional:
+
+```text
+Agents propose.
+Deterministic engines compile and verify.
+Existing certified controllers execute.
+```
+
+---
+
+# What DevAgent should be used for
+
+DevAgent is designed to help engineering teams:
+
+- reduce FAT preparation and verification effort;
+- discover missing engineering information before travel;
+- identify requirement failures before onsite commissioning;
+- create repeatable deterministic test plans;
+- bind physical measurements to exact Twin revisions;
+- detect regression after engineering changes;
+- preserve evidence provenance;
+- produce customer-readable FAT evidence;
+- reduce dependence on manual artifact bookkeeping;
+- make verification results inspectable rather than opaque.
+
+It is **not** a replacement for:
+
+- OEM robot controllers;
+- PLC logic authority;
+- safety PLCs;
+- certified safety functions;
+- site acceptance responsibility;
+- functional-safety engineering;
+- real-world commissioning judgment.
+
+---
+
+# Project status
+
+**v1.3.0 — Production/Stable software workflow**
+
+The bounded software/evidence workflow is production-oriented and continuously tested across Python 3.11, 3.12, and 3.13.
+
+The v1.3 release candidate includes:
+
+```text
+one-command customer intake
+XLSX requirement normalization
+immutable project/Twin lineage
+deterministic verification campaigns
+measured evidence binding
+FAT generation
+Evidence Bundle
+Evidence Viewer
+replay reconstruction
+change impact
+regression
+provider-neutral optional AI front end
+```
+
+Software quality gates include dedicated coverage thresholds for:
+
+```text
+One-Command customer workflow
+Production Authority
+Evidence Trust / Replay
+```
+
+Production/Stable describes the bounded software workflow. It does not claim arbitrary customer cells are physically or site qualified.
+
+---
+
+# 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
+
+Natural-language engineering:
+
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/NATURAL_LANGUAGE_ENGINEERING.md
+
+AI providers:
+
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/AI_PROVIDERS.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
+
+Optimization:
+
+https://github.com/tomha85/devagent-physical-engine/blob/main/docs/OPTIMIZATION.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 the complete ownership and usage terms.