devagent-physical-engine 0.13.0__tar.gz → 1.0.0__tar.gz

devagent_physical_engine-1.0.0/PKG-INFO

@@ -0,0 +1,398 @@
+Metadata-Version: 2.4
+Name: devagent-physical-engine
+Version: 1.0.0
+Summary: Verification-first commercial engineering, simulation, traceability, regression, and FAT evidence runtime for robotics and industrial automation.
+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
+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 commercial engineering, customer Twin import, requirement traceability, regression analysis, and FAT evidence for robotic and industrial automation.**
+
+> **AI proposes. Deterministic engines validate, compile, verify, simulate, measure, and gate promotion. Existing certified robot controllers, PLCs, and safety systems remain authoritative.**
+
+DevAgent Smart Physical Engine helps an engineer move from a customer workcell definition to evidence-backed engineering review without giving an LLM direct robot-control authority. Commercial V1 adds a durable customer workflow around the existing provider-neutral AI, canonical physical Twin, ROS 2 / Gazebo / MoveIt simulation, deterministic verification, and evidence infrastructure.
+
+## Commercial V1 outcome
+
+A customer project can now be handled as one durable evidence chain:
+
+```text
+CUSTOMER PROJECT / SITE / WORKCELL
+                |
+                v
+CUSTOMER FILE INVENTORY + devagent-twin MANIFEST
+                |
+                v
+CANONICAL TWIN + IMMUTABLE twin-r000N REVISION
+                |
+                v
+REQUIREMENT SET
+                |
+                v
+DETERMINISTIC REQUIREMENT CAMPAIGN
+                |
+                v
+REGRESSION COMPARISON
+                |
+                v
+CUSTOMER-READY FAT EVIDENCE REPORT
+```
+
+The commercial workflow is intentionally fail-closed. A CAD, URDF, mesh, YAML, or CSV file being present does **not** prove a robot base pose, TCP, dimension, coordinate frame, collision model, calibration, or physics property. Those facts must be explicitly declared or measured before DevAgent promotes them as engineering evidence.
+
+## Install
+
+Python 3.11+ is required.
+
+```bash
+python -m pip install devagent-physical-engine
+```
+
+Optional AI providers:
+
+```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 all supported provider SDKs
+python -m pip install "devagent-physical-engine[ai]"
+```
+
+`pip install` does not install ROS, Gazebo, MoveIt, OEM robot drivers, or privileged operating-system dependencies.
+
+## Commercial quick start
+
+Create durable customer identity:
+
+```bash
+devagent-commercial init warehouse-cnc-04 \
+  --name "Warehouse CNC Loading Cell 04" \
+  --site atl-01 \
+  --workcell cnc-04
+```
+
+Import a customer folder:
+
+```bash
+devagent-commercial import-twin warehouse-cnc-04 ./customer-cell
+```
+
+The folder may contain supported engineering assets such as:
+
+```text
+customer-cell/
+├── devagent-twin.yaml
+├── robot.urdf
+├── robot.srdf
+├── meshes/
+│   ├── gripper.stl
+│   └── fixture.stl
+└── notes-or-export.json
+```
+
+Commercial V1 inventories `.urdf`, `.xacro`, `.srdf`, `.stl`, `.dae`, `.obj`, `.step`, `.stp`, `.iges`, `.igs`, `.yaml`, `.yml`, `.json`, and `.csv` files. Customer assets are SHA-256 fingerprinted with bounded streaming I/O; individual inventoried assets are limited to 512 MiB. A `devagent-twin.yaml`, `devagent-twin.yml`, or `devagent-twin.json` manifest is required before file inventory becomes physical Twin evidence.
+
+If the manifest or required physical facts are missing, DevAgent returns `needs_information` with explicit engineering questions instead of inventing values.
+
+Import requirements:
+
+```bash
+devagent-commercial requirements warehouse-cnc-04 requirements.csv
+```
+
+Run deterministic requirement verification against the latest Twin revision:
+
+```bash
+devagent-commercial campaign warehouse-cnc-04 requirements.csv
+```
+
+Or bind the campaign to an exact immutable revision:
+
+```bash
+devagent-commercial campaign warehouse-cnc-04 requirements.csv \
+  --revision twin-r0002
+```
+
+Compare a previous campaign with a current campaign:
+
+```bash
+devagent-commercial regression warehouse-cnc-04 \
+  art-BASELINE \
+  art-CURRENT
+```
+
+Generate a FAT Markdown report:
+
+```bash
+devagent-commercial fat-report warehouse-cnc-04 \
+  art-CURRENT \
+  --regression art-REGRESSION \
+  --output FAT_REPORT.md
+```
+
+Inspect commercial readiness and immutable evidence:
+
+```bash
+devagent-commercial status warehouse-cnc-04
+devagent-commercial artifacts warehouse-cnc-04
+```
+
+The default commercial evidence database is:
+
+```text
+~/.devagent/projects.db
+```
+
+## Customer Twin manifest
+
+Commercial V1 is manifest-driven so engineering facts have explicit provenance. A minimal structure is:
+
+```yaml
+schema_version: 1
+length_unit: mm
+angle_unit: deg
+
+engineering_request:
+  robot: ur5e
+  operation: load
+  object_id: BOX_101
+  source: conveyor_a
+  destination: cnc_04
+  tool: parallel_gripper
+  payload_kg: 1.5
+  purpose: simulate
+
+robot_base_pose:
+  x: 0
+  y: 0
+  z: 0
+  origin: measured
+  source_ref: site-survey
+
+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]
+
+tool:
+  id: parallel_gripper
+  tcp:
+    x: 0
+    y: 0
+    z: 180
+    origin: measured
+  geometry:
+    kind: box
+    dimensions: [120, 80, 200]
+  max_payload_kg:
+    value: 5.0
+    origin: imported
+```
+
+A mesh can be referenced by relative asset path, for example:
+
+```yaml
+geometry:
+  kind: mesh
+  asset: meshes/fixture.stl
+```
+
+The referenced file must have been discovered inside the customer source root. Absolute paths, `..` traversal, and symlinked customer assets are rejected.
+
+## Requirement traceability
+
+CSV example:
+
+```csv
+requirement_id,text,check,target,expected,severity
+REQ-001,Twin shall be planning ready,planning_allowed,,true,must
+REQ-002,Workpiece shall exist,entity_present,BOX_101,true,must
+REQ-003,Unit mismatch shall be absent,validation_issue_absent,possible_unit_mismatch,true,must
+```
+
+Commercial V1 deterministic checks are deliberately small and auditable:
+
+- `planning_allowed`
+- `physics_allowed`
+- `entity_present`
+- `validation_issue_absent`
+- `twin_state`
+
+A prose requirement without a supported deterministic check is reported as `NOT_TESTED`. It is never auto-passed by an LLM. A required (`must`) item that fails or remains untested blocks customer-review readiness.
+
+## Evidence and regression
+
+Project, Twin, import, campaign, regression, and FAT artifacts are stored with stable identities and content hashes. Twin revisions are monotonic and immutable (`twin-r0001`, `twin-r0002`, ...).
+
+Regression analysis explicitly identifies a requirement that changed from `PASS` in the baseline campaign to any non-pass state in the current campaign. A regression blocks release readiness.
+
+The FAT report includes project/site/workcell identity, exact Twin revision and hash, requirement counts, pass/fail/not-tested results, coverage, regression state, and bounded release readiness.
+
+`READY FOR CUSTOMER REVIEW` means the declared/imported Twin scope and mapped deterministic requirements passed the commercial evidence gates. It does **not** mean functional-safety certification, site qualification, commissioning approval, or permission to move a production robot.
+
+## AI engineering layer
+
+The runtime remains provider-neutral. OpenAI, Anthropic, and Gemini can be used for interpretation, planning, critique, and recovery while deterministic code owns schema validation, semantic policy, Twin validation, collision/clearance contracts, evidence, qualification, and execution gating.
+
+Check a provider:
+
+```bash
+devagent-physical-ai doctor --provider openai
+```
+
+Run an 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 <model-id>
+```
+
+Use `--quiet` for machine-readable JSON without progress messages on stdout.
+
+## Physical simulation
+
+The repository retains the evidence-gated ROS 2 / Gazebo / MoveIt physical simulation stack and the packaged UR5e reference workcell. The reference stack target is:
+
+```text
+Ubuntu 24.04
+ROS 2 Jazzy
+Gazebo Harmonic
+gz_ros2_control
+Universal Robots ROS 2 driver
+ur_simulation_gz
+MoveIt 2
+```
+
+Useful commands:
+
+```bash
+devagent-physical setup --profile ur5e-sim --dry-run
+devagent-physical setup --profile ur5e-sim
+devagent-physical ros doctor
+devagent-physical ros demo
+devagent-physical ros qualify-trajectory-runtime
+```
+
+Hosted Python CI cannot truthfully exercise a graphical Gazebo process, MoveIt `move_group`, TF, ROS controllers, or Gazebo services. Those paths retain separate executable target qualification. A registry entry for FANUC, KUKA, ABB, or another robot family does not imply identical physical simulation qualification.
+
+## Safety and authority boundary
+
+Commercial V1 is an engineering verification product, not a safety controller. It intentionally preserves these boundaries:
+
+```text
+AI / COMMERCIAL WORKFLOW
+        |
+        v
+DETERMINISTIC DEVAGENT EVIDENCE
+        |
+        v
+SIMULATION / ENGINEERING REVIEW
+        |
+        X
+NO AUTOMATIC PRODUCTION-HARDWARE AUTHORITY
+```
+
+Simulation success does not override OEM controllers, PLC interlocks, safety PLCs, risk assessments, guarding, functional-safety validation, site commissioning procedures, or engineer approval.
+
+Commercial outputs therefore continue to report:
+
+```text
+site_qualification=false
+real_execution_allowed=false
+```
+
+unless a separately implemented and evidence-qualified authority path explicitly proves otherwise. Commercial V1 does not add such a path.
+
+## Software verification and releases
+
+Repository CI verifies Python 3.11, 3.12, and 3.13, compilation, unit regression, Ruff correctness, branch coverage, package build, clean wheel installation, and runtime dependency vulnerability audit.
+
+A green `main` release is tied to the exact CI-tested commit. Release artifacts are rebuilt from the exact tag, checked with Twine, clean-installed, accompanied by a CycloneDX runtime SBOM and SHA-256 checksums, attached to the GitHub Release, and published to PyPI through Trusted Publishing with digital attestations.
+
+## Documentation
+
+- [Commercial V1](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMERCIAL_V1.md)
+- [Commercial project spine](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/COMMERCIAL_PROJECT_SPINE.md)
+- [Production readiness](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/PRODUCTION_READINESS.md)
+- [Architecture](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ARCHITECTURE.md)
+- [Agent Core](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/AGENT_CORE.md)
+- [AI providers](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/AI_PROVIDERS.md)
+- [Natural-language engineering](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/NATURAL_LANGUAGE_ENGINEERING.md)
+- [Robot platform and Twin](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/ROBOT_PLATFORM_AND_TWIN.md)
+- [Measured physical runtime](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/MEASURED_PHYSICAL_RUNTIME.md)
+- [Qualification](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/QUALIFICATION.md)
+- [Optimization](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/OPTIMIZATION.md)
+- [Workstation setup](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/SETUP.md)
+- [PyPI release process](https://github.com/tomha85/devagent-physical-engine/blob/main/docs/PYPI_RELEASE.md)
+
+## Project status
+
+**v1.0.0 — Production/Stable software / commercial engineering workflow with evidence-gated customer Twin import, requirement traceability, regression analysis, and FAT reporting.**
+
+Production/Stable describes the shipped software/API/CLI and release process for the bounded V1 scope. Physical and site readiness remain evidence- and adapter-specific. Arbitrary CAD/URDF content is inventoried and fingerprinted but is not semantically trusted merely because a file exists; customer physical facts are promoted only through explicit manifest/evidence contracts. Real robot execution remains locked by default. Functional-safety certification and customer-site commissioning are not claimed.
+
+## 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.