# Apprentissage continu d'UNIQUE (tout sur Hugging Face)

> **Obsolète depuis la v4.1** : le mode Jobs (pilote automatique, professeur, alimentation, export) est retiré. Le fonctionnement actuel est décrit dans [ADR-004](ADR-004-LOCAL.md).

```
OpenCodeInstruct ─▶ job d'alimentation (CPU, chaque heure) ─┐
Space M.O.U.H. (sessions avec tests) ───────────────────────┴─▶ dataset privé RDS777/mouh-trajectories
                                                                        │
            ┌───────────── job d'entraînement (GPU T4, relancé chaque heure s'il ne tourne pas) ◀┘
            │  boucle : SFT (TRL) → porte pass@1 → GRPO récompensé par pytest (TRL) → porte → …
            ▼
   adaptateur promu RDS777/unique-qwen2.5-coder-0.5b-lora ─▶ redémarrage du Space (générateur « UNIQUE »)
   progression toutes les ~20 s ─▶ bucket privé RDS777/unique-progress ─▶ panneau en direct dans le Space
```

## La boucle

1. **Alimentation** (`jobs/ingest_tasks.py`, CPU `cpu-upgrade`, chaque heure) : tranche suivante de 4 000 lignes de
   `nvidia/OpenCodeInstruct` (CC BY 4.0), tests convertis en pytest, solutions **ré-exécutées**, seules celles qui passent
   sont ajoutées.
2. **SFT** (`trl.SFTTrainer`, LoRA r=16, perte sur la réponse seulement) sur la tranche suivante de 2 000 exemples,
   en repartant de l'adaptateur en service.
3. **Porte** : pass@1 réel (tests pytest exécutés) sur un **heldout figé** de 100 tâches jamais vues. Promotion seulement si
   le candidat fait strictement mieux que l'adaptateur en service (ou que la base au départ).
4. **GRPO** (`trl.GRPOTrainer`) : 4 solutions générées par tâche, récompense = 1 si les tests passent, 0,1 si le code
   compile mais échoue, 0 sinon. Même porte.
5. Après une promotion, le Space redémarre et charge le nouvel adaptateur.

Un passage dure au plus 11 h 30 (UNIQUE_RUN_HOURS) ; le job planifié chaque heure relance la boucle dès qu'aucun passage ne tourne
(jamais deux à la fois). Un passage qui démarre alors que le budget GPU du jour est épuisé s'arrête aussitôt.

## Améliorations (v3) et interrupteurs de retour arrière

Chaque amélioration se coupe par une variable du Space (Settings → Variables), sans ré-uploader de fichier :
le Space recrée alors le job concerné avec l'ancien comportement.

| Amélioration | Ce qu'elle fait | Interrupteur (mettre `0` pour revenir en arrière) |
|---|---|---|
| Curriculum adaptatif | GRPO choisit en priorité les tâches que l'élève réussit *parfois* (les seules qui donnent un signal) ; statistiques par tâche gardées d'un passage à l'autre | `UNIQUE_CURRICULUM` |
| Vrais échecs | les échecs d'UNIQUE pendant GRPO sont enregistrés avec leur vraie trace pytest (`failures/` du dataset) | `UNIQUE_SAVE_FAILURES` |
| Réflexion fondée sur les tests | 25 % des prompts GRPO demandent de corriger un échec réel à partir de sa trace | `GRPO_REPAIR_FRACTION` (= `0`) |
| Modèle maître | job toutes les 2 h : 30 tâches nouvelles au niveau de l'élève (facile / moyen / difficile selon son score), gardées seulement si la solution passe ses tests **et** si les tests tuent au moins 60 % des mutants (test par mutation) ; + correction des vrais échecs, validée par pytest | `UNIQUE_TEACHER` (supprime le job) |
| Benchmark indépendant | HumanEval (164 tâches, jamais utilisé à l'entraînement) mesuré pour la base et pour chaque nouvel adaptateur en service ; les sessions qui partagent 13 mots consécutifs avec HumanEval sont retirées de l'entraînement | `UNIQUE_BENCHMARK` |
| Mémoire à long terme | recherche BM25 des 2 tâches validées les plus proches, données en exemple ; jamais la tâche elle-même ni un quasi-doublon. Mesurée avec / sans sur le heldout (panneau) | mesure : `UNIQUE_MEMORY_AB` ; utilisation dans le Space : `UNIQUE_MEMORY=1` seulement si le panneau affiche « gain » |

Modèle maître : `UNIQUE_TEACHER_MODEL` (défaut `Qwen/Qwen3-Coder-30B-A3B-Instruct`), appelé via les Inference Providers
de Hugging Face, facturé à l'usage sur votre compte. Le jeton `HF_TOKEN` doit avoir le droit « Make calls to Inference
Providers ». Sans ce droit, le job du maître échoue proprement et les autres continuent.

Retour complet à la version précédente : remettre les fichiers de la version « boucle continue » (onglet Files →
historique de chaque fichier), puis redémarrer le Space ; les jobs sont recréés automatiquement.

## Panneau dans le Space

En haut de la page : phase en cours avec barre de progression et temps restant, budget GPU du jour, perte et
récompense, score base / meilleur en service, courbe des scores avec les promotions. Rafraîchi toutes les 15 s.

## Réglages (Settings → Variables and secrets)

| Variable | Défaut | Effet |
|---|---|---|
| `UNIQUE_AUTOTRAIN` | — | `1` = accord pour les dépenses ; sans elle, rien ne démarre |
| `UNIQUE_MAX_GPU_HOURS_PER_DAY` | `24` | plafond quotidien d'heures GPU (24 = non-stop) |
| `UNIQUE_FLAVOR` | `t4-small` | matériel d'entraînement |
| `UNIQUE_INGEST` | `1` | `0` coupe l'alimentation |
| `INGEST_SOURCE` | `opencodeinstruct` | `kodcode` possible (licence CC BY-NC : non commercial) |

Le secret `UNIQUE_ADMIN_KEY` protège les boutons « Alimenter maintenant » et « Entraîner maintenant ».
Pour tout arrêter : suspendre les deux jobs sur huggingface.co/settings/jobs (retirer la variable ne suffit pas).

## Coûts

`t4-small` : 0,40 $/h. En non-stop : environ 9,60 $ par jour, 290 $ par mois. L'alimentation CPU coûte quelques
centimes par jour. Réduire `UNIQUE_MAX_GPU_HOURS_PER_DAY` plafonne la dépense.

## Limites

- Non mesuré en conditions réelles : durée d'un cycle sur T4, part des tâches qui passent la re-vérification, gain réel.
- GRPO sur un modèle de 0,5 Md n'apprend que si certaines générations réussissent déjà : sur les tâches trop dures,
  toutes les récompenses sont nulles et la phase n'apporte rien (visible dans le panneau, `reward` proche de 0).
- « Certifié » = passe les tests fournis. La qualité du modèle dépend de celle des tests.
- Le heldout est figé pour que les scores restent comparables ; s'il est agrandi, la base et l'adaptateur en service
  sont re-mesurés avant toute nouvelle promotion.