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

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

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

Sous Linux :

#+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=.

*** 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=.

*** 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

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 et la configuration Gemini. Sous Windows, les exécutables
externes doivent être accessibles depuis =PATH=. 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.