openphysicalai 0.2.1__tar.gz

openphysicalai-0.2.1/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: openphysicalai
+Version: 0.2.1
+Summary: OpenPhysicalAI Lab core: budget-aware, latency-coupled evaluation for Physical AI
+License-Expression: Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: mujoco>=3.1
+Requires-Dist: numpy>=1.24
+Requires-Dist: psutil>=5.9
+Provides-Extra: sim
+Requires-Dist: mujoco>=3.1; extra == "sim"
+Provides-Extra: gpu
+Requires-Dist: psutil; extra == "gpu"
+Requires-Dist: nvidia-ml-py; extra == "gpu"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+<div align="center">
+
+# 🤖 OpenPhysicalAI Lab (`v0.2.1`)
+
+**Real-Time Embodied AI Simulation, Closed-Loop Failure Recovery & Hardware Budget Benchmarking — Engineered to Run Inside 4 GB VRAM.**
+
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![Phase-1 Gate](https://img.shields.io/badge/Phase--1_Gate-200%2F200_(100%25)-brightgreen.svg)](#verified-benchmarks--scientific-results)
+[![MuJoCo](https://img.shields.io/badge/MuJoCo-3.16.0_3D_GPU-orange.svg)](#system-architecture)
+[![Hardware Tier](https://img.shields.io/badge/Verified_Tier-OPAI--4G_(RTX_3050_4GB)-76b900.svg)](#community-hardware-leaderboard)
+[![Platform](https://img.shields.io/badge/Platform-Windows_11_%7C_Linux_%7C_macOS-informational.svg)](#quick-start)
+
+</div>
+
+---
+
+## ⚡ Why OpenPhysicalAI Lab?
+
+Most embodied AI frameworks assume you have a 24 GB RTX 4090 or an 80 GB datacenter GPU. **OpenPhysicalAI Lab** proves that deterministic 3D physics, vision perception, local LLM task planning, and closed-loop failure recovery can run **entirely locally on a 4 GB VRAM laptop (`OPAI-4G`)**.
+
+Unlike static benchmarks that pause the physics engine while the LLM thinks, OpenPhysicalAI Lab enforces **Real-Time Mode**: the physical world keeps moving while the planner reasons, exposing the true **Latency Tax** of slow models and measuring capability under strict **VRAM, System RAM, Latency, and Energy (Joule) Budget Cards**.
+
+---
+
+## 🏗️ System Architecture
+
+```mermaid
+flowchart LR
+    subgraph Sim["MuJoCo 3.16 Real-Time Engine (432 FPS)"]
+        World["5-DOF Arm + Parallel Gripper\nTable, Cubes, Conveyor"]
+        Inject["Seeded Failure Injector\n(Slip, Displacement, Noise)"]
+        Render["3D OpenGL GPU Renderer\n(Shadows + Orthographic Vision)"]
+    end
+
+    subgraph Percep["Perception & Kinematics"]
+        Vision["Vision / Oracle Detector\n(~1 mm Accuracy)"]
+        Kalman["Alpha-Beta Velocity Tracker\n(Latency Lead Compensation)"]
+    end
+
+    subgraph Agent["Closed-Loop Recovery Agent"]
+        Verifier["Tiered Verifiers\n(V0 Oracle | V1 Proprio | V2 Camera)"]
+        Planner["Local Ollama LLM Planner\n(Gemma 2 2B / Qwen3 4B JSON)"]
+    end
+
+    subgraph Telemetry["NVML & Budget Auditor"]
+        Profiler["NVML + Ollama /api/ps\n(VRAM, RAM, Watts, Temp)"]
+        Card["SQLite + Signed\nBudget Card (.md / .csv)"]
+    end
+
+    World --> Inject --> Render --> Vision --> Kalman
+    Kalman --> Verifier --> Planner
+    Planner -- "Hold Policy Advances World by Δt_plan" --> World
+    Sim -.-> Profiler --> Card
+    Agent -.-> Profiler
+```
+
+---
+
+## ✅ What Is Real & Verified
+
+| Subsystem | Implementation Status |
+|---|---|
+| **Physics Engine** | Real MuJoCo 3.16.0: 5-DOF robotic arm, parallel friction gripper, table, multi-size cubes, open-top container, and kinematic moving conveyor. Analytic IK + Cartesian skill primitives. |
+| **3D GPU Rendering** | Native `mujoco.Renderer` 3D perspective camera (distance 0.92 m, elevation -26°, azimuth 135°) with directional shadow mapping (~432 FPS / 2.3 ms/frame on RTX 3050 Laptop GPU) + 1 mm accurate orthographic vision pipeline. |
+| **Phase-1 Gate** | Deterministic scripted pick-and-place passes **200/200 random scenes (100.0%)** (`python python/gate1.py`). |
+| **Benchmark Tasks** | 5 seeded, cross-process deterministic tasks: `pick_place`, `smallest`, spatial (`left_of`), `multi_object`, and `dynamic` (moving conveyor cube). |
+| **Local LLM Planners** | Rule-based baseline + Ollama local LLMs (`gemma2:2b`, `qwen3:4b-instruct-2507-q4_K_M`) with strict JSON-schema output and kinematic action validation. |
+| **Agent Architectures** | Open-Loop (blind execution), Closed-Loop (abort on anomaly), and Recovery Agent (active failure detection, diagnosis, re-observation, and replanning). |
+| **Hardware Profiler** | Tracks process-tree RSS, system RAM, NVML Compute/Graphics VRAM, Ollama `/api/ps` VRAM, GPU power (W), energy per episode (J), core temperature (°C), and thermal throttling. |
+
+---
+
+## 📊 Verified Benchmarks & Scientific Results
+
+All benchmarks below were executed on an HP Victus 15 (**OPAI-4G Reference Tier**: NVIDIA GeForce RTX 3050 Laptop GPU 4.0 GB VRAM, 16 GB System RAM, Windows 11, MuJoCo 3.16.0).
+
+### 1. Local LLM Planner Speed & Footprint (OPAI-4G Tier)
+
+| Local Model (Ollama) | Weights Size | Peak Device VRAM | Warm Planning Latency | Throughput | Schema Compliance |
+### 1. Local LLM Planner Speed & Footprint (OPAI-4G Tier, N=20 per Model, Real-Time Mode)
+
+All models evaluated under identical real-time closed-loop pick-and-place tasks on an NVIDIA GeForce RTX 3050 Laptop GPU (4.0 GB VRAM):
+
+| Local Model (Ollama) | Weights Size | Peak Device VRAM | Warm Planning Latency (p50 / p95) | Throughput | TSR (95% CI, N=20) | Notes |
+|---|---|---|---|---|---|---|
+| **`qwen2.5:3b`** | 1.9 GB | 2.57 GB | **469 ms / 493 ms** | 70.6 tok/s | **100.0%** (83.9%–100.0%) | Fastest response, reliable spatial parsing |
+| **`gemma2:2b`** | 1.6 GB | 2.36 GB | **715 ms / 751 ms** | 69.5 tok/s | **100.0%** (83.9%–100.0%) | Consistent schema compliance & low footprint |
+| **`llama3.2:1b`** | 1.3 GB | 1.97 GB | **577 ms / 608 ms** | 99.9 tok/s | **0.0%** (0.0%–16.1%) | Fast generation, but frequent JSON/action schema violations |
+
+### 2. Verifier Honesty Benchmark (Moderate Perturbation, Real-Time Mode, N=100 per Cell)
+
+Evaluated with Rule-Based Recovery Agent under moderate failure injection (slip probability $p=0.25$, displacement, and wrong placement). Raw JSON exported in `verifier_benchmark_summary_N100.json`:
+
+| Agent | Verifier Level | Mode | TSR (95% CI, N=100) | Injections | Detect Rate | Recover Rate | Missed Failures | False Alarms | Planning p95 |
+|---|---|---|---|---|---|---|---|---|---|
+| **Recovery** | **V0 (Simulator Oracle)** | realtime | **74.0%** (64.6%–81.6%) | 138 | 97.1% | 52.2% | **0.0%** | 0.0% | 0.03 ms |
+| **Recovery** | **V1 (Proprioception Only)** | realtime | **68.0%** (58.3%–76.3%) | 124 | 87.9% | 51.4% | **3.7%** | 0.0% | 0.03 ms |
+| **Recovery** | **V2 (Proprio + Camera Vision)**| realtime | **73.0%** (63.6%–80.7%) | 137 | 96.4% | 51.5% | **0.3%** | 0.0% | 0.03 ms |
+
+> [!IMPORTANT]
+> **Key Verifier Finding**: Proprioceptive verification alone (`V1`) suffers a **3.7% missed-failure rate** because joint sensors cannot detect when a placed object lands outside the container boundary (`wrong_placement`). Vision verification (`V2`) closes this gap, reducing missed failures to **0.3%**, approaching oracle upper bound (`V0`).
+
+### 3. The Latency Tax on Dynamic Conveyor Tasks
+
+Measured on the `dynamic` task with moving cube at $0.02\text{ m/s}$, single-frame perception, without velocity lead compensation:
+
+| Agent Architecture | Verifier | Execution Mode | Planner Delay ($\Delta t$) | TSR (95% CI, N=50) | Physical Mechanism |
+|---|---|---|---|---|---|
+| **Closed-Loop (Rule)** | V1 | sync | 0 ms | **38.0%** (25.9%–51.8%) | Physics paused while planning |
+| **Closed-Loop (Rule)** | V1 | realtime | 0 ms | **38.0%** (25.9%–51.8%) | Real-time baseline |
+| **Closed-Loop (Rule)** | V1 | realtime | 1,000 ms (1.0 s) | **0.0%** (0.0%–7.1%) | Cube shifts ~20 mm past gripper capture zone |
+| **Closed-Loop (Rule)** | V1 | realtime | 2,000 ms (2.0 s) | **0.0%** (0.0%–7.1%) | Stale observation causes complete grasp miss |
+| **Recovery (Velocity-Lead)**| V1 | realtime | 1,000 ms (1.0 s) | **100.0%** (72.2%–100.0%) | Forward-projected intercept overcomes latency tax |
+
+> [!NOTE]
+> Physical AI agents relying purely on reactive perception fail when planner latency exceeds the physical dynamic timescale. Latency compensation (velocity projection $\hat{v} \cdot (\tau_{\text{plan}} + \tau_{\text{travel}})$) restores 100% reliability even at multi-second planning delays.
+
+---
+
+## 🚀 Quick Start
+
+### 1. One-Click Windows Launch (Desktop App)
+Clone the repository and double-click `start-app.bat`, or run from terminal:
+
+```bash
+git clone https://github.com/VedantJadhav701/OpenphysicalAI-lab.git
+cd OpenphysicalAI-lab
+
+# Optional: activate your existing Conda environment (auto-detected by main.js)
+conda activate thermo_agent
+
+npm install
+npm start
+```
+
+### 2. Pull the Recommended 4GB-Tier Local LLM Planner
+
+```bash
+ollama pull gemma2:2b
+
+# Or for the 4B Qwen3 planner:
+ollama pull qwen3:4b-instruct-2507-q4_K_M
+```
+
+### 3. Headless CLI & Phase-1 Gate Verification
+
+```bash
+python python/gate1.py
+pytest python/tests
+python -m openphysicalai.cli run --task pick_place --perception vision --perturb moderate --verifier V2 --episodes 50
+```
+
+---
+
+## 🏆 Community Hardware Leaderboard
+
+Run the benchmark suite on your machine, generate a signed Budget Card (`budget_card_run_*.md`), and submit a Pull Request to add your hardware configuration below!
+
+| Contributor | Device / GPU | Tier Class | Planner Model | Peak Device VRAM | Planning p95 | Recovery TSR | Energy / Ep | Budget Status |
+|---|---|---|---|---|---|---|---|---|
+| **@VedantJadhav701** | HP Victus 15 (RTX 3050 4GB, 16GB RAM) | `OPAI-4G` | `gemma2:2b` | 2.10 GB | 698 ms | 100.0% | ~92 J | ✅ PASS |
+| **@VedantJadhav701** | HP Victus 15 (RTX 3050 4GB, 16GB RAM) | `OPAI-4G` | `qwen3:4b-q4_K_M` | 2.53 GB | 1344 ms | 100.0% | 133.6 J | ✅ PASS |
+| *Your GitHub Handle* | *Add your GPU / Apple Silicon / CPU* | *OPAI-4G/8G/16G* | *Any Ollama Model* | *Measured GB* | *Measured ms* | *Measured %* | *Measured J* | *Submit PR!* |
+
+---
+
+## 🗂️ Repository Layout
+
+```text
+├── main.js / preload.js         # Electron main process, Conda auto-discovery, single-instance lock
+├── start-app.bat                # One-click Windows launcher
+├── src/                         # iOS-style Electron frontend UI
+├── python/
+│   ├── gate1.py                 # 200-scene deterministic Phase-1 physics gate
+│   ├── tests/                   # Pytest unit & integration test suite
+│   └── openphysicalai/          # Core engine: sim, tasks, skills, perception, render (3D GPU),
+│                                # planners, injection, runner, profiler, budget, store, cli
+└── docs/                        # Architectural roadmap & experimental specifications
+```
+
+---
+
+## 📄 License
+
+Licensed under the Apache License 2.0 — see [LICENSE](LICENSE) for full details.

openphysicalai-0.2.1/README.md

@@ -0,0 +1,185 @@
+<div align="center">
+
+# 🤖 OpenPhysicalAI Lab (`v0.2.1`)
+
+**Real-Time Embodied AI Simulation, Closed-Loop Failure Recovery & Hardware Budget Benchmarking — Engineered to Run Inside 4 GB VRAM.**
+
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![Phase-1 Gate](https://img.shields.io/badge/Phase--1_Gate-200%2F200_(100%25)-brightgreen.svg)](#verified-benchmarks--scientific-results)
+[![MuJoCo](https://img.shields.io/badge/MuJoCo-3.16.0_3D_GPU-orange.svg)](#system-architecture)
+[![Hardware Tier](https://img.shields.io/badge/Verified_Tier-OPAI--4G_(RTX_3050_4GB)-76b900.svg)](#community-hardware-leaderboard)
+[![Platform](https://img.shields.io/badge/Platform-Windows_11_%7C_Linux_%7C_macOS-informational.svg)](#quick-start)
+
+</div>
+
+---
+
+## ⚡ Why OpenPhysicalAI Lab?
+
+Most embodied AI frameworks assume you have a 24 GB RTX 4090 or an 80 GB datacenter GPU. **OpenPhysicalAI Lab** proves that deterministic 3D physics, vision perception, local LLM task planning, and closed-loop failure recovery can run **entirely locally on a 4 GB VRAM laptop (`OPAI-4G`)**.
+
+Unlike static benchmarks that pause the physics engine while the LLM thinks, OpenPhysicalAI Lab enforces **Real-Time Mode**: the physical world keeps moving while the planner reasons, exposing the true **Latency Tax** of slow models and measuring capability under strict **VRAM, System RAM, Latency, and Energy (Joule) Budget Cards**.
+
+---
+
+## 🏗️ System Architecture
+
+```mermaid
+flowchart LR
+    subgraph Sim["MuJoCo 3.16 Real-Time Engine (432 FPS)"]
+        World["5-DOF Arm + Parallel Gripper\nTable, Cubes, Conveyor"]
+        Inject["Seeded Failure Injector\n(Slip, Displacement, Noise)"]
+        Render["3D OpenGL GPU Renderer\n(Shadows + Orthographic Vision)"]
+    end
+
+    subgraph Percep["Perception & Kinematics"]
+        Vision["Vision / Oracle Detector\n(~1 mm Accuracy)"]
+        Kalman["Alpha-Beta Velocity Tracker\n(Latency Lead Compensation)"]
+    end
+
+    subgraph Agent["Closed-Loop Recovery Agent"]
+        Verifier["Tiered Verifiers\n(V0 Oracle | V1 Proprio | V2 Camera)"]
+        Planner["Local Ollama LLM Planner\n(Gemma 2 2B / Qwen3 4B JSON)"]
+    end
+
+    subgraph Telemetry["NVML & Budget Auditor"]
+        Profiler["NVML + Ollama /api/ps\n(VRAM, RAM, Watts, Temp)"]
+        Card["SQLite + Signed\nBudget Card (.md / .csv)"]
+    end
+
+    World --> Inject --> Render --> Vision --> Kalman
+    Kalman --> Verifier --> Planner
+    Planner -- "Hold Policy Advances World by Δt_plan" --> World
+    Sim -.-> Profiler --> Card
+    Agent -.-> Profiler
+```
+
+---
+
+## ✅ What Is Real & Verified
+
+| Subsystem | Implementation Status |
+|---|---|
+| **Physics Engine** | Real MuJoCo 3.16.0: 5-DOF robotic arm, parallel friction gripper, table, multi-size cubes, open-top container, and kinematic moving conveyor. Analytic IK + Cartesian skill primitives. |
+| **3D GPU Rendering** | Native `mujoco.Renderer` 3D perspective camera (distance 0.92 m, elevation -26°, azimuth 135°) with directional shadow mapping (~432 FPS / 2.3 ms/frame on RTX 3050 Laptop GPU) + 1 mm accurate orthographic vision pipeline. |
+| **Phase-1 Gate** | Deterministic scripted pick-and-place passes **200/200 random scenes (100.0%)** (`python python/gate1.py`). |
+| **Benchmark Tasks** | 5 seeded, cross-process deterministic tasks: `pick_place`, `smallest`, spatial (`left_of`), `multi_object`, and `dynamic` (moving conveyor cube). |
+| **Local LLM Planners** | Rule-based baseline + Ollama local LLMs (`gemma2:2b`, `qwen3:4b-instruct-2507-q4_K_M`) with strict JSON-schema output and kinematic action validation. |
+| **Agent Architectures** | Open-Loop (blind execution), Closed-Loop (abort on anomaly), and Recovery Agent (active failure detection, diagnosis, re-observation, and replanning). |
+| **Hardware Profiler** | Tracks process-tree RSS, system RAM, NVML Compute/Graphics VRAM, Ollama `/api/ps` VRAM, GPU power (W), energy per episode (J), core temperature (°C), and thermal throttling. |
+
+---
+
+## 📊 Verified Benchmarks & Scientific Results
+
+All benchmarks below were executed on an HP Victus 15 (**OPAI-4G Reference Tier**: NVIDIA GeForce RTX 3050 Laptop GPU 4.0 GB VRAM, 16 GB System RAM, Windows 11, MuJoCo 3.16.0).
+
+### 1. Local LLM Planner Speed & Footprint (OPAI-4G Tier)
+
+| Local Model (Ollama) | Weights Size | Peak Device VRAM | Warm Planning Latency | Throughput | Schema Compliance |
+### 1. Local LLM Planner Speed & Footprint (OPAI-4G Tier, N=20 per Model, Real-Time Mode)
+
+All models evaluated under identical real-time closed-loop pick-and-place tasks on an NVIDIA GeForce RTX 3050 Laptop GPU (4.0 GB VRAM):
+
+| Local Model (Ollama) | Weights Size | Peak Device VRAM | Warm Planning Latency (p50 / p95) | Throughput | TSR (95% CI, N=20) | Notes |
+|---|---|---|---|---|---|---|
+| **`qwen2.5:3b`** | 1.9 GB | 2.57 GB | **469 ms / 493 ms** | 70.6 tok/s | **100.0%** (83.9%–100.0%) | Fastest response, reliable spatial parsing |
+| **`gemma2:2b`** | 1.6 GB | 2.36 GB | **715 ms / 751 ms** | 69.5 tok/s | **100.0%** (83.9%–100.0%) | Consistent schema compliance & low footprint |
+| **`llama3.2:1b`** | 1.3 GB | 1.97 GB | **577 ms / 608 ms** | 99.9 tok/s | **0.0%** (0.0%–16.1%) | Fast generation, but frequent JSON/action schema violations |
+
+### 2. Verifier Honesty Benchmark (Moderate Perturbation, Real-Time Mode, N=100 per Cell)
+
+Evaluated with Rule-Based Recovery Agent under moderate failure injection (slip probability $p=0.25$, displacement, and wrong placement). Raw JSON exported in `verifier_benchmark_summary_N100.json`:
+
+| Agent | Verifier Level | Mode | TSR (95% CI, N=100) | Injections | Detect Rate | Recover Rate | Missed Failures | False Alarms | Planning p95 |
+|---|---|---|---|---|---|---|---|---|---|
+| **Recovery** | **V0 (Simulator Oracle)** | realtime | **74.0%** (64.6%–81.6%) | 138 | 97.1% | 52.2% | **0.0%** | 0.0% | 0.03 ms |
+| **Recovery** | **V1 (Proprioception Only)** | realtime | **68.0%** (58.3%–76.3%) | 124 | 87.9% | 51.4% | **3.7%** | 0.0% | 0.03 ms |
+| **Recovery** | **V2 (Proprio + Camera Vision)**| realtime | **73.0%** (63.6%–80.7%) | 137 | 96.4% | 51.5% | **0.3%** | 0.0% | 0.03 ms |
+
+> [!IMPORTANT]
+> **Key Verifier Finding**: Proprioceptive verification alone (`V1`) suffers a **3.7% missed-failure rate** because joint sensors cannot detect when a placed object lands outside the container boundary (`wrong_placement`). Vision verification (`V2`) closes this gap, reducing missed failures to **0.3%**, approaching oracle upper bound (`V0`).
+
+### 3. The Latency Tax on Dynamic Conveyor Tasks
+
+Measured on the `dynamic` task with moving cube at $0.02\text{ m/s}$, single-frame perception, without velocity lead compensation:
+
+| Agent Architecture | Verifier | Execution Mode | Planner Delay ($\Delta t$) | TSR (95% CI, N=50) | Physical Mechanism |
+|---|---|---|---|---|---|
+| **Closed-Loop (Rule)** | V1 | sync | 0 ms | **38.0%** (25.9%–51.8%) | Physics paused while planning |
+| **Closed-Loop (Rule)** | V1 | realtime | 0 ms | **38.0%** (25.9%–51.8%) | Real-time baseline |
+| **Closed-Loop (Rule)** | V1 | realtime | 1,000 ms (1.0 s) | **0.0%** (0.0%–7.1%) | Cube shifts ~20 mm past gripper capture zone |
+| **Closed-Loop (Rule)** | V1 | realtime | 2,000 ms (2.0 s) | **0.0%** (0.0%–7.1%) | Stale observation causes complete grasp miss |
+| **Recovery (Velocity-Lead)**| V1 | realtime | 1,000 ms (1.0 s) | **100.0%** (72.2%–100.0%) | Forward-projected intercept overcomes latency tax |
+
+> [!NOTE]
+> Physical AI agents relying purely on reactive perception fail when planner latency exceeds the physical dynamic timescale. Latency compensation (velocity projection $\hat{v} \cdot (\tau_{\text{plan}} + \tau_{\text{travel}})$) restores 100% reliability even at multi-second planning delays.
+
+---
+
+## 🚀 Quick Start
+
+### 1. One-Click Windows Launch (Desktop App)
+Clone the repository and double-click `start-app.bat`, or run from terminal:
+
+```bash
+git clone https://github.com/VedantJadhav701/OpenphysicalAI-lab.git
+cd OpenphysicalAI-lab
+
+# Optional: activate your existing Conda environment (auto-detected by main.js)
+conda activate thermo_agent
+
+npm install
+npm start
+```
+
+### 2. Pull the Recommended 4GB-Tier Local LLM Planner
+
+```bash
+ollama pull gemma2:2b
+
+# Or for the 4B Qwen3 planner:
+ollama pull qwen3:4b-instruct-2507-q4_K_M
+```
+
+### 3. Headless CLI & Phase-1 Gate Verification
+
+```bash
+python python/gate1.py
+pytest python/tests
+python -m openphysicalai.cli run --task pick_place --perception vision --perturb moderate --verifier V2 --episodes 50
+```
+
+---
+
+## 🏆 Community Hardware Leaderboard
+
+Run the benchmark suite on your machine, generate a signed Budget Card (`budget_card_run_*.md`), and submit a Pull Request to add your hardware configuration below!
+
+| Contributor | Device / GPU | Tier Class | Planner Model | Peak Device VRAM | Planning p95 | Recovery TSR | Energy / Ep | Budget Status |
+|---|---|---|---|---|---|---|---|---|
+| **@VedantJadhav701** | HP Victus 15 (RTX 3050 4GB, 16GB RAM) | `OPAI-4G` | `gemma2:2b` | 2.10 GB | 698 ms | 100.0% | ~92 J | ✅ PASS |
+| **@VedantJadhav701** | HP Victus 15 (RTX 3050 4GB, 16GB RAM) | `OPAI-4G` | `qwen3:4b-q4_K_M` | 2.53 GB | 1344 ms | 100.0% | 133.6 J | ✅ PASS |
+| *Your GitHub Handle* | *Add your GPU / Apple Silicon / CPU* | *OPAI-4G/8G/16G* | *Any Ollama Model* | *Measured GB* | *Measured ms* | *Measured %* | *Measured J* | *Submit PR!* |
+
+---
+
+## 🗂️ Repository Layout
+
+```text
+├── main.js / preload.js         # Electron main process, Conda auto-discovery, single-instance lock
+├── start-app.bat                # One-click Windows launcher
+├── src/                         # iOS-style Electron frontend UI
+├── python/
+│   ├── gate1.py                 # 200-scene deterministic Phase-1 physics gate
+│   ├── tests/                   # Pytest unit & integration test suite
+│   └── openphysicalai/          # Core engine: sim, tasks, skills, perception, render (3D GPU),
+│                                # planners, injection, runner, profiler, budget, store, cli
+└── docs/                        # Architectural roadmap & experimental specifications
+```
+
+---
+
+## 📄 License
+
+Licensed under the Apache License 2.0 — see [LICENSE](LICENSE) for full details.

openphysicalai-0.2.1/openphysicalai/__init__.py

@@ -0,0 +1,9 @@
+"""OpenPhysicalAI Lab core (early scaffold).
+
+Interfaces and budget logic only. MuJoCo backend, scheduler and real policies
+arrive in Phase 1+ (see docs/OpenPhysicalAI_Lab_Plan_v3.md).
+"""
+__version__ = "0.2.1"
+
+from .budget import Budget, BudgetCheck, evaluate_budget  # noqa: F401
+from .stats import wilson_interval  # noqa: F401

openphysicalai-0.2.1/openphysicalai/budget.py

@@ -0,0 +1,59 @@
+"""Budget contract: separate caps for process-attributed and device-wide usage."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass(frozen=True)
+class Budget:
+    vram_process_peak_gb: float = 3.2
+    vram_device_peak_gb: float = 3.8
+    ram_process_peak_gb: float = 8.0
+    ram_system_peak_gb: float = 14.0
+    planning_ms_p95: float = 2500.0
+    profile: str = "standard"
+
+
+@dataclass
+class BudgetCheck:
+    name: str
+    value: Optional[float]
+    cap: float
+    ok: bool
+    note: str = ""
+
+
+@dataclass
+class BudgetResult:
+    passed: bool
+    checks: List[BudgetCheck] = field(default_factory=list)
+
+
+def evaluate_budget(budget: Budget, observed: Dict[str, Optional[float]], not_applicable: tuple = ()) -> BudgetResult:
+    """Compare observed peaks to caps. A missing observation is a failure of measurement, not a pass.
+    `not_applicable` lists keys that do not apply on this machine (e.g. VRAM caps on a CPU-only machine)."""
+    spec = [
+        ("vram_process_peak_gb", budget.vram_process_peak_gb),
+        ("vram_device_peak_gb", budget.vram_device_peak_gb),
+        ("ram_process_peak_gb", budget.ram_process_peak_gb),
+        ("ram_system_peak_gb", budget.ram_system_peak_gb),
+        ("planning_ms_p95", budget.planning_ms_p95),
+    ]
+    checks: List[BudgetCheck] = []
+    for name, cap in spec:
+        v = observed.get(name)
+        if name in not_applicable:
+            checks.append(BudgetCheck(name, None, cap, True, "not applicable"))
+        elif v is None:
+            checks.append(BudgetCheck(name, None, cap, False, "not measured"))
+        else:
+            checks.append(BudgetCheck(name, float(v), cap, float(v) <= cap))
+    return BudgetResult(all(c.ok for c in checks), checks)
+
+
+PROFILES = {
+    "relaxed":  Budget(3.2, 3.8, 8.0, 14.0, 4000.0, "relaxed"),
+    "standard": Budget(3.2, 3.8, 8.0, 14.0, 2500.0, "standard"),
+    "strict":   Budget(3.2, 3.8, 8.0, 14.0, 500.0, "strict"),
+}

openphysicalai-0.2.1/openphysicalai/cli.py

@@ -0,0 +1,115 @@
+"""opai CLI (scaffold): `opai profile`, `opai check-budget`."""
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import shutil
+import subprocess
+import sys
+
+from . import __version__
+from .budget import Budget, evaluate_budget
+from .profiler import gpu_snapshot
+
+
+def cmd_profile(_args) -> int:
+    info = {
+        "version": __version__,
+        "os": platform.platform(),
+        "python": sys.version.split()[0],
+        "gpu": gpu_snapshot(),
+    }
+    print(json.dumps(info, indent=2))
+    return 0
+
+
+def cmd_doctor(_args) -> int:
+    import psutil
+    g = gpu_snapshot()
+    mem = psutil.virtual_memory()
+    cls = "CPU-only"
+    if g:
+        t = g["total_gb"]
+        cls = "OPAI-2G" if t <= 3 else "OPAI-4G" if t <= 6 else "OPAI-8G" if t <= 12 else "OPAI-16G"
+    doc = {
+        "version": __version__,
+        "platform": platform.platform(),
+        "python": sys.version.split()[0],
+        "processor": platform.processor(),
+        "cpu_count_physical": psutil.cpu_count(logical=False),
+        "cpu_count_logical": psutil.cpu_count(logical=True),
+        "ram_total_gb": round(mem.total / (1024**3), 2),
+        "ram_available_gb": round(mem.available / (1024**3), 2),
+        "hardware_class": cls,
+        "gpu": g,
+    }
+    print(json.dumps(doc, indent=2))
+    return 0
+
+
+def cmd_check_budget(args) -> int:
+    observed = json.loads(args.observed)
+    res = evaluate_budget(Budget(), observed)
+    print("PASS" if res.passed else "FAIL")
+    for c in res.checks:
+        print(f"  {'ok ' if c.ok else 'BAD'} {c.name}: {c.value} / {c.cap} {c.note}")
+    return 0 if res.passed else 1
+
+
+def cmd_run(args) -> int:
+    from .report import budget_card
+    from .runner import RunConfig, run
+    cfg_dict = {k: v for k, v in vars(args).items() if k not in ("cmd", "fn", "export_json") and v is not None}
+    cfg = RunConfig.from_dict(cfg_dict)
+    cfg.frames = False
+
+    reproduce_cmd = (
+        f"opai run --task {cfg.task} --policy {cfg.policy} --agent {cfg.agent} "
+        f"--perception {cfg.perception} --verifier {cfg.verifier} --perturb {cfg.perturb} "
+        f"--mode {cfg.mode} --budget {cfg.budget} --episodes {cfg.episodes} --seed {cfg.seed}"
+    )
+
+    def emit(e):
+        if e.get("event") == "progress" and e["done"] % 10 == 0:
+            print(f"  episode {e['done']}/{e['total']}  successes {e['successes']}", file=sys.stderr)
+
+    res = run(cfg, emit=emit)
+    res["reproduce_command"] = reproduce_cmd
+    card_text = budget_card(res)
+    print(card_text)
+    print(f"\nReproduce command:\n  {reproduce_cmd}\n")
+
+    if getattr(args, "export_json", None):
+        out_path = args.export_json
+        with open(out_path, "w") as f:
+            json.dump(res, f, indent=2)
+        print(f"Exported raw run data to {out_path}")
+
+    return 0
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="opai")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("profile").set_defaults(fn=cmd_profile)
+    sub.add_parser("doctor", help="inspect host hardware, NVML, and budget class").set_defaults(fn=cmd_doctor)
+    cb = sub.add_parser("check-budget")
+    cb.add_argument("observed", help='JSON, e.g. \'{"vram_process_peak_gb": 2.1}\'')
+    cb.set_defaults(fn=cmd_check_budget)
+    r = sub.add_parser("run", help="headless benchmark run, prints a Budget Card")
+    for name, default in (("task", "pick_place"), ("policy", "rule"), ("agent", "recovery"), ("perception", "oracle"), ("verifier", "V1"),
+                          ("perturb", "clean"), ("mode", "sync"), ("budget", "standard")):
+        r.add_argument("--" + name, default=default)
+    r.add_argument("--episodes", type=int, default=50)
+    r.add_argument("--seed", type=int, default=0)
+    r.add_argument("--extra-latency-ms", dest="extra_latency_ms", type=float, default=0.0)
+    r.add_argument("--velocity-lead", dest="velocity_lead", action=argparse.BooleanOptionalAction, default=True)
+    r.add_argument("--export-json", dest="export_json", type=str, default=None, help="path to export raw run.json")
+    r.set_defaults(fn=cmd_run)
+    args = p.parse_args(argv)
+    return args.fn(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

openphysicalai-0.2.1/openphysicalai/injection.py

@@ -0,0 +1,64 @@
+"""Seeded failure / perturbation injection. Ground truth of what was injected is logged for scoring
+only and is never exposed to the agent."""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Dict, List
+
+import numpy as np
+
+LEVELS = {
+    "clean":    {"p": 0.00, "pos_noise": 0.000, "pix_noise": 0.0},
+    "mild":     {"p": 0.10, "pos_noise": 0.010, "pix_noise": 8.0},
+    "moderate": {"p": 0.25, "pos_noise": 0.020, "pix_noise": 16.0},
+    "severe":   {"p": 0.40, "pos_noise": 0.035, "pix_noise": 28.0},
+}
+
+EXPECTED_DIAGNOSIS = {"grasp_slip": "object_dropped", "object_displaced": "grasp_miss", "wrong_placement": "wrong_placement"}
+
+
+@dataclass
+class Injector:
+    level: str
+    rng: np.random.Generator
+    log: List[Dict] = field(default_factory=list)
+
+    def __post_init__(self):
+        self.cfg = LEVELS[self.level]
+
+    @property
+    def pos_noise(self) -> float:
+        return self.cfg["pos_noise"]
+
+    @property
+    def pix_noise(self) -> float:
+        return self.cfg["pix_noise"]
+
+    def _roll(self) -> bool:
+        return self.cfg["p"] > 0 and self.rng.random() < self.cfg["p"]
+
+    def displace(self, world, oid: str, step: int) -> bool:
+        if self._roll():
+            ang = self.rng.uniform(0, 2 * math.pi)
+            d = self.rng.uniform(0.06, 0.09)
+            x0, y0 = world.obj_pos(oid)[:2]
+            nx, ny = x0 + d * math.cos(ang), y0 + d * math.sin(ang)
+            nx, ny = min(max(nx, 0.10), 0.36), min(max(ny, -0.25), 0.25)
+            world.teleport(oid, nx - x0, ny - y0)
+            self.log.append({"type": "object_displaced", "step": step, "object": oid})
+            return True
+        return False
+
+    def slip(self, step: int) -> bool:
+        if self._roll():
+            self.log.append({"type": "grasp_slip", "step": step})
+            return True
+        return False
+
+    def placement_offset(self, step: int):
+        if self._roll():
+            ang = self.rng.uniform(0, 2 * math.pi)
+            self.log.append({"type": "wrong_placement", "step": step})
+            return 0.12 * math.cos(ang), 0.12 * math.sin(ang)
+        return 0.0, 0.0