devagent-physical-engine 2.3.1__tar.gz → 2.10.0__tar.gz

devagent_physical_engine-2.10.0/PKG-INFO

@@ -0,0 +1,568 @@
+Metadata-Version: 2.4
+Name: devagent-physical-engine
+Version: 2.10.0
+Summary: Verification-first multi-vendor commissioning control plane with flexible guided customer-file intake, deterministic source/evidence authority, exact-Twin lineage, regression, FAT reporting, and pre-site readiness.
+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
+Requires-Dist: uv<1,>=0.11
+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: numpy<3,>=1.26; 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 files into a bounded pre-site verification workflow: it discovers what is available, normalizes engineering inputs, maps requirements to deterministic checks, runs only qualified verification paths, records evidence, detects regression, and produces FAT/readiness artifacts.
+
+> **Safety boundary:** DevAgent does not turn simulation, AI output, or a generated report into site qualification, functional-safety certification, or permission for real robot motion. OEM controllers, PLCs, safety PLCs, qualified site processes, live interlocks, and measured physical evidence remain authoritative.
+
+## 30-second overview
+
+If you are new to DevAgent, remember this flow:
+
+```text
+customer engineering files
+        ↓
+devagent verify ./customer-project
+        ↓
+normalize source + Twin + requirements
+        ↓
+deterministic checks / qualified simulation when available
+        ↓
+measured evidence + PASS / FAIL / NOT_TESTED
+        ↓
+regression + FAT + pre-site readiness
+```
+
+The normal customer entry point is intentionally simple:
+
+```bash
+devagent verify ./customer-project
+```
+
+DevAgent is designed to fail closed. Missing information becomes a question, `NOT_TESTED`, or a blocked capability. It does not invent a PASS just to complete a workflow.
+
+## Two product front doors
+
+DevAgent v2.10.0 exposes two product identities on the same deterministic authority/evidence core:
+
+> **DevAgent Community — Connect AI to your robot.**
+>
+> **DevAgent Enterprise — Verify AI and automation before it reaches production.**
+
+Community users can inspect the AI-to-robot surface with:
+
+```bash
+devagent community --help
+```
+
+Enterprise/customer verification continues to start with `devagent verify ./customer-project`. Neither front door bypasses physical qualification, interlocks, exact identity, or operator approval.
+
+## Install in 2–5 minutes
+
+Python 3.11+ is required. A virtual environment is recommended:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install --upgrade devagent-physical-engine==2.10.0
+```
+
+Verify exactly what was installed:
+
+```bash
+python -c "import devagent_physical_engine as d; print(d.__version__)"
+devagent --help
+```
+
+Expected package version:
+
+```text
+2.10.0
+```
+
+The base install does **not** require ROS 2, Gazebo, MoveIt, CUDA, robot hardware, or an AI-provider API key.
+
+## First safe result in under 10 minutes
+
+Start with a no-motion runtime inspection:
+
+```bash
+devagent engine status
+```
+
+Then inspect discovered robot/adaptor authority:
+
+```bash
+devagent discover
+```
+
+These commands do not command a robot. They show the installed control plane and what is or is not currently qualified. Real execution remains disabled by default.
+
+For machine-readable inspection:
+
+```bash
+devagent engine status --json
+devagent discover --json
+```
+
+## Verify a customer project
+
+You do not need to convert a customer project into a special DevAgent repository first. Put the engineering material you already have into one folder:
+
+```text
+customer-project/
+├── requirements.xlsx
+├── PLC/
+├── Robot/
+├── cell.step
+├── FAT_results.xlsx
+├── calibration/
+├── drawings.pdf
+└── other customer engineering files
+```
+
+Run the normal workflow:
+
+```bash
+devagent verify ./customer-project
+```
+
+Request qualified simulation where the exact execution path exists:
+
+```bash
+devagent verify ./customer-project --simulate
+```
+
+Open the generated Evidence Viewer after verification:
+
+```bash
+devagent verify ./customer-project --simulate --open
+```
+
+For CI or automation:
+
+```bash
+devagent verify ./customer-project --json
+```
+
+Default locations:
+
+```text
+Evidence database: ~/.devagent/projects.db
+Results:           <customer-project>/devagent-results/
+```
+
+A first project does not need to be complete. Missing evidence remains `NOT_TESTED`, reduces scope, or produces explicit information requests. Generated `devagent-results/` files do not become customer-source authority on the next run.
+
+## What gets installed — and what does not
+
+| Layer | How it arrives | What it includes | Required for the first safe result? |
+| --- | --- | --- | --- |
+| **pip-installed** | `pip install devagent-physical-engine` | DevAgent Python package, base runtime dependencies, CLI entry points, deterministic control/evidence logic | **Yes** |
+| **optional AI extras** | `pip install "devagent-physical-engine[openai]"` etc. | Provider SDKs for advisory interpretation/planning | No |
+| **DevAgent-managed humanoid runtime** | `devagent robot setup unitree_g1_29dof --managed` | Exact qualified GR00T/SONIC runtime materialized in user storage and attested before authority | No |
+| **external system/runtime stack** | Installed by the engineer/OEM/platform owner | ROS 2, Gazebo, MoveIt, CUDA/runtime drivers, OEM robot drivers, firmware, privileged OS packages | No for base verification; yes for the corresponding simulation/physical capability |
+| **physical authority** | Never installed as a shortcut | Measured campaign evidence, exact identity, external admission, live interlocks, explicit approval | Never implicit |
+
+The base Python package currently declares only normal Python runtime dependencies. Physical simulation and robot execution intentionally remain separate from `pip install`.
+
+### Humanoid setup system prerequisites
+
+The DevAgent-managed Unitree G1 setup can manage the qualified user-space runtime, but it does not silently install privileged OS packages. Its setup doctor checks system tools such as:
+
+```text
+git
+git-lfs
+bash
+cmake
+cc
+make
+tmux
+```
+
+Preview setup without installing anything:
+
+```bash
+devagent robot setup unitree_g1_29dof --dry-run
+```
+
+Inspect an existing runtime without changing it:
+
+```bash
+devagent robot setup unitree_g1_29dof --doctor --json
+```
+
+## Safe progression from inspection to execution
+
+Use DevAgent in increasing levels of authority:
+
+```text
+1. inspect
+   devagent engine status / devagent discover
+
+2. verify customer engineering
+   devagent verify ./customer-project
+
+3. request qualified simulation
+   devagent verify ./customer-project --simulate
+
+4. review evidence / regression / FAT
+   devagent-results/
+
+5. physical execution
+   only through separately qualified adapters, measured evidence,
+   live interlocks, exact identity, and explicit operator approval
+```
+
+A simulation result never grants physical authority by itself.
+
+## 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 · exact-Twin verification.</sub></p>
+
+## 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 execution/evidence
+        ↓
+Evidence Graph
+        ↓
+PASS / FAIL / NOT_TESTED
+        ↓
+Change Impact + Regression
+        ↓
+FAT Report + Evidence Bundle
+        ↓
+Immutable pre-site commissioning decision
+```
+
+The bounded readiness decision is one of:
+
+```text
+READY_FOR_PRE_SITE_COMMISSIONING
+NOT_READY_FOR_PRE_SITE_COMMISSIONING
+```
+
+This means the declared pre-site engineering scope has complete, current evidence according to installed DevAgent authority contracts. It does **not** mean the real site is commissioned.
+
+## Evidence and generated outputs
+
+DevAgent records lineage for requirements, Twin revisions, verification plans, requirement-to-case mappings, findings, evidence, campaigns, regressions, FAT reports, and readiness decisions.
+
+A previous READY decision becomes stale when readiness-relevant state changes. Change impact and regression are therefore first-class rather than optional post-processing.
+
+Typical outputs:
+
+```text
+customer-project/
+└── devagent-results/
+    ├── RUN.log
+    ├── SOURCE_MANIFEST.json
+    ├── INTAKE_READINESS.json
+    ├── SUMMARY.json
+    ├── PRE_SITE_READINESS.json
+    ├── FAT_REPORT.html
+    └── EVIDENCE.html
+```
+
+## Industrial robot support
+
+The verification engine retains bounded industrial robot workflows, including the target-proven UR5e path and exact simulation-supported ABB IRB1200, FANUC CRX-10iA, and KUKA KR6 R900-2 profiles within their declared qualification scopes.
+
+Inspect available robot profiles and doctors:
+
+```bash
+devagent robots
+devagent robot doctor abb_irb1200
+devagent robot doctor fanuc_crx10ia
+devagent robot doctor kuka_kr6_r900_2
+```
+
+Generic family profiles and arbitrary customer workcells do not inherit measured authority from a reference workcell.
+
+## Unitree G1 bounded natural-language workflow
+
+The humanoid product path separates natural-language intent from low-level authority:
+
+```text
+natural-language task
+        ↓
+bounded deterministic task graph
+        ↓
+GEAR-SONIC locomotion / stable hold
+        ↓
+measured distance + balance gates
+        ↓
+qualified GR00T policy selection
+        ↓
+measured manipulation evidence
+        ↓
+verification / replay
+```
+
+Install or adopt the exact managed runtime only when you need this capability:
+
+```bash
+devagent robot setup unitree_g1_29dof --managed
+```
+
+Re-check readiness without motion:
+
+```bash
+devagent robot setup unitree_g1_29dof --doctor --json
+```
+
+Compile a bounded task without motion:
+
+```bash
+devagent robot execute unitree_g1_29dof \
+  --task "Walk to the box, grasp it with both hands, and lift it." \
+  --dry-run
+```
+
+A visualization/simulation request can then be made only in an environment with the qualified runtime:
+
+```bash
+devagent robot execute unitree_g1_29dof \
+  --task "Walk to the box, grasp it with both hands, and lift it." \
+  --visualize
+```
+
+Supported scene/task contracts remain bounded. Placement into bins, stacking, sorting, or other destination tasks are not silently approximated unless a separately qualified capability implements them.
+
+Training output is a candidate, not motion authority. Qualification binds the exact checkpoint and execution evidence before activation can change the active registry.
+
+## Physical simulation prerequisites
+
+`pip install` does not install ROS 2, Gazebo, MoveIt, OEM drivers, CUDA runtimes, robot firmware, or privileged operating-system packages.
+
+Reference industrial simulation stack:
+
+```text
+Ubuntu 24.04
+ROS 2 Jazzy
+Gazebo Harmonic
+gz_ros2_control
+MoveIt 2
+```
+
+Target-stack acceptance must run on the intended workstation. Hosted software CI must not pretend that graphical ROS/Gazebo/MoveIt or GPU humanoid execution was physically exercised when it was not.
+
+## Optional AI providers
+
+AI is optional and advisory. Install only the provider SDK you need:
+
+```bash
+python -m pip install "devagent-physical-engine[openai]==2.10.0"
+python -m pip install "devagent-physical-engine[anthropic]==2.10.0"
+python -m pip install "devagent-physical-engine[gemini]==2.10.0"
+python -m pip install "devagent-physical-engine[ai]==2.10.0"
+```
+
+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             customer onboarding, verification, AI/agent workflows, robot setup/execution
+devagent-commercial  project/evidence/FAT/regression/readiness control plane
+devagent-physical    deterministic core + ROS/qualification tools
+devagent-physical-ai optional provider-backed engineering front end
+```
+
+New users should start with `devagent`. The other entry points expose deeper engineering/control-plane functionality and are not required for the first successful onboarding path.
+
+## Architecture — learn this after the first result
+
+DevAgent separates proposal from proof:
+
+```text
+AI / natural language / customer intent
+        ↓
+proposal + interpretation
+        ↓
+deterministic capability / task / verification contracts
+        ↓
+exact source + Twin + model + adapter identity
+        ↓
+qualified simulation / measured execution
+        ↓
+evidence
+        ↓
+deterministic verdict
+        ↓
+authority gate
+```
+
+The important rule is simple:
+
+```text
+AI may propose.
+Deterministic contracts decide what can be attempted.
+Measured evidence decides what can be claimed.
+Authority gates decide what may execute.
+```
+
+A generated plan is not physical proof. A replay is not a new execution. An AI answer is not engineering evidence. A simulation result does not grant site qualification.
+
+## v2.10.0 / V59 drawing-to-simulation release scope
+
+**v2.10.0 — Production/Stable software**
+
+v2.10.0 adds a fail-closed Drawing-to-Simulation setup path for bounded industrial workcells. `devagent robot setup-from-drawing ...` lets an AI provider identify semantic entities and explicit dimension callouts from a drawing while deterministic DevAgent geometry remains the only metric authority. AI-derived or visually scaled dimensions are rejected, and missing authoritative dimensions return `drawing_setup_needs_input` until a named user-verified value is supplied.
+
+The generated Twin, runtime configuration, and fixed-camera contract pass through the existing Setup Qualification authority before simulation. The new `devagent robot setup-camera-verify ...` gate performs a no-motion render-alignment verification: it launches the simulation scene, captures the fixed camera, obtains only a semantic image-region hypothesis from the AI provider, reads exact Gazebo geometry, and compares deterministic projection/inverse-projection results against the bounded localization authority. Camera-guided execution remains blocked unless this alignment is verified.
+
+v2.10.0 also corrects the Gazebo camera projection contract so custom `fx`, `fy`, `cx`, and `cy` live under the SDFormat lens intrinsics block and an explicit horizontal FOV is emitted. A regression check prevents silent fallback to the Gazebo default projection from drifting the rendered image away from deterministic camera geometry.
+
+The existing V58 setup qualification progression (`blocked -> geometric -> physical -> reality_calibrated`), V52 industrial-arm AI + vision execution authority, V51 Community surface, and V50 verification-first core remain intact. The qualified industrial motion acceptance remains unchanged: deterministic collision/preexecution checks, controller/FK readback, 2 mm TCP position acceptance, 0.5° orientation acceptance, and exact evidence identity remain authoritative. AI has no joint, trajectory, metric, or physical-execution authority.
+
+The production release remains fail-closed on exact target-workstation campaign evidence for declared industrial robot configurations. Software CI, generated plans, single-run simulation, drawing completeness, setup completeness, camera alignment, or AI output alone cannot satisfy physical qualification or grant motion authority.
+
+Physical authority remains conservative by construction: compatibility and simulation do not grant motion; hardware and site evidence cannot be skipped; external admission is required; exact identity drift invalidates qualification; and site-qualified evidence does not bypass the independent runtime approval and live-interlock gates.
+
+Real hardware execution and measured FAT promotion remain disabled until their separate physical campaigns satisfy the required evidence contracts.
+
+## Exit codes
+
+| Exit | Meaning |
+| ---: | --- |
+| `0` | deterministic current project state is `READY_FOR_PRE_SITE_COMMISSIONING` |
+| `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.10.0 — Production/Stable software; V59 drawing-to-simulation and camera render-alignment on the V58 setup-qualification, V52 industrial AI + vision, V51 Community, and V50 verification-first core**
+
+Production/Stable describes the bounded software workflow and runtime authority contracts. It does not claim arbitrary customer workcells, functional safety, site commissioning, real hardware manipulation, or unqualified robot/model/camera combinations are automatically qualified.
+
+Current hard authority boundaries remain:
+
+```text
+site_qualification = false
+functional_safety_certification = false
+commissioning_completed = false
+real_execution_allowed = false
+```
+
+unless separately proven by the appropriate qualified process.
+
+## Documentation
+
+- [v2.7.0 Release Notes](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/RELEASE_NOTES_V2_7_0.md)
+- [Community Production V51](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMUNITY_PRODUCTION_V51.md)
+- [Flexible Guided Intake](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/FLEXIBLE_GUIDED_INTAKE_V23.md)
+- [Commissioning Agent Orchestrator](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMISSIONING_AGENT_ORCHESTRATOR_V1.md)
+- [Humanoid Pip-First Setup](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/HUMANOID_PIP_FIRST_V32.md)
+- [Humanoid GR00T Manipulation](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/HUMANOID_GROOT_MANIPULATION_V27.md)
+- [Humanoid Task Orchestrator](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/HUMANOID_TASK_ORCHESTRATOR_V28.md)
+- [Humanoid High-Quality Demonstrations](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/HUMANOID_HIGH_QUALITY_DEMONSTRATIONS_V31.md)
+- [Physical AI Runtime V40](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/PHYSICAL_AI_RUNTIME_V40.md)
+- [V40 Production Gate](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/V40_PRODUCTION_GATE.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)
+- [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)
+- [Laptop Acceptance](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/LAPTOP_ACCEPTANCE.md)
+
+Release history is available from the GitHub Releases page and versioned release-note documents in `docs/`.
+
+## 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.