Document-vers-cahier

Transformez un article de recherche (PDF, HTML, LaTeX, Markdown, etc.) en un cahier marimo interactif et exécutable pour l'apprentissage.

Qu'est-ce que Document-vers-cahier ?

Cette compétence permet à un agent IA de convertir un unique article de recherche en un cahier marimo exécutable, conçu comme une leçon interactive plutôt qu'un simple résumé. Le cahier guide le lecteur à travers les concepts clés, les équations et les figures, avec des explications adaptées à plusieurs niveaux de compréhension (de l'enfant à l'expert), des widgets interactifs pour explorer les paramètres, des quiz et des vérifications informelles. Elle prend en charge les entrées PDF, HTML et texte brut (LaTeX, Markdown), et produit un fichier `.py` exécutable avec `uvx marimo edit --sandbox`. L'agent extrait d'abord le texte intégral, la structure, les termes clés et les équations, puis planifie un parcours pédagogique, génère le cahier en respectant des règles strictes de rédaction (pas de prose générique, définition des symboles, attribution des sources) et le valide avant de le remettre à l'utilisateur. La compétence inclut un système d'échelles d'explication (modélisé sur la série '5 niveaux' de WIRED) pour les concepts fondamentaux, avec des vérifications adaptées à chaque niveau.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ericmjl/paper-to-notebook-skill/tree/main

Installed? Explore more Recherche et analyse de données skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Document vers cahier

Guider un agent d'un article vers un cahier marimo exécutable qui aide un lecteur à comprendre cet article. Le cahier est une leçon, pas une page de résumé : explications en langage clair, widgets interactifs là où ils aident, et vérifications informelles tout au long du parcours. L'écriture doit être intelligible et représentative de l'article, pas une prose générique d'IA.

Ce fichier est une ébauche. De nombreux détails seront ajoutés ultérieurement. Les éléments marqués TODO sont encore indécis ou seulement esquissés.

Contrat

EntréeUn article au format PDF, HTML ou texte brut (LaTeX, Markdown, etc.). Chemin, URL ou identifiant convient tant que le texte intégral peut être obtenu.
SortieUn cahier marimo exécutable (*.py) que le lecteur peut ouvrir avec uvx marimo edit --sandbox ….

Entrées facultatives à demander si elles manquent (ne pas bloquer si l'utilisateur ne donne que l'article) :

  • Public cible de départ ou « adapter au fur et à mesure ». Hypothèse de travail par défaut : du niveau licence au niveau master, plus les professionnels en activité novices dans cet article ou ce domaine, avec quelques connaissances scientifiques générales. TODO : préciser la valeur par défaut.
  • Contexte supplémentaire : informations complémentaires, articles cités ou autres sources que l'utilisateur souhaite traiter comme des sources de référence (pas seulement des connaissances générales).
  • Profondeur : visite complète vs. méthodes, résultats, ou une seule figure.
  • Chemin de sortie et contraintes d'exécution.

Ne pas traiter cette compétence comme un outil de revue d'une vaste littérature. C'est un travail différent.

Workflow

1. Ingérer l'article (PDF / HTML / texte brut)
2. Extraire la structure, les termes, les équations, les figures et les lacunes
3. Planifier le parcours d'apprentissage
4. Générer le cahier marimo
5. Valider son exécution avec `uv run`, puis remettre

1. Ingérer l'article

Obtenir le texte intégral, pas seulement un résumé. Se brancher sur le type d'entrée ; placer les notes spécifiques au format dans resources/ et les aides dans scripts/ (toujours uv run, jamais un pip install global).

  • PDF : TODO : comment récupérer et analyser (texte, mathématiques, figures, ordre de lecture). Signaler les échecs plutôt que deviner.
  • HTML : TODO : comment récupérer et analyser (texte principal vs. navigation/chrome, MathJax/MathML, figures).
  • Texte brut (LaTeX, Markdown, etc.) : TODO : comment suivre les inclusions, la bibliographie et les fichiers de figures ; comment conserver les étiquettes des équations et des figures.

Enregistrer le titre, les auteurs, l'année et un lien stable ou un identifiant de l'article lorsqu'ils sont disponibles.

2. Extraire la structure, les équations et les figures

Construire une image intermédiaire de l'article avant d'écrire un quelconque cahier. TODO : fixer les formes de données pour cette étape (voir aussi l'idée que des structures intermédiaires solides facilitent le reste).

Extraire au moins :

  • Le problème et la contribution, dans vos propres mots.
  • Le profil des prérequis : ce qu'un lecteur à chaque niveau sait, ne sait pas et doit apprendre (voir Expliquer à plusieurs niveaux).
  • Les concepts clés et les termes que l'article utilise mais ne définit pas (métadonnées de base ou termes du domaine). Exemple soulevé lors de la discussion de conception : un article sur les crises cardiaques qui n'explique jamais « infarctus du myocarde ».
  • Les équations clés, numérotées comme dans l'article, avec les variables.
  • Les figures clés : ce que chacune encode, comment elle est étiquetée, et si les données sous-jacentes semblent disponibles.
  • Les points de risque pour la génération : LaTeX lourd ou mathématiques, étiquettes de figures en lettres grecques, autre texte non ASCII.
  • Les lacunes évidentes dans les méthodes ou le compte rendu. Ne pas inventer de résultats expérimentaux manquants.

Classer la maturité du domaine (établi, émergent, interdisciplinaire ou mixte) en utilisant la rubrique et l'échantillon léger de littérature dans resources/field-maturity.md. Enregistrer la classe, les preuves et les composants du cahier d'intégration du vocabulaire requis (glossaire, désambiguïsation, terminologie en évolution).

TODO : classer ou non l'article comme de type algorithme (exercices de codage, rétro-ingénierie de la méthode) vs. de type concept (widgets d'explication générés par l'agent). Exemples de chimie utilisés dans la discussion : bilan massique, cinétique des réactions, un nouveau modèle cinétique.

3. Planifier le parcours d'apprentissage

Concevoir un parcours qu'un humain peut suivre en une seule séance. TODO : durée cible.

Ne pas verrouiller l'ensemble du cahier à un seul niveau de lecture. Planifier une explication adaptative : le lecteur doit pouvoir obtenir un compte rendu plus simple ou plus avancé d'un passage difficile. TODO : direction par défaut — commencer simple et ajouter de la complexité, ou commencer haut et descendre quand le lecteur est confus. Les deux ont été proposés ; aucun n'a été choisi. Les concepts fondamentaux obtiennent une échelle complète (voir Expliquer à plusieurs niveaux).

Colonne vertébrale suggérée (ajuster selon l'article) :

  1. Pourquoi cet article est important.
  2. Intuition ou exemple jouet avant la notation lourde.
  3. Mise en place : notation, hypothèses, termes et intégration du vocabulaire du domaine (glossaire ; désambiguïsation ou terminologie en évolution si nécessaire — voir resources/field-maturity.md).
  4. Idée centrale, liée à une équation ou une figure.
  5. Parcours pas à pas aligné sur l'article.
  6. Vérifications informelles après les segments, adaptées au niveau d'explication : expliquer, prédire, appliquer ou critiquer (pas d'évaluation formelle — l'évaluation formelle est hors de portée).
  7. Pour les lecteurs de niveau master et supérieur, points de critique : la conception expérimentale répond-elle à la question posée ; le cadre statistique est-il un choix approprié ; qu'est-ce qui manque ; quelles hypothèses le lecteur fait-il.
  8. Conclusion : limites, quoi lire ensuite, citation.
  9. Quiz final : cinq questions à choix multiples sur l'article, toujours la dernière section (voir Quiz final).

TODO : jusqu'où vont la critique, l'analyse de la section résultats et les invitations à interpréter les figures dans la première version, par opposition à une simple visite guidée.

Si l'utilisateur a fourni des sources supplémentaires, planifier où elles seront citées dans le cahier et comment les preuves sourcées seront distinguées des connaissances générales. TODO : le mécanisme de cette distinction, et si une petite carte conceptuelle ou un « wiki de connaissances » appartient ici plus tard.

4. Générer le cahier marimo

Commencer à partir d'un modèle assets/ lorsqu'il existe (TODO : ajouter assets/notebook_template.py). Écrire un cahier marimo qui peut être ouvert avec uvx marimo edit --sandbox.

Suivre les compétences marimo installées dans .agents/skills/ (une cellule import marimo as mo ; noms uniques au niveau supérieur ; widgets qui guident l'exploration, pas la décoration) :

  • marimo-notebook-patterns : lire avant d'écrire ou de modifier une cellule de cahier (règles d'importation et de paramètres de cellule, variables uniques, signatures d'API des widgets, erreurs courantes).
  • marimo : référence d'écriture plus large, y compris l'appairage en direct et l'intégration de cahiers sur le web.
  • awesome-marimo-notebook : comment rendre un cahier d'explication d'article ou de données engageant et soigné.

Déclarer les dépendances dans un bloc de métadonnées de script en ligne PEP 723 en haut du fichier (# /// script … # ///), listant marimo et chaque package que le cahier importe, chacun avec une version minimale (par exemple numpy>=2.0). Cela permet à uv run et marimo edit --sandbox de les installer.

Terminer le cahier par le quiz de cinq questions décrit sous Quiz final.

Exigences strictes pour la prose :

  • Intelligible et représentative des idées centrales de l'article.
  • Pas de « bouillie d'IA » générique. Si une phrase aurait pu être écrite sur n'importe quel article, la réécrire.
  • Définir les symboles et les termes du domaine quand ils apparaissent pour la première fois, ou renvoyer à un glossaire / une info-bulle / une aide à l'explication par surbrillance. Suivre resources/field-maturity.md pour les sections d'intégration spécifiques à la maturité. TODO : lesquelles de ces aides au lecteur livrer en premier. « Marimo Lens » a été mentionné comme une possibilité pour l'explication par surbrillance ; confirmer le nom réel de la fonctionnalité et le support de l'hôte.

Autres règles de génération :

  • Équations : LaTeX dans mo.md ; widgets sur les paramètres lorsque cela construit l'intuition.
  • Figures : reproduire ou simplifier lorsque les données le permettent ; créer un lien vers le numéro de figure de l'article. Si les données ne sont pas disponibles, le dire — ne pas inventer de graphiques. TODO : jusqu'où aller avec les estimations basées sur la vision ou les interprétations de figures écrites par le lecteur dans la v1.
  • Visites guidées de figures : lorsqu'une figure clé nécessite une visite guidée pas à pas, lire resources/dynamic_figure_annotation.md (FigureAnnotatorWidget plus un assistant d'audit de coordonnées dans scripts/).
  • Concepts fondamentaux (1 à 3 par cahier) : obtenir une échelle d'explication (Expliquer à plusieurs niveaux).
  • Vérifications informelles : questions courtes, pas d'évaluation notée. Utiliser le modèle show_check dans resources/explanation-levels.md §9 (bouton radio, réponse numérique avec tolérance, ou réponse libre avec une réponse modèle).
  • Mode domaine de l'étape 2 : exercices de codage et reconstruction de méthode pour les articles de type algorithme ; widgets de visualisation/explication générés par l'agent pour les articles de type concept (par exemple, un mécanisme dans une cellule).
  • Étiqueter tout ce qui va au-delà de l'article (« Notre démo », « Hypothèse simplifiée »).
  • Inclure les métadonnées et les citations de l'article.

5. Valider et remettre

Minimum (v1 ébauche) : le cahier doit s'exécuter.

uv run scripts/validate_notebook.py path/to/notebook.py --run

Il vérifie la syntaxe Python, exécute marimo check --strict, et avec --run exécute le cahier du début à la fin. Corriger chaque problème signalé avant la livraison.

Dire à l'utilisateur :

  • Le chemin du cahier et la commande pour l'ouvrir (uvx marimo edit --sandbox …).
  • Le public cible supposé et ce qui a été simplifié.
  • Les TODO et lacunes connues (y compris les données manquantes ou les termes non définis).
  • La référence à l'article (titre, auteurs, année, lien).

Validation prévue au-delà de « ça s'exécute » (pas toutes requises pour une première esquisse) :

  • L'écriture est intelligible et représentative, pas de la bouillie.
  • Les concepts fondamentaux et les termes de métadonnées sont réellement expliqués.
  • Aucun nombre ou affirmation fabriqué.
  • Le cahier se termine par le quiz de cinq questions, et ses questions portent sur les affirmations, les résultats et les limites de l'article, pas sur ses détails d'implémentation.
  • Chaque échelle explique la même colonne vertébrale du mécanisme à tous les niveaux ; chaque simplification de la comptabilité est corrigée à un niveau ultérieur ; la limite de l'analogie est énoncée.
  • Intégration du vocabulaire : pour les études de cas établies, émergentes et interdisciplinaires, vérifier la couverture du glossaire et, si nécessaire, les sections de désambiguïsation ou de terminologie en évolution selon resources/field-maturity.md §8.
  • TODO : évaluations par assertion ou question de référence ; exécutions multi-modèles (les modèles chinois open-weight et Claude ont été proposés) ; LLM-en-tant-que-juge seulement comme premier filtre plus fiable pour dire « c'est mauvais » que pour dire « c'est bon » ; un essai humain sur un article non familier ; une relecture par un expert du domaine après un test de fumée dans son propre domaine.
  • TODO : un ensemble d'articles de test partagé couvrant les travaux établis, émergents et interdisciplinaires, et les sous-domaines, pas seulement un domaine. Un article sur la grippe de 2016 a été proposé comme cas possible ; la liste n'est pas choisie.

Expliquer à plusieurs niveaux

Les idées fondamentales obtiennent une échelle d'explication : un mécanisme expliqué à cinq niveaux, chacun écrit pour un lecteur ayant des prérequis spécifiques. Il est modélisé sur la série 5 niveaux de WIRED. Les noms des niveaux sont des raccourcis. Ce qui définit un niveau, ce sont les connaissances disciplinaires et mathématiques du lecteur, ainsi que la précision que le niveau ajoute.

Niveau (raccourci)Connaissances disciplinaires supposéesMathématiques supposéesAjoute au mécanisme
1 · EnfantExpérience quotidienneCompter et comparerCause et effet, en termes quotidiens
2 · AdolescentCulture scientifique généraleArithmétique, pourcentages, graphiques simplesUn exemple jouet avec des nombres réels et petits
3 · LicenceUn cours d'introduction dans le domaineLes outils d'introduction du domaineL'équation ou l'algorithme exact, chaque symbole défini
4 · MasterLes méthodes standard d'un domaine adjacentSuit les dérivations de l'articleHypothèses, quand ça tient, ce qui casse, et comment ça se compare à l'approche standard
5 · ExpertLa littérature de ce sous-domaineFormalisme completCe qui est nouveau, les compromis, les limites et les questions ouvertes

Règles :

  1. Profil des prérequis par article (Phase 1) : pour chaque niveau, ce que le lecteur sait, ce qu'il ne sait pas et ce que le cahier doit enseigner. Faire correspondre le contexte déclaré par l'utilisateur (issu des entrées facultatives sous Contrat) à un niveau.

  2. Un mécanisme à chaque niveau. Écrire d'abord une colonne vertébrale du mécanisme d'une phrase ; chaque niveau y ajoute de la précision. Aucun niveau ne se substitue à un mécanisme plus vague ou différent.

  3. Précis à chaque niveau. Simplifier en omettant des choses, jamais en disant quelque chose de faux. Enregistrer chaque simplification dans une comptabilité et la corriger à un niveau ultérieur.

  4. Cartographier l'analogie et énoncer sa limite. Porter un point d'ancrage jusqu'au niveau 3, cartographier ses parties sur les parties de la méthode, et dire où elle casse au niveau 3.

  5. Vérifications adaptées au niveau :

    • Enfant : expliquer.
    • Adolescent : prédire.
    • Licence : appliquer.
    • Master : appliquer et critiquer les hypothèses.
    • Expert : critiquer.

    Chaque vérification a une réponse attendue, le raisonnement et l'emplacement dans l'article.

  6. Les échelles sont pour le noyau : 1 à 3 concepts par cahier.

  7. Ancré : citer les emplacements du texte que vous avez lu, et ne jamais deviner. Marquer les lacunes [cite : …] lors de la rédaction, et les résoudre avant la livraison.

  8. Les nombres portent leurs conditions : le tableau, la cohorte, l'ensemble de caractéristiques ou la plage vont dans la même phrase. Lors des tests sur des articles réels, les deux idées fausses causées par les échelles provenaient d'un nombre dépouillé de sa condition.

Dans le cahier : ajouter un sélecteur de niveau près du haut. Chaque échelle obtient mo.ui.tabs qui s'ouvrent au niveau du lecteur, avec la vérification de ce niveau en dessous.

Lire avant d'écrire : resources/explanation-levels.md contient les modèles de profil et de comptabilité, un exemple travaillé, des cellules marimo testées et des pièges. resources/examples/ contient deux autres échelles complètes,

…

[truncé pour la traduction]

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills associés