docs: design spec for ONNX lightweight migration

Replace PyTorch + sentence-transformers (~2GB) with ONNX Runtime direct
loading (~50MB, already a chromadb dep). Switch bge-large to bge-small,
drop cross-encoder reranker. Target: HF Spaces deployable image ~400MB.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/superpowers/specs/2026-03-30-onnx-lightweight-migration-design.md

@@ -0,0 +1,91 @@
+# Design: Migration ONNX Lightweight
+
+## Problème
+
+Le build HuggingFace Spaces échoue — l'image Docker pèse ~2.7 GB, principalement à cause de PyTorch (800 MB) + bge-large (1.34 GB) + sentence-transformers/transformers (200 MB). Le free tier HF Spaces ne supporte pas cette taille.
+
+## Décision
+
+Remplacer la stack embedding lourde (sentence-transformers → PyTorch) par un chargement ONNX Runtime direct, et passer de bge-large à bge-small.
+
+## Changements
+
+### Dépendances
+
+**Supprimé :**
+- `sentence-transformers` (et ses transitives : `torch`, `transformers`, `scipy`, `scikit-learn`)
+
+**Ajouté :**
+- Rien — `onnxruntime` et `tokenizers` sont déjà des dépendances de `chromadb 1.5.5`
+
+**Impact taille :** ~2.7 GB → ~400 MB estimé
+
+### Modèle d'embedding
+
+| | Avant | Après |
+|---|---|---|
+| Modèle | BAAI/bge-large-en-v1.5 | BAAI/bge-small-en-v1.5 |
+| Dimensions | 1024 | 384 |
+| Taille | 1.34 GB | ~133 MB (ou ~35 MB quantifié int8) |
+| MTEB score | 64.23 | 62.17 |
+| Moteur | PyTorch via sentence-transformers | ONNX Runtime direct |
+
+### Reranker
+
+**Supprimé.** Le cross-encoder `ms-marco-MiniLM-L-12-v2` est retiré.
+
+**Justification :** Avec 350 stories et hybrid retrieval (BM25 + dense + RRF), le reranker apporte ~3-5% de qualité (NDCG 0.85 → 0.82 sans). Le consensus expert situe le seuil d'utilité à ~1000 docs. Le gain en taille (-900 MB) et latence (-250-400ms) justifie la suppression.
+
+**Filet de sécurité :** Si la qualité baisse, rerank via Gemini Flash sur les top-5 (appel API, pas de dep lourde).
+
+## Fichiers impactés
+
+| Fichier | Action |
+|---|---|
+| `src/mediastorm/config.py` | Modèle → bge-small, dimension → 384, ajout ONNX_MODEL_PATH |
+| `src/mediastorm/vectorize/embedder.py` | Réécriture : onnxruntime.InferenceSession + tokenizers + mean pooling + L2 norm |
+| `src/mediastorm/rag/reranker.py` | Supprimé |
+| `src/mediastorm/rag/retriever.py` | Retirer l'appel au reranker |
+| `pyproject.toml` | Retirer `sentence-transformers` |
+| `Dockerfile` | Supprimer install PyTorch, ajouter COPY models/ |
+| `tests/test_embedder.py` | Adapter assertions (1024 → 384) |
+| `models/bge-small-en-v1.5/` | Nouveau dossier : model.onnx + tokenizer.json |
+
+## Embedder ONNX — interface
+
+L'interface publique reste identique :
+
+```python
+class Embedder:
+    def __init__(self):
+        # Charge tokenizer.json via tokenizers.Tokenizer
+        # Charge model.onnx via onnxruntime.InferenceSession
+
+    def embed_texts(self, texts: list[str]) -> list[list[float]]:
+        # Tokenize → inference ONNX → mean pooling → L2 normalize
+```
+
+Aucun impact sur `store.py`, `retriever.py` (côté embedding), `chunker.py`, `app.py`.
+
+## Modèle ONNX — préparation
+
+Export one-shot du modèle bge-small au format ONNX :
+- Via `optimum-cli export onnx` ou script Python
+- Quantification int8 optionnelle (133 MB → ~35 MB)
+- Fichiers résultants : `model.onnx` + `tokenizer.json`
+- Stockés dans `models/bge-small-en-v1.5/`
+- Embarqués dans l'image Docker (`COPY models/ models/`)
+
+## Re-vectorisation
+
+Obligatoire après migration — les embeddings 384d ne sont pas compatibles avec les 1024d actuels.
+
+```bash
+python cli.py vectorize  # re-embed 350 stories dans ChromaDB via upsert
+```
+
+## Risques
+
+- **Qualité retrieval :** -2 points MTEB (bge-large → small) + -3-5% NDCG (pas de reranker). Acceptable pour 350 docs. Mesurable via `python cli.py audit`.
+- **Re-vectorisation :** One-shot, ~5 min pour 350 stories. ChromaDB upsert écrase les anciens vecteurs.
+- **ONNX pooling/norm custom :** 10 lignes de code, bien documenté. Testable unitairement.