Transformer un livre de programmation en compétence d’agent IA

Votre agent cite des passages sans page, mélange deux versions d’une bibliothèque ou exécute un exemple incomplet ?

La solution la plus fiable cette semaine consiste à séparer le flux en trois couches : extraction du PDF, Knowledge Base pour les faits et Agent Skill pour la procédure. Ne placez le livre entier dans le Skill que si son contenu est court, stable et réellement opérationnel.

Pour qui ce flux est conçu

Ce guide s’adresse à vous si vous traitez des PDF de programmation contenant du code, des tableaux, des captures d’écran ou des pages numérisées. Il convient aussi aux développeurs qui hésitent entre intégrer un document complet dans un agent et construire une base de connaissances interrogeable.

Les équipes qui maintiennent plusieurs livres, éditions ou versions de frameworks y trouveront surtout une méthode de déploiement et de contrôle. L’objectif n’est pas de citer davantage de pages, mais de permettre à l’agent de retrouver la bonne information, de l’appliquer dans le bon contexte et de signaler ses limites.

Architecture des trois couches

Le flux recommandé est le suivant :

1. Extraction : récupérer texte, blocs, tableaux, images et pages avec le moins de perte possible.
2. Knowledge Base : transformer ces éléments en unités de connaissance consultables et traçables.
3. Agent Skill : définir le déclenchement, la recherche, l’exécution et la vérification.

Cette séparation évite une erreur fréquente : transformer un livre en longue consigne. Un Skill volumineux devient difficile à relire, coûteux à charger et fragile lorsque le contenu évolue. La documentation officielle sur les Agent Skills décrit une organisation fondée sur des instructions, des scripts et des fichiers de référence chargés progressivement selon la tâche.

La règle est simple : la Knowledge Base répond à « qu’est-ce qui est écrit et dans quel contexte ? ». Le Skill répond à « que doit faire l’agent maintenant, avec quelles vérifications ? ».

Diagnostic du PDF

Avant de choisir une bibliothèque, inspectez le document. Un fichier qui s’ouvre correctement dans un lecteur PDF n’est pas nécessairement exploitable par un agent.

Vérifiez d’abord si vous pouvez sélectionner le texte. Ensuite, examinez quelques pages au début, au milieu et à la fin. Cherchez les symptômes suivants :

• ordre de lecture incohérent dans les colonnes ;
• en-têtes et pieds de page répétés dans chaque paragraphe ;
• caractères remplacés par des symboles illisibles ;
• indentation perdue dans les exemples de code ;
• tableaux convertis en lignes sans relation entre les cellules ;
• captures d’écran contenant du code non sélectionnable ;
• titres de chapitre absents des blocs extraits.

Pour un PDF textuel, la documentation PyMuPDF sur l’extraction des blocs explique que get_text("blocks") conserve les coordonnées des blocs et qu’un tri spatial peut être demandé. Cette information est importante pour distinguer un paragraphe, une colonne et un extrait de code.

Ne normalisez pas immédiatement tout le contenu en texte brut. Conservez au minimum :

source_id
book_title
edition
chapter
page
block_type
language
raw_text
bounding_box

Cette version brute sert de référence lorsque l’agent donne une réponse surprenante. Sans elle, vous ne saurez pas si l’erreur vient de l’extraction, de la segmentation ou de la génération.

Extraction des PDF textuels

Pour un livre numérique correctement encodé, commencez par une extraction directe. PyMuPDF permet de récupérer le texte, les blocs, les mots et des sorties structurées comme JSON ou Markdown. Les recettes officielles d’extraction de texte montrent notamment l’intérêt des blocs positionnés pour les environnements de recherche et de génération.

Votre pipeline peut suivre cette séquence :

1. ouvrir le PDF en lecture seule ;
2. extraire chaque page avec son numéro d’origine ;
3. récupérer les blocs et leurs coordonnées ;
4. reconstruire l’ordre de lecture ;
5. détecter les titres, paragraphes, listes, tableaux et blocs de code ;
6. supprimer les éléments répétitifs après comparaison avec la page originale ;
7. enregistrer le résultat brut avant toute réécriture.

Pour les livres à deux colonnes, le tri automatique n’est pas une garantie. Comparez toujours une page extraite avec son rendu visuel. Une phrase provenant de la colonne droite peut être placée avant la fin d’un exemple situé dans la colonne gauche.

Les pages contenant du code demandent une vérification plus stricte que les pages explicatives. Contrôlez les espaces, les tabulations, les guillemets, les parenthèses, les signes > et <, ainsi que les noms de fichiers. Une seule erreur de caractère peut rendre un exemple inutilisable.

OCR ciblé pour les pages numérisées

L’OCR ne doit pas être votre première réponse à tous les PDF. Détectez d’abord les pages sans couche de texte ou celles dont la couche est manifestement vide. La documentation PyMuPDF consacrée à l’OCR recommande de déterminer si l’OCR est réellement nécessaire, puis de réutiliser le résultat pour les extractions et recherches ultérieures. Elle signale aussi que l’OCR peut être environ mille fois plus lent que l’extraction textuelle standard.

Ces niveaux ne sont pas des mesures universelles. Ils servent à prioriser votre contrôle humain. Un exemple de code extrait par OCR ne doit pas être considéré comme exécutable tant qu’il n’a pas passé un test dans un environnement isolé.

Pour les documents complexes, les stratégies de partitionnement documentées par Unstructured permettent de choisir entre plusieurs modes de traitement selon la présence de texte, d’images, de tableaux et de colonnes. Une stratégie adaptée à la mise en page peut être préférable à une simple reconnaissance optique lorsque la position des éléments porte une partie du sens.

Attention : n’effacez jamais la page originale après OCR. Conservez l’image, le texte reconnu et la version corrigée comme trois artefacts distincts. Vous pourrez ainsi expliquer pourquoi une ligne de code a été modifiée.

Pour un tableau ou une page à plusieurs colonnes, ajoutez un contrôle spécifique. Une extraction textuelle peut conserver tous les mots tout en détruisant leurs relations. Dans une table de paramètres, cette perte est parfois plus grave qu’un caractère mal reconnu.

Structuration des livres orientés code

Un livre de programmation ne se résume pas à une suite de paragraphes et de blocs de code. Un exemple utile dépend généralement de plusieurs éléments :

• objectif de l’exemple ;
• langage et version ;
• système ou environnement attendu ;
• dépendances à installer ;
• fichiers à créer ;
• commandes à exécuter ;
• sortie attendue ;
• limites ou avertissements ;
• pages de référence.

Regroupez ces éléments dans une unité cohérente. Ne séparez pas mécaniquement l’explication et le code si le code dépend de trois paragraphes précédents.

Un schéma de données simple peut ressembler à ceci :

{
  "type": "code_example",
  "title": "Création d'un client API",
  "language": "Python",
  "version": "à vérifier dans la source",
  "prerequisites": ["dépendance", "variable d'environnement"],
  "code": "…",
  "expected_result": "…",
  "source": {
    "book": "…",
    "chapter": "…",
    "pages": ["…"]
  }
}

La version doit rester « à vérifier » si le livre ne la précise pas. N’inventez pas une compatibilité à partir de la version actuellement installée sur votre serveur.

Pour les exemples audio, vidéo ou design, ajoutez aussi le type de fichier d’entrée, le format de sortie et les outils externes nécessaires. Une procédure de génération d’image ou de montage vidéo peut être conceptuellement correcte mais impossible à reproduire si les codecs, les modèles ou les fichiers médias manquent.

Découpage et citations de la Knowledge Base

Le découpage fixe, par exemple tous les mêmes nombres de caractères, est rapide mais souvent inadapté à un livre technique. Il peut couper une définition de son exception, un exemple de sa sortie ou une commande de ses prérequis.

Préférez une segmentation guidée par la structure :

1. chapitre et sous-chapitre ;
2. objectif d’une section ;
3. explication associée à son exemple ;
4. code avec dépendances et résultat ;
5. avertissement attaché au passage concerné.

Les principes de découpage sémantique d’Unstructured recommandent de partir des éléments structurés du document et de ne recourir au fractionnement supplémentaire que lorsqu’un élément dépasse la taille souhaitée.

Chaque unité de connaissance devrait porter ses métadonnées :

book_title
author
edition
publication_date
chapter
section
page_start
page_end
language
framework_version
content_type
source_hash

La citation doit être exploitable par l’agent et par vous. Une réponse comme « le livre explique cette méthode » ne suffit pas. Le résultat attendu est plutôt : titre, chapitre, page, édition et éventuellement extrait court.

Ne fusionnez pas automatiquement deux passages provenant d’éditions différentes. Un index commun peut regrouper le thème, mais les sources doivent rester séparées afin que l’agent puisse signaler une divergence.

Construction de l’Agent Skill

Le Skill ne doit pas recopier le livre. Il doit orchestrer son usage.

Un Skill dédié à un livre de programmation peut contenir :

• une description précise des demandes qui le déclenchent ;
• une règle imposant la recherche dans la Knowledge Base ;
• une procédure de sélection des passages pertinents ;
• une obligation de citer chapitre et page ;
• une étape de vérification de version ;
• une procédure d’exécution en environnement isolé ;
• une liste de résultats attendus ;
• une règle d’arrêt en cas de source contradictoire.

La structure officielle des Agent Skills repose sur un fichier SKILL.md accompagné, si nécessaire, de ressources et de scripts. Les métadonnées servent à la découverte, tandis que les instructions et ressources sont chargées progressivement.

Exemple de logique :

Si la demande concerne une méthode décrite dans le livre :
1. identifier le langage, le framework et la version ;
2. rechercher les unités de connaissance correspondantes ;
3. vérifier les prérequis ;
4. présenter la procédure avec ses sources ;
5. demander confirmation avant toute exécution destructive ;
6. exécuter dans le bac à sable ;
7. comparer la sortie avec le résultat attendu ;
8. signaler les écarts et les hypothèses.

Ajoutez des scripts lorsque le contrôle doit être déterministe : validation d’un fichier, exécution de tests, comparaison d’une sortie ou vérification d’une version. Un Skill qui demande seulement au modèle de « vérifier le code » dépend trop fortement de son interprétation.

Le nom et la description du Skill doivent être spécifiques. Utilisez une formulation courte, descriptive et stable. Évitez les noms génériques comme book-helper ou coding-agent, qui rendent la sélection automatique ambiguë lorsque plusieurs compétences sont installées.

Exécution isolée et contrôle

Un agent qui lit un exemple n’est pas encore un agent capable de l’appliquer. Pour les tâches qui exécutent du code, séparez les permissions de lecture, d’écriture et d’accès réseau.

Votre environnement de validation doit prévoir :

1. un répertoire temporaire par tâche ;
2. des dépendances explicitement déclarées ;
3. une version de langage contrôlée ;
4. des limites CPU et mémoire adaptées ;
5. un accès réseau désactivé par défaut ;
6. une durée maximale d’exécution ;
7. la conservation des journaux ;
8. la suppression des secrets après la tâche.

Ne transmettez pas automatiquement les identifiants présents dans votre environnement principal. Un exemple de livre peut contenir une commande destructive, un téléchargement non vérifié ou une configuration incompatible avec votre système.

Pour les projets audio, vidéo et design, contrôlez aussi les fichiers d’entrée et de sortie. Un script qui réussit avec un fichier de test peut échouer avec une vidéo à cadence variable, une piste audio multicanale ou une image possédant un profil colorimétrique différent.

Maintenance de plusieurs livres

Lorsque vous ajoutez plusieurs ouvrages, construisez un index par sujet, mais conservez l’origine de chaque passage. Vous pouvez regrouper les connaissances sur un même framework ou langage, sans masquer les différences d’édition.

Le cycle de maintenance recommandé est le suivant :

• identifier les chapitres touchés par la nouvelle édition ;
• recalculer les empreintes des sources ;
• reconstruire uniquement les unités modifiées ;
• marquer les anciennes unités comme obsolètes ou concurrentes ;
• rechercher les contradictions de version ;
• rejouer les scénarios du Skill ;
• vérifier les citations produites par l’agent.

Ne faites pas de « mise à jour silencieuse ». Si une nouvelle source contredit l’ancienne, l’agent doit pouvoir le dire. Cette transparence vaut mieux qu’une réponse unique, mais faussement certaine.

Plan d’implémentation en sept étapes

Pour démarrer sans construire une plateforme complète, procédez ainsi :

1. sélectionnez un seul livre dont vous détenez les droits d’utilisation ;
2. classez ses pages en texte, scan, tableau, image et code ;
3. extrayez d’abord les pages textuelles sans OCR ;
4. appliquez l’OCR uniquement aux pages qui le nécessitent ;
5. créez des unités sémantiques avec leurs références ;
6. construisez un Skill minimal centré sur une tâche réelle ;
7. testez dix demandes représentatives, dont au moins une demande ambiguë et une demande nécessitant l’exécution de code.

Mesurez quatre résultats : exactitude de la citation, cohérence du contexte, réussite de l’exécution et capacité à refuser lorsque la source est insuffisante. Un agent qui répond moins souvent mais cite correctement est préférable à un agent qui produit beaucoup de procédures invérifiables.

Si votre équipe doit préparer un environnement temporaire pour l’extraction, l’OCR ou l’exécution isolée, consultez la présentation de VPSSpark afin de vérifier le cadre de service disponible. Pour clarifier les contraintes d’un traitement de documents ou d’un besoin ponctuel, vous pouvez également contacter VPSSpark.

Questions fréquentes

Les réponses suivantes résument les choix qui provoquent le plus souvent des erreurs lors du passage d’un PDF vers un Agent Skill.

Décision finale

Pour un livre complet, la solution actuelle — PDF directement injecté dans un prompt ou dans un Skill — présente quatre défauts : les sources sont difficiles à maintenir, les références de pages disparaissent facilement, les versions se mélangent et l’exécution du code reste insuffisamment contrôlée. Elle peut convenir à une démonstration courte, mais elle devient fragile dès que le document contient des scans, des tableaux ou plusieurs éditions.

La séparation extraction → Knowledge Base → Agent Skill vous donne une base plus durable. Si vous devez seulement consulter quelques passages, une solution locale peut suffire. Si vous devez traiter plusieurs PDF, effectuer de l’OCR et exécuter des exemples dans un environnement temporaire, louer une machine Mac auprès de VPSSpark peut offrir un cadre plus propre qu’un poste de développement partagé, surtout pour isoler les dépendances et conserver des journaux distincts. Vous pouvez examiner une option de machine Mac disponible aux États-Unis, puis choisir selon la durée réelle du traitement et les exigences de votre équipe.