4NK_IA_back/docs/API-NOTARIALE.md

# API Notariale 4NK - Documentation Complète

## 🎯 Vue d'ensemble

L'API Notariale 4NK est un système complet de traitement de documents notariaux utilisant l'IA pour l'OCR, la classification, l'extraction d'entités, la vérification externe et l'analyse contextuelle via LLM.

## 🏗️ Architecture

### Composants Principaux

1. **API FastAPI** (`services/host_api/`)
   - Endpoints REST pour l'upload et l'analyse
   - Gestion des tâches asynchrones
   - Intégration avec les services externes

2. **Pipeline de Traitement Avancé** (`services/worker/`)
   - **Préprocessing** : Validation, conversion et optimisation des documents
   - **OCR** : Extraction de texte avec Tesseract et correction lexicale notariale
   - **Classification** : Détection du type de document via LLM
   - **Extraction** : Extraction d'entités (identités, adresses, biens, montants, dates)
   - **Indexation** : Indexation multi-système (AnythingLLM, OpenSearch, Neo4j)
   - **Vérifications** : Contrôles métier et vérifications externes automatisées
   - **Finalisation** : Synthèse et archivage avec score de vraisemblance

3. **Traitement Asynchrone** (Celery)
   - Queues spécialisées pour chaque étape du pipeline
   - Scalabilité horizontale des workers
   - Monitoring des tâches en temps réel
   - Gestion robuste des erreurs

4. **Services Externes Intégrés**
   - **Ollama** : Modèles LLM locaux (Llama 3, Mistral)
   - **APIs Gouvernementales** : Cadastre, Géorisques, BODACC, Infogreffe, RBE
   - **Base de données PostgreSQL** : Métadonnées et résultats
   - **Stockage MinIO** : Documents et artefacts
   - **Cache Redis** : Performance et queues Celery
   - **Neo4j** : Graphe de connaissances
   - **OpenSearch** : Recherche plein-texte
   - **AnythingLLM** : Indexation sémantique

## 📋 Types de Documents Supportés

### Documents Notariaux
- **Acte de Vente** : Vente immobilière
- **Acte de Donation** : Donation entre vifs
- **Acte de Succession** : Succession et notoriété
- **Contrat** : Contrats divers
- **CNI** : Carte nationale d'identité
- **Autre** : Documents non classés

### Formats Supportés
- **PDF** : Documents scannés ou natifs
- **Images** : JPEG, PNG, TIFF, HEIC

## 🔧 Installation et Configuration

### Prérequis
```bash
# Python 3.11+
python3 --version

# Docker et Docker Compose
docker --version
docker-compose --version

# Tesseract OCR
sudo apt-get install tesseract-ocr tesseract-ocr-fra

# Autres dépendances système
sudo apt-get install poppler-utils imagemagick ghostscript
```

### Installation
```bash
# 1. Cloner le projet
git clone <repository>
cd 4NK_IA

# 2. Créer l'environnement virtuel
python3 -m venv venv
source venv/bin/activate

# 3. Installer les dépendances
pip install -r docker/host-api/requirements.txt

# 4. Configuration
cp infra/.env.example infra/.env
# Éditer infra/.env avec vos paramètres

# 5. Démarrer les services
make bootstrap
```

## 🚀 Utilisation

### API REST

#### Upload d'un Document
```bash
curl -X POST "http://localhost:8000/api/notary/upload" \
  -F "file=@document.pdf" \
  -F "id_dossier=D-2025-001" \
  -F "etude_id=E-001" \
  -F "utilisateur_id=U-123" \
  -F "type_document_attendu=acte_vente"
```

**Réponse :**
```json
{
  "document_id": "uuid-123",
  "status": "queued",
  "message": "Document mis en file de traitement",
  "estimated_processing_time": 120
}
```

#### Statut de Traitement
```bash
curl "http://localhost:8000/api/notary/document/{document_id}/status"
```

**Réponse :**
```json
{
  "document_id": "uuid-123",
  "status": "processing",
  "progress": 45,
  "current_step": "extraction_entites",
  "estimated_completion": 1640995200
}
```

#### Analyse Complète
```bash
curl "http://localhost:8000/api/notary/document/{document_id}/analysis"
```

**Réponse :**
```json
{
  "document_id": "uuid-123",
  "type_detecte": "acte_vente",
  "confiance_classification": 0.95,
  "texte_extrait": "Texte extrait du document...",
  "entites_extraites": {
    "identites": [
      {
        "nom": "DUPONT",
        "prenom": "Jean",
        "type": "vendeur",
        "confidence": 0.9
      }
    ],
    "adresses": [
      {
        "adresse_complete": "123 rue de la Paix, 75001 Paris",
        "type": "bien_vendu",
        "confidence": 0.8
      }
    ],
    "biens": [
      {
        "description": "Appartement 3 pièces",
        "surface": "75m²",
        "prix": "250000€",
        "confidence": 0.9
      }
    ]
  },
  "verifications_externes": {
    "cadastre": {
      "status": "verified",
      "data": {
        "parcelle": "1234",
        "section": "A",
        "surface": "75m²"
      },
      "confidence": 0.9
    },
    "georisques": {
      "status": "verified",
      "data": {
        "risques": [
          {
            "type": "retrait_gonflement_argiles",
            "niveau": "moyen"
          }
        ]
      },
      "confidence": 0.8
    }
  },
  "score_vraisemblance": 0.92,
  "avis_synthese": "Document cohérent et vraisemblable...",
  "recommandations": [
    "Vérifier l'identité des parties",
    "Contrôler la conformité du prix"
  ],
  "timestamp_analyse": "2025-01-09 10:30:00"
}
```

### Interface Web

#### Démarrage
```bash
# Démarrer l'API
cd services/host_api
uvicorn app:app --host 0.0.0.0 --port 8000

# Démarrer l'interface web (dans un autre terminal)
cd services/web_interface
python start_web.py
```

#### Accès
- **Interface Web** : http://localhost:8080
- **API Documentation** : http://localhost:8000/docs
- **API Health** : http://localhost:8000/api/health

## 🔍 Pipeline de Traitement

### 1. Upload et Validation
- Validation du type de fichier
- Génération d'un ID unique
- Sauvegarde du document original

### 2. OCR et Extraction de Texte
- Conversion PDF en images (si nécessaire)
- Amélioration de la qualité d'image
- OCR avec Tesseract (optimisé pour le français)
- Correction lexicale notariale
- Post-traitement du texte

### 3. Classification du Document
- Classification par règles (mots-clés)
- Classification par LLM (Ollama)
- Fusion des résultats
- Validation de cohérence

### 4. Extraction d'Entités
- Extraction par patterns regex
- Extraction par LLM
- Fusion et déduplication
- Classification des entités par type

### 5. Vérifications Externes
- **Cadastre** : Vérification des parcelles
- **Géorisques** : Analyse des risques
- **BODACC** : Vérification des annonces
- **Gel des Avoirs** : Contrôle des sanctions
- **Infogreffe** : Vérification des entreprises
- **RBE** : Bénéficiaires effectifs

### 6. Calcul du Score de Vraisemblance
- Score OCR (qualité de l'extraction)
- Score classification (confiance du type)
- Score entités (complétude et qualité)
- Score vérifications (cohérence externe)
- Score cohérence (règles métier)
- Application de pénalités

### 7. Analyse Contextuelle LLM
- Génération d'un avis de synthèse
- Analyse de cohérence
- Recommandations spécifiques
- Identification des risques

## 🛠️ Configuration Avancée

### Variables d'Environnement

```bash
# Base de données
POSTGRES_USER=notariat
POSTGRES_PASSWORD=notariat_pwd
POSTGRES_DB=notariat

# Redis
REDIS_PASSWORD=

# MinIO
MINIO_ROOT_USER=minio
MINIO_ROOT_PASSWORD=minio_pwd
MINIO_BUCKET=ingest

# Ollama
OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_DEFAULT_MODEL=llama3:8b

# APIs Externes
API_GOUV_KEY=your_api_gouv_key
RBE_API_KEY=your_rbe_key
GEOFONCIER_USERNAME=your_username
GEOFONCIER_PASSWORD=your_password
```

### Modèles LLM

#### Modèles Recommandés
- **llama3:8b** : Équilibré, bon pour la classification
- **mistral:7b** : Rapide, bon pour l'extraction
- **llama3:70b** : Plus précis, nécessite plus de ressources

#### Configuration Ollama
```bash
# Télécharger un modèle
ollama pull llama3:8b

# Vérifier les modèles disponibles
ollama list
```

## 📊 Monitoring et Logs

### Logs
```bash
# Logs de l'API
docker-compose logs -f host-api

# Logs des workers
docker-compose logs -f worker

# Logs de tous les services
make logs
```

### Métriques
- **Temps de traitement** : Moyenne par type de document
- **Taux de réussite** : Pourcentage de documents traités avec succès
- **Qualité OCR** : Confiance moyenne de l'extraction
- **Score de vraisemblance** : Distribution des scores

### Health Checks
```bash
# Statut de l'API
curl http://localhost:8000/api/health

# Statut des services
curl http://localhost:8000/api/notary/stats
```

## 🔒 Sécurité

### Authentification
- JWT tokens pour l'API
- Sessions utilisateur pour l'interface web
- Clés API pour les services externes

### Chiffrement
- TLS pour les communications
- Chiffrement des données sensibles
- Stockage sécurisé des clés

### Conformité
- RGPD : Anonymisation des données
- Audit trail complet
- Rétention des données configurable

## 🚨 Dépannage

### Problèmes Courants

#### OCR de Mauvaise Qualité
```bash
# Vérifier Tesseract
tesseract --version

# Tester l'OCR
tesseract image.png output -l fra
```

#### Erreurs de Classification
```bash
# Vérifier Ollama
curl http://localhost:11434/api/tags

# Tester un modèle
curl http://localhost:11434/api/generate -d '{"model":"llama3:8b","prompt":"Test"}'
```

#### APIs Externes Inaccessibles
```bash
# Tester la connectivité
curl https://apicarto.ign.fr/api/cadastre/parcelle

# Vérifier les clés API
echo $API_GOUV_KEY
```

### Logs de Debug
```python
# Activer les logs détaillés
import logging
logging.basicConfig(level=logging.DEBUG)
```

## 📈 Performance

### Optimisations
- **Cache Redis** : Mise en cache des résultats
- **Traitement parallèle** : Workers multiples
- **Compression** : Images optimisées pour l'OCR
- **Indexation** : Base de données optimisée

### Benchmarks
- **PDF simple** : ~30 secondes
- **PDF complexe** : ~2 minutes
- **Image haute résolution** : ~45 secondes
- **Débit** : ~10 documents/heure (configuration standard)

## 🔄 Mise à Jour

### Mise à Jour du Code
```bash
git pull origin main
pip install -r docker/host-api/requirements.txt
docker-compose down
docker-compose up -d
```

### Mise à Jour des Modèles
```bash
# Nouveau modèle
ollama pull llama3:70b

# Mise à jour de la configuration
export OLLAMA_DEFAULT_MODEL=llama3:70b
```

## 📞 Support

### Documentation
- **API Docs** : http://localhost:8000/docs
- **Code Source** : Repository Git
- **Issues** : git.4nkweb.com Issues

### Contact
- **Email** : support@4nkweb.com
- **Documentation** : docs/README.md

---

**Version** : 1.0.0
**Dernière mise à jour** : 9 janvier 2025
**Auteur** : Équipe 4NK