lang2sim 2.0.0__py3-none-any.whl

lang2sim/runtime/docker_runner.py

@@ -0,0 +1,286 @@
+"""
+Starts/stops the sim container. The user never runs Docker themselves.
+File: lang2sim/runtime/docker_runner.py
+
+`build_run_args()` is pure (RunOptions -> argv) so every display/GPU/mount
+combination is unit-tested without Docker. `DockerRunner` shells out to the
+docker CLI (no SDK dependency) and takes an injectable `run` for tests.
+
+Ports are published on 127.0.0.1 only (noVNC has no password):
+    9090 control API, 8765 foxglove_bridge, 6080 noVNC.
+"""
+
+from __future__ import annotations
+
+import importlib
+import json
+import os
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+from typing import Callable, Dict, List, Optional, Sequence
+
+from lang2sim.runtime.display import DisplayPlan
+
+# NB: `from lang2sim.core import config` yields the Config *instance* (core/__init__
+# re-exports it under the module's name), so load the module explicitly.
+cfg = importlib.import_module("lang2sim.core.config")
+
+CONTAINER_NAME = "lang2sim-sim"
+LABEL = "dev.lang2sim.role=sim"
+SIM_USER = "lang2sim"  # runtime user in docker/sim/Dockerfile
+
+# In-container ports are fixed by the image; host ports are configurable.
+CONTAINER_API_PORT = 9090
+CONTAINER_FOXGLOVE_PORT = 8765
+CONTAINER_NOVNC_PORT = 6080
+
+RunFn = Callable[..., "subprocess.CompletedProcess[str]"]
+
+
+class DockerError(RuntimeError):
+    def __init__(self, message: str, stderr: str = ""):
+        super().__init__(message if not stderr else f"{message}: {stderr.strip()}")
+        self.stderr = stderr
+
+
+@dataclass(frozen=True)
+class RunOptions:
+    image: str
+    plan: DisplayPlan
+    projects_dir: Path
+    catalog_dir: Optional[Path] = None
+    src_dir: Optional[Path] = None          # dev: bind-mount the repo over the baked-in package
+    host_uid: Optional[int] = None
+    host_gid: Optional[int] = None
+    api_port: int = CONTAINER_API_PORT
+    foxglove_port: int = CONTAINER_FOXGLOVE_PORT
+    novnc_port: int = CONTAINER_NOVNC_PORT
+    host_env: Dict[str, str] = field(default_factory=dict)  # DISPLAY, WAYLAND_DISPLAY, XAUTHORITY
+    has_dxg: bool = False
+    extra_env: Dict[str, str] = field(default_factory=dict)
+    name: str = CONTAINER_NAME
+    shm_size: str = "2g"
+    command: Sequence[str] = ("serve",)
+
+
+# ---------------------------------------------------------------------------
+# Pure helpers
+# ---------------------------------------------------------------------------
+
+def image_for(base_image: str, plan: DisplayPlan) -> str:
+    """Pick the `-vnc` tag variant when the plan needs it.
+
+    ghcr.io/x/lang2sim-sim:staging  + vnc -> ghcr.io/x/lang2sim-sim:staging-vnc
+    """
+    if plan.image_variant != "sim-vnc":
+        return base_image
+    name, sep, tag = base_image.rpartition(":")
+    if not sep or "/" in tag:  # no tag (the ':' was a registry port)
+        return f"{base_image}:latest-vnc"
+    return base_image if tag.endswith("-vnc") else f"{name}:{tag}-vnc"
+
+
+def host_to_container_path(host_path: Path, projects_dir: Path) -> str:
+    """Map a host path under projects_dir to its path inside the container."""
+    rel = Path(host_path).resolve().relative_to(Path(projects_dir).resolve())
+    return str(PurePosixPath(cfg.CONTAINER_PROJECTS_DIR, *rel.parts))
+
+
+def build_run_args(opts: RunOptions) -> List[str]:
+    """argv after `docker` for starting the sim container (detached)."""
+    plan = opts.plan
+    a: List[str] = ["run", "-d", "--name", opts.name, "--label", LABEL,
+                    "--shm-size", opts.shm_size]
+
+    def env(k: str, v: object) -> None:
+        a.extend(["-e", f"{k}={v}"])
+
+    def mount(src: object, dst: str, ro: bool = False) -> None:
+        a.extend(["-v", f"{src}:{dst}{':ro' if ro else ''}"])
+
+    # Ports (localhost only)
+    a.extend(["-p", f"127.0.0.1:{opts.api_port}:{CONTAINER_API_PORT}"])
+    if plan.foxglove:
+        a.extend(["-p", f"127.0.0.1:{opts.foxglove_port}:{CONTAINER_FOXGLOVE_PORT}"])
+    if plan.mode == "vnc":
+        a.extend(["-p", f"127.0.0.1:{opts.novnc_port}:{CONTAINER_NOVNC_PORT}"])
+
+    # Identity + plan (read by docker/sim/entrypoint.sh)
+    if opts.host_uid is not None:
+        env("L2S_HOST_UID", opts.host_uid)
+    if opts.host_gid is not None:
+        env("L2S_HOST_GID", opts.host_gid)
+    env("L2S_DISPLAY_MODE", plan.mode)
+    env("L2S_GPU", plan.gpu)
+    env("L2S_FOXGLOVE", 1 if plan.foxglove else 0)
+
+    # Data
+    mount(opts.projects_dir, cfg.CONTAINER_PROJECTS_DIR)
+    if opts.catalog_dir is not None:
+        mount(opts.catalog_dir, cfg.CONTAINER_CATALOG_DIR, ro=True)
+    if opts.src_dir is not None:
+        mount(opts.src_dir, cfg.CONTAINER_SRC_DIR, ro=True)
+
+    # Display
+    if plan.mode == "x11":
+        mount("/tmp/.X11-unix", "/tmp/.X11-unix")
+        env("DISPLAY", opts.host_env.get("DISPLAY", ":0"))
+        xauth = opts.host_env.get("XAUTHORITY")
+        if xauth:
+            mount(xauth, "/tmp/.Xauthority", ro=True)
+            env("XAUTHORITY", "/tmp/.Xauthority")
+    elif plan.mode == "wslg":
+        mount("/tmp/.X11-unix", "/tmp/.X11-unix")
+        mount("/mnt/wslg", "/mnt/wslg")
+        env("DISPLAY", opts.host_env.get("DISPLAY", ":0"))
+        env("WAYLAND_DISPLAY", opts.host_env.get("WAYLAND_DISPLAY", "wayland-0"))
+        env("XDG_RUNTIME_DIR", "/mnt/wslg/runtime-dir")
+        env("PULSE_SERVER", "/mnt/wslg/PulseServer")
+
+    # GPU
+    if plan.gpu == "nvidia":
+        a.extend(["--gpus", "all"])
+    elif plan.gpu == "dri":
+        if plan.mode == "wslg" and opts.has_dxg:
+            a.extend(["--device", "/dev/dxg"])
+            mount("/usr/lib/wsl", "/usr/lib/wsl", ro=True)
+        else:
+            a.extend(["--device", "/dev/dri"])
+
+    for k, v in sorted(opts.extra_env.items()):
+        env(k, v)
+
+    a.append(opts.image)
+    a.extend(opts.command)
+    return a
+
+
+def default_run_options(plan: DisplayPlan, *, image: Optional[str] = None,
+                        project_src: Optional[Path] = None,
+                        host_env: Optional[Dict[str, str]] = None,
+                        has_dxg: bool = False) -> RunOptions:
+    """RunOptions from core.config for this user (paths, ports, uid)."""
+    projects = cfg.get_projects_dir()
+    catalog = cfg.get_catalog_dir()
+    uid = os.getuid() if hasattr(os, "getuid") else None
+    gid = os.getgid() if hasattr(os, "getgid") else None
+    return RunOptions(
+        image=image_for(image or cfg.DEFAULT_SIM_IMAGE, plan),
+        plan=plan,
+        projects_dir=projects,
+        catalog_dir=catalog if catalog.is_dir() else None,
+        src_dir=project_src,
+        host_uid=uid,
+        host_gid=gid,
+        api_port=cfg.DEFAULT_CONTROL_PORT,
+        foxglove_port=cfg.DEFAULT_FOXGLOVE_PORT,
+        novnc_port=cfg.DEFAULT_NOVNC_PORT,
+        host_env=dict(host_env or {}),
+        has_dxg=has_dxg,
+    )
+
+
+def allow_local_x11_clients() -> bool:
+    """`xhost +SI:localuser:<me>`: let containers running as our UID draw on X.
+
+    Needed on Ubuntu desktops (X/XWayland reject unknown clients by default).
+    No-op where xhost or DISPLAY is missing. Returns True if it ran.
+    """
+    import getpass
+    import shutil
+
+    if not os.environ.get("DISPLAY") or not shutil.which("xhost"):
+        return False
+    try:
+        subprocess.run(["xhost", f"+SI:localuser:{getpass.getuser()}"],
+                       capture_output=True, timeout=5, check=False)
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return True
+
+
+# ---------------------------------------------------------------------------
+# Docker CLI wrapper
+# ---------------------------------------------------------------------------
+
+class DockerRunner:
+    def __init__(self, docker: str = "docker", run: RunFn = subprocess.run):
+        self.docker = docker
+        self._run = run
+
+    def _call(self, args: Sequence[str], check: bool = True, timeout: Optional[float] = 60,
+              ) -> "subprocess.CompletedProcess[str]":
+        try:
+            cp = self._run([self.docker, *args], capture_output=True, text=True,
+                           timeout=timeout, check=False)
+        except FileNotFoundError as e:
+            raise DockerError("docker CLI not found") from e
+        except subprocess.TimeoutExpired as e:
+            raise DockerError(f"`docker {args[0]}` timed out") from e
+        if check and cp.returncode != 0:
+            raise DockerError(f"`docker {' '.join(args[:2])}` failed", cp.stderr)
+        return cp
+
+    # images
+    def image_present(self, image: str) -> bool:
+        return self._call(["image", "inspect", image], check=False).returncode == 0
+
+    def pull(self, image: str) -> None:
+        self._call(["pull", image], timeout=None)
+
+    def ensure_image(self, image: str) -> bool:
+        """Pull if missing. Returns True if a pull happened."""
+        if self.image_present(image):
+            return False
+        self.pull(image)
+        return True
+
+    # containers
+    def inspect(self, name: str = CONTAINER_NAME) -> Optional[dict]:
+        cp = self._call(["container", "inspect", name], check=False)
+        if cp.returncode != 0:
+            return None
+        data = json.loads(cp.stdout or "[]")
+        return data[0] if data else None
+
+    def state(self, name: str = CONTAINER_NAME) -> Optional[dict]:
+        """Docker's .State (Status, Running, ExitCode, Health, ...) or None if absent."""
+        info = self.inspect(name)
+        return info.get("State") if info else None
+
+    def is_running(self, name: str = CONTAINER_NAME) -> bool:
+        st = self.state(name)
+        return bool(st and st.get("Running"))
+
+    def start(self, opts: RunOptions, replace: bool = True) -> str:
+        """Start the container; returns its id. Replaces a stale one by default."""
+        if self.inspect(opts.name) is not None:
+            if not replace:
+                raise DockerError(f"container {opts.name} already exists")
+            self.remove(opts.name)
+        if opts.plan.mode == "x11":
+            allow_local_x11_clients()
+        cp = self._call(build_run_args(opts), timeout=120)
+        return cp.stdout.strip()
+
+    def stop(self, name: str = CONTAINER_NAME, timeout: int = 10) -> None:
+        self._call(["stop", "-t", str(timeout), name], check=False, timeout=timeout + 30)
+
+    def remove(self, name: str = CONTAINER_NAME) -> None:
+        self._call(["rm", "-f", name], check=False)
+
+    def logs(self, name: str = CONTAINER_NAME, tail: int = 200) -> str:
+        cp = self._call(["logs", "--tail", str(tail), name], check=False)
+        return (cp.stdout or "") + (cp.stderr or "")
+
+    def exec(self, cmd: Sequence[str], name: str = CONTAINER_NAME,
+             timeout: Optional[float] = 60, user: str = SIM_USER,
+             ) -> "subprocess.CompletedProcess[str]":
+        """Run a command in the container as the sim user.
+
+        Must match the user the sim runs as: ROS 2's default (Fast DDS) shared
+        memory transport is per-user, so a root `ros2 topic echo` discovers
+        topics but never receives data.
+        """
+        return self._call(["exec", "-u", user, name, *cmd], check=False, timeout=timeout)

lang2sim/runtime/doctor.py

@@ -0,0 +1,220 @@
+"""
+`lang2sim doctor`: can this machine run the simulation, and how will it look?
+File: lang2sim/runtime/doctor.py
+
+Part 2 wires the CLI subcommand to `run_checks()` / `format_report()`.
+Standalone:  python -m lang2sim.runtime.doctor [--json] [--display vnc] [--api]
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib
+import json
+import shutil
+import socket
+import sys
+from dataclasses import asdict, dataclass
+from typing import List, Literal, Optional
+
+from lang2sim.runtime import hardware_probe
+from lang2sim.runtime import platform as host_platform
+from lang2sim.runtime.display import DISPLAY_MODES, DisplayPlan, choose_display
+from lang2sim.runtime.docker_runner import CONTAINER_NAME, DockerRunner, image_for
+
+# NB: `from lang2sim.core import config` yields the Config *instance* (core/__init__
+# re-exports it under the module's name), so load the module explicitly.
+cfg = importlib.import_module("lang2sim.core.config")
+
+Status = Literal["ok", "warn", "fail"]
+
+MIN_DISK_GB = 10
+MIN_RAM_MB = 8 * 1024
+MIN_DOCKER_MEM_MB = 6 * 1024
+MIN_DOCKER_CPUS = 4
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    name: str
+    status: Status
+    detail: str
+    fix: Optional[str] = None
+
+
+def _port_free(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            s.bind(("127.0.0.1", port))
+        except OSError:
+            return False
+    return True
+
+
+def run_checks(plat: Optional[host_platform.HostPlatform] = None,
+               hw: Optional[hardware_probe.HardwareInfo] = None,
+               prefer_display: Optional[str] = None,
+               image: Optional[str] = None,
+               runner: Optional[DockerRunner] = None,
+               check_api: bool = False) -> List[CheckResult]:
+    plat = plat or host_platform.detect()
+    hw = hw or hardware_probe.probe()
+    runner = runner or DockerRunner()
+    r: List[CheckResult] = []
+    d = plat.docker
+
+    # Docker
+    if not d.installed:
+        fix = {"macos": "Install Docker Desktop: https://docs.docker.com/desktop/setup/install/mac-install/",
+               "windows": "Install Docker Desktop with the WSL 2 backend",
+               "wsl": "Install Docker Desktop on Windows and enable WSL integration for this distro",
+               }.get(plat.os, "Install Docker Engine: https://docs.docker.com/engine/install/ubuntu/")
+        r.append(CheckResult("docker", "fail", "docker CLI not found", fix))
+    elif not d.server_reachable:
+        r.append(CheckResult("docker", "fail", d.error or "daemon not reachable",
+                             "Start Docker Desktop" if plat.os in ("macos", "windows", "wsl")
+                             else "sudo systemctl start docker && sudo usermod -aG docker $USER"))
+    else:
+        r.append(CheckResult("docker", "ok", f"{d.operating_system or 'docker'} {d.server_version} ({d.arch})"))
+        if plat.arch != "unknown" and d.arch != "unknown" and plat.arch != d.arch:
+            r.append(CheckResult("docker arch", "warn",
+                                 f"host is {plat.arch} but daemon is {d.arch}; image runs emulated (slow)"))
+
+        # Docker Desktop's VM often gets less than the machine has; Gazebo + Nav2 need room.
+        if d.mem_total_mb and d.mem_total_mb < MIN_DOCKER_MEM_MB:
+            r.append(CheckResult("docker memory", "warn",
+                                 f"Docker can use {d.mem_total_mb / 1024:.1f} GB; Gazebo + Nav2 want 6 GB+",
+                                 "Docker Desktop > Settings > Resources > Memory: 8 GB"
+                                 if d.is_desktop else "free memory or add swap"))
+        if d.cpus and d.cpus < MIN_DOCKER_CPUS:
+            r.append(CheckResult("docker cpus", "warn",
+                                 f"Docker can use {d.cpus} CPUs; the sim will run below real time",
+                                 "Docker Desktop > Settings > Resources > CPUs: 4+" if d.is_desktop else None))
+    if plat.os == "windows":
+        r.append(CheckResult("windows", "warn",
+                             "running outside WSL2: no native windows, the sim opens in a browser (noVNC)",
+                             "for Gazebo/RViz windows, run lang2sim from an Ubuntu terminal inside WSL2"))
+
+    # Display plan
+    plan: Optional[DisplayPlan] = None
+    try:
+        plan = choose_display(plat, hw, prefer=prefer_display)  # type: ignore[arg-type]
+        r.append(CheckResult("display", "ok", plan.describe() + " — " + "; ".join(plan.reasons)))
+    except ValueError as e:
+        r.append(CheckResult("display", "fail", str(e), f"use one of {', '.join(DISPLAY_MODES)}"))
+
+    if plan and plan.mode == "x11" and plat.display:
+        r.append(CheckResult("x11", "ok", f"DISPLAY={plat.display}",
+                             None))
+        if not shutil.which("xhost"):
+            r.append(CheckResult("xhost", "warn", "xhost not found; container may be refused by X",
+                                 "sudo apt install x11-xserver-utils"))
+    if plan and plan.mode == "wslg" and not hw.has_dxg:
+        r.append(CheckResult("wsl gpu", "warn", "/dev/dxg missing: software rendering",
+                             "Update the Windows GPU driver and `wsl --update`"))
+    nv = hw.nvidia
+    if nv and d.server_reachable and not d.has_nvidia_runtime:
+        r.append(CheckResult("nvidia toolkit", "warn", "NVIDIA GPU but Docker has no nvidia runtime",
+                             "Install nvidia-container-toolkit, then `sudo nvidia-ctk runtime configure "
+                             "--runtime=docker && sudo systemctl restart docker`"))
+
+    # Image
+    if plan and d.server_reachable:
+        img = image_for(image or cfg.DEFAULT_SIM_IMAGE, plan)
+        try:
+            present = runner.image_present(img)
+        except Exception as e:  # noqa: BLE001 - doctor must not crash
+            present, err = False, str(e)
+        else:
+            err = ""
+        if present:
+            r.append(CheckResult("image", "ok", img))
+        else:
+            r.append(CheckResult("image", "warn", f"{img} not pulled yet {err}".strip(),
+                                 f"docker pull {img}  (~1.5 GB; first `lang2sim` run does this)"))
+
+    # Ports
+    ours = False
+    try:
+        ours = d.server_reachable and runner.is_running(CONTAINER_NAME)
+    except Exception:  # noqa: BLE001
+        pass
+    ports = {"control API": cfg.DEFAULT_CONTROL_PORT}
+    if plan and plan.foxglove:
+        ports["foxglove"] = cfg.DEFAULT_FOXGLOVE_PORT
+    if plan and plan.mode == "vnc":
+        ports["noVNC"] = cfg.DEFAULT_NOVNC_PORT
+    for label, port in ports.items():
+        if _port_free(port):
+            r.append(CheckResult(f"port {port}", "ok", f"{label} port free"))
+        elif ours:
+            r.append(CheckResult(f"port {port}", "ok", f"{label} served by running {CONTAINER_NAME}"))
+        else:
+            r.append(CheckResult(f"port {port}", "fail", f"{label} port {port} in use",
+                                 f"free it or set L2S_{'API' if label == 'control API' else label.upper()}_PORT"))
+
+    # Resources
+    try:
+        free_gb = shutil.disk_usage(cfg.get_projects_dir()).free / 1e9
+        r.append(CheckResult("disk", "ok" if free_gb >= MIN_DISK_GB else "warn",
+                             f"{free_gb:.0f} GB free in {cfg.get_projects_dir()}"))
+    except OSError as e:
+        r.append(CheckResult("disk", "warn", str(e)))
+    if hw.mem_total_mb:
+        r.append(CheckResult("memory", "ok" if hw.mem_total_mb >= MIN_RAM_MB else "warn",
+                             f"{hw.mem_total_mb // 1024} GB RAM"
+                             + ("" if hw.mem_total_mb >= MIN_RAM_MB else " (Gazebo + Nav2 want 8 GB+)")))
+
+    # Live API (optional)
+    if check_api:
+        r.append(asyncio.run(_check_api()))
+    return r
+
+
+async def _check_api() -> CheckResult:
+    from lang2sim.runtime.control_api.client import ControlAPIError, ControlClient
+
+    try:
+        async with ControlClient(timeout=3) as api:
+            h = await api.health()
+            i = await api.info()
+        return CheckResult("control API", "ok",
+                           f"v{h.get('version')} display={i.get('display_mode')} gpu={i.get('gpu')}")
+    except ControlAPIError as e:
+        return CheckResult("control API", "warn", str(e), "Start the sim (it boots the container)")
+
+
+def format_report(results: List[CheckResult]) -> str:
+    icon = {"ok": "✓", "warn": "!", "fail": "✗"}
+    lines = []
+    for c in results:
+        lines.append(f" {icon[c.status]} {c.name:<16} {c.detail}")
+        if c.fix and c.status != "ok":
+            lines.append(f"   {'':<16} fix: {c.fix}")
+    worst = "fail" if any(c.status == "fail" for c in results) else \
+            "warn" if any(c.status == "warn" for c in results) else "ok"
+    lines.append({"ok": "\nReady to simulate.", "warn": "\nUsable, with warnings.",
+                  "fail": "\nNot ready: fix the ✗ items above."}[worst])
+    return "\n".join(lines)
+
+
+def exit_code(results: List[CheckResult]) -> int:
+    return 1 if any(c.status == "fail" for c in results) else 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    ap = argparse.ArgumentParser(prog="lang2sim doctor")
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument("--display", choices=DISPLAY_MODES)
+    ap.add_argument("--image")
+    ap.add_argument("--api", action="store_true", help="also query a running control API")
+    a = ap.parse_args(argv)
+    res = run_checks(prefer_display=a.display, image=a.image, check_api=a.api)
+    print(json.dumps([asdict(c) for c in res], indent=2) if a.json else format_report(res))
+    return exit_code(res)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

lang2sim/runtime/hardware_probe.py

@@ -0,0 +1,144 @@
+"""
+Host hardware introspection: GPUs, VRAM, RAM, render nodes.
+File: lang2sim/runtime/hardware_probe.py
+
+Parsing is split from probing so the parsers are unit-testable without the
+hardware. `probe()` never raises; missing tools just mean less information.
+"""
+
+from __future__ import annotations
+
+import glob
+import os
+import platform as _platform
+import shutil
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Literal, Optional
+
+GpuVendor = Literal["nvidia", "intel", "amd", "apple", "unknown"]
+
+# Decision 4: below this much VRAM we render in software (GUI stays on).
+LOW_VRAM_MB = 2048
+
+_PCI_VENDORS = {"0x10de": "nvidia", "0x8086": "intel", "0x1002": "amd"}
+
+
+@dataclass(frozen=True)
+class GpuInfo:
+    vendor: GpuVendor
+    name: str = ""
+    vram_total_mb: Optional[int] = None
+    vram_free_mb: Optional[int] = None
+
+
+@dataclass(frozen=True)
+class HardwareInfo:
+    cpu_count: int = 1
+    mem_total_mb: Optional[int] = None
+    gpus: List[GpuInfo] = field(default_factory=list)
+    dri_render_nodes: List[str] = field(default_factory=list)
+    has_dxg: bool = False  # WSL2 GPU paravirtualisation (/dev/dxg)
+
+    @property
+    def nvidia(self) -> Optional[GpuInfo]:
+        return next((g for g in self.gpus if g.vendor == "nvidia"), None)
+
+    @property
+    def max_vram_mb(self) -> Optional[int]:
+        vals = [g.vram_total_mb for g in self.gpus if g.vram_total_mb is not None]
+        return max(vals) if vals else None
+
+
+# ---------------------------------------------------------------------------
+# Parsers (pure)
+# ---------------------------------------------------------------------------
+
+def parse_nvidia_smi(csv_text: str) -> List[GpuInfo]:
+    """Parse `nvidia-smi --query-gpu=name,memory.total,memory.free --format=csv,noheader,nounits`."""
+    gpus: List[GpuInfo] = []
+    for line in csv_text.strip().splitlines():
+        parts = [p.strip() for p in line.split(",")]
+        if len(parts) < 3:
+            continue
+        name, total, free = parts[0], parts[1], parts[2]
+        gpus.append(GpuInfo("nvidia", name, _to_int(total), _to_int(free)))
+    return gpus
+
+
+def parse_meminfo(text: str) -> Optional[int]:
+    """MemTotal from /proc/meminfo, in MB."""
+    for line in text.splitlines():
+        if line.startswith("MemTotal:"):
+            kb = _to_int(line.split()[1])
+            return kb // 1024 if kb is not None else None
+    return None
+
+
+def vendor_from_pci_id(vendor_id: str) -> GpuVendor:
+    return _PCI_VENDORS.get(vendor_id.strip().lower(), "unknown")  # type: ignore[return-value]
+
+
+def _to_int(s: str) -> Optional[int]:
+    try:
+        return int(float(s))
+    except (TypeError, ValueError):
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Probes
+# ---------------------------------------------------------------------------
+
+def _run(cmd: List[str], timeout: float = 5.0) -> Optional[str]:
+    if not shutil.which(cmd[0]):
+        return None
+    try:
+        out = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, check=False)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return out.stdout if out.returncode == 0 else None
+
+
+def _probe_nvidia() -> List[GpuInfo]:
+    out = _run(["nvidia-smi", "--query-gpu=name,memory.total,memory.free",
+                "--format=csv,noheader,nounits"])
+    return parse_nvidia_smi(out) if out else []
+
+
+def _probe_dri() -> List[GpuInfo]:
+    gpus: List[GpuInfo] = []
+    for node in sorted(glob.glob("/sys/class/drm/renderD*/device/vendor")):
+        try:
+            vendor = vendor_from_pci_id(Path(node).read_text())
+        except OSError:
+            continue
+        if vendor != "nvidia":  # NVIDIA is covered (with VRAM) by nvidia-smi
+            gpus.append(GpuInfo(vendor))
+    return gpus
+
+
+def _probe_mem_mb() -> Optional[int]:
+    try:
+        return parse_meminfo(Path("/proc/meminfo").read_text())
+    except OSError:
+        pass
+    out = _run(["sysctl", "-n", "hw.memsize"])  # macOS
+    if out and out.strip().isdigit():
+        return int(out.strip()) // (1024 * 1024)
+    return None
+
+
+def probe() -> HardwareInfo:
+    """Best-effort snapshot of this host. Never raises."""
+    gpus = _probe_nvidia() + _probe_dri()
+    if _platform.system() == "Darwin" and _platform.machine() == "arm64":
+        gpus.append(GpuInfo("apple", "Apple Silicon (not passed through to Docker)"))
+    return HardwareInfo(
+        cpu_count=os.cpu_count() or 1,
+        mem_total_mb=_probe_mem_mb(),
+        gpus=gpus,
+        dri_render_nodes=sorted(glob.glob("/dev/dri/renderD*")),
+        has_dxg=os.path.exists("/dev/dxg"),
+    )