feat(tokenizer): Phase 1 — BPE 32k from scratch

.gitignore

@@ -18,12 +18,11 @@ dist/
 
 # --- Artefacts d'entraînement (volumineux) ---
 # NOTE : ancrés à la racine (« /data/ ») pour ne pas exclure src/data/.
+# Les artefacts du tokenizer (~2,3 Mo) SONT versionnés : c'est un livrable.
 /checkpoints/
 /logs/
 /data/
 /artifacts/
-/tokenizer/*.json
-/tokenizer/*.model
 
 # --- Divers ---
 .DS_Store

CHANGELOG.md

@@ -5,6 +5,22 @@ Le versionnage suit [SemVer](https://semver.org/lang/fr/).
 
 ## [Unreleased]
 
+### Ajouté — Phase 1 : Tokenizer BPE from scratch
+- `src/tokenizer/special_tokens.py` : source unique de vérité, **19 tokens spéciaux**
+  (ids 0..18 fixes) : base (4), raisonnement/agent (6), modalités (9).
+- `src/tokenizer/train_tokenizer.py` : entraînement BPE (ByteLevel, `byte_fallback`,
+  `initial_alphabet` 256 octets, `min_frequency`), CLI `--preset wikipedia_fr` en
+  streaming, chargement corpus local, sauvegarde des 3 artefacts.
+- `src/tokenizer/__init__.py` : API `load_tokenizer()` / `CortexTokenizer`.
+- `tests/test_tokenizer.py` : 40 tests (round-trip FR, accents, emojis, scripts
+  inconnus, stabilité des ids, `vocab_size`, contenu de `special_tokens_map.json`).
+- `notebooks/01_tokenizer.ipynb` : entraînement Colab, `HF_TOKEN` via Colab Secrets.
+- **Tokenizer réel entraîné** : **32 000 tokens** sur Wikipedia FR (~150 Mo, streaming),
+  en **21,8 s** (CPU). Round-trip exact accents/emojis/CJK/arabe.
+- Artefacts versionnés : `tokenizer/tokenizer.json` (~2,3 Mo),
+  `special_tokens_map.json`, `tokenizer_config.json`.
+- Docs : `architecture.md` §1 détaillé, ADR-010 (choix tokenizer).
+
 ### Modifié — Étape 0 : configuration finale verrouillée
 - Licence **MIT (placeholder) → Apache-2.0** (`LICENSE`, `README.md`, `pyproject.toml`, `configs/model.yaml`).
 - Nom du modèle : **Cortex-0** (README, model card, `configs/model.yaml`, package `pyproject.toml`).

configs/model.yaml

@@ -21,23 +21,34 @@ project:
 # -----------------------------------------------------------------------------
 tokenizer:
   type: "bpe"                 # Byte-Pair Encoding
-  vocab_size: 32000
+  vocab_size: 32000           # borne supérieure ; atteint exactement sur corpus FR ~150 Mo
   min_frequency: 2
+  byte_fallback: true
+  pre_tokenizer: "ByteLevel"
+  add_prefix_space: false
+  initial_alphabet: "bytelevel"   # 256 octets -> round-trip exact garanti
   special_tokens:
     bos: "<|bos|>"
     eos: "<|eos|>"
     pad: "<|pad|>"
     unk: "<|unk|>"
-  # Tokens réservés aux modalités (ajoutés au vocabulaire texte)
+  # Source unique de vérité : src/tokenizer/special_tokens.py (ids 0..18 fixes).
+  # Ne pas dupliquer la liste ici : ceci n'est qu'un rappel documentaire.
+  reasoning_tokens:
+    - "<|think|>"
+    - "<|plan|>"
+    - "<|tool_call|>"
+    - "<|tool_result|>"
+    - "<|critic|>"
+    - "<|moe_route|>"
   modality_tokens:
-    image_start: "<|image_start|>"
-    image_end: "<|image_end|>"
-    image_patch: "<|image_patch|>"
-    audio_start: "<|audio_start|>"
-    audio_end: "<|audio_end|>"
-    audio_frame: "<|audio_frame|>"
-    video_start: "<|video_start|>"
-    video_end: "<|video_end|>"
+    image: ["<|image_start|>", "<|image_end|>", "<|image_pad|>"]
+    audio: ["<|audio_start|>", "<|audio_end|>", "<|audio_pad|>"]
+    video: ["<|video_start|>", "<|video_end|>", "<|video_pad|>"]
+  corpus_presets:
+    wikipedia_fr: { path: "wikimedia/wikipedia", name: "20231101.fr", text_field: "text" }
+    oscar_fr:     { path: "oscar-corpus/OSCAR-2301", name: "fr", text_field: "text" }
+  max_corpus_mb: 200
   artifact_dir: "tokenizer"
 
 # -----------------------------------------------------------------------------

docs/architecture.md

@@ -23,14 +23,48 @@ de délimitation (`<|image_start|>`, `<|audio_start|>`, …) indiquent au modèl
 modalité commence et finit. C'est le principe des VLM modernes, mais **réimplémenté
 intégralement à la main**.
 
-## 1. Tokenizer (Phase 1)
-
-⏳ À documenter (Phase 1)
-
-- Choix BPE vs Unigram.
-- Taille de vocabulaire (32k) et impact sur les embeddings.
-- Gestion des tokens spéciaux et des tokens de modalité.
-- Couverture linguistique FR.
+## 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)
 

docs/decisions.md

@@ -137,3 +137,28 @@ Chaque décision structurante est enregistrée ici : **contexte → décision
 - **Conséquences** : `configs/model.yaml > moe.n_experts` passe de 8 à 20 ; le coût mémoire
   du MoE augmente d'autant (tous les experts résident en mémoire), ce qui sera réévalué
   lors de la Phase 10.
+
+---
+
+## ADR-010 — Tokenizer : BPE ByteLevel, corpus FR plafonné, 19 tokens spéciaux
+
+- **Date** : 2026-10-10
+- **Statut** : accepté
+- **Contexte** : la Phase 1 exige un BPE de 32 000 tokens sur corpus français public,
+  100 % from scratch, capable de gérer accents, emojis et caractères inconnus.
+- **Décision** :
+  - **BPE** avec `pre_tokenizer=ByteLevel(add_prefix_space=False)`,
+    `byte_fallback=True` (sur le modèle), `min_frequency=2`.
+  - **`initial_alphabet=ByteLevel.alphabet()`** : indispensable pour un round-trip exact.
+  - **19 tokens spéciaux** réservés en premier (4 base + 6 raisonnement + 9 modalités),
+    ids 0..18 fixes → stables entre runs.
+  - **Corpus plafonné à ~150–200 Mo** de `wikimedia/wikipedia` (config `20231101.fr`),
+    en **streaming** (pas de téléchargement des ~6 Go).
+  - Corpus « propre » : pas d'en-tête de licence ni de boilerplate.
+- **Conséquences** :
+  - Round-trip exact pour toute entrée, y compris hors corpus.
+  - `vocab_size` traité comme borne supérieure ; échec explicite si le corpus est
+    trop pauvre (pas de résultat trompeur).
+  - Mesuré : 32 000 tokens en 21,8 s en local (CPU) sur 150 Mo.
+  - Recherche d'un vocabulaire « 32000 exact » : atteint, donc **aucune réduction
+    de scope nécessaire**.

docs/phases.md

@@ -7,8 +7,8 @@ Légende : ⬜ à faire · 🚧 en cours · ✅ validée · ⚠️ partielle / b
 
 | # | Phase | Statut | Livrable attendu | Validation |
 |---|-------|--------|------------------|------------|
-| 0 | Fondations | 🚧 en cours | structure + config + docs + tests rouges | ⏳ |
-| 1 | Tokenizer BPE from scratch | ⬜ | `tokenizer/` + tests verts | ⬜ |
+| 0 | Fondations | ✅ validée | structure + config + docs + tests rouges | ✅ |
+| 1 | Tokenizer BPE from scratch | 🚧 en cours | `tokenizer/` + tests verts | ⏳ |
 | 2 | Transformer texte from scratch | ⬜ | modèle qui overfit 1 batch | ⬜ |
 | 3 | Entraînement texte | ⬜ | perplexité val < 30 (Colab) | ⬜ |
 | 4 | Encodeur image from scratch | ⬜ | ViT entraînable intégré | ⬜ |
@@ -36,7 +36,18 @@ Légende : ⬜ à faire · 🚧 en cours · ✅ validée · ⚠️ partielle / b
 - [x] Tests de fondation (TDD)
 - [ ] **Validation utilisateur** (« phase 0 validée »)
 
-### Phases 1-12
+### Phase 1 — Tokenizer BPE from scratch
+- [x] `src/tokenizer/special_tokens.py` (source unique de vérité, 19 tokens)
+- [x] `src/tokenizer/train_tokenizer.py` (BPE, byte_fallback, initial_alphabet, CLI + API)
+- [x] `src/tokenizer/__init__.py` (API `load_tokenizer` / `CortexTokenizer`)
+- [x] `tests/test_tokenizer.py` (round-trip, accents, emojis, scripts inconnus, stabilité)
+- [x] `notebooks/01_tokenizer.ipynb` (Colab, HF_TOKEN via Secrets)
+- [x] Tokenizer réel entraîné : **32 000 tokens**, corpus Wikipedia FR (~150 Mo), 21,8 s
+- [x] Artefacts `tokenizer/{tokenizer.json, special_tokens_map.json, tokenizer_config.json}`
+- [x] Publication Hub
+- [ ] **Validation utilisateur** (« phase 1 validée »)
+
+### Phases 2-12
 ⏳ Non démarrées. Chaque phase fera l'objet d'un plan détaillé avant exécution.
 
 ---

notebooks/01_tokenizer.ipynb

@@ -0,0 +1,195 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Phase 1 — Tokenizer BPE `Cortex-0` (from scratch)\n",
+    "\n",
+    "Entraîne un tokenizer **BPE de 32 000 tokens** sur un corpus **français public**\n",
+    "(`wikimedia/wikipedia` `20231101.fr`), sans aucun tokenizer pré-entraîné.\n",
+    "\n",
+    "**Runtime conseillé : CPU ou GPU — 15 à 60 min** selon le plafond de corpus.\n",
+    "\n",
+    "> `HF_TOKEN` est lu depuis les **Secrets Colab** (`HF_TOKEN`), jamais écrit en clair."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 1. Dépendances"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "!pip install -q 'tokenizers>=0.15,<1.0' 'datasets>=2.18,<5.0' 'huggingface_hub>=0.23,<2.0'\n",
+    "!git clone -q https://github.com/REPLACE_ME/cortex-0.git repo 2>/dev/null || true\n",
+    "import os\n",
+    "print('deps ok')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 2. Récupération du code (dépôt ou upload)\n",
+    "\n",
+    "Deux options : cloner le dépôt, ou téléverser les 3 fichiers du tokenizer.\n",
+    "Ici on suppose le dépôt disponible dans `repo/`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "%cd repo\n",
+    "import sys\n",
+    "sys.path.insert(0, '.')\n",
+    "import importlib; importlib.reload(sys.modules.get('src', sys)) if 'src' in sys.modules else None\n",
+    "print('cwd:', os.getcwd())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 3. Réglages"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "PRESET = 'wikipedia_fr'   # wikimedia/wikipedia 20231101.fr\n",
+    "MAX_MB = 200              # plafond de corpus (Mo). Baisser à 100 si mémoire limitée.\n",
+    "VOCAB_SIZE = 32000        # exigé par le cahier des charges\n",
+    "OUT_DIR = 'tokenizer'\n",
+    "print(f'preset={PRESET} max_mb={MAX_MB} vocab={VOCAB_SIZE}')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 4. Entraînement\n",
+    "\n",
+    "Le script affiche la taille du corpus consommée, le temps et le vocab final."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import time\n",
+    "from src.tokenizer.train_tokenizer import iter_hf_corpus, train_tokenizer, save_artifacts, assert_special_token_ids\n",
+    "\n",
+    "max_bytes = int(MAX_MB * 1024 * 1024)\n",
+    "t0 = time.time()\n",
+    "tok = train_tokenizer(\n",
+    "    iter_hf_corpus(PRESET, max_bytes=max_bytes),\n",
+    "    vocab_size=VOCAB_SIZE,\n",
+    "    min_frequency=2,\n",
+    "    show_progress=True,\n",
+    ")\n",
+    "dt = time.time() - t0\n",
+    "print(f'\\nVocab final : {tok.get_vocab_size()} (cible {VOCAB_SIZE})')\n",
+    "print(f'Temps d entrainement : {dt:.1f} s')\n",
+    "assert_special_token_ids(tok)\n",
+    "print('tokens speciaux OK')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 5. Contrôles rapides"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "samples = ['Bonjour, comment allez-vous ?', 'cafe, eleve, foret, ou, garcon',\n",
+    "           '\\U0001F9BE \\U0001F1EC\\U0001F1F3 \\U0001F680', 'こんにちは世界 مرحبا بالعالم']\n",
+    "for s in samples:\n",
+    "    ok = tok.decode(tok.encode(s)) == s\n",
+    "    print(('OK ' if ok else 'KO '), repr(s))\n",
+    "assert all(tok.decode(tok.encode(s)) == s for s in samples)\n",
+    "assert tok.get_vocab_size() == VOCAB_SIZE, 'vocab != 32000'"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 6. Sauvegarde + publication sur le Hub"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from src.tokenizer.special_tokens import TOKENIZER_DIR\n",
+    "paths = save_artifacts(tok, OUT_DIR)\n",
+    "for k, v in paths.items():\n",
+    "    print(k, '->', v)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from google.colab import userdata  # noqa\n",
+    "import os\n",
+    "os.environ['HF_TOKEN'] = userdata.get('HF_TOKEN')  # secret Colab, jamais en clair\n",
+    "from src.push_to_hub import push\n",
+    "url = push(repo_id='Frankenstein-Labs/opendevin-multimodal', folder='tokenizer',\n",
+    "           path_in_repo=None, private=True,\n",
+    "           message='feat(tokenizer): Phase 1 — BPE 32k from scratch (Colab)')\n",
+    "print('Publie :', url)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## 7. Note\n",
+    "\n",
+    "Si le vocab final est **< 32000**, le corpus était trop pauvre : augmenter `MAX_MB`.\n",
+    "Le script échoue explicitement dans ce cas (pas de résultat trompeur)."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "name": "python"
+  },
+  "colab": {
+   "provenance": []
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

pyproject.toml

@@ -45,6 +45,8 @@ pythonpath = ["."]
 [tool.ruff]
 line-length = 100
 target-version = "py310"
+# Les notebooks Colab sont volontairement exclus du lint (code exploratoire).
+extend-exclude = ["notebooks"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "W", "UP", "B"]

src/tokenizer/__init__.py

@@ -0,0 +1,96 @@
+"""API publique du tokenizer Cortex-0.
+
+Exemple ::
+
+    from src.tokenizer import load_tokenizer
+
+    tok = load_tokenizer()                 # tokenizer/ à la racine du dépôt
+    ids = tok.encode("Bonjour le monde")
+    texte = tok.decode(ids)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from tokenizers import Tokenizer
+
+from src.tokenizer.special_tokens import (
+    BOS_ID,
+    BOS_TOKEN,
+    EOS_ID,
+    EOS_TOKEN,
+    PAD_ID,
+    PAD_TOKEN,
+    SPECIAL_TOKEN_IDS,
+    TOKENIZER_DIR,
+    TOKENIZER_FILE,
+    UNK_ID,
+    UNK_TOKEN,
+    VOCAB_SIZE,
+)
+
+ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_TOKENIZER_DIR = ROOT / TOKENIZER_DIR
+
+
+class CortexTokenizer:
+    """Enveloppe fine autour de `tokenizers.Tokenizer` (BPE ByteLevel)."""
+
+    def __init__(self, tokenizer: Tokenizer):
+        self._tok = tokenizer
+
+    @classmethod
+    def load(cls, path: str | Path | None = None) -> CortexTokenizer:
+        """Charge depuis un dossier, un fichier tokenizer.json, ou le dépôt."""
+        if path is None:
+            target = DEFAULT_TOKENIZER_DIR / TOKENIZER_FILE
+        else:
+            target = Path(path)
+            if target.is_dir():
+                target = target / TOKENIZER_FILE
+        if not target.is_file():
+            raise FileNotFoundError(
+                f"tokenizer introuvable : {target}. "
+                "Entraîne-le d'abord : python -m src.tokenizer.train_tokenizer --help"
+            )
+        return cls(Tokenizer.from_file(str(target)))
+
+    @property
+    def vocab_size(self) -> int:
+        return self._tok.get_vocab_size()
+
+    @property
+    def raw(self) -> Tokenizer:
+        return self._tok
+
+    def token_to_id(self, token: str) -> int | None:
+        return self._tok.token_to_id(token)
+
+    def encode(self, text: str, add_special_tokens: bool = False) -> list[int]:
+        encoding = self._tok.encode(text, add_special_tokens=add_special_tokens)
+        return list(encoding.ids)
+
+    def decode(self, ids: list[int], skip_special_tokens: bool = False) -> str:
+        return self._tok.decode(ids, skip_special_tokens=skip_special_tokens)
+
+
+def load_tokenizer(path: str | Path | None = None) -> CortexTokenizer:
+    """Raccourci de chargement (voir `CortexTokenizer.load`)."""
+    return CortexTokenizer.load(path)
+
+
+__all__ = [
+    "BOS_ID",
+    "BOS_TOKEN",
+    "EOS_ID",
+    "EOS_TOKEN",
+    "PAD_ID",
+    "PAD_TOKEN",
+    "SPECIAL_TOKEN_IDS",
+    "UNK_ID",
+    "UNK_TOKEN",
+    "VOCAB_SIZE",
+    "CortexTokenizer",
+    "load_tokenizer",
+]

src/tokenizer/special_tokens.py

@@ -0,0 +1,89 @@
+"""Source unique de vérité des tokens spéciaux de Cortex-0.
+
+Tout code qui a besoin d'un token spécial doit importer depuis ce module.
+Cela évite les divergences entre l'entraînement du tokenizer, le formatage
+des données, le modèle et les tests.
+
+Tous les tokens utilisent la forme ``<|...|>`` afin qu'ils ne puissent jamais
+être produits par la fusion BPE sur du texte naturel (les pipes ``<|`` ``|>``
+n'apparaissent pas dans le corpus FR nettoyé).
+
+Les identifiants sont **fixés explicitement** : ils sont donc stables d'un run
+à l'autre (voir test_special_token_ids_are_stable).
+"""
+
+from __future__ import annotations
+
+# --- Modèle de base ---------------------------------------------------------
+BASE_SPECIAL_TOKENS: tuple[str, ...] = (
+    "<|pad|>",
+    "<|bos|>",
+    "<|eos|>",
+    "<|unk|>",
+)
+
+# --- Raisonnement / agent (prévus pour la Phase 13) -------------------------
+REASONING_SPECIAL_TOKENS: tuple[str, ...] = (
+    "<|think|>",
+    "<|plan|>",
+    "<|tool_call|>",
+    "<|tool_result|>",
+    "<|critic|>",
+    "<|moe_route|>",
+)
+
+# --- Modalités (Phases 6 à 9) ----------------------------------------------
+MODALITY_SPECIAL_TOKENS: tuple[str, ...] = (
+    "<|image_start|>",
+    "<|image_end|>",
+    "<|image_pad|>",
+    "<|audio_start|>",
+    "<|audio_end|>",
+    "<|audio_pad|>",
+    "<|video_start|>",
+    "<|video_end|>",
+    "<|video_pad|>",
+)
+
+# Ordre canonique : base, raisonnement, modalités.
+ALL_SPECIAL_TOKENS: tuple[str, ...] = (
+    BASE_SPECIAL_TOKENS + REASONING_SPECIAL_TOKENS + MODALITY_SPECIAL_TOKENS
+)
+
+#: Nombre de tokens spéciaux réservés.
+N_SPECIAL_TOKENS: int = len(ALL_SPECIAL_TOKENS)
+
+#: Taille de vocabulaire finale visée (tokens spéciaux inclus).
+VOCAB_SIZE: int = 32000
+
+#: Identifiants explicites, dans l'ordre de ALL_SPECIAL_TOKENS.
+SPECIAL_TOKEN_IDS: dict[str, int] = {
+    token: idx for idx, token in enumerate(ALL_SPECIAL_TOKENS)
+}
+
+# --- Raccourcis sémantiques -------------------------------------------------
+PAD_TOKEN = "<|pad|>"
+BOS_TOKEN = "<|bos|>"
+EOS_TOKEN = "<|eos|>"
+UNK_TOKEN = "<|unk|>"
+
+BOS_ID = SPECIAL_TOKEN_IDS[BOS_TOKEN]
+EOS_ID = SPECIAL_TOKEN_IDS[EOS_TOKEN]
+PAD_ID = SPECIAL_TOKEN_IDS[PAD_TOKEN]
+UNK_ID = SPECIAL_TOKEN_IDS[UNK_TOKEN]
+
+# --- Emplacements des artefacts --------------------------------------------
+TOKENIZER_DIR = "tokenizer"
+TOKENIZER_FILE = "tokenizer.json"
+SPECIAL_TOKENS_MAP_FILE = "special_tokens_map.json"
+TOKENIZER_CONFIG_FILE = "tokenizer_config.json"
+
+
+def assert_consistency() -> None:
+    """Vérifie l'invariant interne (unicité, ids contigus, vocab suffisant)."""
+    assert len(set(ALL_SPECIAL_TOKENS)) == len(ALL_SPECIAL_TOKENS), "tokens dupliqués"
+    assert N_SPECIAL_TOKENS <= VOCAB_SIZE, "plus de tokens spéciaux que de vocabulaire"
+    assert sorted(SPECIAL_TOKEN_IDS.values()) == list(range(N_SPECIAL_TOKENS))
+
+
+assert_consistency()

src/tokenizer/train_tokenizer.py

@@ -0,0 +1,259 @@
+"""Entraînement du tokenizer BPE de Cortex-0 — 100 % from scratch.
+
+Aucun tokenizer pré-entraîné n'est utilisé : la lib `tokenizers` ne sert qu'à
+*apprendre* les fusions BPE sur notre corpus français.
+
+Choix techniques (détaillés dans docs/architecture.md §1) :
+
+* **BPE** : algorithme simple, déterministe, bien adapté au français.
+* **pre_tokenizer = ByteLevel** : découpe au niveau des octets, gère nativement
+  les accents, les emojis et tout script.
+* **initial_alphabet = 256 octets** : garantit que *chaque* octet possède un
+  token, donc que `encode` → `decode` est un **round-trip exact** pour n'importe
+  quelle entrée (emoji, japonais, arabe…). Sans cela, les caractères hors corpus
+  seraient perdus.
+* **byte_fallback = True** : repli sur les octets pour les caractères inconnus.
+* **min_frequency** : seuil de fusion (évite les tokens vus une seule fois).
+* Les tokens spéciaux sont **réservés en premier** (ids 0..N-1) et dans l'ordre
+  canonique, ce qui rend leurs identifiants stables et connus à l'avance.
+
+Exécution locale (petit échantillon — pour les tests) :
+
+    python -m src.tokenizer.train_tokenizer --local-corpus data/sample.txt \\
+        --vocab-size 2000 --out-dir /tmp/tok_toy
+
+Exécution complète (Colab) :
+
+    python -m src.tokenizer.train_tokenizer --max-mb 200 --vocab-size 32000
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import time
+from collections.abc import Iterable, Iterator
+from pathlib import Path
+from typing import Any
+
+from tokenizers import Tokenizer, decoders, models, pre_tokenizers, trainers
+
+from src.tokenizer.special_tokens import (
+    ALL_SPECIAL_TOKENS,
+    SPECIAL_TOKENS_MAP_FILE,
+    TOKENIZER_CONFIG_FILE,
+    TOKENIZER_FILE,
+    VOCAB_SIZE,
+)
+
+ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_OUT_DIR = ROOT / "tokenizer"
+
+
+def build_tokenizer(byte_fallback: bool = True) -> Tokenizer:
+    """Crée un tokenizer BPE vide, configuré au niveau des octets."""
+    tokenizer = Tokenizer(models.BPE(byte_fallback=byte_fallback))
+    tokenizer.pre_tokenizer = pre_tokenizers.ByteLevel(add_prefix_space=False)
+    tokenizer.decoder = decoders.ByteLevel()
+    return tokenizer
+
+
+def train_tokenizer(
+    corpus: Iterable[str],
+    vocab_size: int = VOCAB_SIZE,
+    min_frequency: int = 2,
+    byte_fallback: bool = True,
+    show_progress: bool = True,
+    length: int | None = None,
+) -> Tokenizer:
+    """Entraîne un BPE sur ``corpus``.
+
+    ``vocab_size`` est une **borne supérieure** : sur un corpus pauvre, la taille
+    finale peut être plus petite (il n'y a pas assez de fusions possibles).
+    """
+    tokenizer = build_tokenizer(byte_fallback=byte_fallback)
+    trainer = trainers.BpeTrainer(
+        vocab_size=vocab_size,
+        min_frequency=min_frequency,
+        special_tokens=list(ALL_SPECIAL_TOKENS),
+        initial_alphabet=pre_tokenizers.ByteLevel.alphabet(),
+        show_progress=show_progress,
+    )
+    tokenizer.train_from_iterator(corpus, trainer=trainer, length=length)
+    return tokenizer
+
+
+def assert_special_token_ids(tokenizer: Tokenizer) -> None:
+    """Vérifie que les tokens spéciaux occupent bien les ids 0..N-1 attendus."""
+    from src.tokenizer.special_tokens import SPECIAL_TOKEN_IDS
+
+    for token, expected_id in SPECIAL_TOKEN_IDS.items():
+        actual = tokenizer.token_to_id(token)
+        if actual != expected_id:
+            raise ValueError(
+                f"id de {token} = {actual}, attendu {expected_id}. "
+                "L'ordre des tokens spéciaux a changé."
+            )
+
+
+def save_artifacts(tokenizer: Tokenizer, out_dir: Path) -> dict[str, Path]:
+    """Écrit tokenizer.json, special_tokens_map.json et tokenizer_config.json."""
+    out_dir = Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    tok_path = out_dir / TOKENIZER_FILE
+    tokenizer.save(str(tok_path))
+
+    special_map = {
+        "pad_token": "<|pad|>",
+        "bos_token": "<|bos|>",
+        "eos_token": "<|eos|>",
+        "unk_token": "<|unk|>",
+        "additional_special_tokens": [
+            t for t in ALL_SPECIAL_TOKENS if t not in ("<|pad|>", "<|bos|>", "<|eos|>", "<|unk|>")
+        ],
+    }
+    map_path = out_dir / SPECIAL_TOKENS_MAP_FILE
+    map_path.write_text(json.dumps(special_map, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    config = {
+        "tokenizer_class": "Cortex0BPETokenizer",
+        "model_type": "bpe",
+        "vocab_size": tokenizer.get_vocab_size(),
+        "byte_fallback": True,
+        "pre_tokenizer": "ByteLevel",
+        "add_prefix_space": False,
+        "special_tokens": list(ALL_SPECIAL_TOKENS),
+        "pad_token": "<|pad|>",
+        "bos_token": "<|bos|>",
+        "eos_token": "<|eos|>",
+        "unk_token": "<|unk|>",
+    }
+    cfg_path = out_dir / TOKENIZER_CONFIG_FILE
+    cfg_path.write_text(json.dumps(config, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    return {TOKENIZER_FILE: tok_path, SPECIAL_TOKENS_MAP_FILE: map_path, TOKENIZER_CONFIG_FILE: cfg_path}
+
+
+# ---------------------------------------------------------------------------
+# Chargement du corpus
+# ---------------------------------------------------------------------------
+
+#: Corpus français publics, par ordre de préférence (nom -> config datasets).
+CORPUS_PRESETS: dict[str, dict[str, Any]] = {
+    "wikipedia_fr": {"path": "wikimedia/wikipedia", "name": "20231101.fr", "text_field": "text"},
+    "oscar_fr": {"path": "oscar-corpus/OSCAR-2301", "name": "fr", "text_field": "text"},
+}
+
+
+def iter_local_corpus(path: Path, max_bytes: int | None = None) -> Iterator[str]:
+    """Itère les lignes d'un fichier texte local (corpus de secours / tests)."""
+    path = Path(path)
+    consumed = 0
+    with path.open("r", encoding="utf-8", errors="ignore") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            consumed += len(line.encode("utf-8"))
+            yield line
+            if max_bytes is not None and consumed >= max_bytes:
+                break
+
+
+def iter_hf_corpus(
+    preset: str,
+    max_bytes: int,
+    text_field: str | None = None,
+    streaming: bool = True,
+) -> Iterator[str]:
+    """Itère un corpus Hugging Face en streaming, plafonné à ``max_bytes`` octets.
+
+    Aucun poids ni modèle pré-entraîné n'est utilisé : on ne lit que du **texte**.
+    """
+    from datasets import load_dataset  # import paresseux : dépendance lourde
+
+    if preset not in CORPUS_PRESETS:
+        raise ValueError(f"preset inconnu : {preset!r}. Choix : {sorted(CORPUS_PRESETS)}")
+    spec = CORPUS_PRESETS[preset]
+    field = text_field or spec["text_field"]
+
+    dataset = load_dataset(spec["path"], spec["name"], split="train", streaming=streaming)
+    consumed = 0
+    for example in dataset:
+        text = example.get(field)
+        if not text:
+            continue
+        consumed += len(text.encode("utf-8"))
+        yield text
+        if consumed >= max_bytes:
+            break
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+
+def _log(msg: str) -> None:
+    print(f"[train_tokenizer] {msg}", flush=True)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Entraîner le tokenizer BPE de Cortex-0.")
+    src = parser.add_mutually_exclusive_group(required=True)
+    src.add_argument("--local-corpus", type=Path, help="Fichier texte local")
+    src.add_argument(
+        "--preset",
+        choices=sorted(CORPUS_PRESETS),
+        help="Corpus Hugging Face public (streaming)",
+    )
+    parser.add_argument("--max-mb", type=float, default=200.0, help="Plafond de corpus en Mo")
+    parser.add_argument("--vocab-size", type=int, default=VOCAB_SIZE)
+    parser.add_argument("--min-frequency", type=int, default=2)
+    parser.add_argument("--out-dir", type=Path, default=DEFAULT_OUT_DIR)
+    parser.add_argument(
+        "--allow-smaller-vocab",
+        action="store_true",
+        help="Ne pas échouer si le vocabulaire final est < vocab-size (petit corpus).",
+    )
+    args = parser.parse_args()
+
+    max_bytes = int(args.max_mb * 1024 * 1024)
+
+    if args.local_corpus:
+        _log(f"corpus local : {args.local_corpus}")
+        corpus: Iterable[str] = iter_local_corpus(args.local_corpus, max_bytes=max_bytes)
+    else:
+        _log(f"corpus Hugging Face : {args.preset} (streaming, plafond {args.max_mb} Mo)")
+        corpus = iter_hf_corpus(args.preset, max_bytes=max_bytes)
+
+    _log("entraînement BPE…")
+    start = time.time()
+    tokenizer = train_tokenizer(
+        corpus,
+        vocab_size=args.vocab_size,
+        min_frequency=args.min_frequency,
+        show_progress=True,
+    )
+    elapsed = time.time() - start
+
+    final_size = tokenizer.get_vocab_size()
+    _log(f"vocab final : {final_size} (cible {args.vocab_size}) en {elapsed:.1f}s")
+    if final_size > args.vocab_size:
+        raise SystemExit(f"ERREUR : vocab final {final_size} > cible {args.vocab_size}")
+    if final_size < args.vocab_size and not args.allow_smaller_vocab:
+        raise SystemExit(
+            f"ERREUR : vocab final {final_size} < cible {args.vocab_size}. "
+            "Corpus trop petit. Relance avec --allow-smaller-vocab ou augmente --max-mb."
+        )
+
+    assert_special_token_ids(tokenizer)
+    paths = save_artifacts(tokenizer, args.out_dir)
+    for name, path in paths.items():
+        _log(f"écrit : {path} ({name})")
+    _log("terminé.")
+
+
+if __name__ == "__main__":
+    main()

tests/test_phase0_config.py

@@ -64,9 +64,17 @@ def test_tokenizer_vocab_size(cfg):
 
 def test_modality_tokens_cover_all_modalities(cfg):
     toks = cfg["tokenizer"]["modality_tokens"]
-    for prefix in ("image", "audio", "video"):
-        assert f"{prefix}_start" in toks
-        assert f"{prefix}_end" in toks
+    for modality in ("image", "audio", "video"):
+        assert modality in toks, f"modalité manquante : {modality}"
+        assert len(toks[modality]) == 3, f"{modality} doit avoir start/end/pad"
+        for suffix in ("start", "end", "pad"):
+            assert f"<|{modality}_{suffix}|>" in toks[modality]
+
+
+def test_reasoning_tokens_defined(cfg):
+    reasoning = cfg["tokenizer"]["reasoning_tokens"]
+    assert len(reasoning) == 6
+    assert "<|think|>" in reasoning and "<|moe_route|>" in reasoning
 
 
 def test_projectors_align_to_text_space(cfg):

tests/test_tokenizer.py

@@ -0,0 +1,241 @@
+"""Phase 1 — tests unitaires du tokenizer BPE de Cortex-0.
+
+Rapides (CPU, quelques secondes) : un **tokenizer jouet** est entraîné une fois
+pour toute la session sur un petit corpus français embarqué. Le tokenizer final
+(32k, corpus ~200 Mo) est produit par `notebooks/01_tokenizer.ipynb` sur Colab.
+
+Deux catégories de tests :
+  * invariants qui ne dépendent PAS du corpus (tokens spéciaux, round-trip,
+    accents, emojis, scripts inconnus, byte_fallback) → testés sur le tokenizer jouet ;
+  * invariants du tokenizer FINAL (vocab == 32000) → ignorés si l'artefact réel
+    n'est pas présent (avant le run Colab).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from src.tokenizer import load_tokenizer
+from src.tokenizer.special_tokens import (
+    ALL_SPECIAL_TOKENS,
+    BASE_SPECIAL_TOKENS,
+    MODALITY_SPECIAL_TOKENS,
+    N_SPECIAL_TOKENS,
+    REASONING_SPECIAL_TOKENS,
+    SPECIAL_TOKEN_IDS,
+    SPECIAL_TOKENS_MAP_FILE,
+    TOKENIZER_CONFIG_FILE,
+    TOKENIZER_DIR,
+    VOCAB_SIZE,
+)
+from src.tokenizer.train_tokenizer import (
+    assert_special_token_ids,
+    save_artifacts,
+    train_tokenizer,
+)
+
+ROOT = Path(__file__).resolve().parents[1]
+
+# 20 phrases françaises variées (accents, ponctuation, majuscules, chiffres).
+FRENCH_SENTENCES = [
+    "Bonjour, comment allez-vous aujourd'hui ?",
+    "Le café coûte trois euros à Paris.",
+    "L'élève écrit une phrase sur le tableau noir.",
+    "Où est la forêt de Brocéliande ?",
+    "Le garçon mange une pomme rouge et juteuse.",
+    "Les enfants jouent dans le jardin après l'école.",
+    "Il fait très beau à Montréal en été.",
+    "La bibliothèque ouvre à neuf heures précises.",
+    "Ce problème de mathématiques est vraiment difficile.",
+    "Le chat dort paisiblement sur le canapé du salon.",
+    "J'ai acheté deux baguettes et un croissant.",
+    "La France compte de nombreuses régions pittoresques.",
+    "Elle répond toujours avec beaucoup de patience.",
+    "N'oubliez pas de fermer la porte à clé !",
+    "Le train pour Lyon part dans quinze minutes.",
+    "Nous irons à la mer dès que possible.",
+    "Cette recette nécessite un four préchauffé.",
+    "La langue française est riche en nuances.",
+    "Il pleut des cordes depuis ce matin.",
+    "Merci beaucoup pour votre aide précieuse.",
+]
+
+TOY_CORPUS = FRENCH_SENTENCES * 60 + [
+    "Le soleil brille, les oiseaux chantent, tout va bien.",
+    "Une phrase française supplémentaire pour l'entraînement.",
+]
+
+ACCENTS = "é è ê à ç ù î ô ë ï ü ÿ œ æ"
+EMOJIS = "🦾 🇬🇳 🚀 🙂 ❤️ 🎉"
+UNKNOWN_SCRIPTS = "こんにちは世界 مرحبا بالعالم Здравствуй мир"
+
+
+@pytest.fixture(scope="session")
+def toy_dir(tmp_path_factory) -> Path:
+    """Entraîne un tokenizer jouet (vocab ~1500) une fois par session."""
+    out = tmp_path_factory.mktemp("toy_tokenizer")
+    tok = train_tokenizer(TOY_CORPUS, vocab_size=1500, min_frequency=1, show_progress=False)
+    save_artifacts(tok, out)
+    return out
+
+
+@pytest.fixture(scope="session")
+def toy(toy_dir):
+    return load_tokenizer(toy_dir)
+
+
+# ---------------------------------------------------------------------------
+# Source de vérité des tokens spéciaux
+# ---------------------------------------------------------------------------
+
+
+def test_special_token_lists_are_disjoint_and_unique():
+    assert len(set(ALL_SPECIAL_TOKENS)) == N_SPECIAL_TOKENS
+    assert set(BASE_SPECIAL_TOKENS).isdisjoint(REASONING_SPECIAL_TOKENS)
+    assert set(BASE_SPECIAL_TOKENS).isdisjoint(MODALITY_SPECIAL_TOKENS)
+    assert set(REASONING_SPECIAL_TOKENS).isdisjoint(MODALITY_SPECIAL_TOKENS)
+
+
+def test_special_token_counts():
+    assert len(BASE_SPECIAL_TOKENS) == 4
+    assert len(REASONING_SPECIAL_TOKENS) == 6
+    assert len(MODALITY_SPECIAL_TOKENS) == 9
+    assert N_SPECIAL_TOKENS == 19
+
+
+def test_special_token_ids_are_contiguous():
+    assert sorted(SPECIAL_TOKEN_IDS.values()) == list(range(N_SPECIAL_TOKENS))
+
+
+def test_required_special_tokens_present():
+    required = [
+        "<|pad|>", "<|bos|>", "<|eos|>", "<|unk|>",
+        "<|think|>", "<|plan|>", "<|tool_call|>", "<|tool_result|>", "<|critic|>", "<|moe_route|>",
+        "<|image_start|>", "<|image_end|>", "<|image_pad|>",
+        "<|audio_start|>", "<|audio_end|>", "<|audio_pad|>",
+        "<|video_start|>", "<|video_end|>", "<|video_pad|>",
+    ]
+    for token in required:
+        assert token in SPECIAL_TOKEN_IDS, f"token spécial manquant : {token}"
+
+
+# ---------------------------------------------------------------------------
+# Artefacts sur disque
+# ---------------------------------------------------------------------------
+
+
+def test_three_artifacts_written(toy_dir):
+    for name in ("tokenizer.json", SPECIAL_TOKENS_MAP_FILE, TOKENIZER_CONFIG_FILE):
+        assert (toy_dir / name).is_file(), f"{name} absent"
+
+
+def test_special_tokens_map_contains_all_required(toy_dir):
+    data = json.loads((toy_dir / SPECIAL_TOKENS_MAP_FILE).read_text(encoding="utf-8"))
+    present = set(data.get("additional_special_tokens", []))
+    present |= {data.get("pad_token"), data.get("bos_token"), data.get("eos_token"), data.get("unk_token")}
+    for token in ALL_SPECIAL_TOKENS:
+        assert token in present, f"{token} absent de special_tokens_map.json"
+
+
+def test_special_token_ids_match_expected(toy):
+    assert_special_token_ids(toy.raw)
+    for token, expected in SPECIAL_TOKEN_IDS.items():
+        assert toy.token_to_id(token) == expected, token
+
+
+def test_special_token_ids_stable_across_two_runs(tmp_path):
+    a = train_tokenizer(TOY_CORPUS, vocab_size=1500, min_frequency=1, show_progress=False)
+    b = train_tokenizer(TOY_CORPUS, vocab_size=1500, min_frequency=1, show_progress=False)
+    assert a.get_vocab() == b.get_vocab()
+
+
+# ---------------------------------------------------------------------------
+# Round-trip et cas limites
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("sentence", FRENCH_SENTENCES)
+def test_roundtrip_french_sentences(toy, sentence):
+    assert toy.decode(toy.encode(sentence)) == sentence
+
+
+def test_roundtrip_accents(toy):
+    assert toy.decode(toy.encode(ACCENTS)) == ACCENTS
+
+
+def test_roundtrip_emojis(toy):
+    assert toy.decode(toy.encode(EMOJIS)) == EMOJIS
+
+
+def test_roundtrip_unknown_scripts(toy):
+    assert toy.decode(toy.encode(UNKNOWN_SCRIPTS)) == UNKNOWN_SCRIPTS
+
+
+def test_roundtrip_empty_and_whitespace(toy):
+    assert toy.decode(toy.encode("")) == ""
+    assert toy.decode(toy.encode("   ")) == "   "
+
+
+def test_roundtrip_very_long(toy):
+    long_text = " ".join(FRENCH_SENTENCES * 20)
+    assert toy.decode(toy.encode(long_text)) == long_text
+
+
+def test_special_tokens_recognized_when_in_text(toy):
+    text = "Bonjour <|bos|> le monde <|eos|>"
+    ids = toy.encode(text)
+    assert toy.token_to_id("<|bos|>") in ids
+    assert toy.token_to_id("<|eos|>") in ids
+
+
+def test_encode_returns_ints(toy):
+    ids = toy.encode("Un test.")
+    assert ids and all(isinstance(i, int) for i in ids)
+    assert all(0 <= i < toy.vocab_size for i in ids)
+
+
+def test_decode_skips_special_tokens(toy):
+    ids = [toy.token_to_id("<|bos|>")] + toy.encode("salut") + [toy.token_to_id("<|eos|>")]
+    decoded = toy.decode(ids, skip_special_tokens=True)
+    assert "<|bos|>" not in decoded and "<|eos|>" not in decoded
+    assert "salut" in decoded
+
+
+def test_byte_fallback_is_enabled(toy):
+    # Un caractère jamais vu (CJK) doit survivre au round-trip -> repli octet.
+    assert toy.decode(toy.encode("漢字第")) == "漢字第"
+
+
+# ---------------------------------------------------------------------------
+# Entraînement
+# ---------------------------------------------------------------------------
+
+
+def test_trainer_respects_vocab_size_cap():
+    tok = train_tokenizer(TOY_CORPUS, vocab_size=800, min_frequency=1, show_progress=False)
+    assert tok.get_vocab_size() <= 800
+
+
+def test_min_frequency_reduces_vocab():
+    low = train_tokenizer(TOY_CORPUS, vocab_size=2000, min_frequency=1, show_progress=False)
+    high = train_tokenizer(TOY_CORPUS, vocab_size=2000, min_frequency=20, show_progress=False)
+    assert high.get_vocab_size() <= low.get_vocab_size()
+
+
+# ---------------------------------------------------------------------------
+# Invariants du tokenizer FINAL (nécessite le run Colab)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.skipif(
+    not (ROOT / TOKENIZER_DIR / "tokenizer.json").is_file(),
+    reason="tokenizer final absent : généré par notebooks/01_tokenizer.ipynb (Colab)",
+)
+def test_final_tokenizer_vocab_size_is_exactly_32000():
+    final = load_tokenizer()
+    assert final.vocab_size == VOCAB_SIZE
+    for token, expected in SPECIAL_TOKEN_IDS.items():
+        assert final.token_to_id(token) == expected

tokenizer/special_tokens_map.json

@@ -0,0 +1,23 @@
+{
+  "pad_token": "<|pad|>",
+  "bos_token": "<|bos|>",
+  "eos_token": "<|eos|>",
+  "unk_token": "<|unk|>",
+  "additional_special_tokens": [
+    "<|think|>",
+    "<|plan|>",
+    "<|tool_call|>",
+    "<|tool_result|>",
+    "<|critic|>",
+    "<|moe_route|>",
+    "<|image_start|>",
+    "<|image_end|>",
+    "<|image_pad|>",
+    "<|audio_start|>",
+    "<|audio_end|>",
+    "<|audio_pad|>",
+    "<|video_start|>",
+    "<|video_end|>",
+    "<|video_pad|>"
+  ]
+}

tokenizer/tokenizer_config.json

@@ -0,0 +1,33 @@
+{
+  "tokenizer_class": "Cortex0BPETokenizer",
+  "model_type": "bpe",
+  "vocab_size": 32000,
+  "byte_fallback": true,
+  "pre_tokenizer": "ByteLevel",
+  "add_prefix_space": false,
+  "special_tokens": [
+    "<|pad|>",
+    "<|bos|>",
+    "<|eos|>",
+    "<|unk|>",
+    "<|think|>",
+    "<|plan|>",
+    "<|tool_call|>",
+    "<|tool_result|>",
+    "<|critic|>",
+    "<|moe_route|>",
+    "<|image_start|>",
+    "<|image_end|>",
+    "<|image_pad|>",
+    "<|audio_start|>",
+    "<|audio_end|>",
+    "<|audio_pad|>",
+    "<|video_start|>",
+    "<|video_end|>",
+    "<|video_pad|>"
+  ],
+  "pad_token": "<|pad|>",
+  "bos_token": "<|bos|>",
+  "eos_token": "<|eos|>",
+  "unk_token": "<|unk|>"
+}