open-school/MEMORY.md

Memoire Projet

Contexte

Ce projet est un POC de professeur virtuel pour enfants, avec:

• frontend React + Vite
• backend FastAPI
• PostgreSQL pour les donnees eleve
• Redis present dans la stack
• integration OpenAI pour reponses texte et transcription audio

Points Importants

• Le frontend appelle l'API via le prefixe /api.
• Le backend expose une route POST /transcribe pour la transcription audio.
• La route /transcribe utilise UploadFile, donc python-multipart est requis dans le backend.
• Le backend a un socle d'authentification avec comptes users, roles student, teacher, maintenance.
• Le compte admin/prof initial est seede depuis .env via ADMIN_USERNAME et ADMIN_PASSWORD.
• Le login pose un cookie HTTP-only professeur_top_session et renvoie aussi un token bearer.
• Le frontend affiche maintenant une page de connexion avant l'application et verifie la session via /auth/me.
• Apres connexion admin/prof, l'interface actuelle reste accessible avec un bouton de deconnexion.
• Les routes eleves principales verifient maintenant les roles:
  • teacher et maintenance peuvent acceder aux eleves
  • student ne peut acceder qu'a son propre student_id
• Le backend expose POST /admin/student-accounts pour creer une fiche eleve et son compte login en une seule operation.
• Le frontend masque le choix/creation d'eleve pour un compte student et ouvre directement sa propre seance.
• Le backend expose GET /students/{student_id}/messages pour relire l'historique de conversation stocke en base.
• Les reponses aux mini-tests sont maintenant aussi enregistrees dans messages avec le role user.
• Le frontend recharge l'historique quand un eleve est selectionne, mais ne met plus automatiquement la derniere ancienne phrase au centre.
• Au demarrage d'une nouvelle seance, Professeur TOP doit faire une courte reprise de l'historique puis annoncer le cours du jour.
• L'interface de seance est maintenant en hauteur fixe 100vh: pas de scroll global, cours central au milieu, pas de conversation visible.
• La conversation reste stockee en base pour analyse, mais l'ecran de cours remplace la consigne/reponse courante au lieu d'empiler des bulles.
• Les reponses de mini-test utilisent la meme zone de reponse eleve en bas; le texte du prof reste au-dessus et pourra accueillir une image sous le texte.
• Cote eleve, le bouton principal bascule entre Demarrer la seance et Fin de la seance.
• Cote eleve, la colonne gauche affiche les themes du jour: une card lecon avec pourcentage local, une card exercice avec statut.
• Le bilan complet de progression reste reserve aux vues prof/admin.
• Les options TTS visibles doivent etre libellees Voix Douce, Voix Rigolote, etc.; la mention "Voix IA non humaine..." est portee par un tooltip.
• Le declenchement manuel de mini-test/exercice doit disparaitre de l'interface eleve; le programme doit etre determine par Professeur TOP.
• A prevoir cote admin: tableau par eleve et prompts/instructions personnalises pour guider Professeur TOP par eleve.
• L'ecran eleve affiche une petite card "Transmis au prof" au-dessus de la zone de saisie pour montrer le texte capte/envoye.
• Le backend ajoute une consigne de tours de parole courts pour que Professeur TOP laisse le temps a l'enfant de repondre.
• Gestion interruption a prevoir: detection de parole pendant TTS, pause audio, transcription, classification pertinent/accidentel, puis reprise courte.
• La transcription audio force maintenant language="fr" avec un prompt francais pour eviter les erreurs de detection de langue sur phrases tres courtes.
• Le vrai docker-compose.yml de production n'est pas dans ce repo. Il est situe un niveau au-dessus sur le serveur.
• La conf nginx reelle route:
  • /api/ vers tutor-backend:8000
  • / vers tutor-frontend:3000

Dictée Vocale

• L'ancien bouton de dictee marchait en mode manuel avec MediaRecorder.start() puis stop().
• Le mode actuel est un mode mains libres:
  • activation via un clic utilisateur
  • enregistrement automatique
  • detection du silence
  • transcription automatique
  • envoi automatique du message
• Firefox s'est montre capricieux avec la mesure temps reel via AnalyserNode.
• La solution retenue s'appuie sur un traitement plus direct du flux audio pour determiner le niveau sonore.
• L'ecoute se rearme automatiquement apres:
  • la transcription/envoi du message eleve
  • la fin de lecture vocale du professeur

Voix du Professeur

• L'ancien systeme de voix navigateur a ete remplace par une vraie TTS OpenAI.
• Le backend expose maintenant:
  • GET /tts/profiles pour lister les profils de voix
  • POST /tts pour generer un MP3 a partir d'un texte et d'un profile_id
• Les profils actuels sont:
  • rigolote
  • petillante
  • douce
  • sobre
• Chaque profil TTS definit:
  • une voix OpenAI
  • une vitesse
  • des instructions de style vocal
• Le frontend ne depend plus de speechSynthesis pour la voix sortante.
• Le choix de voix est memorise dans localStorage avec la cle professeur-top-tts-profile.
• La lecture audio se fait via un blob MP3 retourne par le backend.
• Le mode micro auto doit continuer a se re-armer apres la fin de lecture du MP3.

Identite Produit

• Le personnage et le nom visibles dans le frontend ont ete renommes de ProfAmi vers Professeur TOP.
• Le nouvel avatar image est stocke dans:
  • frontend/src/assets/professeur-top.png
• Le composant avatar React utilise maintenant l'image raster au lieu du visage CSS/SVG precedent.
• Le backend a aussi ete aligne dans le prompt systeme et le message de debut de session avec le nom Professeur TOP.

Notes de Session 2026-04-24 21:58:39 +02:00

• Repo clone dans c:\DataS\OpenSquared\OpenSchool\ProfTop.
• safe.directory Git ajoute globalement pour ce dossier a cause d'un mismatch d'ownership Windows.
• Image utilisateur face.png integree dans le frontend sous frontend/src/assets/professeur-top.png.
• Libelles assistant remplaces par Professeur TOP dans l'UI.
• README mis a jour pour refleter la TTS OpenAI au lieu de la voix navigateur.
• Le frontend n'a pas encore ete verifie par build local car frontend/node_modules est absent.
• Lors d'un prochain demarrage, penser a installer les dependances frontend avant validation finale.
• La TTS OpenAI suppose une OPENAI_API_KEY valide cote backend.

Notes de Session 2026-04-25 - Auth, UI Eleve, Audio

• Authentification ajoutee:
  • table users
  • roles student, teacher, maintenance
  • login via /auth/login
  • session via cookie HTTP-only professeur_top_session
  • compte admin/prof seede depuis .env
• Acces eleve/admin:
  • un compte eleve est rattache a un student_id
  • un eleve ne peut acceder qu'a sa propre fiche/seance
  • prof/maintenance gardent l'acces global
  • creation d'un compte eleve via POST /admin/student-accounts
• UI eleve:
  • page login active
  • l'eleve ne voit plus la creation ni le choix d'eleves
  • l'ecran de cours ne montre plus la conversation complete
  • le cours courant remplace la consigne precedente au centre
  • la zone de reponse eleve reste en bas
  • card "Transmis au prof" ajoutee pour afficher le dernier texte envoye/capte
  • bouton principal Demarrer la seance / Fin de la seance
  • colonne gauche eleve limitee aux themes du jour, pas au bilan global
• Conversation et analyse:
  • les messages restent stockes en base
  • GET /students/{student_id}/messages permet de relire l'historique
  • le chat complet sera surtout utile aux rapports admin
• Voix/TTS:
  • les voix visibles sont libellees Voix Douce, Voix Rigolote, etc.
  • la mention "Voix IA non humaine..." est deplacee en tooltip
  • Professeur TOP a maintenant une consigne backend de tours de parole courts
• Transcription:
  • language="fr" force dans la transcription OpenAI
  • prompt de transcription ajoute pour phrases scolaires courtes
  • correction faite apres erreur type langue asiatique sur une phrase simple comme "nous chantons"
• Deploiement serveur:
  • .env du compose doit etre dans /root/.env ou passe via --env-file
  • rebuild backend necessaire pour changements backend
  • rebuild frontend necessaire pour changements UI

Idee Technique - Interruptions Trop Frequentes

Objectif: permettre a l'enfant de couper Professeur TOP sans perdre le fil, tout en evitant les faux positifs.

Approche progressive recommandee:

1. Barge-in simple avec TTS MP3 actuel:

   • garder l'analyse micro active pendant la lecture audio
   • si volume/parole detectee pendant que speaking=true, mettre l'audio en pause ou l'arreter
   • enregistrer un court segment jusqu'au silence
   • transcrire en francais
   • envoyer au backend avec un marqueur du type interruption=true
   • demander au LLM de classer implicitement: pertinent, question, correction, bruit/accident
   • si pertinent: repondre a l'enfant puis reprendre la lecon
   • si accidentel: repondre tres court puis continuer la consigne

2. Anti-faux positifs:

   • imposer un seuil plus haut pendant la lecture TTS
   • ignorer les segments tres courts, par exemple moins de 600 ms
   • ignorer les transcriptions vides ou tres faibles
   • utiliser une courte fenetre de cooldown apres chaque interruption
   • afficher dans "Transmis au prof" uniquement ce qui est vraiment envoye

3. Meilleure solution moyen terme:

   • passer sur OpenAI Realtime/WebRTC
   • gerer interruption, VAD, tour-taking et streaming audio nativement
   • envoyer des evenements de session avec contexte pedagogique
   • conserver en base les transcriptions et messages comme aujourd'hui

4. Donnees a stocker plus tard:

   • session_id
   • message_type: text, image, audio, interruption
   • source: keyboard, microphone, system
   • interruption_of_message_id
   • timestamp debut/fin de parole
   • confiance transcription

Points de Vigilance

• Les erreurs WebSocket Vite/HMR sur wss://prof.open-squared.tech/... sont du bruit de dev tant que le frontend tourne via Vite derriere nginx.
• Ces erreurs ne sont pas la cause principale si /api/* renvoie des 502 ou si le micro se comporte mal.
• En cas de 502 sur /api/*, verifier d'abord docker logs tutor-backend.
• Pour tester l'auth locale actuelle: .env contient ADMIN_USERNAME=admin et ADMIN_PASSWORD=admin; a changer avant tout usage partage.

Note Programme Pedagogique par Eleve

• Le mode admin doit devenir une gestion du programme par eleve.
• Pour chaque eleve configure, le professeur/admin doit pouvoir choisir une lecon dans le contenu disponible localement.
• La source prioritaire du contenu est:
  • C:\DataS\OpenSquared\OpenSchool\Programme\contenus_pedagogiques
• Le contenu est classe par cycle, niveau et matiere:
  • cycle 3: CM1, CM2, 6e
  • cycle 4: 5e, 4e, 3e
• Pour un eleve de CM1, l'admin doit pouvoir choisir par exemple:
  • mathematiques > nombres entiers
• Les fiches .svg associees a la lecon choisie doivent s'afficher dans la zone centrale de Professeur TOP cote eleve.
• Premier essai implemente: une affectation active par eleve, selectionnee en admin, puis visible dans l'ecran eleve.
• A prevoir ensuite:
  • plusieurs cours possibles par eleve
  • progression equilibree entre lecons et matieres
  • instructions personnalisees par eleve
  • suivi fin des fiches vues / exercices faits
• Vigilance langue française: les libellés visibles doivent utiliser les accents et formulations françaises correctes, par exemple Démarrer la leçon.

Session Programme / Mobile / Fiches SVG

• Le contenu pedagogique a ete copie dans le repo sous:
  • backend/contenus_pedagogiques
• Objectif: le git pull serveur doit recuperer les contenus pedagogiques en meme temps que l'application.
• Le backend cherche maintenant le contenu prioritairement dans:
  • backend/contenus_pedagogiques en local
  • /app/contenus_pedagogiques dans le conteneur backend
  • puis les anciens chemins externes si besoin
• Le cas test valide localement:
  • niveau: CM1
  • lecon: CM1 - Nombres entiers
  • 7 fiches SVG detectees
• Le mode admin ne doit plus afficher Professeur TOP ni permettre de dialoguer avec lui.
• Le mode admin est maintenant une console de gestion:
  • selection / creation d'eleve
  • affectation d'une lecon active
  • resume de l'eleve selectionne
  • apercu des fiches SVG de la lecon
• Le mode eleve reste le seul mode avec Professeur TOP, voix, saisie, micro et affichage de lecon.
• Les fiches SVG sont decoupees dynamiquement en etapes/cards a partir des grands groupes <g> internes.
• Exemple pour la premiere fiche Lecture Ecriture Nombres Entiers:
  • La méthode
  • Exemple
  • À retenir
  • Exemples résolus
• Le frontend avance maintenant par etape de fiche plutot que seulement par fiche entiere.
• Le pourcentage affiche dans la lecon est calcule sur toutes les etapes detectees:
  • progression proportionnelle
  • fin de parcours arrondie a 100%
• Sur laptop:
  • la fiche/card reste lisible dans la zone centrale
  • le parcours pedagogique doit quand meme suivre les cards une par une
• Sur telephone:
  • ne pas afficher les 7 fiches d'un coup
  • ne pas afficher la fiche paysage complete
  • afficher une seule card recadree en gros plan
  • la card doit prendre le maximum de largeur possible
  • eviter les doubles encadrements: pas de card dans une card dans l'encadre bleu
  • les bords de la card doivent presque toucher les cotes de l'ecran
  • les boutons precedent/suivant doivent rester petits et secondaires
  • une seule zone eleve en bas: elle sert a la fois a taper et a recevoir la transcription micro
• Le bouton/lien "Agrandir la fiche" a ete retire apres decoupage des cards: la card doit etre lisible directement.
• Le texte visible de Professeur TOP est compacte a l'ecran pour garder de la place a la card.
• La voix peut rester plus longue, mais l'affichage texte ne doit pas occuper trop de hauteur.
• Le frontend envoie maintenant au backend un contexte de lecon avec /chat:
  • titre de lecon
  • titre de fiche
  • titre de card/section affichee
  • pourcentage d'avancement
• Le backend ajoute ce contexte au prompt pour que Professeur TOP parle de la card actuellement affichee.
• Au demarrage de seance, si une lecon est affectee, Professeur TOP doit parler de la premiere card affichee et verifier la comprehension.
• Probleme restant important:
  • Professeur TOP ne pilote pas encore automatiquement le changement de card.
  • Prochaine brique: faire produire une intention structuree du type advance_lesson_step=true quand l'eleve dit qu'il a compris.
  • Le frontend devra alors avancer automatiquement a la card suivante.
• Probleme principal restant:
  • Le discours de Professeur TOP n'est pas encore assez correle a la card affichee.
  • Le simple contexte titre de card + titre de fiche ne suffit pas toujours: le modele peut repartir sur l'historique ou une notion voisine.
  • Il faudra probablement generer et stocker un texte pedagogique specifique par fiche/card.
  • Ce texte de card devra decrire exactement ce qui est affiche, proposer une consigne orale courte et verifier la comprehension.
  • Exemple attendu: pour la card La méthode, Professeur TOP doit expliquer le decoupage en groupes de 3 chiffres, puis demander si l'eleve comprend cette methode.
  • Ces textes pourraient etre generes depuis les SVG/Markdown puis sauvegardes comme metadonnees de programme, plutot que recrees a chaque seance.
• Direction pedagogique retenue:
  • Professeur TOP presente la card active.
  • Il demande si l'eleve comprend.
  • Si oui, il passe a la card suivante.
  • Si non, il explique uniquement cette card, avec un exemple court.
  • Sur laptop il peut dire par exemple "en haut a gauche, tu vois la méthode".
  • Sur telephone il doit parler de la card affichee en gros plan.

Plan de Dev Acces Eleve / Admin

1. Socle comptes et roles: table users, hash password, seed admin depuis .env, login, session courante.
2. Separation UI: LoginPage, StudentApp, AdminApp, composants partages.
3. Conversation persistante: endpoints de lecture messages, puis sessions et rattachement des messages/tentatives.
4. UI eleve sans scroll: Professeur TOP en haut, log de seance a gauche, derniere instruction au centre, saisie/micro en bas.
5. Dashboard prof/admin: creation eleves/comptes, rapports, historique seances, conversation complete, stats de reussite.

Fichiers Touchés Pendant Cette Session

• frontend/src/App.jsx
• frontend/src/styles.css
• frontend/src/assets/professeur-top.png
• frontend/vite.config.js
• backend/app/main.py
• backend/app/schemas.py
• backend/app/services.py
• backend/requirements.txt
• README.md
• MEMORY.md