Graphical Abstract Builder
Transformez des documents de recherche (PDF, notes, enregistrements) en un résumé
graphique sur une page dont chaque élément est traçable jusqu'au matériel source,
plus un result.json complet et contractuel.
Division du travail — vous faites la science, les scripts font le dessin :
- Vous (l'agent) : lisez le matériel réel, extrayez entités/relations/données, choisissez le codage visuel, décidez ce qui va sur le canevas ou la légende, vérifiez la figure par rapport au matériel.
- Les scripts (
scripts/, Python pur + matplotlib) : mise en page, rendu, vérifications, assemblage du résultat. Déterministes : même modèle en entrée → même figure en sortie.
Environnement et chemins
- Racine de la compétence :
/skills/weekly-skill(scripts sousscripts/, doc de schéma sousreferences/). Travaillez sous/app/work; les livrables finaux vont dans/app/output. - Entrée :
/input/case.json(+ task.md ; les fichiers matériels référencés par le cas). - Python avec matplotlib est attendu ; s'il manque, l'export PNG tombe automatiquement sur Pillow et l'export PDF lève une exception avec une solution — consultez le playbook.
- Coût typique : 10–20 requêtes de modèle, bien dans le budget de 64 requêtes / 900 secondes. Chaque exécution de script build/vérification est un appel d'outil.
Workflow
Étape 0 — Lire le cas et préparer result.json (faites ceci d'abord)
Lisez /input/case.json intégralement. Notez case_id et chaque champ de
output_contract — ce sont vos obligations de livraison. Exécutez immédiatement :
python scripts/make_result.py --stage init \
--case /input/case.json --out /app/output/result.json
Ceci écrit chaque champ du contrat comme un null explicite avec une raison en
attente. Désormais, même un crash laisse un livrable complet et contractuel.
Réexécutez --stage final (Étape 6) pour le remplir.
Étape 1 — Lire le matériel réel
Ouvrez les vrais fichiers vers lesquels le cas pointe (ne supposez jamais le
contenu à partir des étiquettes). Pour les PDF, utilisez pdf-text-tool /
scientific-python ; ne scannez les pages que si une OCR est nécessaire.
Sauvegardez un sources.json mappant chaque fichier matériel à son texte extrait
— les étapes ultérieures vérifient automatiquement les citations par rapport à
lui :
{ "materials/paper.pdf": "<texte extrait complet>" }
Étape 2 — Extraire la science (votre jugement, pas celui d'un script)
Remplissez une feuille de travail (modèle : templates/agent_worksheet.md)
directement à partir du matériel :
- Question — quel problème le matériel pose-t-il ? Citez-le textuellement.
- Entités — les choses qui doivent apparaître (molécules, cellules, dispositifs, méthodes, cohortes...). Pour chacune : étiquette, une citation textuelle, localisateur (fichier + page/section/phrase).
- Relations — connexions directionnelles énoncées par le matériel (A active B, dosage motive la question...). Enregistrez la direction et la phrase qui l'énonce.
- Données — chaque nombre que vous pourriez dessiner : valeur, unité,
condition, et la phrase d'où il vient. Si un nombre que vous voulez n'est
pas dans le matériel, ne le dessinez pas ; listez-le dans
uncertainty/limitsà la place. - Conclusion — les affirmations que le matériel lui-même fait.
Règles de preuve : les citations sont des sous-chaînes textuelles du matériel ; les localisateurs sont assez précis pour qu'un humain les trouve en quelques secondes ; tout ce que vous ne pouvez pas sourcer va dans la légende/notes, jamais sur le canevas en tant que donnée.
Étape 3 — Créer figure_model.json
Écrivez /app/work/figure_model.json en suivant le schéma dans
references/model_schema.md (exemple complet : examples/transformer-1706.03762/).
Décisions clés que vous prenez :
- Plan des panneaux : généralement 4–6 panneaux dans l'ordre de lecture question → méthode → résultats (1–2) → conclusion ; un résultat par panneau.
- Mise en page par panneau :
flow(boîtes + flèches pour entités/relations),chart(bar/hbar/grouped_bar/line pour les données),stats(encadrés de grands nombres pour 2–4 valeurs phares),text(conclusions à puces). - Canaux visuels : longueur pour les grandeurs avec une unité commune et une ligne de base zéro ; position pour les séries temporelles ; couleur uniquement pour les séries catégorielles (la palette Okabe–Ito est intégrée ; jamais de rouge pur contre vert) ; forme/accent pour l'entité focale. Un canal par sens, un sens par canal.
- Canevas : par défaut 1800×1000 px (≈ A4 paysage à 150 dpi). Assurez-vous que chaque police ≥ 12 px (le vérificateur l'applique).
- Copiez les citations/localisateurs de votre feuille de travail dans le
sourcede chaque élément.
Étape 4 — Construire et itérer
python scripts/build_figure.py --model /app/work/figure_model.json \
--outdir /app/work/out --sources /app/work/sources.json
Produit graphical_abstract.svg (source de vérité modifiable : identifiants
nommés, groupes layer-*, de provenance sur chaque élément), .png
(300 dpi), .pdf, element_map.json, export_report.json. Code de sortie 2 =
modèle invalide (corrigez le JSON), 3 = échec SVG (corrigez selon le playbook).
Les échecs de rendu PNG/PDF n'interrompent jamais l'exécution — ils atterrissent
dans export_report.json.failures.
Itérez : si le rapport montre des erreurs, éditez le modèle (pas le SVG) et rebâtissez. La figure est incorrecte jusqu'à ce que chaque code d'erreur soit éliminé.
Étape 5 — Vérifier comme un relecteur
python scripts/check_figure.py --outdir /app/work/out --sources /app/work/sources.json
Ceci relance toutes les vérifications : bonne formation du SVG, taille minimale de police, limites du canevas, exhaustivité de la carte des éléments, citations vs matériel (détecte les nombres inventés et les mauvaises citations), niveaux de gris/contraste, intégrité des exports. Ensuite, regardez le PNG vous-même (lisez l'aperçu rendu) et vérifiez : l'ordre de lecture est-il évident ? Les entités/directions des flèches correspondent-elles au matériel ? La légende correspond-elle au codage ? Y a-t-il des unités sur chaque axe ? Si un avertissement ne peut être éliminé, enregistrez-le — ne le cachez pas.
Étape 6 — Assembler le fichier result.json final
Écrivez /app/work/values.json avec les valeurs de vos champs contractuels
(scientific_summary, uncertainty, listes de chemins, export_checks...).
element_source_map et export_checks sont automatiquement remplis à partir
de la construction. Ensuite :
python scripts/make_result.py --stage final \
--case /input/case.json --out /app/output/result.json \
--values /app/work/values.json \
--map /app/work/out/element_map.json \
--export /app/work/out/export_report.json \
--issues /app/work/out/issues.json \
--status complete --uncertainty "<une phrase honnête>"
Le matcher remplit les champs contractuels par clé exacte, puis par contenance,
puis par mots-clés de description ; les champs non appariés restent null
explicite avec raisons. Si des problèmes de niveau erreur subsistent, le statut
est automatiquement déclassé en partial — ne prétendez jamais complete sur
des vérifications échouées. Copiez les livrables vers /app/output :
graphical_abstract.svg + figure_model.json (sources modifiables),
graphical_abstract.png (aperçu) + graphical_abstract.pdf (export),
result.json.
Étape 7 — Auto-vérification finale
- result.json :
case_idprésent ; chaque champ contractuel rempli ounullexplicite avec raison ; statut honnête (déclassement automatique respecté). - Le SVG s'ouvre (XML bien formé), le texte est un vrai
<text>(modifiable), chaque élément a un identifiant, les couches sont nommées. - Le PNG et le PDF existent et ne sont pas vides ; PNG ≥ 300 dpi.
- Chaque nombre sur le canevas apparaît dans une citation dans
element_map.json. - La légende correspond exactement au codage couleur/série.
-
uncertainty/limitsmentionne chaque élément dégradé ou non sourcé.
En cas de problème
Tous les modes de défaillance, leurs signatures et solutions (matériel manquant,
chiffres clés, ambiguïté d'entité, débordement de texte, substitution de police,
débordement du canevas, échecs d'export, absence de matplotlib...) se trouvent
dans references/exception_playbook.md — consultez-le en cas de sortie rouge.
La règle qui prime tout : enregistrez honnêtement, ne fabriquez jamais.
Un résultat partial avec des limites documentées obtient un meilleur score
qu'une jolie figure avec des preuves inventées.
Références
references/model_schema.md— figure_model.json champ par champ avec valeurs par défaut et contraintes.references/exception_playbook.md— signatures de défaillance → solutions.references/design_notes.md— règles de codage visuel, sécurité daltonienne, conventions de mise en page utilisées par le constructeur.templates/agent_worksheet.md— feuille de travail pour l'étape 2.templates/figure_model.template.json— modèle minimal de départ.examples/transformer-1706.03762/— exemple complet sur un article réel (arXiv:1706.03762, citations textuelles + sha256).