Problème
Un élève bloqué sur un concept (gravité, dérivée, pH, tri à bulles) n’a que du texte ou des vidéos qui ne répondent pas à sa question précise. Générer une animation à la demande avec un modèle de langage est possible, mais ce que le modèle écrit est rarement fiable : un code qui tourne peut afficher une figure fausse ou confuse, et attendre plusieurs minutes une vidéo fait perdre l’élève. Deux contraintes ont guidé le projet : la démonstration ne doit pas pouvoir échouer, et une explication fausse vaut pire que pas d’explication.
Solution
Le modèle écrit un document JSON (plan, paramètres, modèle de calcul, scènes) validé par un schéma Zod, que des primitives du dépôt interprètent dans un lecteur Remotion. Un modèle juge relit le plan, puis chaque scène passe six règles déterministes et un contrôle de conformité : une scène non validée est corrigée ou écartée, jamais affichée. Les scènes arrivent en flux, la première se jouant pendant que les suivantes se préparent, et un mode dégradé propose 24 explications de référence sans réseau ni base.
Mon rôle
- Produit, design, développement full-stack et déploiement, en solo, du 12 au 24 octobre 2026 (153 commits)
- Pipeline de génération : sortie du modèle contrainte par schéma, plan relu par un juge, six règles de validation par scène, quatre rôles de modèle pouvant viser chacun un fournisseur différent
- Interpréteur d’expressions écrit pour le projet (sans eval), pour que les curseurs recalculent la figure et le résultat à chaque image, avec un budget de 16 ms par image vérifié par un script
- Exécution isolée du code Manim généré : conteneur sans réseau, racine en lecture seule, sans capacité Linux, arrêt à 150 s, contrôle statique en simple préfiltre
- Voix synthétisée avec repli entre Azure Speech, Kokoro et Pocket TTS ; sans voix joignable, l’explication se joue avec les sous-titres seuls
- Design system « Planche » (thèmes Papier et Tableau), accessibilité, français et anglais dès le départ
- Méthode Spec Kit : constitution de huit principes, spécification, plan, 98 tâches et contrats ; développement mené avec Claude Code et des agents de code délégués par tâche
Impact
- Premier jeton en 0,7 à 1,0 s (deepseek-flash sans réflexion) ; première scène sans voix en moins de 15 s sur quatre concepts, avec un fournisseur réel
- Une explication déjà générée (même concept, niveau et langue) repart du cache en environ 1 s
- Rôle du juge réglé après mesure : plus de 20 s avec réflexion, 2 s sans, donc réflexion coupée sur ce rôle
- Rendu Manim d’une scène de 30 s en 20 s (2 CPU, 2 Go) ; une connexion sortante et une écriture hors du volume d’échange échouent bien
- ≈ 85 000 lignes de TypeScript, 118 fichiers de tests, 10 parcours Playwright, 50 fichiers Python ; 91 tâches sur 98 faites
- Limites : les 24 explications de référence ont été produites avec le modèle et ne sont pas encore relues par une personne ; aucun test avec des élèves n’a eu lieu, donc aucun retour d’utilisateur réel à citer
- Limites : le jeu de 40 questions n’a pas encore été joué sur la version déployée, et l’isolation du bac à sable Manim est vérifiée en local, pas encore sous Dokploy
Fonctionnalités clés
- Question libre : une phrase à compléter, le niveau (collège, lycée, supérieur), la langue (français, anglais) et le thème (Papier ou Tableau) ; la première scène se joue pendant que les suivantes se préparent
- Curseurs sur les grandeurs du concept (masses, distance, tension…) : la figure, les valeurs et le résultat surligné se recalculent à chaque image
- « Je n’ai toujours pas compris » : une autre analogie, une version plus simple, un zoom sur une étape ou une question de suivi libre, avec la liste des versions de la session
- Quiz de quelques questions : une erreur renvoie à la scène à revoir
- Colophon « Comment cette explication a été construite » : plan pédagogique, analogie retenue et verdict de vérification de chaque scène
- Voix synchronisée sur la durée réelle des fichiers audio, sous-titres, raccourcis clavier et mouvement réduit respecté
- Lien de partage public et export MP4 préparés en arrière-plan ; version approfondie en Manim rendue dans un conteneur isolé
- 24 explications de référence (12 concepts × 2 langues, six matières) jouables sans réseau ni base de données, et un point de santé qui expose l’état de chaque service
