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

# 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

# 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

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 :

{
  "document_id": "uuid-123",
  "status": "queued",
  "message": "Document mis en file de traitement",
  "estimated_processing_time": 120
}

Statut de Traitement

curl "http://localhost:8000/api/notary/document/{document_id}/status"

Réponse :

{
  "document_id": "uuid-123",
  "status": "processing",
  "progress": 45,
  "current_step": "extraction_entites",
  "estimated_completion": 1640995200
}

Analyse Complète

curl "http://localhost:8000/api/notary/document/{document_id}/analysis"

Réponse :

{
  "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

# 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

# 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

# Télécharger un modèle
ollama pull llama3:8b

# Vérifier les modèles disponibles
ollama list

📊 Monitoring et Logs

Logs

# 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

# 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é

# Vérifier Tesseract
tesseract --version

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

Erreurs de Classification

# 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

# Tester la connectivité
curl https://apicarto.ign.fr/api/cadastre/parcelle

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

Logs de Debug

# 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

git pull origin main
pip install -r docker/host-api/requirements.txt
docker-compose down
docker-compose up -d

Mise à Jour des Modèles

# 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 : GitHub Issues

Contact

• Email : support@4nkweb.com
• Documentation : docs/README.md

---

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