refactor: switch Coral TPU deployment strategy back to Docker with USB passthrough

solderzzc · solderzzc · commit c5f0d4039b0b · 2026-03-27T20:24:56.000-07:00
This reverts the deployment logic to the Docker-first approach originally introduced in commit 9137400 to bypass sudo and libedgetpu installation hurdles on macOS. The compiled tflite models added in recent commits remain.
diff --git a/skills/detection/yolo-detection-2026-coral-tpu/SKILL.md b/skills/detection/yolo-detection-2026-coral-tpu/SKILL.md
@@ -1,15 +1,14 @@
 ---
 name: yolo-detection-2026-coral-tpu
-description: "Google Coral Edge TPU — real-time object detection with LiteRT"
-version: 2.0.0
+description: "Google Coral Edge TPU — real-time object detection via Docker"
+version: 1.0.0
 icon: assets/icon.png
 entry: scripts/detect.py
 deploy: deploy.sh
+runtime: docker
 
 requirements:
-  python: ">=3.9"
-  ai-edge-litert: ">=2.1.0"
-  system: "libedgetpu"
+  docker: ">=20.10"
   platforms: ["linux", "macos", "windows"]
 
 parameters:
@@ -79,56 +78,59 @@ mutex: detection
 
 # Coral TPU Object Detection
 
-Real-time object detection using Google Coral Edge TPU accelerator. Uses [ai-edge-litert](https://pypi.org/project/ai-edge-litert/) (LiteRT — the modern successor to TFLite/pycoral) with the `libedgetpu` delegate for hardware acceleration. Detects 80 COCO classes with ~4ms inference on 320×320 input.
+Real-time object detection using Google Coral Edge TPU accelerator. Runs inside Docker for cross-platform support. Detects 80 COCO classes (person, car, dog, cat, etc.) with ~4ms inference on 320×320 input.
 
 ## Requirements
 
 - **Google Coral USB Accelerator** (USB 3.0 port recommended)
-- **Python 3.9+** (3.9–3.13 supported via ai-edge-litert)
-- **libedgetpu** system library (installed per platform, see below)
+- **Docker Desktop 4.35+** (all platforms — Linux, macOS, Windows)
+- USB 3.0 cable (the included cable is recommended)
 - Adequate cooling for sustained inference
 
 ## How It Works
 
-1. `deploy.sh` creates a Python venv, installs `ai-edge-litert`, and checks for `libedgetpu`
-2. Aegis writes camera frame JPEG to shared `/tmp/aegis_detection/` directory
-3. Sends `frame` event via stdin JSONL to `detect.py`
-4. `detect.py` loads the Edge TPU delegate via `litert.load_delegate('libedgetpu')`
-5. Returns `detections` event via stdout JSONL
-6. Same protocol as `yolo-detection-2026` — Aegis sees no difference
+```
+┌─────────────────────────────────────────────────────┐
+│ Host (Aegis-AI)                                     │
+│   frame.jpg → /tmp/aegis_detection/                 │
+│   stdin  ──→ ┌──────────────────────────────┐       │
+│              │ Docker Container              │       │
+│              │   detect.py                   │       │
+│              │   ├─ loads _edgetpu.tflite     │       │
+│              │   ├─ reads frame from volume   │       │
+│              │   └─ runs inference on TPU    │       │
+│   stdout ←── │   → JSONL detections          │       │
+│              └──────────────────────────────┘       │
+│   USB ──→ /dev/bus/usb (Linux) or USB/IP (Mac/Win) │
+└─────────────────────────────────────────────────────┘
+```
+
+1. Aegis writes camera frame JPEG to shared `/tmp/aegis_detection/` volume
+2. Sends `frame` event via stdin JSONL to Docker container
+3. `detect.py` reads frame, runs inference on Edge TPU
+4. Returns `detections` event via stdout JSONL
+5. Same protocol as `yolo-detection-2026` — Aegis sees no difference
 
 ## Platform Setup
 
 ### Linux
 ```bash
-# 1. Install libedgetpu (deploy.sh auto-installs on Debian/Ubuntu)
-echo "deb https://packages.cloud.google.com/apt coral-edgetpu-stable main" | \
-  sudo tee /etc/apt/sources.list.d/coral-edgetpu.list
-curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
-sudo apt-get update && sudo apt-get install libedgetpu1-std
-
-# 2. Connect Coral USB Accelerator, then:
+# USB Coral should be auto-detected
+# Docker uses --device /dev/bus/usb for direct access
 ./deploy.sh
 ```
 
-### macOS
+### macOS (Docker Desktop 4.35+)
 ```bash
-# 1. Install libedgetpu
-curl -LO https://github.com/google-coral/libedgetpu/releases/download/release-grouper/edgetpu_runtime_20221024.zip
-unzip edgetpu_runtime_20221024.zip && cd edgetpu_runtime && sudo bash install.sh
-
-# 2. Connect Coral USB Accelerator, then:
+# Docker Desktop USB/IP handles USB passthrough
+# ARM64 Docker image builds natively on Apple Silicon
 ./deploy.sh
 ```
 
 ### Windows
 ```powershell
-# 1. Install libedgetpu
-# Download edgetpu_runtime_20221024.zip from:
-#   https://github.com/google-coral/libedgetpu/releases
-# Extract and run install.bat
-
-# 2. Connect Coral USB Accelerator, then:
+# Docker Desktop 4.35+ with USB/IP support
+# Or WSL2 backend with usbipd-win
 .\deploy.bat
 ```
 
@@ -137,6 +139,7 @@ unzip edgetpu_runtime_20221024.zip && cd edgetpu_runtime && sudo bash install.sh
 Ships with pre-compiled `yolo26n_edgetpu.tflite` (YOLO 2026 nano, INT8 quantized, 320×320). To compile custom models:
 
 ```bash
+# Requires x86_64 Linux or Docker --platform linux/amd64
 python scripts/compile_model.py --model yolo26s --size 320
 ```
 
@@ -155,7 +158,7 @@ Same JSONL as `yolo-detection-2026`:
 
 ### Skill → Aegis (stdout)
 ```jsonl
-{"event": "ready", "model": "yolo26n_edgetpu", "device": "coral", "format": "edgetpu_tflite", "runtime": "ai-edge-litert", "tpu_count": 1, "classes": 80}
+{"event": "ready", "model": "yolo26n_edgetpu", "device": "coral", "format": "edgetpu_tflite", "tpu_count": 1, "classes": 80}
 {"event": "detections", "frame_id": 42, "camera_id": "front_door", "objects": [{"class": "person", "confidence": 0.85, "bbox": [100, 50, 300, 400]}]}
 {"event": "perf_stats", "total_frames": 50, "timings_ms": {"inference": {"avg": 4.1, "p50": 3.9, "p95": 5.2}}}
 ```
@@ -169,8 +172,4 @@ Same JSONL as `yolo-detection-2026`:
 ./deploy.sh
 ```
 
-The deployer creates a Python venv, installs `ai-edge-litert` and dependencies, checks for the `libedgetpu` system library, probes for Edge TPU devices, and sets the native `run_command`.
-
-### Docker (Optional)
-
-A `Dockerfile` is provided for environments where native installation is impractical. Note: Docker requires USB/IP passthrough for Edge TPU access on macOS and Windows.
+The deployer builds the Docker image locally, probes for TPU devices, and sets the runtime command. No packages pulled from external registries beyond Docker base images and Coral apt repo.
diff --git a/skills/detection/yolo-detection-2026-coral-tpu/deploy.bat b/skills/detection/yolo-detection-2026-coral-tpu/deploy.bat
@@ -1,96 +1,71 @@
 @echo off
-REM deploy.bat — Native bootstrapper for Coral TPU Detection Skill (Windows)
+REM deploy.bat — Docker-based bootstrapper for Coral TPU Detection Skill (Windows)
 REM
-REM Installs ai-edge-litert in a Python venv and verifies Edge TPU connectivity.
+REM Builds the Docker image locally and verifies Edge TPU connectivity.
 REM Called by Aegis skill-runtime-manager during installation.
 REM
-REM Prerequisites:
-REM   - Python 3.9+ installed and on PATH
-REM   - libedgetpu installed (https://github.com/google-coral/libedgetpu/releases)
-REM
-REM Exit codes:
-REM   0 = success (Edge TPU detected)
-REM   1 = fatal error
-REM   2 = partial success (no TPU, CPU fallback)
-
-setlocal EnableDelayedExpansion
+REM Requires: Docker Desktop 4.35+ with USB/IP support
 
-set SKILL_DIR=%~dp0
-set VENV_DIR=%SKILL_DIR%.venv
-set LOG_PREFIX=[coral-tpu-deploy]
+setlocal enabledelayedexpansion
 
-REM ─── Step 1: Find Python ───────────────────────────────────────────────────
+set "SKILL_DIR=%~dp0"
+set "IMAGE_NAME=aegis-coral-tpu"
+set "IMAGE_TAG=latest"
+set "LOG_PREFIX=[coral-tpu-deploy]"
 
-echo %LOG_PREFIX% Checking for Python 3.9+... >&2
+REM ─── Step 1: Check Docker ────────────────────────────────────────────────
 
-where python >nul 2>&1
-if errorlevel 1 (
-    echo {"event": "error", "stage": "python", "message": "Python not found. Install Python 3.9+"}
+where docker >nul 2>&1
+if %errorlevel% neq 0 (
+    echo %LOG_PREFIX% ERROR: Docker not found. Install Docker Desktop 4.35+ 1>&2
+    echo {"event": "error", "stage": "docker", "message": "Docker not found. Install Docker Desktop 4.35+"}
     exit /b 1
 )
 
-for /f "tokens=2" %%v in ('python --version 2^>^&1') do set PY_VER=%%v
-echo %LOG_PREFIX% Found Python %PY_VER% >&2
-
-REM ─── Step 2: Create virtual environment ────────────────────────────────────
-
-if not exist "%VENV_DIR%\Scripts\python.exe" (
-    echo {"event": "progress", "stage": "venv", "message": "Creating virtual environment..."}
-    python -m venv "%VENV_DIR%"
-    if errorlevel 1 (
-        echo {"event": "error", "stage": "venv", "message": "Failed to create virtual environment"}
-        exit /b 1
-    )
+docker info >nul 2>&1
+if %errorlevel% neq 0 (
+    echo %LOG_PREFIX% ERROR: Docker daemon not running. Start Docker Desktop. 1>&2
+    echo {"event": "error", "stage": "docker", "message": "Docker daemon not running"}
+    exit /b 1
 )
 
-set VENV_PIP=%VENV_DIR%\Scripts\pip.exe
-set VENV_PYTHON=%VENV_DIR%\Scripts\python.exe
-
-echo %LOG_PREFIX% Virtual environment ready >&2
-
-REM ─── Step 3: Install dependencies ─────────────────────────────────────────
-
-echo {"event": "progress", "stage": "install", "message": "Installing ai-edge-litert and dependencies..."}
-"%VENV_PIP%" install --upgrade pip -q 2>&1
-"%VENV_PIP%" install -r "%SKILL_DIR%requirements.txt" -q 2>&1
+for /f "tokens=*" %%v in ('docker version --format "{{.Server.Version}}" 2^>nul') do set "DOCKER_VER=%%v"
+echo %LOG_PREFIX% Using Docker (version: %DOCKER_VER%) 1>&2
+echo {"event": "progress", "stage": "docker", "message": "Docker ready (%DOCKER_VER%)"}
 
-echo %LOG_PREFIX% Dependencies installed >&2
-echo {"event": "progress", "stage": "install", "message": "Dependencies installed"}
+REM ─── Step 2: Build Docker image ──────────────────────────────────────────
 
-REM ─── Step 4: Check libedgetpu ──────────────────────────────────────────────
+echo %LOG_PREFIX% Building Docker image: %IMAGE_NAME%:%IMAGE_TAG% ... 1>&2
+echo {"event": "progress", "stage": "build", "message": "Building Docker image..."}
 
-echo %LOG_PREFIX% Checking for libedgetpu... >&2
-echo {"event": "progress", "stage": "driver", "message": "Checking for Edge TPU driver..."}
-
-where edgetpu.dll >nul 2>&1
-if errorlevel 1 (
-    echo %LOG_PREFIX% WARNING: edgetpu.dll not found. >&2
-    echo %LOG_PREFIX% Download the runtime from: >&2
-    echo %LOG_PREFIX%   https://github.com/google-coral/libedgetpu/releases/download/release-grouper/edgetpu_runtime_20221024.zip >&2
-    echo %LOG_PREFIX% Extract and run install.bat >&2
-    echo {"event": "progress", "stage": "driver", "message": "libedgetpu not found — install from Google releases"}
+docker build -t %IMAGE_NAME%:%IMAGE_TAG% "%SKILL_DIR%"
+if %errorlevel% neq 0 (
+    echo %LOG_PREFIX% ERROR: Docker build failed 1>&2
+    echo {"event": "error", "stage": "build", "message": "Docker image build failed"}
+    exit /b 1
 )
 
-REM ─── Step 5: Probe for Edge TPU ───────────────────────────────────────────
+echo {"event": "progress", "stage": "build", "message": "Docker image ready"}
 
+REM ─── Step 3: Probe for Edge TPU ──────────────────────────────────────────
+
+echo %LOG_PREFIX% Probing for Edge TPU devices... 1>&2
 echo {"event": "progress", "stage": "probe", "message": "Checking for Edge TPU devices..."}
 
-set TPU_FOUND=false
-"%VENV_PYTHON%" "%SKILL_DIR%scripts\tpu_probe.py" > "%TEMP%\tpu_probe_result.json" 2>nul
-if not errorlevel 1 (
-    set TPU_FOUND=true
+docker run --rm --privileged %IMAGE_NAME%:%IMAGE_TAG% python3 scripts/tpu_probe.py >nul 2>&1
+if %errorlevel% equ 0 (
+    echo %LOG_PREFIX% Edge TPU detected 1>&2
+    echo {"event": "progress", "stage": "probe", "message": "Edge TPU detected"}
+) else (
+    echo %LOG_PREFIX% WARNING: No Edge TPU detected - CPU fallback 1>&2
+    echo {"event": "progress", "stage": "probe", "message": "No Edge TPU detected - CPU fallback"}
 )
 
-REM ─── Step 6: Complete ──────────────────────────────────────────────────────
+REM ─── Step 4: Set run command ──────────────────────────────────────────────
 
-set RUN_CMD=%VENV_PYTHON% %SKILL_DIR%scripts\detect.py
+set "RUN_CMD=docker run -i --rm --privileged -v /tmp/aegis_detection:/tmp/aegis_detection --env AEGIS_SKILL_ID --env AEGIS_SKILL_PARAMS --env PYTHONUNBUFFERED=1 %IMAGE_NAME%:%IMAGE_TAG%"
 
-if "%TPU_FOUND%"=="true" (
-    echo {"event": "complete", "status": "success", "accelerator_found": true, "run_command": "%RUN_CMD%", "message": "Coral TPU skill installed — Edge TPU ready"}
-    echo %LOG_PREFIX% Done! Edge TPU ready. >&2
-    exit /b 0
-) else (
-    echo {"event": "complete", "status": "partial", "accelerator_found": false, "run_command": "%RUN_CMD%", "message": "Coral TPU skill installed — no TPU detected (CPU fallback)"}
-    echo %LOG_PREFIX% Done with warning: no TPU detected. >&2
-    exit /b 2
-)
+echo {"event": "complete", "status": "success", "run_command": "%RUN_CMD%", "message": "Coral TPU skill installed"}
+
+echo %LOG_PREFIX% Done! 1>&2
+exit /b 0
diff --git a/skills/detection/yolo-detection-2026-coral-tpu/deploy.sh b/skills/detection/yolo-detection-2026-coral-tpu/deploy.sh
