Guide d'utilisateur GUI ; Recoverable statement/Persp Gemini generation

docs/guide_utilisateur_gui.md

@@ -0,0 +1,421 @@
+# Copienator — guide de l’interface graphique
+
+Ce guide suit les intitulés et l’ordre des étapes de l’interface. Un **label** est l’identifiant d’une question ; une **copie** correspond au travail d’un élève.
+
+## Prendre en main l’interface
+
+- Choisissez le dossier **Évaluation** avec **Parcourir…**, puis **Charger**.
+- Suivez la liste de gauche. Avant **Exécuter**, vérifiez le **Mode**, la **Cible** et les prérequis signalés. La cible est normalement toute l’évaluation ; choisir un fichier permet, lorsque proposé, de ne traiter qu’une copie. Les aides **ⓘ** précisent les options.
+- N’activez une option d’écrasement que pour remplacer volontairement les résultats précédents.
+
+## Préparation et énoncé
+
+### Vérifier les fichiers d’entrée
+
+**Effet :** vérifie la présence des documents nécessaires à l’évaluation.
+
+Placez les scans des copies, `enonce.pdf`, `enonce.tex`, `correction.tex` et la liste d’élèves `names` dans le dossier d’évaluation (`names` peut aussi être à la racine du projet).
+
+Pour un dossier nommé `A`, les noms `A.pdf`, `A.tex`, `Ac.tex` sont également acceptés. Vérifiez que qu’aucun PDF étranger ne sera pris pour une copie.
+
+Après un ajout, cliquez sur **Recharger — vérifier à nouveau**.
+
+### Analyser l’énoncé
+
+**Effet :** extrait les labels des questions, les contenus des questions, contextes et solutions de vos fichiers, puis prépare des regroupement initiaux de questions, ainsi que des barèmes.
+
+Choisissez **Analyse avec Gemini**.
+
+Éventuellement traitez les alertes **Problèmes LaTeX…** avant de poursuivre.
+
+**Ignorer le cache** recommence l’analyse Gemini : à réserver à une
+analyse devenue incorrecte ou obsolète.
+
+### Relire les barèmes — facultatif
+
+**Effet :** permet de vérifier et d’ajuster les instructions qui guideront la correction.
+
+Ouvrez les barèmes dans `Persp`. Vérifiez les réponses acceptables, les raisonnements alternatifs et les exigences de justification ; corrigez les consignes trop sévères, ambiguës ou erronées. Enregistrez vos modifications avant de marquer l’étape terminée.
+
+## Prétraitement des copies
+
+### Retourner toutes les copies — facultatif
+
+**Effet :** applique une rotation de 180° à tous les scans de copies du dossier.
+
+Exécutez seulement si toutes les copies sont à l’envers.
+
+### Renommer les PDF en CopieXX.pdf
+
+**Effet :** attribue un numéro aux copies selon l’ordre de leurs noms de fichiers.
+
+Vérifiez qu’un PDF correspond à une copie et que le dossier ne contient pas de documents parasites. Exécutez puis contrôlez le nombre de copies.
+
+### Séparer et réordonner les pages
+
+**Effet :** Découpe les scans A3 en pages A4 correctement ordonnées.
+
+Examinez chaque page :
+ - déplacer la coupure si jamais l'élève a dépassé d'une moitié de sa
+   copie A3 sur l'autre.
+ - Utiliser les raccourcis donnés pour retirer les pages vides.
+
+Suivez les raccourcis affichés dans la fenêtre, qui peuvent varier
+selon votre profil. Par défaut :
+
+| Action                                                              | Touche          |
+|---------------------------------------------------------------------|-----------------|
+| Déplacer la séparation                                              | ← / →           |
+| Garder les deux moitiés et avancer                                  | `s`             |
+| Garder seulement la gauche / la droite                              | `q` / `d`       |
+| Garder la page entière, pour une page déjà A4                       | `f`             |
+| Écarter une page réellement vide                                    | `z`             |
+| Retourner la page / toutes les pages du fichier / tous les fichiers | `r` / `R` / `,` |
+| Envoyer la page en fin / inverser l’ordre des pages                 | `a` / `i`       |
+| Recommencer le fichier / revenir au fichier précédent               | `T` / `P`       |
+| Ouvrir l’outil de réorganisation, s’il est disponible               | `A`             |
+
+**Copies signalées uniquement** limite le traitement aux copies
+précédemment signalées (par une étape suivante).
+
+### Rogner les zones vides — facultatif
+
+**Effet :** retire les marges vides en haut et en bas des pages, avec
+sauvegarde des versions précédentes.
+
+Ce n'est pas particulièrement utile, et il pourrait y avoir des faux positifs.
+
+### Découper une partie à gauche pour détection des labels
+
+**Effet :** Prépare des images qui seront utilisées pour repérés les numéros de questions.
+
+Éventuellement, cocher `Toujours utiliser la page entière`. Pour rendre
+cette étape non interactive, cocher aussi `et ne pas vérifier visuellement`.
+Ce mode est plus cher : sans avoir vérifié, Astra estime que le coût
+passerait de 0,50€ à 2€.
+
+Sans quoi, pour chaque copie, il faut cadrer la bande pour qu'elle
+contienne bien tous les labels :
+
+**←/→** la déplacent, **↑/↓** l’élargissent ou la réduisent ; **Entrée** valide.
+
+Si les labels sont dispersés, utilisez **1** pour utiliser les pages entières pour cette copie.
+
+Cette vérification visuelle permet toutefois de repérer des copies à
+l'envers, ou dont les pages sont dans le mauvais ordre. Utiliser **!**
+pour signaler une copie problématique.
+
+Vous pourrez alors relancer l'étape de réordonnement des copies avec
+les copies signalées.
+
+## Labels et regroupement
+
+### Détecter les labels avec Gemini
+
+**Effet :** reconnaît les identifiants de questions et leur position dans les copies.
+
+### Vérifier visuellement les labels
+
+**Effet :** valide ou corrige les repères qui serviront à découper les réponses.
+
+Vérifiez visuellement les labels.
+ - Quand un label est manquant, le suivant est affiché en jaune.
+ - Quand un label n'est pas dans le bon ordre, il est affiché en rouge.
+
+Pour faire des modifications : **e** ouvre le fichier .json à modifier à la main
+ - Vous pouvez retirer un label, ou le modifier.
+ - Pour ajouter un label manqué :
+   - cliquer sur l'image là où est le label, ce qui va copie les coordonnées correspondantes
+   - puis les coller dans le fichier .json, et renseignez le label.
+
+**Entrée** pour valider, **i** pour ouvrir l'énoncer, **o** pour
+ouvrir la copie d'origine, **p** pour revenir en arrière.
+
+### Découper les réponses par question
+
+**Effet :** crée un document de réponse pour chaque question repérée
+dans chaque copie.
+
+### Rogner le bas des réponses — facultatif
+
+**Effet :** enlève les grands espaces vides sous les réponses découpées, avec sauvegarde des originaux.
+
+### Regrouper les réponses
+
+**Effet :** regroupe les réponses par label pour préparer la correction.
+
+## Correction
+
+### Lancer ou intégrer la correction
+
+**Effet :** obtient les corrections automatiques ou intègre des résultats préparés en différé.
+
+Il faut choisir un des modes suivants.
+
+Initialement, vous voulez
+ - soit le mode **Correction immédiate**, qui
+   va faire les requêtes de corrections en live, ce qui peut prendre de
+   l'ordre de 30min ou 1h. (Si elle est interrompue, il suffit de la
+   relancer pour qu'elle reprenne d'où elle en était).
+ - soit le mode **Préparer toutes les requêtes batch** : au lieu de
+   faire des requêtes en live, les requêtes sont batchées et toutes
+   envoyée à Gemini, qui les traitera en théorie au pire sous 24h, en
+   pratique dans l'heure. L'avantage est que le coût est divisé par
+   deux.
+
+Le mode **Batch à partir d'un label** est un mode hybride inutile, où
+certaines requêtes sont faites en live, et d'autres sont batch.
+
+| Mode                                   | À faire et à vérifier                                                                                                     |
+|----------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
+| **Correction immédiate**               | Lancez et surveillez le nombre de groupes traités.                                                                        |
+| **Préparer toutes les requêtes batch** | Préparez les demandes, puis passez à **Envoyer les batchs** : la préparation seule ne les envoie pas.                     |
+| **Batch à partir d’un label**          | Indiquez le premier label différé ; les précédents sont corrigés immédiatement. Suivez ensuite le circuit batch.          |
+| **Recorrection depuis refaire.json**   | Relancez les questions sélectionnées, notamment après résolution des conflits. Vérifiez la sélection avant de lancer.     |
+| **Intégrer les résultats batch**       | Utilisez après leur récupération ; attendez la fin de l’intégration avant de générer les annotations.                     |
+| **Réinitialiser les corrections**      | Réservez ce mode à un recommencement volontaire ; lisez la confirmation et sauvegardez les corrections utiles auparavant. |
+
+Laissez **Écraser les corrections existantes** décoché pour reprendre
+sans tout recalculer. Une **Limite d’appels Pro** peut limiter le
+travail de cette exécution : vérifiez ce qui reste à traiter.
+**Interrompre** bloque les nouveaux appels, attend ceux en cours et
+sauvegarde leurs résultats ; relancez pour terminer les validations
+restantes. Examinez les erreurs et les conflits proposés, puis relisez
+les résultats sur les copies annotées.
+
+### Envoyer les batchs — si correction différée
+
+**Effet :** transmet à Gemini les demandes de correction préparées.
+
+Exécutez après la préparation batch et vérifiez que les envois
+aboutissent. En cas d’envoi partiel, reprenez cette étape et consultez
+l’état des jobs avant de poursuivre.
+
+### Consulter l’état des batchs — si correction différée
+
+**Effet :** vérifie si tous les traitements différés ont réussi et sont récupérables.
+
+Cliquez sur **Exécuter**, ou sur **Vérifier toutes les 5 minutes** en
+gardant Copienator ouvert. Attendez que tous les résultats soient
+prêts ; une notification l’indique. Un job en attente ou en échec ne
+vaut pas une correction terminée : lisez son état au lieu de forcer le
+passage à la suite.
+
+### Récupérer les résultats batch — si correction différée
+
+**Effet :** télécharge et rassemble les réponses des traitements terminés.
+
+Exécutez lorsque tous les résultats sont disponibles. Vérifiez
+l’absence de récupération manquante ; l’interface revient ensuite à
+**Lancer ou intégrer la correction**, en mode **Intégrer les résultats
+batch**. Exécutez cette intégration.
+
+### Résoudre les conflits manuels — si des conflits sont signalés
+
+**Effet :** corrige les attributions ambiguës de réponses avant leur recorrection.
+
+Lors de la correction, certains labels seront inévitablement érronés
+(l'étudiant a mis le mauvais label, ou n'a pas mis de label, ou à
+traiter une question à droite d'une autre).
+
+L'étape de correction détecte ces problèmes (enfin, certains…), et
+essaie de les corriger automatiquement. Les cas non automatiques
+(«conflits») sont ceux où elle détecte un contenu correspondant à un
+label `B`, alors qu'il y a déjà une image pour le label `B`
+
+Cette étape permet de résoudre manuellement les conflits : on vous
+donne une image initiale, avec un label d'origine `A` dont le contenu
+est bizarre et correspond, éventuellement partiellement, à un label
+`B` cible, qui a déjà une image.
+
+On vous demande de choisir ce qu'il doit advenir de l'image d'origine.
+
+Ouvrez les PDF source et cible proposés et comparez-les à l’énoncé.
+
+Cliquez sur **Ouvrir dans un éditeur de texte** pour ajuster les
+instructions. Leur forme est `Copie01 Label source OP Label cible|`.
+Choisissez l’action d’après le contenu réel :
+
+| Opérateur   | Résultat                                                                        |
+|-------------|---------------------------------------------------------------------------------|
+| `->` / `x>` | Ajouter la source à la cible ; conserver / archiver la source pour le label `A` |
+| `-x` / `xx` | Remplacer la cible par la source ; conserver / archiver la source.              |
+| `ss`        | Garder les deux réponses séparées (= ne rien faire)                             |
+| `sx` / `xs` | Garder la source / la cible et archiver l’autre.                                |
+
+Pour une fusion, `Cible|` met la cible avant la source, `|Cible` fait l’inverse.
+
+Une autre opération est **Cut** : dans les cas où vous voulez découper
+l'image d'origine en deux. Utiliser le bouton **Cut** pour choisir la
+coupure, et quelle moitié doit être gardée. L'interface graphique vous
+fournira alors une instruction texte à copier et à mettre dans le
+fichier texte.
+
+Enregistrez le fichier texte, éventuellement le **Recharger**, puis
+**Exécuter**.
+
+Retirer une instruction signifie accepter les PDF sans changement ;
+exécutez même si vous avez retiré toutes les lignes.
+
+Après succès, l’interface revient à l'étape de correction (avec le
+mode **recorrection à partir de refaire.json** ) : lancez-la.
+
+### Nettoyer la correction
+
+**Effet :** Essaye de réparer des problèmes d'encodages courant dans les réponses de Gemini.
+
+## Annotations et tablette
+
+### Générer les copies annotées
+
+**Effet :** Génère des versions des copies, annotées avec la correction Gemini.
+
+Choisir le mode :
+ - **Annotations simples (Anot)** Annote chaque copie en des documents qu
+ - **Annotations avec cases (Bnot)** Annote chaque copie, avec des
+   cases qui vous permettrons, en les cochant, de supprimer certains
+   commentaires, ou de modifier la note
+ - **Annotations groupées (BGnot)** Génère des documents pdf, où les
+   réponses annotées sont regroupées par label (ou plutôt par groupes
+   de label).
+
+   Les groupes de label sont ceux qui ont été générés dans l'analyse
+   de l'énoncé. Il est possible de les modifier à la main ici.
+
+**Écraser les sorties** remplace les documents existants. **Mode
+refaire** ne concerne qu’une reprise sélectionnée ; utilisez de
+préférence le parcours dédié décrit plus bas.
+
+### Exporter — facultatif
+
+**Effet :** place les documents générés dans le dossier de transfert configuré.
+
+Choisissez le même **Dossier d’annotations** qu’à la génération.
+
+### Annoter les PDF sur la tablette
+
+**Effet :** recueille votre validation pédagogique, vos changements de scores et vos annotations manuscrites.
+
+Relisez chaque réponse avec sa correction. Dans les modes avec cases, cochez une seule note par question pour la remplacer ; laissez les notes correctes inchangées.
+
+Une case près d’un commentaire le supprime, celle sur un rectangle
+supprime ce rectangle ; **clr** supprime tous les commentaires et
+rectangles de la question. Ajoutez vos propres remarques sans écrire
+accidentellement dans les cases. Gardez les dimensions et l’ordre des
+pages pour permettre la lecture du retour.
+
+Avec le circuit d’export/import, renvoyez les fichiers sous **leur nom
+exporté** (groupe ou `CopieXX.pdf`), dans le dossier d’import prévu.
+
+### Importer les annotations manuscrites
+
+**Effet :** rattache les fichiers modifiés manuellement aux documents de l’évaluation.
+
+Vérifiez l’évaluation, le dossier d’import et le **Dossier
+d’annotations**, puis exécutez. Écartez les anciens retours et ceux
+d’autres évaluations pour éviter une mauvaise association.
+
+## Finalisation
+
+### Lire les annotations manuscrites
+
+**Effet :** applique les cases cochées et les ajouts manuscrits pour reconstruire les copies et leurs scores.
+
+Choisissez **Lecture Bnot** ou **Lecture BGnot** conformément à la
+génération. Pour le parcours `Anot`, passez directement à
+l’attribution des noms. Après lecture, ouvrez les résultats et
+vérifiez notes modifiées, suppressions de commentaires et remarques
+manuscrites.
+
+Si les options `answers` sont présentes, choisissez les compléments
+souhaités dans les réponses individuelles : contexte, énoncé,
+correction.
+
+En mode groupé, le PDF final peut omettre une réponse parfaite sans
+commentaire conservé ni annotation manuscrite significative ; son
+score reste enregistré. Le PDF peut même être absent si aucune réponse
+ne reste à y inclure. Contrôlez donc aussi les scores et l’image
+complète, sans assimiler automatiquement une omission à une perte de
+réponse.
+
+Le mode **Régénérer avec les nouveaux énoncés/corrigés et les
+score.json** sert à mettre à jour les scores sur les images finales à
+partir d'une modification manuelle des fichiers `score.json`.
+
+
+### Attribuer les noms et préparer A Rendre
+
+**Effet :** rassemble les résultats de chaque élève dans le dossier `A Rendre`.
+
+Choisissez le dossier d’annotations utilisé et exécutez. Dans
+**Vérification des noms**, traitez tous les noms `Unknown` et les
+doublons : **Ouvrir l’originale**, saisir le nom, puis **Renommer**.
+
+**Mettre à jour uniquement les images de answers** ne rafraîchit que
+les réponses individuelles des élèves existants.
+
+## Refaire une partie de l’évaluation
+
+Utilisez ce parcours après avoir terminé le passage principal. Conservez ses annotations : elles servent à préserver les questions non sélectionnées. Ne démarrez **Nouvelle reprise** qu’après avoir importé et fusionné la reprise courante ; **Refaire la même sélection** permet de repartir avec les mêmes copies et questions.
+
+### Choisir les copies et les questions
+
+**Effet :** enregistre les réponses à reprendre et leur mode de présentation.
+
+Choisissez une copie et une question, puis **+ Ajouter** ; répétez selon les besoins. **Toute la copie** sélectionne toutes ses questions ; **Toutes les copies** applique le choix à la classe. Vérifiez le tableau, retirez les erreurs, choisissez le **Passage principal** correct et la présentation **PDF à vérifier**, puis **Enregistrer la sélection**.
+
+### Reprendre le découpage — facultatif
+
+**Effet :** permet de corriger les repères des copies sélectionnées.
+
+Reprenez les contrôles de la vérification visuelle des labels. Validez les images modifiées ; chaque copie sélectionnée s’ouvre à son tour, et fermer sa fenêtre passe à la suivante. Ignorez si les découpages sont déjà corrects.
+
+### Redécouper les réponses — facultatif
+
+**Effet :** reconstruit les réponses des copies sélectionnées à partir des repères corrigés.
+
+Exécutez après toute modification du découpage. Ouvrez les réponses concernées et vérifiez leurs limites ; en présence de résolutions manuelles, contrôlez particulièrement les versions `_new` et `_old`. Ignorez si le découpage n’a pas changé.
+
+### Refaire la correction — facultatif
+
+**Effet :** relance la correction automatique des seules questions sélectionnées.
+
+Vérifiez la sélection puis exécutez. Contrôlez les erreurs et les résultats proposés. Ignorez si vous souhaitez uniquement modifier les notes ou commentaires à la main lors de la relecture.
+
+### Préparer les copies à vérifier
+
+**Effet :** génère dans `BRnot` les documents avec cases du passage de reprise.
+
+Exécutez puis vérifiez que seules les réponses voulues sont présentes, avec la présentation choisie. Cette génération remplace les documents de reprise concernés : ne la relancez pas sur une relecture manuscrite à conserver.
+
+### Exporter vers la tablette — facultatif
+
+**Effet :** transfère les documents du passage de reprise vers le dossier d’export.
+
+Écartez les anciens exports, exécutez et contrôlez les documents transférés. Conservez leur nom complet, y compris le préfixe de reprise s’il est présent : il permet d’associer les retours au bon passage. Ignorez si vous relisez directement les fichiers locaux.
+
+### Vérifier sur la tablette
+
+**Effet :** recueille la validation et les modifications des réponses reprises.
+
+Appliquez les mêmes règles de cases et d’écriture que pour le premier passage. Retournez tous les documents, même sans changement, sous leur nom exporté dans le dossier d’import ; retirez les anciens retours. En travail local, placez les `Concat_annotated.pdf` dans les sous-dossiers de cette reprise.
+
+### Importer les copies vérifiées — facultatif
+
+**Effet :** récupère les annotations du passage de reprise courant.
+
+Exécutez et vérifiez que tous les retours attendus sont acceptés. Les fichiers portant le préfixe d’une autre reprise sont ignorés. Ignorez cette étape seulement si les `Concat_annotated.pdf` sont déjà au bon endroit.
+
+### Mettre à jour les copies finales
+
+**Effet :** fusionne les réponses refaites avec les autres réponses conservées du passage principal.
+
+Vérifiez le **Passage principal**, puis exécutez. Contrôlez une question refaite et une question conservée pour chaque copie concernée ; résolvez tout retour manquant avant de poursuivre. Relancez ensuite **Attribuer les noms et préparer A Rendre** et vérifiez les livrables mis à jour avant de les remettre aux élèves.
+
+## Archivage
+
+### Nettoyer les fichiers intermédiaires — facultatif
+
+**Effet :** supprime définitivement les fichiers de travail et la progression de l’interface en conservant les livrables prévus.
+
+Attendez la fin des relectures et reprises. Vérifiez les résultats de tous les élèves dans `A Rendre` et sauvegardez l’évaluation si vous voulez pouvoir reprendre le travail. Choisissez d’abord **Prévisualiser sans supprimer**, puis examinez la liste. Ne lancez **Nettoyage définitif** qu’une fois certain de ne plus avoir besoin des intermédiaires : les PDF traités, textes de l’énoncé, corrections, journaux et livrables de `A Rendre` sont conservés, mais une reprise exigera de régénérer les données supprimées.

docs/statement_recovery.md

@@ -0,0 +1,55 @@
+# Reprendre la génération Gemini de l’énoncé
+
+Relancez la même commande après une erreur ou une interruption :
+
+```sh
+python -m copienator statement Interro05
+```
+
+Sans `--restart`, les sources sont supposées inchangées. Les questions,
+solutions et contextes validés sont conservés dans `Cache/statement_*.json`.
+Une réponse lisible contenant un élément invalide conserve ses autres éléments
+valides. Les solutions et contextes incomplets sont redemandés pour leurs labels
+manquants. Une réponse JSON illisible reste archivée, mais ses éléments ne sont
+pas récupérés automatiquement.
+
+Les questions sont redemandées sous forme d’une liste complète et ordonnée :
+avant leur extraction, aucun inventaire indépendant de labels n’est disponible.
+Les labels déjà observés doivent rester présents. Vérifiez la liste contre
+`enonce.pdf` dans l’éditeur de groupes avant de l’approuver, notamment pour
+repérer une question que Gemini aurait entièrement omise.
+
+Les modifications de `Tmp/exam_items.txt` survivent à une interruption de
+l’éditeur. Après approbation, les groupes sont enregistrés dans
+`Cache/statement_grouping.json` ; une reprise utilise ce checkpoint sans rouvrir
+l’éditeur. Les fichiers générés déjà présents sont conservés, les fichiers
+manquants sont complétés, et seuls les PDF manquants, échoués ou plus anciens
+que leur source générée sont recompilés. Les contextes ne sont pas ajoutés une
+seconde fois lors d’une reprise.
+
+Les barèmes `Persp` valides sont conservés, y compris ceux des autres questions
+d’une réponse dont un barème est invalide. Les labels et groupes sont écrits
+avant la génération des barèmes et la compilation, ce qui permet aussi une
+reprise par `statement Interro05 --persp-only`.
+
+Toutes les réponses d’extraction sont archivées avant décodage dans
+`Cache/statement_responses/`. Les erreurs, avec le texte échappé et le chemin
+de la réponse, sont affichées et ajoutées à `Cache/statement_errors.log`.
+Les barèmes utilisent `Cache/rubric_responses/` et `Cache/rubric_errors.log`.
+Les anciens caches `gemini_questions.json`, `gemini_solutions.json` et
+`gemini_context.json` sont importés une fois : une réponse invalide n’est pas
+rechargée indéfiniment.
+
+Pour recommencer explicitement depuis les sources, notamment après les avoir
+modifiées :
+
+```sh
+python -m copienator statement Interro05 --restart
+```
+
+Les checkpoints et modifications des groupes précédents sont déplacés dans
+`Cache/statement_history/`. Les anciennes sorties y sont également déplacées
+quand la nouvelle extraction et les groupes sont prêts, avant leur remplacement.
+Une erreur d’extraction conserve donc les anciennes sorties. Les réponses brutes
+restent disponibles. Si ce nouveau départ échoue, relancez sans `--restart`
+pour reprendre sa progression.