# Architecture — Justifications techniques

> Ce document est **structuré dès la Phase 0** et rempli **au fur et à mesure**.
> Règle 7 du cahier des charges : **chaque choix technique est justifié ici**.
> Tant qu'une section est vide, elle porte la mention `⏳ À documenter (Phase N)`.

## 0. Vue d'ensemble

Un **modèle unifié** traite toutes les modalités comme des **tokens** dans une
**séquence unique** :

```
texte  ──► embeddings texte ─┐
image  ──► ViT maison ──► MLP ─┤
audio  ──► transformer mel ──► MLP ─┼──► séquence concaténée ──► transformer texte ──► logits
vidéo  ──► (frames = images) + audio ┘        (avec tokens de délimitation)
```

**Pourquoi une séquence unique plutôt que des têtes séparées ?**
Parce qu'un seul décodeur autoregressif peut alors *conditionner* sa génération sur
n'importe quelle combinaison d'entrées, sans architecture ad hoc par tâche. Les tokens
de délimitation (`<|image_start|>`, `<|audio_start|>`, …) indiquent au modèle où une
modalité commence et finit. C'est le principe des VLM modernes, mais **réimplémenté
intégralement à la main**.

## 1. Tokenizer (Phase 1) — ✅ implémenté, entraîné, testé

Choix retenus (voir aussi ADR-010) :

- **BPE** (`tokenizers.models.BPE`) plutôt qu'Unigram/SentencePiece : algorithme
  déterministe, simple à auditer, excellent sur les langues à morphologie riche
  comme le français. Entraînement **sur notre corpus**, aucun tokenizer pré-entraîné.
- **`pre_tokenizer = ByteLevel(add_prefix_space=False)`** : découpe au niveau des
  octets. Conséquence : aucun caractère n'est jamais hors-vocabulaire, les accents
  (é è ê à ç ù î ô œ æ), les emojis et tout script (japonais, arabe…) sont gérés
  nativement.
- **`initial_alphabet = ByteLevel.alphabet()` (256 octets)** : première idée
  fausse — sans cet alphabet initial, seuls les octets *vus dans le corpus* ont un
  token, donc un emoji jamais vu était **perdu** au round-trip (vérifié
  empiriquement). En forçant les 256 octets en tokens `0x00..0xFF`, `encode` →
  `decode` devient un **round-trip exact** pour toute entrée.
- **`byte_fallback=True`** sur le modèle BPE : repli octet pour les caractères
  inconnus. *(En `tokenizers` 0.23, `byte_fallback` est un paramètre du **modèle
  BPE**, pas du trainer — un argument `byte_fallback` passé au trainer est ignoré
  avec un warning. Corrigé dans le code.)*
- **`min_frequency=2`** : évite de figer des paires vues une seule fois.
- **Tokens spéciaux réservés en premier**, dans l'ordre canonique de
  `src/tokenizer/special_tokens.py` → ids **0..18**, stables et connus à l'avance :
  - base (4) : `<|pad|> <|bos|> <|eos|> <|unk|>`
  - raisonnement/agent (6) : `<|think|> <|plan|> <|tool_call|> <|tool_result|> <|critic|> <|moe_route|>`
  - modalités (9) : `<|image_start|> <|image_end|> <|image_pad|>`, idem audio et vidéo.
  - la forme `<|...|>` garantit qu'aucun token spécial ne peut émerger d'une
    fusion BPE sur du texte naturel nettoyé.
- **`vocab_size` est une borne supérieure, pas une garantie** : `BpeTrainer` ne
  produit jamais plus que le nombre de fusions possibles. Sur ~150 Mo de français
  on atteint bien **32000 exactement** (mesuré), mais sur un corpus pauvre le
  vocab final serait plus petit → le script **échoue explicitement** plutôt que
  de produire un tokenizer trompeur.

**Résultat mesuré (local, sur cette machine CPU)** : corpus Wikipedia FR
(`wikimedia/wikipedia` `20231101.fr`, streaming, plafond 150 Mo), **32 000
tokens**, **21,8 s**, round-trip exact sur accents/emojis/CJK/arabe.

**Corpus** : plafonné à ~150–200 Mo (au lieu des ~6 Go de Wikipedia FR complet),
pour tenir sur Colab et rester raisonnable en local. Documenté en ADR-010.
**Pas** d'en-tête de licence ni de boilerplate injecté dans le corpus (consigne
explicite).

## 2. Transformer texte (Phase 2) — ✅ implémenté, testé

Modules : `src/model/{rope,attention,ffn,block,text_model}.py`. Aucun module
`transformers`, aucun `nn.MultiheadAttention` : projections, découpage en têtes,
masque causal, softmax et rotations RoPE sont **écrits à la main**.

### 2.1 RoPE (Rotary Position Embedding)
**Choix** : RoPE plutôt qu'un embedding positionnel absolu appris.
**Justification** :
- En faisant tourner les paires de dimensions de Q et K d'un angle proportionnel
  à la position, le produit scalaire `Q·K` **ne dépend que de l'écart relatif**
  de position (test `test_rope_makes_attention_depend_on_relative_position`).
- **Zéro paramètre**, aucune limite intrinsèque de longueur.
- Meilleure **extrapolation** qu'un embedding absolu, et réutilisable tel quel
  pour image/audio (une position = un indice dans la séquence).
- Chaque paire (2i, 2i+1) est une **rotation** → la norme est conservée
  (test `test_rope_preserves_norm`).
Config : `rope_theta = 10000`, `head_dim` pair requis.

### 2.2 Pre-norm + residual
    x = x + Attention(LN(x))
    x = x + FFN(LN(x))
**Justification** : le gradient traverse la connexion résiduelle **sans être
multiplié** par la norme → stabilise les réseaux profonds, rend le warmup moins
critique. Forme des transformers modernes. Test : `test_block_is_prenorm`.

### 2.3 Attention causale
Le masque est un triangulaire supérieur mis à `-inf` **avant** le softmax, donc
les poids vers le futur valent **exactement 0**. Preuves par test :
- `test_attention_is_strictly_causal` : modifier le futur ne change pas les sorties passées ;
- `test_model_is_causal` : idem au niveau des logits du modèle complet ;
- `test_attention_matches_manual_inference_for_second_token` : comparaison à un
  calcul d'attention refait entièrement à la main.

### 2.4 FFN GELU
MLP à deux couches, dimension cachée `ffn_mult * n_embd` (défaut 4). `lm_head`
lié aux embeddings (`tie_embeddings`) dans un profil, séparé dans l'autre.

### 2.5 Paramètres : l'écart 50 M vs réalité
Point d'honnêteté déjà noté (valeurs **vérifiées** en Phase 0) :

Formule utilisée (vocab `V`, dim `E`, couches `L`, FFN `4E`, biais désactivés) :
```
params = V·E (embeddings) + L·(4E² + 8E² + 2E) + E (norm finale) [+ V·E si lm_head non lié]
```

| Profil | V | E | L | lm_head | Total |
|---|---|---|---|---|---|
| `text_model` (défaut, demandé) | 32000 | 384 | 6 | lié | **22.9 M** |
| `text_model` (idem) | 32000 | 384 | 6 | non lié | **35.2 M** |
| `text_model_50m` | 32000 | 512 | 6 | non lié | **51.6 M** |

Le profil demandé (`n_embd=384, n_layer=6`) ne fait donc **pas** 50 M. Le profil
`text_model_50m` (`n_embd=512, n_head=8, n_layer=6`, embeddings non liés) atteint
**51.6 M**. Les deux sont fournis ; l'écart est documenté, jamais masqué.
Ces tailles sont **recalculées à partir du vrai modèle** dans
`tests/test_phase0_params.py` (aucun chiffre codé en dur non vérifié).

### 2.6 Résultats mesurés (local, CPU)
- Test unitaire `test_overfit_single_batch` : loss → **< 0.05** sur un lot unique.
- Démo réelle : mini-corpus FR (4 phrases × 40, `n_layer=4, n_embd=128`, 300 pas,
  **68 s**) → loss **10.45 → 0.011**. Génération (T=0.7, top-k=40) :

> « Le chat noir dort sur le canapé du salon. Marie mange une pomme rouge dans le jardin. Les enfants jouent ensemble après… »

### 2.7 Génération (`src/generate.py`)
Échantillonnage entièrement écrit à la main : **température**, **top-k**,
**top-p (nucleus)**, glouton, arrêt sur `<|eos|>`. Aucune fonction `model.generate`.

### 2.8 Entraînement texte (Phase 3)
`src/data/prepare_text.py` + `src/train/train_text.py` + `src/evaluate.py`.

- **Données** : tokenisation du corpus en un tableau `uint16` (le vocab 32 000
  tient sur 16 bits → 2 octets/token), un `<|eos|>` après chaque document.
  Découpe train/val **séquentielle** (la val est la fin du flux) pour éviter
  toute fuite. `np.memmap` : aucune copie en RAM. Encodage par lots
  (`encode_batch`, Rust) pour la vitesse.
- **Optimiseur** : AdamW, **weight decay 0.1 uniquement sur les matrices**
  (`dim >= 2`), jamais sur les normes ni les biais — convention standard.
- **LR** : warmup linéaire puis cosinus jusqu'à `lr * min_lr_ratio`, planificateur
  écrit à la main (testé : croissant puis décroissant, monotone après warmup).
- **Stabilité** : `clip_grad_norm_` (1.0), `autocast` (bf16/fp16 sur GPU, fp32 sur CPU).
- **Checkpoints** : `last.pt` et `best.pt` (sur val), logs `train_log.jsonl`.

**Résultat mesuré (local, CPU, 8 Mo de Wikipedia FR = 1,91 M tokens)** :
`n_layer=4, n_embd=128` (~9 M params), 300 pas en 258 s → loss **10.40 → 6.06**,
perplexité val **475**. Échantillon réel (T=0.7) :

> « La France est alors que les trois villes, les États-Unis, dans des plus de la plus de la ville. Le gouvernement et la fin de l'est que une première place de l'origine… »

À 300 pas sur 8 Mo, la cible **ppl < 30** n'est **pas** atteinte : elle demande le
run complet (~200 Mo, profil 50 M, plusieurs heures GPU — voir
`notebooks/02_train_text.ipynb`). Aucun résultat n'est annoncé sans mesure.

## 3. Encodeur image (Phase 4) — ✅ implémenté, testé

Modules : `src/model/vit.py`, `src/model/projectors.py`, `src/data/toy_images.py`.

### 3.1 Architecture
- **Patch embedding** : convolution noyau/pas `patch_size` → découpe l'image en
  patchs non chevauchants et projette chacun en `n_embd`. Équivaut à une
  projection linéaire par patch, mais plus simple à écrire.
- **Token CLS** appris (pool `cls`) ou moyenne des patchs (pool `mean`).
- **Positional embedding appris** : sur une grille 2D de taille **fixe et connue**,
  un vecteur par position est simple et suffisant. **RoPE 2D n'apporte rien** ici,
  donc on ne l'utilise pas pour l'image (il reste utilisé pour le texte).
- N blocs transformer + LayerNorm finale.

### 3.2 Attention bidirectionnelle (bug réel corrigé)
Un encodeur d'image doit utiliser une attention **non causale** : chaque patch
(et le CLS) doit voir toute l'image. La première version réutilisait l'attention
**causale** du texte → le CLS, en position 0, ne voyait **aucun** patch et le
modèle restait bloqué à la perte de hasard (logits identiques pour toutes les
images, vérifié au débogage). Correction : drapeau `causal` sur l'attention
(`causal=True` pour le texte, `causal=False` pour image/audio). Un test de
régression (`test_encoder_is_bidirectional_not_causal`) empêche le retour du bug.

### 3.3 Générateur d'images jouets (maison)
`src/data/toy_images.py` génère des images RGB 32×32 avec une forme colorée
(cercle / carré / triangle × rouge / vert / bleu = **9 classes**), une légende
française (« un cercle rouge ») et du bruit léger. Déterministe (seed), aucune
dépendance à des données externes. Sert aux Phases 4, 5 et 6.

### 3.4 Projecteurs
`MLPProjector` : `LayerNorm → Linear → GELU → Linear` projette image/audio vers
`text_dim`. Un MLP (non linéaire) plutôt qu'une projection linéaire, pour un coût
modeste — c'est le composant qui aligne les modalités.

### 3.5 Résultats mesurés (local, CPU)
- Classification 9 classes, 18 images, `n_embd=32`, 2 blocs : **acc > 0.9**
  (overfit volontaire, jeu minuscule).
- Reconstruction (auto-encodeur) : **MSE < 0.05** après 120 pas.

## 4. Alignement image-texte (Phase 5) — ✅ implémenté, testé

Modules : `src/model/clip.py`, `src/data/prepare_image_text.py`,
`src/train/train_clip.py`.

### 4.1 Architecture
`CortexClip` = `VisionEncoder` (Phase 4) + transformer texte (Phase 2), chacun suivi
d'un `MLPProjector` vers un espace commun `embed_dim`, **normalisés L2**. La
similarité est le produit scalaire ; la température est une `logit_scale` apprise
(init `1/0.07`, plafonnée à 100).

### 4.2 Loss contrastive symétrique
`contrastive_loss` (écrite à la main) : cross-entropy sur les lignes **et** les
colonnes, bonne paire sur la diagonale, moyenne des deux. Vérifié par tests :
diagonale forte → perte ≈ 0 ; similarités uniformes → perte = `log(batch)` ;
symétrie en échangeant image/texte.

### 4.3 Deux pièges réels rencontrés (et corrigés)
1. **Le pooling du texte incluait les tokens de padding.** Toutes les légendes se
   ressemblaient. Correction : un **masque d'attention** (1 sur les vrais tokens,
   0 sur le PAD) est maintenant threadé jusqu'au pooling.
2. **Les légendes se répètent dans le lot.** Avec 9 classes et 1800 images, un lot
   aléatoire contient des légendes dupliquées : l'appariement image↔texte n'est plus
   1-1 et la perte symétrique devient **contradictoire → collapse** (perte figée à
   `log(batch)`, embeddings alignés). Correction : `_build_batches` construit des
   lots où **chaque légende apparaît une seule fois** (au plus une image par classe
   et par lot). Sans ce correctif, même une architecture correcte ne converge pas.

Un lr trop élevé (3e-3 → 8e-3) provoque aussi un collapse ; **gradient clipping 1.0**
+ lr modéré stabilisent l'entraînement.

### 4.4 Métrique
`class_retrieval_accuracy` : retrieval image→texte **au niveau des classes** (banque
de légendes uniques), pas l'argmax diagonal (biaisé par les doublons).

### 4.5 Résultats mesurés (local, CPU)
- Paires jouets 32×32 (9 classes), `embed_dim=64`, 2+2 blocs, **1200 pas en 126 s** :
  loss **2.20 → 0.15**, retrieval val **0.81** (hasard 0.11).
- Sur 9 images/légendes uniques, retrieval diagonal **1.00** (loss → 0.00).

## 5. Modèle multimodal génératif image+texte (Phase 6) — ✅ implémenté, testé

Modules : `src/model/vlm.py`, `src/train/train_vlm.py`, `src/model/text_model.py`
(ajout de `inputs_embeds`).

### 5.1 Fusion par embeddings
Les patchs d'image (ViT, Phase 4) sont projetés dans l'espace texte puis **injectés
comme des « tokens d'image »** dans la séquence, encadrés par `<|image_start|>` …
`<|image_end|>`. On passe des `inputs_embeds` au transformer : features projetées
sur les positions d'image, embeddings de tokens ailleurs. Le décodeur causal voit
l'image avant de générer la réponse.

### 5.2 Bug critique corrigé : décalage des labels
`CortexTextLM.forward` ne décale **pas** les targets (convention « décalage géré par
l'appelant », comme en Phase 3). Or `build_example` mettait d'abord `label[t] = ids[t]`
(non décalé) : le modèle prédisait le token qu'il voyait déjà → **loss triviale
(0.0006) et génération cassée**. Correction : `labels[t] = ids[t+1]` sur la réponse
(convention GPT). Un test vérifie l'invariant `labels[t] == ids[t+1]`.

### 5.3 Masquage de la perte
`ignore_index=-100` ajouté à la cross-entropy : seules les positions de réponse
comptent. Vérifié par un test qui recalcule la CE à la main.

### 5.4 Grounding visuel mesuré (local, CPU, 115 s, 400 pas)
Config `grid=32, patch=8` (16 tokens d'image), `n_layer=2, n_embd=64`.
- **Exactitude teacher-forced** (métrique honnête) : légende **0.85**, forme **0.80**,
  couleur **1.00**, comptage **1.00** (hasard : forme 0.33, couleur 0.33).
- **Génération libre (greedy)** : 0.35 — bien plus faible à cause du **biais
  d'exposition** sur un modèle aussi petit. On ne prétend donc pas que la génération
  libre est bonne : le grounding visuel est réel, la génération reste fragile.

### 5.5 Leçons de réglage
Un lr de 5e-3 collapsait la génération ; **2e-3 + gradient clipping 1.0** est stable.
Avec 16×16 et patch 8 (4 tokens seulement) le modèle ne voit pas la forme ; 32×32
(16 tokens) le permet.

## 6. Encodeur audio (Phase 7) — ✅ implémenté, testé

Modules : `src/data/audio_features.py`, `src/data/toy_audio.py`,
`src/model/audio_encoder.py`, `src/data/prepare_audio.py`, `src/train/train_audio.py`.

### 6.1 Mel-spectrogramme écrit à la main
`torchaudio` n'étant pas installé dans l'environnement, l'extraction mel est
**entièrement maison** (encore plus « from scratch ») : STFT via `torch.fft`, fenêtre
de Hann périodique, banc de filtres mel triangulaires (`hz_to_mel`/`mel_to_hz`),
puis log. Vérifié par un test : un sinus pur de 1 kHz produit bien un pic de
magnitude à ~1 kHz.

### 6.2 Architecture
Patch embedding (conv 2D sur le mel, patchs fréquence × temps) + **positional
embedding appris** + blocs transformer **bidirectionnels** (l'audio n'est pas causal :
le clip entier est visible). Un test vérifie la bidirectionnalité. Pooling moyen →
projecteur MLP → espace texte.

### 6.3 Données — réduction de scope assumée
L'environnement de dev n'a pas d'accès audio (pas de Common Voice FR). On
**synthétise** des voyelles par un modèle de formants (F0 + F1/F2, deux hauteurs) :
**10 classes** (5 voyelles × grave/aigu). C'est un jeu jouet, pas de la parole réelle.
La transcription de **parole réelle** (Common Voice fr) reste à faire dans un
environnement avec audio ; le pipeline (mel → encodeur → décodeur) est identique.

### 6.4 Résultats mesurés (local, CPU, 233 s, 600 pas)
- **Transcription** : teacher-forced **1.00**, génération libre **1.00** sur 10 classes
  (hasard 0.10), loss 10.4 → 0.0005. Les voyelles synthétiques sont parfaitement
  transcrites (« voyelle a grave », …).

### 6.5 Fusion réutilisée
`build_modality_example` (généralisé en Phase 7) construit la séquence
`prompt <|audio_start|> [audio_pad × N] <|audio_end|> réponse`, avec labels décalés
comme pour l'image.

## 7. Modèle multimodal complet texte + image + audio (Phase 8) — ✅ implémenté, testé

Modules : `src/model/multimodal.py`, `src/train/train_full_multimodal.py`.

### 8.1 Un seul décodeur pour trois modalités
`CortexMultimodal` réunit le décodeur texte (Phase 2), l'encodeur ViT (Phase 4) et
l'encodeur audio (Phase 7). Chaque modalité est projetée (`MLPProjector`) puis
**injectée dans la même séquence** aux positions marquées par `<|image_pad|>` /
`<|audio_pad|>`. `assemble_embeds` remplace l'embedding du token par la feature
projetée ; le décodeur causal génère la réponse.

### 8.2 Détail important : lignes du lot sans modalité
Dans un lot multi-tâches, certaines lignes n'ont ni image ni audio. On n'encode que
les **lignes concernées** (`mask.any(dim=1)`) avant d'affecter les embeddings, ce qui
évite un décalage de forme (bug rencontré puis corrigé). Un test dédié vérifie ce cas.

### 8.3 Tâches et résultats mesurés (local, CPU, 328 s, 600 pas)
Tâches : `image` (« Décris l'image : »), `audio` (« Transcris : »), `mixte`
(« Image et audio : » -> « <légende> | <transcription> »).
- **Exactitude teacher-forced** : image **0.92**, audio **1.00**, mixte **0.93**
  (hasard : image ~0.11, audio 0.10).
- **Génération libre mixte** : 0.17 — le modèle lit correctement les deux modalités
  isolément, mais la génération libre conjointe reste fragile (biais d'exposition),
  ce qui est attendu pour un modèle de cette taille. On ne le cache pas.

### 8.4 Fusion réutilisable
`build_modality_example` (Phase 7) et `build_sequence` (Phase 8) partagent la même
convention : blocs de tokens spéciaux + labels décalés + `ignore_index=-100`.

## 8. Vidéo — images + audio synchronisés (Phase 9) — ✅ implémenté, testé

Modules : `src/data/toy_video.py`, `src/model/multimodal.py::VideoEncoder`,
`src/train/train_video.py`.

### 7.1 Données jouets — mouvement (tâche réellement temporelle)
Une vidéo = ``n_frames`` images d'une forme colorée qui **se déplace** horizontalement
(vers la droite ou la gauche), + une piste audio synthétique (Phase 7). 18 classes
(3 formes × 3 couleurs × 2 directions). La direction ne peut être lue qu'en comparant
les frames : un test vérifie que le centroïde horizontal croît (« droite ») ou décroît
(« gauche »).

### 7.2 Architecture
`VideoEncoder` = un ViT (Phase 4) **partagé** sur chaque frame + un **embedding
temporel appris** par frame + un petit transformer **spatio-temporel** (bidirectionnel)
sur l'ensemble des `n_frames × n_patches` tokens. Un test vérifie que réordonner les
frames change les features (le modèle regarde bien le temps). Coût quadratique de
l'attention sur le nombre de tokens (limite documentée : on garde `n_frames` petit).

### 7.3 Tâches et résultats mesurés (local, CPU, 98 s, 300 pas, 4 frames)
- « Décris la vidéo : » -> exactitude teacher-forced **0.78** ;
- « Que se passe-t-il ? » (frames + audio) -> **0.85** (hasard ~0.055).
- Génération libre 0.0 : non caché — décrire une vidéo en génération libre reste
  hors de portée d'un modèle de cette taille ; le grounding est réel.

## 9. Mixture-of-Experts — 20 experts, top-2 (Phase 10) — ✅ implémenté, entraîné, testé

Module : `src/model/moe.py`, entraînement `src/train/train_moe.py`.

### 9.1 Pourquoi MoE
Un MoE **augmente la capacité** (nombre total de paramètres) **sans** augmenter le coût
de calcul par token : seuls les `top_k` experts activés sont traversés. On remplace les
FFN denses du transformer texte par `MoEFFN` (`n_experts=20`, `top_k=2`).

### 9.2 Routeur (écrit à la main)
`router = Linear(n_embd, n_experts)` ; on garde les `top_k` plus grands logits, on
renormalise les portes, et on n'applique chaque expert qu'aux tokens qui le choisissent
(calcul épars). Pendant l'entraînement, un **bruit gaussien** (`jitter`) est ajouté aux
logits pour l'exploration.

### 9.3 Loss auxiliaire d'équilibrage
Loss Switch-Transformer : `E * Σ_i f_i · P_i` (`f_i` = fraction de tokens routés vers
l'expert `i`, `P_i` = probabilité moyenne). Pénalise la concentration. Poids
`aux_loss_coef=0.01`. La perte totale = perte de langage + `aux_loss_coef * aux_loss`.

### 9.4 Résultats mesurés (local, CPU, 400 pas, 373 s, corpus FR jouet)
- Perte val **0.0052**, **perplexité val 1.005** (le modèle apprend le corpus jouet).
- **Entropie de charge normalisée 0.9999** sur 20 experts → routage quasi parfaitement
  équilibré, **0 expert mort**.
- **14 855 296** paramètres totaux vs **5 418 112** actifs par token (ratio ~2.7×) :
  c'est le gain MoE — plus de capacité, coût par token borné par `top_k`.

### 9.5 Coûts / limites
Tous les experts restent **résidents en mémoire** ; le routeur peut devenir instable
sans loss auxiliaire ; le débit d'entraînement dépend de l'implémentation éparse
(boucle par expert ici — suffisant à l'échelle jouet, à vectoriser pour du grand).

## 10. Mémoire / « apprendre des cours » (Phase 11) — ✅ implémenté, testé

Modules : `src/memory/rag.py` (mode A), `src/memory/permanent.py` (mode B).

### 10.1 Mode A — RAG (réaliste, recommandé)
Pipeline écrit à la main, sans service externe :
1. **Découpage** d'un cours en passages (`chunk_text`, par phrases jusqu'à `max_words`).
2. **Embeddings maison** par *feature hashing* déterministe (sac de mots signé, pondéré
   par IDF), L2-normalisés. Aucun paramètre appris — honnête à petite échelle : deux
   textes lexicalement proches le sont aussi vectoriellement (testé).
3. **Index vectoriel numpy** (`VectorIndex`) : recherche par similarité cosinus.
4. Un cours **vidéo** = transcription horodatée **+ légendes de frames clés**
   (`add_video`) ; les sources (fichier, timestamps) sont conservées.
5. Réponse **extractive** : le meilleur passage réel du cours est renvoyé verbatim,
   avec sources et confiance (cosinus) — **pas d'hallucination** pour le mode A.
   Une variante générative (`answer_with_model`) met le contexte dans le prompt.

### 10.2 Mode B — apprentissage permanent : EXPÉRIMENTAL ET INSTABLE ⚠️
Mise à jour des **poids** pendant l'ingestion (`PermanentLearner.ingest`) : quelques pas
de gradient AdamW (maison) sur le texte du cours, avec un **tampon de rejeu** pour
limiter l'oubli catastrophique. Avertissements tenus par des **tests** :
- après ingestion, la perte sur la leçon **chute** (mémorisation réelle) ;
- **sans rejeu**, la perte sur une phrase déjà apprise **augmente** — l'oubli
  catastrophique est démontré, pas caché.
Ce mode **mémorise un texte court** et le restitue ; il **ne remplace pas** un
fine-tuning, peut **dégrader** d'autres capacités, et n'offre **aucune garantie** de
stabilité. Il est implémenté **en dernier** et présenté comme recherche.

## 12. API · Démo · Publication (Phase 12) — ✅ implémenté, testé

### 12.1 Moteur d'inférence unifié (`src/inference.py`)
`CortexEngine` rassemble le décodeur texte et les encodeurs image/audio/vidéo derrière
une API unique (`chat`, `describe_image`, `transcribe_audio`, `describe_video`). Les
entrées sont décodées sans dépendance lourde : images via numpy/Pillow, audio WAV via
`wave`, vidéo via tableau `(T,H,W,3)`. La fusion se fait par masques : les embeddings
du décodeur sont remplacés aux positions `image_pad`/`audio_pad`/`video_pad` par les
features projetées. `trained=False` tant qu'aucun checkpoint n'est chargé — **honnête** :
les poids sont alors l'initialisation aléatoire, seule la tuyauterie est réelle.

### 12.2 API FastAPI (`src/api.py`)
Endpoints `/health`, `/capabilities`, `/chat`, `/vision`, `/audio`, `/video`,
`/memory/ingest`, `/memory/query`. Le checkpoint est choisi par `CORTEX_CHECKPOINT`
(jamais de secret en dur). Tests via `TestClient` (14 tests) — tournent sur CPU.

### 12.3 Démo Gradio (`app/gradio_app.py`)
Onglets Texte/Image/Audio/Vidéo/Mémoire. Les handlers sont testés sans lancer de serveur.

### 12.4 Publication (`src/push_to_hub.py`, `Dockerfile`)
`push_to_hub` publie le dépôt, un `checkpoints/*.pt` optionnel et la carte de modèle
(front-matter avec `license: apache-2.0`). Le Dockerfile expose l'API (8000) et la démo
(7860) ; `HF_TOKEN`/`CORTEX_CHECKPOINT` sont fournis au runtime, jamais cuits dans l'image.

## 11. Limites assumées

- Un modèle de quelques dizaines de millions de paramètres **ne raisonne pas** comme un
  modèle de plusieurs centaines de milliards. Aucune équivalence ne sera prétendue.
- Entraînement réel limité par le matériel (CPU ici → Colab pour l'entraînement).
- Les résultats seront **mesurés**, jamais inventés.