openphysicalai 0.2.1__py3-none-any.whl

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/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/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/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

openphysicalai/interfaces.py

@@ -0,0 +1,47 @@
+"""Core interfaces (frozen in Phase 0). Implementations arrive in later phases."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Literal, Optional, Protocol
+
+Track = Literal["planner", "learned", "hybrid", "scripted"]
+Assist = Literal["A0", "A1", "A2", "A3"]
+Verifier = Literal["V0", "V1", "V2"]
+
+
+@dataclass
+class EvaluationContract:
+    observation_access: tuple = ("rgb", "proprio")
+    control_hz: int = 20
+    action_space: str = "skill_level"
+    controller_assistance: Assist = "A3"
+    verifier_level: Verifier = "V1"
+    episodes: int = 100
+    seeds: str = "shared"
+
+
+@dataclass
+class ActionResult:
+    action: Any
+    t_obs_ns: int = 0
+    t_submit_ns: int = 0
+    t_ready_ns: int = 0
+    meta: Dict[str, Any] = field(default_factory=dict)
+
+
+class Policy(Protocol):
+    name: str
+    track: Track
+
+    def reset(self, task: str, seed: int, contract: EvaluationContract) -> None: ...
+
+    def act(self, obs: Any, world_state: Optional[dict] = None, deadline_ms: Optional[float] = None) -> ActionResult: ...
+
+
+class Backend(Protocol):
+    def reset(self, seed: int) -> Any: ...
+
+    def step(self, action: Any) -> Any: ...
+
+    def evaluation_oracle_success(self) -> bool:
+        """Ground-truth scoring. Never exposed to the agent."""

openphysicalai/perception.py

@@ -0,0 +1,237 @@
+"""Perception: Oracle (simulator truth + optional noise) and Vision (colour segmentation on the
+software top-down image with Alpha-Beta temporal velocity tracking). Both return the same WorldState dict."""
+from __future__ import annotations
+
+import math
+from collections import deque
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+
+from . import render as R
+from .sim import CONTAINER_HALF_IN, World
+
+
+def _in_box(x, y, c):
+    return abs(x - c[0]) < CONTAINER_HALF_IN and abs(y - c[1]) < CONTAINER_HALF_IN
+
+
+@dataclass
+class TrackedObjectState:
+    pos: np.ndarray
+    vel: np.ndarray
+    sim_time: float
+    samples: int = 1
+
+
+class TemporalVelocityTracker:
+    """Lightweight Alpha-Beta kinematic filter for VisionPerception.
+    Estimates 3D object velocity (vx, vy, vz) purely from sequential
+    top-down colour-segmentation centroids without touching MuJoCo qvel."""
+
+    def __init__(
+        self,
+        alpha: float = 0.75,
+        beta: float = 0.45,
+        max_speed_mps: float = 0.50,
+        min_dt: float = 1e-3,
+        max_dt: float = 5.0,
+    ) -> None:
+        self.alpha = alpha
+        self.beta = beta
+        self.max_speed_mps = max_speed_mps
+        self.min_dt = min_dt
+        self.max_dt = max_dt
+        self._tracks: Dict[str, TrackedObjectState] = {}
+
+    def reset(self) -> None:
+        self._tracks.clear()
+
+    def update(
+        self, obj_id: str, measured_pos: np.ndarray, sim_time: float
+    ) -> Tuple[np.ndarray, np.ndarray]:
+        pos = np.asarray(measured_pos, dtype=np.float64)
+        if obj_id not in self._tracks:
+            self._tracks[obj_id] = TrackedObjectState(
+                pos=pos.copy(),
+                vel=np.zeros(3, dtype=np.float64),
+                sim_time=sim_time,
+                samples=1,
+            )
+            return pos.copy(), np.zeros(3, dtype=np.float64)
+
+        prev = self._tracks[obj_id]
+        dt = sim_time - prev.sim_time
+
+        if dt < self.min_dt or dt > self.max_dt:
+            self._tracks[obj_id] = TrackedObjectState(
+                pos=pos.copy(),
+                vel=prev.vel.copy() if abs(dt) < self.min_dt else np.zeros(3, dtype=np.float64),
+                sim_time=sim_time,
+                samples=prev.samples + 1,
+            )
+            return pos.copy(), self._tracks[obj_id].vel.copy()
+
+        pred_pos = prev.pos + prev.vel * dt
+        residual = pos - pred_pos
+
+        new_pos = pred_pos + self.alpha * residual
+        raw_vel = (pos - prev.pos) / dt
+        new_vel = prev.vel + (self.beta / dt) * residual if prev.samples > 2 else raw_vel
+
+        speed = float(np.linalg.norm(new_vel[:2]))
+        if speed < 0.004:
+            new_vel[:] = 0.0
+        elif speed > self.max_speed_mps:
+            new_vel = new_vel * (self.max_speed_mps / speed)
+
+        new_vel[2] = 0.0
+
+        self._tracks[obj_id] = TrackedObjectState(
+            pos=new_pos,
+            vel=new_vel,
+            sim_time=sim_time,
+            samples=prev.samples + 1,
+        )
+        return new_pos.copy(), new_vel.copy()
+
+    @staticmethod
+    def predict_intercept(
+        pos: np.ndarray,
+        vel: np.ndarray,
+        planner_latency_s: float,
+        arm_travel_time_s: float = 0.32,
+        workspace_bounds: Tuple[Tuple[float, float], Tuple[float, float]] = (
+            (0.10, 0.36),
+            (-0.25, 0.25),
+        ),
+    ) -> np.ndarray:
+        total_lead_s = max(0.0, float(planner_latency_s)) + max(0.0, float(arm_travel_time_s))
+        intercept = np.asarray(pos, dtype=np.float64).copy()
+        intercept[:2] += np.asarray(vel[:2], dtype=np.float64) * total_lead_s
+        (x_min, x_max), (y_min, y_max) = workspace_bounds
+        intercept[0] = float(np.clip(intercept[0], x_min, x_max))
+        intercept[1] = float(np.clip(intercept[1], y_min, y_max))
+        return intercept
+
+
+class OraclePerception:
+    name = "oracle"
+
+    def __init__(self, rng: np.random.Generator, pos_noise: float = 0.0):
+        self.rng, self.pos_noise = rng, pos_noise
+
+    def perceive(self, w: World) -> Dict:
+        c = w.spec.container_pos
+        objs = []
+        for o in w.spec.objects:
+            p = w.obj_pos(o.oid)
+            n = self.rng.normal(0, self.pos_noise, 2) if self.pos_noise > 0 else (0.0, 0.0)
+            x, y = float(p[0] + n[0]), float(p[1] + n[1])
+            d = {"id": o.oid, "color": o.color, "half_size": o.half, "x": round(x, 3), "y": round(y, 3),
+                 "yaw": round(w.obj_yaw(o.oid), 3), "in_container": bool(w.in_container(o.oid))}
+            if np.any(w.vel[o.oid]):
+                d["velocity_y"] = float(w.vel[o.oid][1])
+            objs.append(d)
+        tip = w.tip()
+        return {"t": round(w.time, 3), "source": "oracle", "container": {"x": c[0], "y": c[1]},
+                "gripper": {"closure": round(w.finger_closure(), 4), "tip": [round(float(v), 3) for v in tip]}, "objects": objs}
+
+
+def _components(mask: np.ndarray, min_px: int = 30):
+    h, w = mask.shape
+    seen = np.zeros_like(mask, bool)
+    out = []
+    for r0, c0 in zip(*np.nonzero(mask)):
+        if seen[r0, c0]:
+            continue
+        q = deque([(r0, c0)])
+        seen[r0, c0] = True
+        pix = []
+        while q:
+            r, c = q.popleft()
+            pix.append((r, c))
+            for dr, dc in ((1, 0), (-1, 0), (0, 1), (0, -1)):
+                rr, cc = r + dr, c + dc
+                if 0 <= rr < h and 0 <= cc < w and mask[rr, cc] and not seen[rr, cc]:
+                    seen[rr, cc] = True
+                    q.append((rr, cc))
+        if len(pix) >= min_px:
+            out.append(np.array(pix))
+    return out
+
+
+class VisionPerception:
+    name = "vision"
+
+    def __init__(self, rng: np.random.Generator, pixel_noise: float = 0.0, enable_velocity_tracker: bool = True):
+        self.rng, self.pixel_noise = rng, pixel_noise
+        self.enable_velocity_tracker = enable_velocity_tracker
+        self.tracker = TemporalVelocityTracker(alpha=0.80, beta=0.55)
+
+    def _detect_raw(self, w: World) -> List[Dict]:
+        img = R.render(w, draw_arm=False, rng=self.rng, noise=self.pixel_noise)
+        f = img.astype(np.int32)
+        objs: List[Dict] = []
+        k = 0
+        for color in ("red", "green", "yellow", "orange"):
+            ref = np.array(R.PALETTE[color])
+            m = (np.abs(f - ref).sum(axis=2) < 60 + 3 * self.pixel_noise)
+            for pix in _components(m):
+                cy_, cx_ = pix.mean(axis=0)
+                x, y = R.px_to_world(cy_ + 0.5, cx_ + 0.5)
+                area_m2 = len(pix) * R.RES_X * R.RES_Y
+                half = math.sqrt(area_m2) / 2
+                d = pix - pix.mean(axis=0)
+                wx, wy = -d[:, 0] * R.RES_X, -d[:, 1] * R.RES_Y
+                zc = np.sum((wx + 1j * wy) ** 4)
+                yaw = ((np.angle(zc) - math.pi) / 4) % (math.pi / 2)
+                objs.append({
+                    "id": f"obj_{k}",
+                    "color": color,
+                    "half_size": round(half, 3),
+                    "x": round(x, 3),
+                    "y": round(y, 3),
+                    "_raw_x": float(x),
+                    "_raw_y": float(y),
+                    "yaw": round(yaw, 3),
+                    "in_container": bool(_in_box(x, y, w.spec.container_pos)),
+                })
+                k += 1
+        return objs
+
+    def perceive(self, w: World) -> Dict:
+        raw_objs = self._detect_raw(w)
+        # Cold-start optical burst: step 100 physics ticks (0.20s) so a 0.02 m/s cube
+        # shifts by 4.0mm (~1.7 pixels), overcoming 2.34mm/px quantization on frame 1.
+        if self.enable_velocity_tracker and not self.tracker._tracks:
+            t0 = w.time
+            for o in raw_objs:
+                self.tracker.update(o["color"] + "_" + o["id"], np.array([o["_raw_x"], o["_raw_y"], 0.0]), t0)
+            if any(np.any(v) for v in w.vel.values()):
+                w.step(100)
+                raw_objs = self._detect_raw(w)
+
+        objs: List[Dict] = []
+        for o in raw_objs:
+            rx, ry = o.pop("_raw_x"), o.pop("_raw_y")
+            d = dict(o)
+            if self.enable_velocity_tracker:
+                track_key = o["color"] + "_" + o["id"]
+                filt_pos, est_vel = self.tracker.update(track_key, np.array([rx, ry, 0.0]), w.time)
+                d["x"] = round(float(filt_pos[0]), 3)
+                d["y"] = round(float(filt_pos[1]), 3)
+                if abs(est_vel[1]) >= 0.006:
+                    d["velocity_y"] = float(round(est_vel[1], 4))
+            objs.append(d)
+
+        c = w.spec.container_pos
+        tip = w.tip()
+        return {
+            "t": round(w.time, 3),
+            "source": "vision",
+            "container": {"x": c[0], "y": c[1]},
+            "gripper": {"closure": round(w.finger_closure(), 4), "tip": [round(float(v), 3) for v in tip]},
+            "objects": objs,
+        }