Add Library RAG project and cleanup root directory
- Add complete Library RAG application (Flask + MCP server) - PDF processing pipeline with OCR and LLM extraction - Weaviate vector database integration (BGE-M3 embeddings) - Flask web interface with search and document management - MCP server for Claude Desktop integration - Comprehensive test suite (134 tests) - Clean up root directory - Remove obsolete documentation files - Remove backup and temporary files - Update autonomous agent configuration - Update prompts - Enhance initializer bis prompt with better instructions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
196
generations/library_rag/docs_techniques/TOC_EXTRACTION.md
Normal file
196
generations/library_rag/docs_techniques/TOC_EXTRACTION.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# 📑 Extraction de la Table des Matières (TOC)
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
Le système Philosophia propose **deux méthodes** pour extraire la table des matières des documents PDF :
|
||||
|
||||
1. **Extraction LLM classique** (par défaut) - Analyse sémantique via modèle de langage
|
||||
2. **Extraction avec analyse d'indentation** (recommandé) - Détection visuelle de la hiérarchie
|
||||
|
||||
## 🎯 Méthode recommandée : Analyse d'indentation
|
||||
|
||||
### Fonctionnement
|
||||
|
||||
Cette méthode analyse le **markdown généré par l'OCR** pour détecter la hiérarchie en comptant les espaces d'indentation :
|
||||
|
||||
```
|
||||
Présentation → 0-2 espaces = niveau 1
|
||||
Qu'est-ce que la vertu ? → 3-6 espaces = niveau 2
|
||||
Modèles de définition → 3-6 espaces = niveau 2
|
||||
Ménon ou de la vertu → 0-2 espaces = niveau 1
|
||||
```
|
||||
|
||||
### Avantages
|
||||
|
||||
- ✅ **Fiable** : Détection basée sur la position réelle du texte
|
||||
- ✅ **Rapide** : Pas d'appel API supplémentaire
|
||||
- ✅ **Économique** : Coût zéro (utilise l'OCR déjà effectué)
|
||||
- ✅ **Hiérarchique** : Construit correctement la structure parent/enfant
|
||||
|
||||
### Activation
|
||||
|
||||
Dans l'interface Flask, cochez **"Extraction TOC améliorée (analyse indentation)"** lors de l'upload :
|
||||
|
||||
```python
|
||||
# Via API
|
||||
process_pdf(
|
||||
pdf_path,
|
||||
use_ocr_annotations=True, # Active l'analyse d'indentation
|
||||
)
|
||||
```
|
||||
|
||||
### Algorithme
|
||||
|
||||
1. **Détection de la TOC** : Recherche "Table des matières" dans le markdown
|
||||
2. **Extraction des entrées** : Pattern regex `Titre.....PageNumber`
|
||||
3. **Comptage des espaces** :
|
||||
- `0-2 espaces` → niveau 1 (titre principal)
|
||||
- `3-6 espaces` → niveau 2 (sous-section)
|
||||
- `7+ espaces` → niveau 3 (sous-sous-section)
|
||||
4. **Construction hiérarchique** : Utilisation d'une stack pour organiser parent/enfant
|
||||
|
||||
### Code source
|
||||
|
||||
- **Module principal** : `utils/toc_extractor_markdown.py`
|
||||
- **Intégration pipeline** : `utils/pdf_pipeline.py` (ligne ~290)
|
||||
- **Fonction clé** : `extract_toc_from_markdown()`
|
||||
|
||||
## 📊 Méthode alternative : Extraction LLM
|
||||
|
||||
### Fonctionnement
|
||||
|
||||
Envoie le markdown complet à un LLM (Mistral ou Ollama) qui analyse sémantiquement la structure.
|
||||
|
||||
### Avantages
|
||||
|
||||
- Comprend la structure logique même sans indentation claire
|
||||
- Peut déduire la hiérarchie du contexte
|
||||
|
||||
### Inconvénients
|
||||
|
||||
- ❌ **Moins fiable** : Peut mal interpréter la structure
|
||||
- ❌ **Plus lent** : Appel LLM supplémentaire
|
||||
- ❌ **Plus cher** : Consomme des tokens
|
||||
- ❌ **Aplatit parfois** : Tendance à mettre tout au même niveau
|
||||
|
||||
### Activation
|
||||
|
||||
C'est la méthode par défaut si l'option "Extraction TOC améliorée" n'est **pas** cochée.
|
||||
|
||||
## 🔧 Configuration avancée
|
||||
|
||||
### Paramètres personnalisables
|
||||
|
||||
```python
|
||||
# Dans toc_extractor_markdown.py
|
||||
def extract_toc_from_markdown(
|
||||
markdown_text: str,
|
||||
max_lines: int = 200, # Lignes à analyser pour trouver la TOC
|
||||
):
|
||||
# Seuils d'indentation personnalisables
|
||||
if leading_spaces <= 2:
|
||||
level = 1 # Modifier selon votre format
|
||||
elif leading_spaces <= 6:
|
||||
level = 2
|
||||
else:
|
||||
level = 3
|
||||
```
|
||||
|
||||
### Pattern TOC personnalisable
|
||||
|
||||
Le pattern regex détecte les formats suivants :
|
||||
|
||||
- `Titre.....3` (avec points de suite)
|
||||
- `Titre 3` (avec espaces)
|
||||
- `Titre..3` (avec quelques points)
|
||||
|
||||
Pour modifier, éditer la regex dans `toc_extractor_markdown.py` :
|
||||
|
||||
```python
|
||||
match = re.match(r'^(.+?)\s*\.{2,}\s*(\d+)\s*$', line)
|
||||
```
|
||||
|
||||
## 📈 Résultats comparatifs
|
||||
|
||||
### Document test : Ménon de Platon (107 pages)
|
||||
|
||||
| Méthode | Entrées | Niveaux | Hiérarchie | Temps | Coût |
|
||||
|---------|---------|---------|------------|-------|------|
|
||||
| **LLM classique** | 11 | Tous level 1 | ❌ Plate | ~15s | +0.002€ |
|
||||
| **Analyse indentation** | 11 | 2 niveaux | ✅ Correcte | <1s | 0€ |
|
||||
|
||||
### Exemple de structure obtenue
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Présentation",
|
||||
"level": 1,
|
||||
"children": [
|
||||
{"title": "Qu'est-ce que la vertu ?", "level": 2},
|
||||
{"title": "Modèles de définition", "level": 2},
|
||||
{"title": "Définition de la vertu", "level": 2},
|
||||
...
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Ménon ou de la vertu",
|
||||
"level": 1,
|
||||
"children": []
|
||||
}
|
||||
```
|
||||
|
||||
## 🐛 Dépannage
|
||||
|
||||
### La TOC n'est pas détectée
|
||||
|
||||
**Problème** : Le message "Table des matières introuvable" apparaît
|
||||
|
||||
**Solutions** :
|
||||
1. Vérifier que le PDF contient bien une TOC explicite
|
||||
2. Augmenter `max_lines` si la TOC est très loin dans le document
|
||||
3. Vérifier que la TOC contient le texte "Table des matières" ou variantes
|
||||
|
||||
### Tous les titres sont au level 1
|
||||
|
||||
**Problème** : Aucune hiérarchie détectée
|
||||
|
||||
**Solutions** :
|
||||
1. Vérifier que les titres ont une **indentation visuelle** dans le PDF original
|
||||
2. Ajuster les seuils d'espaces dans le code (lignes ~90-95 de `toc_extractor_markdown.py`)
|
||||
3. Examiner le fichier `.md` pour voir comment l'OCR a préservé l'indentation
|
||||
|
||||
### Entrées manquantes
|
||||
|
||||
**Problème** : Certains titres n'apparaissent pas
|
||||
|
||||
**Solutions** :
|
||||
1. Vérifier le pattern regex (peut ne pas correspondre au format de votre TOC)
|
||||
2. Regarder les logs : `logger.debug()` affiche chaque ligne analysée
|
||||
3. Augmenter la limite de lignes analysées
|
||||
|
||||
## 🔬 Mode debug
|
||||
|
||||
Pour activer les logs détaillés :
|
||||
|
||||
```python
|
||||
import logging
|
||||
logging.getLogger('utils.toc_extractor_markdown').setLevel(logging.DEBUG)
|
||||
```
|
||||
|
||||
Vous verrez :
|
||||
```
|
||||
Extraction TOC depuis markdown (analyse indentation)
|
||||
TOC trouvée à la ligne 42
|
||||
'Présentation' → 0 espaces → level 1 (page 3)
|
||||
'Qu'est-ce que la vertu ?' → 4 espaces → level 2 (page 3)
|
||||
...
|
||||
✅ 11 entrées extraites depuis markdown
|
||||
```
|
||||
|
||||
## 📚 Références
|
||||
|
||||
- **Code source** : `utils/toc_extractor_markdown.py`
|
||||
- **Tests** : Testé sur Platon - Ménon, Tiercelin - La pensée-signe
|
||||
- **Format supporté** : PDF avec TOC textuelle indentée
|
||||
- **Langues** : Français, fonctionne avec toute langue utilisant des espaces
|
||||
|
||||
Reference in New Issue
Block a user