Copies/Readme.org

#+title:  Copienator
#+author: Sébastien Miquel
#+date:   14-03-2026
# Time-stamp: <26-09-26 23:50>
#+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. L'énoncé (pdf/tex) et le corrigé sont analysés
 2. Les labels des questions sont détectées sur les copies.
 3. Les copies sont découpées suivant ces labels.
 4. 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.
 5. 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.
 6. Ces annotations manuscrites sont lues et recompilées en une
    version de la copie pour l'élève.

Le dossier `Example` contient deux exemples de copies pour illustrer
le résultat final.

** Reprendre une compilation LaTeX après l'analyse

Les PDF des questions et solutions reprennent automatiquement les packages et
macros de =enonce.tex= et du corrigé, avec le format recadré de Copienator.
La géométrie des pages du document original est exclue pour préserver le recadrage.
Les packages et fichiers locaux doivent rester accessibles à LaTeX.

Pour recompiler les fragments déjà extraits sans aucune requête Gemini :

#+BEGIN_SRC bash
python -m copienator statement DSI01 --compile-only
#+END_SRC

Dans l'interface, choisir « Recompiler les PDF sans Gemini » à l'étape
« Analyser l’énoncé ». Cette action conserve les sources, les groupes et les
barèmes. Elle reprend les échecs et recompile si les fragments ou leur préambule
ont changé. Une compilation en erreur ne remplace pas le PDF précédent.

** Avertissements

 - 90% du code du repertoire a été vibe codé, sans vérification autre
   que le fait que ça marche sur ma machine.
 - Il en va de même d'une grande partie de la documentation, et le
   workflow n'est probablement pas compréhensible en l'état.

   Cette situation s'améliorera légèrement quand j'aurai convaincu
   quelques collègues du lycée de me laisser les accompagner pour
   essayer.


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

Les niveaux de réflexion Gemini se règlent indépendamment des modèles :
=THINKING_LEVEL_LITE= (énoncés, ="low"=), =THINKING_LEVEL_FOR_LABEL=
(labels, ="medium"=), =THINKING_LEVEL_FLASH= (correction courante,
="medium"=) et =THINKING_LEVEL_PRO= (correction difficile, ="high"=).
Ces réglages s'appliquent aussi aux requêtes batch. Utiliser =None= pour
laisser le modèle choisir son défaut. Les niveaux disponibles dépendent
du modèle : Gemini 3.8 Flash accepte ="low"=, ="medium"= et ="high"=,
mais pas ="minimal"=. Avec un modèle Gemini 2.5, utiliser =None=.

** 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. Lancer l'interface graphique

** Interface graphique

Lancer l'assistant avec :

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

ou

#+BEGIN_SRC bash
./start-gui.sh
#+END_SRC

* Documentation complémentaire

- [[file:docs/guide_utilisateur_gui.md][Guide utilisateur de l’interface graphique]] : actions,
  vérifications et cas particuliers pour chaque étape du parcours non personnel.
- [[file:Script.org][Référence des étapes et des scripts]] : commandes, arguments,
  prérequis, fichiers produits et parcours alternatifs.
- [[file:docs/final_output.md][Fichiers finaux dans A Rendre]] : contenu du JPEG, sélection et
  pagination du PDF, JPEG par réponse, =score.json=, =info.json= et diffusion.
- [[file:Architecture.org][Architecture et conventions de développement]] : API commune,
  état partagé, écritures sûres et règles de maintenance.