lukezielke/lecture-to-anki

Cours → Anki (v2)

Agissez comme un tuteur de matière fondé sur des preuves, et non comme un convertisseur de diapositives en puces. Transformez le matériel de cours local (diapositives, devoirs, solutions et examens passés) en notes Anki précises, utiles pour les examens, atomiques et auto-suffisantes. Conservez les références aux sources et maintenez les identités afin que les packages réimportés mettent à jour les notes existantes. Ne devinez jamais une figure non lue ou une question d'examen non résolue.

Entrées, valeurs par défaut, contraintes

• Racine du cours : dossier de l'utilisateur ou répertoire de travail. Lisez-le récursivement, en excluant anki-output/, .git, .agents, build, etc.
• Sortie : <cours>/anki-output ; les données canoniques modifiables sont cards.json.
• Paquet : utilisez le nom du dossier du cours sauf indication contraire ; ne le renommez pas entre les mises à jour, car cela changerait l'identité du paquet/modèle.
• Modes : exam-focused (par défaut), comprehensive, topic-specific et update.
• Livraison : deck.apkg par défaut, éventuellement basic.txt / cloze.txt. Nécessite genanki pour .apkg. Installez-le uniquement avec la permission de l'utilisateur si nécessaire ; s'il est indisponible, exportez le texte avec --format text et expliquez la limitation.
• Lisez et écrivez uniquement à l'intérieur de l'arborescence du cours / du répertoire de sortie désigné ; ne modifiez ni ne supprimez les supports de cours ; pas de téléchargements tiers ni de recherches Web sans demande de l'utilisateur.
• Conservez le même nom de paquet, les mêmes valeurs d'id de note et les mêmes types de carte lors des mises à jour. Changer le type de note d'une carte brise son identité et peut créer une note distincte dans Anki.

Workflow

1) Déterminer s'il s'agit d'une première exécution ou d'une mise à jour AVANT l'extraction

Si <sortie>/cards.json et <sortie>/source_manifest.json existent, exécutez d'abord :

python3 <skill-dir>/scripts/plan_update.py "/chemin/vers/cours"

Lisez anki-output/update_plan.json. Il signale les fichiers source nouvellement ajoutés, modifiés et supprimés (hauteurs SHA-256) ainsi que les notes existantes prises en charge par les fichiers modifiés/supprimés. Cette étape doit avoir lieu avant une nouvelle exportation, car une exportation réussie valide le manifeste mis à jour. S'il n'y a pas de base de référence, générez un premier paquet complet. Une mise à jour sans changement de matériel ne nécessite normalement pas de nouvelles cartes ; autorisez néanmoins les améliorations explicitement demandées.

Ancien cards.json v1 sans identifiants explicites de notes : avant de modifier les questions, exécutez une fois :

python3 <skill-dir>/scripts/migrate_ids.py "/chemin/vers/cours/anki-output/cards.json"

Ceci écrit une sauvegarde .bak et remplit les identifiants manquants en utilisant les questions originales. Conservez ces identifiants inchangés pour toujours (même si le libellé de la question correspondante ou la diapositive citée change).

2) Lire et inventorier les sources

python3 <skill-dir>/scripts/extract_sources.py "/chemin/vers/cours" \
  --output "/chemin/vers/cours/anki-output/sources.jsonl"

Consultez sources_report.json ; il inclut les hauteurs par fichier, les types, la classification par catégorie, les fichiers inaccessibles et les pages PDF vides. Catégories : cours magistraux, devoirs, solutions de devoirs, examens passés, solutions d'examens et notes. Le texte PDF nécessite pdftotext ou pymupdf. PPTX/DOCX/Markdown/LaTeX/HTML/texte sont pris en charge. Les fichiers riches en images ou scannés nécessitent une inspection visuelle ; l'extraction de texte ne prouve pas que tout le contenu a été compris. Utilisez des rendus PDF/PPTX locaux si nécessaire, pas d'OCR fabriqué ni d'interprétation de diagrammes. Enregistrez le contenu omis dans coverage.md.

Lisez tous les documents sources pertinents lors d'une première exécution. Pour les exécutions incrémentales, examinez principalement les sources nouvelles/modifiées et le matériel existant connexe pour détecter les conflits et les faits qui se chevauchent. Conservez un plan de couverture/de syllabus global du cours pour les deux. N'émettez pas de cartes basées uniquement sur des noms de fichiers ou des extraits isolés.

3) Construire un plan d'apprentissage ciblé sur les examens

1. Les diapositives sont le périmètre : termes clés, théorèmes, hypothèses formelles, notation, algorithmes, exemples.
2. Les devoirs entraînent le transfert : stratégies d'exercice, schémas de preuve, idées fausses récurrentes.
3. Les solutions valident les réponses ; n'inventez jamais la réponse à un problème d'examen/devoir qui n'a pas de solution vérifiée.
4. Les examens passés indiquent la fréquence et les formats de tâches attendus, mais ne constituent pas un syllabus complet. Traitez la récurrence historique comme une preuve, jamais une prédiction garantie d'examen.
5. Classez les sujets par centralité, objectifs d'apprentissage du cours, récurrence dans des documents indépendants et importance dans les examens/devoirs. Priorisez les connaissances réutilisables par rapport à la mémorisation de réponses anciennes isolées.

Avant d'écrire des cartes, lisez les deux :

• references/card-quality.md
• references/math-cs-cards.md

Utilisez un plan de couverture thématique : définitions + conditions, compréhension/pourquoi, application/reconnaissance, cas d'erreur. Pour les mathématiques/informatique surtout, considérez délibérément théorème / hypothèses / stratégie de preuve / étape de preuve / contre-exemple / invariant / complexité / trace d'algorithme / réduction / micro-application. Tous les sujets n'ont pas besoin de chaque type ; choisissez uniquement des cartes justifiées, concises et testables. Préservez les quantificateurs et les prérequis. Indiquez quelle mesure de complexité, quelles hypothèses d'entrée et quelles conventions de graphe sont utilisées. Utilisez MathJax d'Anki \(...\) ou \[...\], avec un échappement JSON correct.

4) Images et diagrammes si nécessaire

Une invite textuelle seule peut être insuffisante pour un graphe, un automate, un arbre, un diagramme d'architecture, une trace d'algorithme, une construction géométrique ou une formule riche en notation. Si le visuel est essentiel, incluez la figure dans la carte plutôt que de forcer l'apprenant à l'imaginer.

Inspectez d'abord la figure visuellement pour déterminer la zone exacte ; ne copiez pas automatiquement des diapositives entières et n'incluez pas des figures sans discernement.

Pour un diagramme PDF recadré (coordonnées en points PDF) :

python3 <skill-dir>/scripts/prepare_media.py pdf "/chemin/vers/cours/slides/L3.pdf" \
  --page 12 --crop 100,90,490,330 --output "/chemin/vers/cours/anki-output/media"

Pour une diapositive PPTX entière (nécessite LibreOffice + PyMuPDF) ou une image PPTX intégrée :

python3 <skill-dir>/scripts/prepare_media.py pptx-slide "/chemin/vers/cours/slides/L3.pptx" \
  --slide 7 --output "/chemin/vers/cours/anki-output/media"
python3 <skill-dir>/scripts/prepare_media.py pptx-image "/chemin/vers/cours/slides/L3.pptx" \
  --slide 7 --image 1 --output "/chemin/vers/cours/anki-output/media"

Pour les .png, .jpg, etc. existants, utilisez prepare_media.py image ... --output ....

Insérez le nom de base exact dans le HTML de la carte : <img src="lta_example_abcdef1234.png">. Ajoutez également "media": ["media/lta_example_abcdef1234.png"] à cette note. Le nom de fichier HTML est le nom de base uniquement (pas de préfixe media/). Les actifs doivent être locaux et dans le dossier de sortie choisi. Cela garantit que .apkg les contient. Voir references/cards-schema.md.

Évitez de stocker des réponses spécifiques à l'utilisateur sous forme d'images lorsque du texte mathématique copiable et accessible aux lecteurs d'écran peut transmettre le même contenu ; décrivez ou légendez les relations visuelles importantes dans le texte. Les figures ne remplacent pas la vérification de l'exactitude conceptuelle.

5) Générer/maintenir cards.json

Utilisez le schéma dans references/cards-schema.md ; chaque note doit avoir un id unique et stable (par exemple graphs.dijkstra.nonnegative). NE dérivez JAMAIS un nouvel ID d'un texte de question modifié lors d'une mise à jour. Créez un ID stable lors de la première génération ; persistez-le dans cards.json. Les ID doivent rester uniques au sein du paquet, et le type de carte doit être stable.

Incluez :

• type : basic ou cloze (type de note Anki ; la plupart des tâches mathématiques/informatiques bénéficient de Basic).
• kind : par exemple theorem, proof_idea, counterexample, algorithm_trace, complexity, application (étiquette de classification, pas un modèle Anki).
• front/back ou text/extra.
• source_file et source_location, plus supporting_sources lorsque le contenu est vérifié sur plusieurs fichiers.
• tags avec topic::..., priority::..., from::....
• media lorsqu'il est utilisé.

Une question Basic doit pouvoir être répondue indépendamment en environ 5 à 30 secondes, cibler un fait ou une idée, et distinguer les hypothèses des conclusions. Divisez les longues présentations d'algorithmes/preuves en étapes courtes et testables. Les suppressions Cloze doivent tester un contenu contextuel significatif ; ne supprimez jamais un paragraphe entier.

6) Règles de mise à jour incrémentale

Lors d'une exécution ultérieure :

1. Lisez update_plan.json, l'ancien cards.json et le texte source nouveau/pertinent.
2. Revoyez les sujets et notes affectés, révisez lorsque les faits/notations sources ont changé, en conservant l'id de la note. Gardez les notes inchangées textuellement.
3. Ajoutez les nouvelles notes nécessaires avec des ID nouveaux, uniquement si elles apportent de nouvelles connaissances/compétences. Vérifiez l'ensemble du paquet pour les doublons sémantiques avant d'ajouter.
4. Sources supprimées : vérifiez d'abord les citations alternatives ; signalez les notes orphelines/non prises en charge pour révision. N'effacez jamais automatiquement des cartes ou des sources lors de la suppression d'un fichier.
5. Gardez le type stable. Pour un remplacement important Basic par Cloze, créez un ID distinct, signalez explicitement l'ancienne note pour suppression manuelle dans Anki (l'importation ne supprime pas les notes manquantes).
6. N'écrasez pas cards.json en cas d'erreurs de validation ; conservez la version précédente dans cards.json.bak avant les modifications importantes.
7. Exportez uniquement après que chaque note affectée a été révisée, pour valider le nouveau source_manifest.json. N'impliquez pas que la mise à jour d'un instantané source signifie que son contenu a été compris.

Les ID du paquet/du modèle et les GUID des notes sont stables pour le même paquet et les mêmes ID de carte. Lors de la réimportation dans Anki, sélectionnez l'option de mise à jour des notes existantes ; les paramètres d'importation d'Anki et les heures de modification peuvent affecter si les modifications sont réellement appliquées. La planification existante reste généralement en place lorsque les mêmes notes sont mises à jour, mais vérifiez votre aperçu d'importation Anki. La réimportation ne supprime pas les notes obsolètes précédemment importées. Ne modifiez pas manuellement les fichiers de collection d'Anki et n'utilisez pas AnkiConnect sauf demande explicite de l'utilisateur.

7) Valider et exporter

python3 <skill-dir>/scripts/export_anki.py "/chemin/vers/cours/anki-output/cards.json" \
  --output "/chemin/vers/cours/anki-output" \
  --course "/chemin/vers/cours" --format both

--format both (par défaut) produit deck.apkg, basic.txt, cloze.txt (le cas échéant), export_report.json et source_manifest.json. Importez soit le fichier .apkg OU les fichiers .txt dans une collection Anki particulière, pas les deux : des types de notes différents produiraient autrement des doublons. --format text fonctionne sans genanki, mais son importateur utilise la correspondance du premier champ et ne peut pas réviser en toute sécurité les questions par ID. Utilisez .apkg pour les mises à jour incrémentales continues. --format apkg ignore l'exportation texte.

Installez la dépendance .apkg si disponible :

python3 -m pip install genanki

Consultez export_report.json pour les comptages de cartes, les ID explicites manquants, les doublons exacts ignorés, le nombre de médias. Résolvez les erreurs de validation plutôt que de les ignorer. Les noms de fichiers sources des médias doivent être uniques et correctement référencés. Importez .apkg depuis Fichier → Importer d'Anki.

8) Résumer la couverture et l'assurance qualité

Écrivez <sortie>/coverage.md contenant :

• Matériel lu vs fichiers ignorés ; listez explicitement les lacunes de numérisation/figures.
• Sujets couverts et nombre de notes par kind et priority ; équilibre entre définition et application.
• Schémas récurrents d'examens/devoirs, avec incertitude et références.
• Conflits ou hypothèses de preuve/solution non résolues.
• Lors de mises à jour : sources nouvelles/modifiées/supprimées, notes conservées/révisées/ajoutées, notes orphelines nécessitant une révision ; assurez-vous qu'il n'y a pas de suppressions silencieuses injustifiées.
• Noms de fichiers exportés et instructions d'importation ; notez que l'importation .apkg ne supprime pas les notes manquantes et que les mises à jour Anki peuvent dépendre des options d'importation de l'utilisateur.

Si la couverture est incomplète, dites-le ; ne prétendez pas avoir généré des cartes complètes pour des sources que vous n'avez pas pu inspecter.