MinorBaek/wiki-ingest-book

Que fait wiki-ingest-book ?

Avant la première ingestion, lisez docs/GOTCHAS.md dans le kit (les difficultés opérationnelles, y compris le calibrage du décalage de page pour les livres).

Étend le modèle d'ingestion du wiki LLM aux livres académiques. Les livres sont très contextualisés et ne peuvent pas être ingérés en une seule fois, cette compétence utilise donc une approche en deux phases : un aperçu du livre d'abord, puis les chapitres sur demande.

Rôle et limites

Fait : crée des notes de livre, crée des notes de chapitre, propage les résultats vers les notes de concepts et de méthodes, met à jour l'index et le journal.

Ne fait PAS : ne lit pas un livre entier en une seule passe (risque de dépassement de contexte), n'invente pas de métadonnées ou de titres de chapitres, ne duplique pas le flux de travail d'ingestion d'article (les chapitres suivent les mêmes règles de propagation de concepts que les articles).

Où se trouvent les choses

Les chemins proviennent de wiki.config.json (voir wiki-ingest). Les livres et chapitres se trouvent dans <racine_du_wiki>/books/. Modèles : templates/book.md et templates/chapter.md. Le dossier contenant votre bibliothèque PDF est pdf_library_dir dans la configuration.

Compétences associées

• wiki-ingest : partage les règles de décision de statut initial et le field_titlecase_map utilisé pour le routage de l'index.
• wiki-lint : exécutez-le après chaque ingestion de chapitre. La vérification 8 (synchronisation de chapters_ingested) et la vérification 9 (chapitre book: dans le frontmatter) détectent les dérives les plus courantes lors de l'ingestion de livres.

Contrats requis (doivent être respectés après chaque ingestion)

1. Chaque note de chapitre dans livres/{livre}_ChNN.md DOIT comporter book: "[[{nom_base_du_livre}]]" dans le frontmatter, et la cible doit correspondre à une note de livre existante. Vérifiez après l'écriture ; si elle manque, wiki-lint Vérification 9 la signale.
2. Chaque ingestion de chapitre DOIT ajouter le numéro du chapitre à la liste chapters_ingested: de la note du livre parent. Après l'ajout, listez {livre}_Ch*.md et confirmez que les deux ensembles correspondent ; sinon, wiki-lint Vérification 8 signale la dérive.
3. Le statut initial suit la table des statuts de wiki-ingest : stub pour définition uniquement, draft en cours, et une note de chapitre atteint final avec 2 résultats sourcés ou plus (un chapitre est lui-même une source). Les notes de concepts et de méthodes dérivées suivent la règle de promotion stricte : final nécessite N œuvres sources distinctes (min_distinct_sources_for_final, par défaut 2), donc un concept construit uniquement à partir de ce seul livre reste draft jusqu'à ce qu'une deuxième source indépendante le corrobore.
4. Le routage de l'index utilise field_titlecase_map pour placer les nouveaux concepts et méthodes sous la bonne sous-section Title Case, jamais dans un bloc fourre-tout daté.

Préambule (toujours, avant le Mode A ou le Mode B)

1. Lisez WIKI_SCHEMA.md.
2. Lisez le modèle : le Mode A utilise templates/book.md ; le Mode B utilise templates/chapter.md (et templates/book.md pour référence).

Outils : utilisez les outils de fichiers de l'hôte (Lecture/Écriture/Édition) pour toutes les écritures dans le coffre.

---

Résolution des PDF locaux (préférée pour le texte intégral)

Dossier par défaut : pdf_library_dir dans la configuration (stockage PDF de votre gestionnaire de références). Extracteur : pdftotext (poppler) ou, pour une meilleure fidélité des tableaux, docling. Exécutez toujours pdftotext avec -enc UTF-8.

Localisez le PDF en énumérant et en grepant l'auteur, PAS avec un outil glob et PAS avec find -iname "*<auteur>*" ; les deux ont des faux négatifs documentés pour les fichiers qui existent sur certains systèmes de fichiers : find "<pdf_library_dir>" -iname "*.pdf" | grep -i <nom_de_famille_du_premier_auteur>. Élargissez la racine à toute la bibliothèque si le premier passage est vide (les livres vivent aussi dans des sous-dossiers thématiques). Exactement 1 correspondance : utilisez-la. 0 ou plus d'une : demandez à l'utilisateur le chemin exact. Si cela échoue également : revenez au texte intégral du gestionnaire de références.

L'algorithme de résolution complet, la cascade de texte intégral local d'abord et la table de décision MCP, la détection de PDF scanné, et le danger des noms de fichiers non ASCII se trouvent dans references/BOOK-INGEST-WORKFLOW.md (sections 1 et 1bis). Lisez-le avant la première extraction d'un nouveau livre. Le corps ci-dessous ne conserve que les commandes utilisées pour chaque chapitre.

Commandes d'extraction

• TOC / aperçu (Mode A) : pdftotext -enc UTF-8 -f 1 -l 20 "<chemin>" - (les 20 premières pages, stdout).
• Plage de chapitre (Mode B) : pdftotext -enc UTF-8 -f <pdf_debut> -l <pdf_fin> "<chemin>" -. -f/-l prennent les numéros de page PDF, pas les numéros de page du livre ; convertissez à partir de la TOC avec le décalage (section suivante).
• Écrire l'extrait dans un fichier que vous lirez : une longue tranche de chapitre peut être plus facile en tant que fichier qu'en tant que stdout. Écrivez-la à l'intérieur du projet (par exemple _temp/{livre}_Ch{NN}.txt), pas dans un /tmp spécifique au système d'exploitation que l'outil de lecture ne peut pas ouvrir (Git Bash sur Windows mappe /tmp quelque part que les outils Windows ne peuvent pas voir).

Calibrage du décalage de page (les pages du livre ne sont pas les pages du PDF)

La TOC d'un livre répertorie les numéros de page du livre ; pdftotext -f/-l adresse les pages PDF. Ils diffèrent d'un décalage (pages liminaires, planches) qui croît de manière non linéaire à travers le livre (figures, tableaux, séparateurs de parties). Passer les numéros de la TOC directement à pdftotext extrait les mauvaises pages, la perte de temps la plus courante dans l'ingestion de chapitres. Calibrez une fois par livre, avant d'extraire un chapitre :

1. Choisissez un chapitre avec une page de début de livre connue. Estimez pdf_debut = page_du_livre + estimation_du_decalage (les pages liminaires sont souvent de 20 à 60 pages).
2. Extrayez seulement sa première page et confirmez que le titre du chapitre apparaît. Ajustez de jusqu'à 5 pages jusqu'à ce qu'il tombe juste.
3. Enregistrez le décalage calibré dans la note du livre (par exemple > [!note] Décalage PDF : page_du_livre + N = page_pdf (zone : Partie X) près de la TOC) afin que les chapitres suivants le réutilisent.
4. Re-calibrez par zone ou partie sur les longs livres : un décalage fixe unique dérive (par exemple +36 au Ch 3 et +56 au Ch 21 dans un manuel). Pour les PDF avec couche de texte, diviser le texte sur les sauts de page donne une carte de page rapide avec les pages de début exactes.

---

Mode A : Aperçu du livre

Déclencheur : /wiki-ingest-book [titre]

1. Résoudre dans le gestionnaire de références : recherchez par titre, puis récupérez les métadonnées (titre, auteurs, éditeurs, année, éditeur, ISBN, édition, DOI, clé de citation).
   • Mise en garde sur la clé de citation avec suffixe d'année (série multi-volumes ou parties) : une clé de citation Better BibTeX comme ...2019a / ...2019b ne correspond PAS de manière fiable à la Partie 1 par rapport à la Partie 2 d'une série du même auteur, même année (le suffixe est l'ordre de désambiguïsation, pas le sens). Confirmez toujours le titre réel (et le sous-titre ou "Partie N") à partir des métadonnées avant de nommer la note ou de faire confiance au volume que vous avez.
2. Résoudre le texte intégral pour la TOC (cascade ; voir "Résolution des PDF locaux") :
   • Primaire : pdftotext -enc UTF-8 -f 1 -l 20 "<chemin_local>" - (environ 3 à 8k tokens).
   • Repli 1 : texte intégral du gestionnaire de références, uniquement si le PDF local est indisponible ET le résultat fait moins de 2 000 mots.
   • Repli 2 : demandez à l'utilisateur de coller la TOC ; marquez-la "Source : fournie par l'utilisateur".
   • Repli 3 : connaissance du modèle pour les manuels bien connus ; marquez chaque élément avec [!note].
3. Déterminer le nom du fichier : PremierAuteur_Année_MotClé.md (nom de famille du premier auteur, ASCII uniquement ; mot-clé est 1 à 3 mots sur le sujet principal du livre). Si livres/{nom_fichier}.md existe, mettez à jour sur place.
4. Créer ou mettre à jour la note du livre à livres/{nom_fichier}.md à partir de templates/book.md. Définissez last_verified à la date du jour.
5. Remplir la TOC à partir de l'étape 2. En cas d'incertitude, marquez les chapitres ? et notez la limitation.
6. Extraire 3 à 5 thèmes de haut niveau (niveau livre uniquement, pas de revendications spécifiques aux chapitres). Propagation légère : mettez à jour les notes concepts/ uniquement si le thème est central à une ligne de recherche ET que 2 articles du wiki ou plus l'abordent déjà ; sinon, listez-le simplement dans la note du livre. Un thème qui atteint une note suit la règle de la table de preuves : étapes 6b et 8b du Mode B.
7. Vérification de gouvernance : appliquez la correspondance de ligne de recherche et le routage concept-versus-méthode de wiki-ingest étape 5. Au niveau de l'aperçu, notez uniquement quels chapitres produiront probablement des notes de méthode versus des notes de concept ; la propagation complète a lieu dans le Mode B.
8. index.md : si l'index intègre des vues Bases, n'ajoutez PAS d'entrée de livre ; seulement incrémentez le compteur ## Quick Stats "Livres (ingérés)" lorsque cela termine une ingestion de livre parent. En mode manual, ajoutez l'entrée. Ne touchez jamais à un index legacy gelé.
9. Ajouter à log.md : ## [AAAA-MM-JJ] ingest-book | {Titre} : aperçu.
10. Rapport : chemin de la note du livre, thèmes identifiés et quels chapitres sont disponibles pour une ingestion approfondie (/wiki-ingest-book [titre] > Chapitre N).

---

Mode B : Ingestion de chapitre

Déclencheur : /wiki-ingest-book [titre] > Chapitre N (ou > Chapitre : [titre du chapitre])

1. Lire la note du livre existante à livres/PremierAuteur_Année_MotClé.md.

   • Si elle n'existe pas : arrêtez. Exécutez d'abord le Mode A, puis réessayez.
   • Si le chapitre n'est pas listé dans la TOC : ajoutez une ligne avec status: pending, notez-le dans le rapport final, continuez.
   • Si le chapitre est déjà marqué ingested : confirmez avec l'utilisateur avant d'écraser (par défaut : mettre à jour sur place, en préservant les [[wikilinks]] existants).

2. Résoudre le contenu du chapitre (cascade ; voir "Résolution des PDF locaux") :

   • Prenez la plage de pages du chapitre à partir de la TOC de la note du livre et convertissez les pages du livre en pages PDF avec le décalage enregistré. Demandez à l'utilisateur uniquement si les numéros de page de la TOC eux-mêmes sont inconnus.
   • Primaire : pdftotext -enc UTF-8 -f <pdf_debut> -l <pdf_fin> "<chemin_local>" - (un chapitre typique fait 1k à 8k tokens).
   • Repli 1 : si le chapitre est un élément bookSection avec sa propre entrée de bibliothèque, utilisez le texte intégral de cet élément.
   • Repli 2 : texte intégral du livre entier depuis le gestionnaire de références, uniquement si le PDF local est indisponible ET le livre fait moins de 5 000 mots.
   • Repli 3 : demandez à l'utilisateur de coller le texte du chapitre.
   • Repli 4 : connaissance du modèle, avec [!warning] sur chaque affirmation. Cela n'atteint jamais une note de concept ou de méthode et ne reçoit aucun sceau.

3. Nom du fichier du chapitre : PremierAuteur_Année_MotClé_ChNN.md (par exemple Knuttgen_1987_Strength_Ch03.md).

4. Créer la note du chapitre à livres/{nom_fichier_chapitre}.md à partir de templates/chapter.md. Définissez last_verified à la date du jour.

   • Contrat requis : émettez book: "[[{nom_base_du_livre_parent}]]" dans le frontmatter et vérifiez qu'il se résout. Si ce n'est pas le cas, le parent n'a pas été ingéré : exécutez d'abord le Mode A.
   • Statut initial : appliquez la table des statuts de wiki-ingest. Un chapitre squelette avec seulement l'entrée de TOC remplie est stub ; un chapitre avec au moins 2 résultats sourcés est final.
   • Niveau de preuve : evidence_level: textbook par défaut. Remplacez par SR-MA ou SR uniquement si le chapitre est lui-même une revue systématique ou une méta-analyse autonome. La qualité de la mesure reste en ligne dans les résultats, jamais dans le frontmatter.

5. Extraire 3 à 8 concepts et 1 à 4 méthodes : mêmes règles d'extraction que wiki-ingest (voir references/BOOK-INGEST-WORKFLOW.md).

6. Vérification de gouvernance : même correspondance de ligne de recherche et routage concept-versus-méthode que wiki-ingest étape 5. Décidez explicitement pour ce chapitre : notes de concept (résultats empiriques), notes de méthode (cadres, protocoles), ou les deux. Le contenu pédagogique général ne produit généralement que des notes de méthode ; ne forcez pas la création de concept pour un contenu qui appartient à methods/. 6b. Tableau de preuves et vérification, avant toute propagation : appliquez wiki-ingest étapes 5b et 5c à ce chapitre, avec un tableau provisoire pour le chapitre. Trois ajouts pour les livres :

   • La colonne de page donne à la fois la page PDF et la page imprimée, et le titre du chapitre est confirmé sur la page sur laquelle vous atterrissez (un mauvais décalage cite un autre chapitre).
   • Un manuel reçoit la lecture stricte : vérifiez chaque mécanisme et marqueur que le résultat nomme. Une liste de causes ou de critères d'un chapitre n'est pas une preuve pour chaque élément à moins que l'élément ne soit sur la page.
   • Dites qui parle : une affirmation que le chapitre attribue à un autre auteur est écrite "X, comme rapporté par [[chapitre]]", et une opinion clinique d'un chapitre n'est pas écrite comme un résultat d'essai. Seules les lignes qui réussissent passent aux étapes 7 et 8. Lisez les signes de la page rendue.

7. Propager vers les notes de concept, identique à l'ingestion d'article : ajoutez le résultat avec un [[note_de_chapitre]] backlink vers la concepts/{Concept}.md existante, ou créez-en une nouvelle à partir de templates/concept.md selon les mêmes règles de création que wiki-ingest/references/CONCEPT-PROPAGATION.md.

8. Propager vers les notes de méthode si applicable. 8b. Sceller la note du chapitre : appliquez wiki-ingest étape 8b avec le chapitre comme œuvre (enregistrez la vérification dans source_verification : clé de bibliothèque, ISBN, chapitre et pages vérifiés, date).

9. Stubs de référence prospective (automatique) : après la rédaction du corps du chapitre, matérialisez toutes les références prospectives vers des chapitres frères qui n'existent pas encore :

   python skills/wiki-ingest-book/scripts/create_forward_ref_stubs.py \
     <racine_du_wiki>/books/{livre}_Ch{NN}.md  <racine_du_wiki>/books/{livre}.md   [--dry-run]
   

   Le script analyse le chapitre fraîchement ingéré pour les liens [[{livre}_ChNN]] (sensible aux alias), lit le tableau ## Table des matières du hub du livre pour récupérer le titre et les pages de chaque chapitre manquant, dérive le DOI et la clé de citation à partir du frontmatter du hub ({doi_base}_{N}, {citekey_base}_ch{N}), et écrit des stubs UTF-8 avec status: stub. Les références prospectives sans ligne de TOC sont ignorées et signalées (ingestion manuelle requise). Les actions sont journalisées dans _temp/wiki_ingest_book_stubs_created.md. wiki-lint Vérification 8 honore status: stub, donc ces stubs ne désynchronisent PAS chapters_ingested, qui reste la liste canonique des chapitres réellement ingérés.

   ⚠️ N'écrivez jamais de marqueur d'état d'ingestion dans la prose d'un chapitre. Pas de *(en attente d'ingestion)*, pas de "pas encore ingéré" à côté d'un chapitre frère, dans ## Articles connexes, dans une puce voir aussi, ou ailleurs. L'état d'ingestion est mutable et a exactement un seul endroit : la ligne ## Table des matières du hub du livre, que l'étape 11 fait passer de pending à ingested. Un marqueur copié dans la prose duplique un fait mutable dans un endroit immuable : le frère est ingéré, la TOC se met à jour, et la prose continue d'affirmer le contraire pour toujours. Dans un audit, cela a produit 68 marques obsolètes dans 58 notes, chaque dépendance déjà ingérée. Aucune vérification de lint ne voit cette classe, car chaque fichier reste cohérent avec lui-même et la contradiction n'existe qu'entre les fichiers. Liez simplement le frère ; si une œuvre est en dehors du wiki, nommez-la en texte brut.

10. Rapport de concepts manquants (automatique) : après la propagation, exécutez wiki-ingest étape 10.

11. Mettre à jour la note du livre :

    • Marquez le chapitre comme ingested dans ## Table des matières
    • Ajoutez Ch{NN} à chapters_ingested: (liste triée, dédupliquée)
    • Mettez à jour last_verified

12. Vérifications finales :

    • Exécutez wiki-lint Vérification 8 (vérifie que chapters_ingested et les fichiers *_Ch*.md correspondent)
    • Exécutez wiki-lint Vérification 9 (vérifie que chaque chapitre a un book: [[lien]] résoluble)

13. Rapport : chemin de la note du chapitre, concepts propagés, méthodes créées, tous les chapitres frères de stub créés, et tous les avertissements (pages de TOC manquantes, concepts non sourcables).

---

Notes et mises en garde

• La limite de contexte est réelle : un chapitre d'un manuel de médecine dense peut dépasser 8 000 tokens. Si la sortie de pdftotext est tronquée, réduisez la plage de pages par intervalles de 5 jusqu'à ce que le chapitre tienne, ou divisez l'extraction en deux parties (gauche, droite) ou en sections logiques.
• Les livres en plusieurs volumes : chaque volume obtient sa propre note de livre. La clé de citation (par exemple Smith_2020a vs Smith_2020b) n'est pas fiable pour l'identification du volume ; utilisez le titre et le numéro de volume. Les mises en garde sur les clés de citation s'appliquent également aux citations dans le texte.
• Les PDF scannés : si pdftotext produit un texte vide ou absurde (par exemple un seul bloc sans sauts de ligne), le PDF est une image scannée. L'OCR est hors de portée pour cette compétence ; revenez au texte intégral du gestionnaire de références ou à une saisie manuelle du chapitre.
• Les manuels sont traités comme des livres avec un niveau de preuve de evidence_level: textbook. Aucun résultat unique de manuel n'atteint le statut final dans une note de concept ; il faut une deuxième source (article, autre livre).
• Les livres de référence (encyclopédies, dictionnaires) : ingérez les entrées individuellement comme des notes de concept, pas comme des chapitres d'un ouvrage en plusieurs volumes. Chaque entrée est un article autonome.
• Ne PAS numéroter à nouveau : si un livre a des numéros de chapitre comme Chapitre 3.1 ou Chapitre A2, utilisez le numéro exact du livre dans le nom du fichier (par exemple Ch3-1, ChA2).