# 🪨 Geotechnical Layer Extractor

Un outil d'extraction automatique des couches géologiques à partir de logs de forage au format PDF, utilisant l'intelligence artificielle pour analyser et structurer les données géotechniques.

## 🎯 Objectif

Ce projet permet d'extraire automatiquement les informations de couches géologiques (profondeurs et descriptions) depuis des documents PDF de logs de forage, souvent complexes et mal structurés. Il utilise Azure Document Intelligence pour l'OCR et GPT-4 pour l'analyse sémantique du contenu.

## ✨ Fonctionnalités

- **Extraction OCR avancée** : Utilise Azure Document Intelligence pour extraire texte et tableaux
- **Analyse par IA** : GPT-4 analyse le contenu pour identifier les couches géologiques
- **Gestion multi-pages** : Traite correctement les documents de plusieurs pages
- **Détection de tableaux** : Identifie et parse les tableaux complexes
- **Déduplication intelligente** : Évite les doublons entre pages
- **Optimisation de prompts** : Outil pour améliorer automatiquement les prompts
- **Export JSON structuré** : Format de sortie standardisé et exploitable

## 📋 Prérequis

- Python 3.8 ou supérieur
- Compte Azure avec accès à :
  - Azure Document Intelligence (Form Recognizer)
  - Azure OpenAI avec accès GPT-4

## 🚀 Installation

### 1. Cloner le repository

```bash
git clone https://git.linaster.online/vincent.morisseau/geotech.git
cd geotech
```

### 2. Installer les dépendances

```bash
make setup
```

Cela va :
- Créer un environnement virtuel Python
- Installer tous les packages nécessaires
- Créer les dossiers requis

### 3. Configuration des variables d'environnement

⚠️ **IMPORTANT** : Les clés API ne doivent jamais être commitées dans Git !

1. **Copier le fichier d'exemple** :
```bash
cp .env.example .env
```

2. **Éditer le fichier `.env`** et remplir vos clés API Azure :
```bash
nano .env  # ou utilisez votre éditeur préféré
```

3. **Remplir les variables suivantes** dans le fichier `.env` :
```env
# Azure Document Intelligence
AZURE_DOC_ENDPOINT=https://your-resource.cognitiveservices.azure.com/
AZURE_DOC_KEY=your-document-intelligence-key-here

# Azure OpenAI
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_KEY=your-openai-key-here
AZURE_DEPLOYMENT=gpt-4o-mini  # ou gpt-4o, gpt-4, etc.
API_VERSION=2024-12-01-preview
```

⚠️ **Note de sécurité** : Le fichier `.env` est automatiquement ignoré par Git (via `.gitignore`) pour protéger vos clés API.

### 4. Obtenir les clés Azure

#### Azure Document Intelligence

1. **Créer une ressource dans le [portail Azure](https://portal.azure.com)**
   - Home → Create a resource
   - IA + Machine Learning → Document Intelligence (Form Recognizer)
   - Choisir la région (ex: East US 2)
   - Pricing tier : S0 (Standard)

2. **Récupérer les credentials**
   - Aller dans votre ressource → Keys and Endpoint
   - Copier `KEY 1` et `Endpoint`
   - Coller ces valeurs dans votre fichier `.env`

#### Azure OpenAI

1. **Demander l'accès à Azure OpenAI** (si nécessaire)
   - [Formulaire de demande d'accès](https://azure.microsoft.com/en-us/products/ai-services/openai-service)
   - Délai : 24-48h généralement

2. **Créer une ressource Azure OpenAI**
   - Home → Create a resource → Azure OpenAI
   - Choisir la région (recommandé : Sweden Central ou East US 2)

3. **Déployer un modèle GPT**
   - Accéder à Azure OpenAI Studio depuis votre ressource
   - Deployments → Create new deployment
   - Choisir votre modèle :
     - `gpt-4o-mini` : Économique, 0,003$/page
     - `gpt-4o` : Meilleur rapport qualité/prix, 0,042$/page
     - `gpt-4` : Plus cher mais plus puissant, 0,21$/page

4. **Récupérer les credentials**
   - Dans Azure OpenAI Studio → Deployments → View code
   - Copier l'endpoint, la clé et le nom du déploiement
   - Coller ces valeurs dans votre fichier `.env`

### 5. Vérifier la configuration

```bash
# Test de connexion aux services Azure
make test

# Ou vérifier manuellement
python -c "from dotenv import load_dotenv; import os; load_dotenv(); print('✅ OK' if os.getenv('AZURE_DOC_KEY') else '❌ .env non configuré')"
```

## 📖 Utilisation

### Extraction d'un seul PDF

```bash
# Extraction simple (sauvegarde dans output/document.json)
make single PDF=document.pdf

# Ou directement avec le script
python extract_single.py document.pdf

# Spécifier un fichier de sortie custom
python extract_single.py document.pdf -o results/custom.json

# Avec formatage JSON lisible
python extract_single.py document.pdf --pretty
```

### Optimisation des prompts

Pour améliorer la qualité d'extraction sur un ensemble de PDFs de test :

1. Placer les PDFs de test dans `examples/`
2. Placer les résultats attendus dans `output_man/` (format : `1_layers.json` pour `1.pdf`)
3. Lancer le test :

```bash
make test-optimizer
```

### Test des connexions Azure

```bash
make test
```

## 📁 Structure du projet

```
geotechnical-extractor/
├── .env.example          # Fichier d'exemple pour les variables d'environnement
├── .env                  # VOS clés API (ignoré par Git)
├── .gitignore            # Fichiers à ignorer (inclut .env)
├── extract_single.py     # Script principal d'extraction
├── prompt_optimizer.py   # Optimiseur de prompts
├── requirements.txt      # Dépendances Python
├── Makefile             # Commandes simplifiées
├── README.md            # Ce fichier
├── examples/            # PDFs de test pour l'optimiseur
│   ├── 1.pdf
│   ├── 2.pdf
│   └── ...
├── output_man/          # Résultats attendus (vérité terrain)
│   ├── 1_layers.json
│   ├── 2_layers.json
│   └── ...
└── output/              # Résultats générés
    ├── document.json
    └── ...
```

## 📊 Format de sortie

Les résultats sont sauvegardés en JSON avec la structure suivante :

```json
{
  "metadata": {
    "source_file": "/path/to/document.pdf",
    "extraction_date": "2025-08-06T10:30:45.123456",
    "extraction_method": "Azure Document Intelligence + GPT-4",
    "pages": 6,
    "layer_count": 12,
    "extraction_time_seconds": 23.5
  },
  "layers": [
    {
      "page": 1,
      "depth_start": 0.0,
      "depth_end": 0.3,
      "description": "Terre végétale, brun foncé, présence de racines"
    },
    {
      "page": 1,
      "depth_start": 0.3,
      "depth_end": 2.5,
      "description": "Argile limoneuse, gris-beige, plastique, humide"
    }
  ]
}
```

### Description des champs

- **metadata** : Informations sur l'extraction
  - `source_file` : Chemin absolu du PDF source
  - `extraction_date` : Date et heure de l'extraction
  - `pages` : Nombre de pages traitées
  - `layer_count` : Nombre de couches extraites
  - `extraction_time_seconds` : Durée de l'extraction

- **layers** : Liste des couches géologiques
  - `page` : Numéro de page où apparaît la couche
  - `depth_start` : Profondeur de début en mètres
  - `depth_end` : Profondeur de fin en mètres
  - `description` : Description complète du matériau

## 💰 Coûts estimés

Entre ~0,003€ et ~0,21€ par page selon le modèle.

**Recommandation** : Utilisez GPT-4o pour le meilleur rapport qualité/prix

## 🚨 Résolution des problèmes

### "Missing Azure credentials"
- Vérifier que le fichier `.env` existe
- Vérifier que toutes les variables sont remplies dans `.env`
- S'assurer d'avoir copié `.env.example` vers `.env`

### "Resource not found"
- Vérifier que l'endpoint Azure est correct (avec ou sans `/` final)
- S'assurer que la ressource est déployée et active

### "Invalid API key"
- Vérifier que vous utilisez la bonne clé
- Les clés Document Intelligence et OpenAI sont différentes
- Vérifier qu'il n'y a pas d'espaces dans les clés

### "Model not found"
- Vérifier le nom exact du déploiement GPT dans `.env`
- S'assurer que le modèle est déployé dans votre région
- Le nom est sensible à la casse

### Extraction incomplète
- Augmenter la limite de caractères dans le script
- Vérifier la qualité du PDF (scan lisible)
- Utiliser GPT-4o au lieu de GPT-4o-mini

### Pages manquantes
- Le script traite maintenant jusqu'à 8000 caractères par page
- Les tableaux sont marqués avec `[TABLE DATA]` pour une meilleure détection

## 🛠️ Personnalisation

### Modifier les prompts

Les prompts sont définis dans la méthode `get_prompts()` des scripts. Vous pouvez les adapter selon vos besoins spécifiques.

### Ajuster les limites

```python
# Augmenter la limite de caractères par page
max_chars = 10000  # Au lieu de 8000

# Augmenter les tokens de réponse
max_tokens=6000  # Au lieu de 4000
```

### Variables d'environnement supplémentaires

Vous pouvez ajouter dans votre `.env` :

```env
# Optionnel : niveau de log
LOG_LEVEL=DEBUG  # ou INFO, WARNING, ERROR

# Optionnel : taille des chunks pour les PDFs volumineux
CHUNK_SIZE=2  # Nombre de pages par chunk
```

### Langues supportées

Les prompts actuels sont en français mais peuvent être traduits. Le système supporte tous les documents que Document Intelligence peut traiter.

## 🧹 Maintenance

```bash
# Nettoyer tous les fichiers générés
make clean

# Voir les informations système
make info
```

## 📈 Performances

- **Temps moyen** : 3-5 secondes par page
- **Précision** : ~85-95% selon la complexité du document
- **Limite** : PDFs jusqu'à 500 pages (limite Azure)

## 🔒 Sécurité

- **Ne jamais committer le fichier `.env`** contenant vos clés API
- Le fichier `.env` est automatiquement ignoré par Git
- Utilisez `.env.example` comme template pour partager la structure
- Changez régulièrement vos clés API Azure
- Utilisez des variables d'environnement en production

## 📝 Licence

Ce projet est sous licence VCGI par Tom BLANCHETON.

## 🙏 Remerciements

- Azure Document Intelligence pour l'OCR de qualité
- OpenAI pour GPT-4
- La communauté géotechnique pour les retours et tests