Copies/Readme.org

#+title:  Copienator
#+author: Sébastien Miquel
#+date:   14-03-2026
# Time-stamp: <22-08-26 12:22>
#+OPTIONS:

* Présentation
** Quézaco

Ce dépôt contient un certain nombre de script Python que j'utilise
pour faire corriger des copies par Gemini.

 1. Les copies sont découpées suivant les labels des questions.
 2. Des requêtes de correction sont faites à Gemini, qui met une note
    entre 0 et 4 à la question, ajoute des commentaires, et encadre
    certaines parties de la réponse.
 3. Une version pdf annotée de la copie est générée, faite pour être
    éditée sur tablette tactile. Le correcteur humain peut modifier la
    note, supprimer des commentaires de l'IA, ou ajouter des remarques
    manuscrites.
 4. Ces annotations manuscrites sont lues et recompilées en une
    version de la copie pour l'élève.

** Limitations

Pour l'instant, la correction est faite question par question : le LLM
n'a accès qu'à la partie de la copie correspondant à une question
fixée. Ça ne gère donc pas les cas où un argument a été donné dans une
question précédente ou autre.

*** Noms de labels sous Windows

Les labels de questions sont utilisés comme noms de fichiers. Les
labels contenant notamment =:= ne sont pas acceptés par Windows.

** Prérequis et installation

*** Python 3.11 ou plus récent

Sous macOS avec Homebrew, installer Python et la version correspondante
de Tkinter avant de créer l'environnement virtuel. Par exemple :

#+BEGIN_SRC bash
brew install python@3.13 python-tk@3.13
#+END_SRC

Utiliser alors =python3.13= à la place de =python= dans les commandes
de création de l'environnement si la commande non versionnée n'est pas
disponible.

Créer et activer un environnement virtuel est recommandé :

#+BEGIN_SRC bash
python -m venv .venv
#+END_SRC

Sous Linux et macOS :

#+BEGIN_SRC bash
source .venv/bin/activate
#+END_SRC

Sous Windows (PowerShell) :

#+BEGIN_SRC powershell
.venv\Scripts\Activate.ps1
#+END_SRC

Installer ensuite Copienator et ses dépendances Python depuis la
racine du dépôt :

#+BEGIN_SRC bash
python -m pip install --upgrade pip
python -m pip install -e .
#+END_SRC

Cette commande installe les modules contrôlés par le diagnostic du GUI
(NumPy, pandas, Matplotlib, Pillow, pydantic, pypdf, pdf2image,
ReportLab, img2pdf, PyMuPDF, ftfy, ezodf et Google Gen AI), ainsi que
les exécutables =copienator= et =copienator-gui=. Le paquet fournissant
=google.genai= est =google-genai=, et non =google=.

Les commandes restent également accessibles avec
=python -m copienator= depuis la racine du dépôt.

*** Programmes externes obligatoires

Le diagnostic vérifie que Poppler et LaTeX sont accessibles depuis
=PATH=.

**** Linux (Debian et Ubuntu)

#+BEGIN_SRC bash
sudo apt install poppler-utils python3-tk texlive-latex-extra texlive-fonts-extra lmodern python3-pygments
#+END_SRC

Cette sélection couvre les modèles LaTeX de la configuration par
défaut, notamment =standalone=, =lmodern=, =mathabx= et =minted=. Selon
les commandes LaTeX utilisées dans vos propres énoncés, d'autres
paquets TeX peuvent être nécessaires. =python3-tk= fournit Tkinter sur
les installations Python qui ne l'incluent pas d'origine.

**** Windows

 1. Télécharger [[https://github.com/oschwartz10612/poppler-windows][Poppler pour Windows]] et ajouter son dossier =bin= à
    =PATH=.
 2. Installer une distribution LaTeX, par exemple MiKTeX ou TeX Live,
    et vérifier que =pdflatex= est accessible depuis =PATH=.

Fermer puis rouvrir le terminal et le GUI après une modification de
=PATH=.

**** macOS

Avec Homebrew, installer Poppler et MacTeX :

#+BEGIN_SRC bash
brew install poppler
brew install --cask mactex
#+END_SRC

MacTeX fournit la distribution TeX Live complète utilisée par les
modèles de Copienator. Après son installation, rouvrir le terminal ou
exécuter :

#+BEGIN_SRC bash
eval "$(/usr/libexec/path_helper)"
#+END_SRC

Copienator recherche aussi les exécutables dans =/opt/homebrew/bin=,
=/usr/local/bin= et =/Library/TeX/texbin=, notamment lorsque le GUI ne
récupère pas le =PATH= du terminal. Ces instructions conviennent aux
Mac Intel et Apple Silicon sous macOS 11 ou plus récent.

*** Programme externe facultatif

PDF Arranger permet d'ouvrir et de réorganiser plus facilement les
PDF. Son absence est signalée comme facultative dans le diagnostic. Il
doit fournir la commande =pdf-arranger= ou =pdfarranger= dans =PATH=.
Sous macOS, Copienator utilise automatiquement Aperçu comme solution de
repli.

*** Accès à Gemini

Il faut créer une clef API pour Gemini (pas facile).

Puis ajouter =GEMINI_API_KEY= à l'environnement avec :

#+BEGIN_SRC bash
export GEMINI_API_KEY=…
#+END_SRC

ou éventuellement, la renseigner directement dans le fichier
`config.py`.

** Configuration

Copier `default_config.py` en `config.py`. Éventuellement le modifier.

** Correction d'un paquet de copies

 1. Créer un fichier =names= dans le dossier courant, avec les
    noms/prénoms des élèves, un par ligne
 2. Créer un dossier correspondant à l'évaluation (=Interro= dans la
    suite)
 3. Suivre les instructions suivantes

** Interface graphique

Lancer l'assistant avec :

#+BEGIN_SRC bash
python -m copienator gui
#+END_SRC

Sous Linux ou macOS, le lanceur exécutable =./start-gui.sh= démarre aussi
l’interface, depuis n’importe quel répertoire. Il utilise le Python de
=.venv= s’il existe, sinon =python3= du PATH. On peut lui passer le dossier
d’évaluation : =./start-gui.sh Interro=. Sans argument, il ouvre le
sous-dossier immédiat non masqué le plus récemment modifié du répertoire
courant, en excluant =copienator=, =copienator_gui=, =tests=, =OLD=,
=__pycache__=, =build=, =dist=, =*.egg-info=, =venv=, =env= et
=node_modules=. S’il n’y a aucun dossier admissible, l’interface démarre
sans évaluation. Un chemin explicite reste utilisable même s’il est exclu
de la sélection automatique.

=Recharger — vérifier à nouveau= relit les fichiers d’entrée du dossier.
Pour reprendre le découpage d’une copie, sélectionnez-la dans =Copies
détectées=, cliquez sur =Refaire la copie sélectionnée=, puis sur
=Exécuter=. Le découpage repart de l’original conservé.
Dans la fenêtre de découpage, =i= inverse l’ordre de toutes les pages
(dernière vers première) et reprend à la nouvelle première page. Les choix
de découpage déjà saisis sont effacés ; les rotations globales sont conservées.
Ce raccourci est configurable via =PAGE_SPLITTER_KB["reverse_pages"]=.
=Copier la commande= copie les commandes complètes (à lancer depuis la
racine du projet). Dans la console, les boutons de copie et le clic droit
permettent de copier la sélection ou toute la sortie ; =Ctrl+C= et
=Ctrl+A= sont également disponibles (=Cmd= sous macOS).

Avec =SHOW_PERSONAL_STEPS = True=, =Analyser l’énoncé= propose le choix
entre Gemini et =Énoncés et solutions personnels (SHEETINFO)=. Ce dernier
lance =python -m copienator statement-personal Interro= : il lit
=enonce.tex=, utilise le service d’exercices sur =localhost:8080= pour
générer =Text=, =Sol=, =Text2=, =Sol2= et les barèmes personnels =Persp=,
et écrit un groupe par exercice dans =label_groups=.

Deux boutons ouvrent ensuite des actions facultatives avec aperçu de
commande et bouton =Exécuter= : =Regrouper avec Gemini…= remplace seulement
=label_groups= (=statement Interro --groups-only=) ; =Remplacer Persp avec
Gemini…= régénère seulement les barèmes des groupes actuels
(=statement Interro --persp-only=), avec le même prompt que le parcours
Gemini complet. Une réponse incomplète ou un échec laisse les anciens
barèmes en place. On peut ignorer ces étapes et conserver les résultats
personnels.

On peut aussi ouvrir directement une évaluation avec =python -m copienator gui
Interro=. L'interface conserve l'état et l'historique des étapes dans
=Interro/.copienator-gui.json=, et les sorties complètes dans
=Interro/.copienator/logs/=. Une relance d'une étape antérieure ne
supprime aucun résultat ; les étapes suivantes sont seulement marquées
comme étant à revalider.

Après la réussite d'un script, l'interface sélectionne automatiquement
l'étape suivante. =Découper les réponses par question= et =Regrouper
les réponses= démarrent automatiquement lors de leur première visite.
Avec le mode =Correction immédiate=, les trois étapes batch sont alors
marquées =Ignorée= à leur première visite. L'étape de résolution
manuelle est traitée de la même façon si =manual_resolutions.txt= est
absent, vide ou ne contient que des commentaires. Ces automatismes ne
se répètent pas lors d'un retour en arrière.

Le bouton =Diagnostic…= vérifie les modules Python, Poppler, LaTeX,
PDF Arranger (ou Aperçu sous macOS) et la configuration Gemini. Sous
Windows, les exécutables externes doivent être accessibles depuis
=PATH=. Sous macOS, les emplacements standards de Homebrew et MacTeX
sont également inspectés. Quand la création de liens symboliques ou
physiques n'est pas autorisée, l'export et la préparation de =A Rendre=
utilisent automatiquement une copie normale.

Les chemins des étapes personnelles peuvent être adaptés avec
=CURRENT_SCORE_ODS_PATH=, =FINAL_SCORE_ODS_PATH=,
=FINAL_SCORE_OUTPUT_DIR= et =FINAL_SCORE_FONT_PATH= dans =config.py=.

* Documentation complémentaire

- [[file:Script.org][Référence des étapes et des scripts]] : commandes, arguments,
  prérequis, fichiers produits et parcours alternatifs.
- [[file:Architecture.org][Architecture et conventions de développement]] : API commune,
  état partagé, écritures sûres et règles de maintenance.