Skill: pdf2rag

Description

Pipeline automatique sans supervision : scan d’un répertoire → conversion PDF/DOCX/PPTX → Markdown → classement dans ~/knowledge-share/ → indexation dans le RAG local (ChromaDB + Ollama).

Objectif : rendre tout document binaire interrogeable via rag query.

Principes

1. Zéro supervision — un fichier qui échoue n’arrête pas les autres.
2. Idempotent — relancer deux fois = même résultat. Anti-doublon à deux niveaux :
   • Conversion : si le .md de destination existe déjà → ignoré.
   • RAG : rag ingest vérifie l’ID de chunk (hash MD5 du chemin + index) → saute automatiquement les chunks déjà indexés.
3. Source canonique — tout .md produit atterrit dans ~/knowledge-share/00-AI-Memory/01-sources/<sujet>/ pour être synchronisé par Syncthing et sauvegardé.
4. Rapport structuré — le script annonce ce qu’il va faire, liste les ignorés avec le motif, et affiche un tableau récapitulatif à la fin.

Utilisation

# Cas nominal : convertir + indexer un dossier de docs
pdf2rag ~/Downloads/rapports/

# Voir ce qui serait fait SANS rien modifier
pdf2rag ~/Downloads/rapports/ --dry-run

# Choisir une destination différente de la valeur par défaut
pdf2rag ~/Downloads/cours/ --dest ~/knowledge-share/00-AI-Memory/01-sources/cours-2026/

# Fusionner les petits fichiers d'un même sous-dossier en un seul .md
pdf2rag ~/Downloads/articles/ --fusion

# Combinaison
pdf2rag ~/Downloads/projet/ --fusion --dest ~/knowledge-share/projets/alpha/ --dry-run

Ordre de priorité des convertisseurs

Structure

~/.hermes/skills/pdf2rag/
├── skill.md          # cette documentation
└── pdf2rag.sh        # script principal

Destination canonique des .md produits :

~/knowledge-share/00-AI-Memory/01-sources/<nom_du_dossier_source>/

Scripts

pdf2rag.sh

pdf2rag <dossier> [--fusion] [--dest <dossier>] [--dry-run]

Arguments

• <dossier> — répertoire à scanner (3 niveaux de profondeur max)
• --dry-run — mode lecture seule, affiche les actions sans les exécuter
• --fusion — après conversion, concatène les .md d’un même sous-dossier en <sous-dossier>_fusion.md (utile pour des séries de cours ou chapitres)
• --dest <dossier> — écrase la destination par défaut

Sortie (toujours dans cet ordre) :

Etape 1/4 : SCAN           — liste les fichiers trouvés
Etape 2/4 : CONVERSION     — + ok  - ignoré  ! erreur
Etape 2b  : FUSION          — si --fusion
Etape 3/4 : INDEXATION RAG — relais vers rag ingest
Etape 4/4 : RAPPORT FINAL  — tableau + liste des erreurs

Code de sortie : 0 si succès ou zéro erreur ; 1 si au moins une conversion a échoué.

5 Questions clés (référence croisée DOC_EXPLOITATION.md)

1. Comment ajouter un nouveau dossier de documents à indexer ?

pdf2rag /chemin/vers/dossier/

Les .md produits sont copiés dans ~/knowledge-share/00-AI-Memory/01-sources/<nom>/ puis ingérés automatiquement. Voir aussi DOC_EXPLOITATION.md § 1.2.

2. Comment reconstruire les index RAG de zéro ?

rm -rf ~/rag-local/chromadb/*
rag ingest ~/knowledge-share/00-AI-Memory/01-sources/

Le script pdf2rag n’est pas nécessaire pour reconstruire — rag ingest suffit si les .md sont déjà présents dans knowledge-share. Voir DOC_EXPLOITATION.md § 2.2 pour la procédure complète.

3. Comment sauvegarder les documents indexés ?

Les .md sources vivent dans ~/knowledge-share/ → synchronisés automatiquement par Syncthing sur toutes les machines (MX, VPS, MacBook). La base vectorielle ChromaDB (~/rag-local/chromadb/) n’a pas besoin d’être sauvegardée : elle se reconstruit depuis les .md en < 5 min. Voir DOC_EXPLOITATION.md § 3.

4. Comment changer le modèle d’embedding ou de génération ?

Éditer ~/rag-local/ingest.py (variable EMBED_MODEL) et ~/rag-local/query.py (variable GEN_MODEL). Après changement de modèle d’embedding : reconstruire les index (cf. question 2 ci-dessus). Voir DOC_EXPLOITATION.md § 4.

5. Comment migrer le skill vers une autre machine ?

# Sur la machine source
rsync -av ~/.hermes/skills/pdf2rag/ dest_machine:~/.hermes/skills/pdf2rag/

# Sur la machine destination — vérifier les dépendances
which markitdown pandoc libreoffice
~/.local/bin/rag status

Les .md source voyagent via Syncthing. La base ChromaDB se reconstruit avec rag ingest ~/knowledge-share/.

Checklist qualité

• bash -n pdf2rag.sh — syntaxe valide
• pdf2rag <dossier> --dry-run — aucune modification de fichier
• Lancer sur dossier vide → sortie propre “Rien a faire”
• Lancer deux fois sur même dossier → second run = 0 convertis (idempotent)
• Lancer avec un fichier corrompu → script continue, erreur listée en fin
• rag status avant/après → le nombre de chunks augmente
• Les .md produits sont dans ~/knowledge-share/ (synchronisables Syncthing)