# Pipeline CORTEX

Ce dossier contient le pipeline qui produit les **propres poids CORTEX** de
Frankenstein-Labs : définition du modèle, tokenizer, entraînement, datasets,
checkpoints et évaluation.

## Règle de provenance

Ce pipeline est **strictement séparé** du checkpoint de 1,65 T distribué dans ce dépôt.

| | Checkpoint distribué | Poids produits par ce pipeline |
|---|---|---|
| Origine | `deepseek-ai/DeepSeek-V4-Pro-0813` | Frankenstein-Labs |
| Entraînement | DeepSeek-AI | Frankenstein-Labs |
| Fichiers | `model-0000*.safetensors` | `checkpoints/**` |
| Licence | MIT (Copyright 2023 DeepSeek) | MIT |
| Modifié par ce pipeline | **non** | — |

Aucun script de ce dossier ne lit, ne modifie ni ne remplace les 66 shards distribués.
`base_model` ne sera renseigné pour un checkpoint CORTEX que si ses poids dérivent
réellement d'un autre modèle — ce qui n'est pas le cas des poids initialisés ici.

## Structure

```text
model/          définition du modèle et entrées/sorties de checkpoints
tokenizer/      chargement et validation du tokenizer CORTEX
training/       boucle d'entraînement
datasets/       datasets de code, avec traçabilité des sources et licences
checkpoints/    checkpoints produits (non versionnés)
evaluation/     évaluation : perte, perplexité, génération
configs/cortex/ configurations d'entraînement
```

## Démarrage rapide

```bash
pip install torch safetensors tokenizers transformers numpy pytest

# 1. Construire les datasets (traçabilité des licences incluse)
python datasets/build.py --all --limit 200

# 2. Entraîner
PYTHONPATH=. python3 -c "
from training.train import train
print(train('configs/cortex/cortex-dev-1.json', ['cortex-code-sft'],
            out_dir='checkpoints/dev', max_steps=100, device='cpu', progress=True))
"

# 3. Évaluer
PYTHONPATH=. python3 -c "
import json
from evaluation.evaluate import report
print(json.dumps(report('checkpoints/dev/final'), indent=2))
"

# 4. Tests de cohérence
PYTHONPATH=. python3 -m pytest tests/test_cortex_pipeline.py -q
```

## Configuration de développement

`configs/cortex/cortex-dev-1.json` décrit un modèle **entraînable** :

| Élément | Valeur |
|---|---|
| Paramètres | ~174,8 M |
| Couches | 12 |
| `hidden_size` | 768 |
| Têtes d'attention | 12 (4 têtes KV) |
| Contexte | 2 048 |
| Vocabulaire | 129 280 (tokenizer CORTEX réutilisé) |
| Précision | float32 |

Le vocabulaire est repris du tokenizer CORTEX pour que les modèles de
développement partagent le même espace de tokens que la distribution principale.

## État réel

| Étape | État |
|---|---|
| Audit de l'architecture distribuée | fait — `docs/architecture-technique.fr.md` |
| Définition du modèle | fait, testée |
| Tokenizer | fait, validé contre `vocab_size` |
| Initialisation et checkpoints | fait, testés (manifeste + SHA-256) |
| Datasets avec licences | fait |
| Boucle d'entraînement | fait, vérifiée sur CPU |
| Entraînement complet | **non exécuté** — voir ci-dessous |
| Remplacement des poids distribués | **non fait, et non prévu** |

### Ce qui a été mesuré

- Les tests de `tests/test_cortex_pipeline.py` passent.
- Un entraînement court sur CPU fait **baisser la perte** sur un corpus de code réel
  (CodeAlpaca), ce qui montre que le pipeline apprend réellement.
- Un checkpoint est écrit, son manifeste est vérifié, et une corruption est détectée.

### Ce qui n'a pas été mesuré

- Aucun entraînement long n'a été mené : l'environnement de développement dispose de
  4 cœurs CPU, ~15 Gio de RAM et aucun GPU. Les étapes y prennent plusieurs dizaines de
  secondes, contre quelques millisecondes sur GPU.
- Aucune qualité de génération de code n'est revendiquée pour l'instant. Un modèle de
  175 M paramètres entraîné quelques centaines d'étapes ne produit pas de code fiable,
  et ce document ne prétend pas le contraire.

## Feuille de route

1. Entraîner `cortex-dev-1` sur GPU jusqu'à convergence, et publier les courbes réelles.
2. Ajouter une évaluation d'exécution (pass@k) sur les tests MBPP, en sandbox.
3. Passer à une échelle intermédiaire (~1 B) une fois le pipeline validé.
4. Ne toucher à `base_model` et à la présentation publique que lorsque des poids CORTEX
   réellement entraînés le justifient.