Upload README.md with huggingface_hub

README.md

@@ -123,3 +123,72 @@ backbone (matching across time/cameras) and v2 as the query encoder
 
 Full session report:
 `gs://thunderdome-tracking-lab/test-runs/CLIP_DATASET_REPORT.md`
+
+## Edge Export (Hailo-10H)
+
+This release includes deployment artifacts for the full path from training to chip:
+
+| Artifact | Size | Purpose |
+|---|---|---|
+| `best.pt` / `last.pt` | 598 MB | PyTorch fine-tuned weights (full precision) |
+| `clip-aerial-vit-b16-v3-224.onnx` | 345 MB | Clean ONNX (x86 / ARM CPU / GPU runtime) |
+| `clip-aerial-vit-b16-v3-surgical.onnx` | 344 MB | Hailo-DFC-compatible ONNX (weights grafted into HMZ ref ONNX) |
+| `clip-aerial-vit-b16-v3-224-hailo10h.hef` | 79.7 MB | **Compiled HEF for Hailo-10H edge accelerator** |
+| `quant_report.json` | — | INT8 quantization report from DFC compile |
+| `validate_report.json` | — | PT-fp32 vs HEF (SDK_QUANTIZED) cosine + overlap@5 |
+
+### HEF compilation pipeline
+
+```bash
+thunderdome clip onnx-surgery \
+    --our-pt best.pt \
+    --output clip-aerial-vit-b16-v3-surgical.onnx \
+    --ref-onnx /tmp/hailo_ref/clip_vit_b_16.onnx          # ViT-B/16 surgery (DFC parser bug workaround)
+
+thunderdome clip compile-hef \
+    --onnx clip-aerial-vit-b16-v3-surgical.onnx \
+    --alls configs/hailo/clip_vit_b_16_image_encoder_hailomz.alls \
+    --calib-dir <crops_dir> --calib-count 500 \
+    --target hailo10h --output-dir hef/ \
+    --net-name clip_aerial_vit_b_16 --imgsz 224
+```
+
+### Surgery + quantization fidelity
+
+- Surgical ONNX vs PT (fp32 cosine, single pass): **0.9798**
+- HEF emulator (SDK_QUANTIZED) vs PT (20-image mean cosine): **0.9551**
+- HEF emulator vs PT overlap@5 (ranking agreement): **0.820**
+
+The drop from 0.98 → 0.96 → 0.82 is INT8 quantization noise + the
+documented QuickGELU↔GELU activation mismatch in Hailo's reference
+ONNX. Retrieval rankings remain in agreement, which is what matters
+for downstream ReID / open-vocab search.
+
+### Runtime preprocessing
+
+The HEF has the OpenAI CLIP normalization layer **baked into the
+compiled graph** (via `norm1` in the alls config). On the chip,
+pass **letterbox-padded raw uint8** images (114-gray fill, 224×224):
+
+```python
+from PIL import Image
+import numpy as np
+
+def letterbox(img, sz=224, fill=(114, 114, 114)):
+    w, h = img.size
+    s = sz / max(w, h)
+    nw, nh = int(round(w*s)), int(round(h*s))
+    img = img.resize((nw, nh), Image.BILINEAR)
+    canvas = Image.new("RGB", (sz, sz), fill)
+    canvas.paste(img, ((sz-nw)//2, (sz-nh)//2))
+    return canvas
+
+# Pass to HEF as np.uint8 [1, 224, 224, 3] (NHWC).
+```
+
+### Architecture preserved
+
+- Same `ViT-B-16` body as v2 (no quantization-aware training)
+- 512-dim embedding (drop-in for arc-uas / any ViT-B/16 consumer)
+- Text encoder frozen during fine-tune → text embeddings can come
+  from any standard openai-pretrained ViT-B/16