4NK_IA_back/README.md

# 🏛️ 4NK Notariat - Système de Traitement de Documents Notariaux

## 🎯 Vue d'ensemble

Le système 4NK Notariat est une solution complète d'IA pour le traitement automatisé de documents notariaux. Il combine OCR avancé, classification intelligente, extraction d'entités, vérifications externes et analyse contextuelle via LLM pour fournir aux notaires un outil puissant d'analyse et de validation de documents.

## ✨ Fonctionnalités Principales

### 🔍 **Pipeline de Traitement Avancé**
- **Préprocessing Intelligent** : Validation, conversion et optimisation automatique des documents
- **OCR Avancé** : Extraction de texte avec Tesseract et correction lexicale notariale spécialisée
- **Classification Automatique** : Détection du type de document via LLM (acte de vente, donation, succession, CNI, etc.)
- **Extraction d'Entités** : Identification automatique des identités, adresses, biens, montants, dates
- **Support Multi-format** : PDF, JPEG, PNG, TIFF, HEIC avec conversion automatique
- **Traitement Asynchrone** : Pipeline Celery avec queues spécialisées pour la scalabilité

### 🔗 **Vérifications Externes Automatisées**
- **API Cadastre** : Vérification des parcelles et propriétés immobilières
- **API Géorisques** : Analyse des risques géologiques (inondation, argiles, radon, etc.)
- **API BODACC** : Vérification des annonces légales et entreprises
- **API Infogreffe** : Recherche d'informations d'entreprises
- **API RBE** : Registre des Bénéficiaires Effectifs
- **Géocodage** : Conversion d'adresses en coordonnées GPS

### 🧠 **Intelligence Artificielle Intégrée**
- **LLM Local** : Analyse contextuelle avec Ollama (Llama 3, Mistral)
- **Score de Vraisemblance** : Évaluation automatique basée sur les vérifications externes
- **Indexation Sémantique** : AnythingLLM pour la recherche intelligente
- **Graphe de Connaissances** : Neo4j pour les relations entre entités
- **Recherche Plein-texte** : OpenSearch avec analyseur français

### 🏗️ **Architecture Moderne**
- **API REST** : FastAPI avec documentation automatique
- **Traitement Asynchrone** : Celery avec Redis pour la performance
- **Stockage S3** : MinIO pour la gestion des documents
- **Monitoring** : Prometheus et Grafana pour la supervision
- **Configuration** : Bootstrap automatisé et gestion d'environnement

## 🚀 Démarrage Rapide

### Prérequis
```bash
# Système
- Ubuntu/Debian 20.04+
- Python 3.11+
- Docker & Docker Compose
- 16GB RAM minimum (32GB recommandé pour les modèles LLM)
- 100GB espace disque (pour les modèles et documents)

# Dépendances système
sudo apt-get update
sudo apt-get install -y python3 python3-pip python3-venv docker.io docker-compose
sudo apt-get install -y tesseract-ocr tesseract-ocr-fra poppler-utils imagemagick
sudo apt-get install -y wget curl jq
```

### Installation Automatisée
```bash
# Cloner le repository
git clone https://git.4nkweb.com/4nk/4NK_IA_back.git
cd 4NK_IA_back

# Bootstrap automatique (recommandé)
chmod +x ops/bootstrap.sh
./ops/bootstrap.sh

# Ou installation manuelle
cd infra
# Le fichier .env est créé automatiquement avec les valeurs par défaut
docker compose up -d
```

### Démarrage Rapide
```bash
# 1. Cloner le projet
git clone https://git.4nkweb.com/4nk/4NK_IA_back.git
cd 4NK_IA_back

# 2. Démarrage automatique (recommandé)
./start-stack.sh

# Ou démarrage manuel
cd infra
docker compose up -d

# 3. Vérification
curl http://localhost:8000/api/health
```

### Accès aux Services
- **API Notariale** : http://localhost:8000
- **Documentation API** : http://localhost:8000/docs
- **MinIO Console** : http://localhost:9001
- **PostgreSQL** : localhost:5432
- **Redis** : localhost:6379

## 📋 Types de Documents Supportés

| Type | Description | Entités Extraites |
|------|-------------|-------------------|
| **Acte de Vente** | Vente immobilière | Vendeur, acheteur, bien, prix, adresse |
| **Acte de Donation** | Donation entre vifs | Donateur, donataire, bien, valeur |
| **Acte de Succession** | Succession et notoriété | Héritiers, défunt, biens, parts |
| **CNI** | Carte d'identité | Identité, date de naissance, nationalité |
| **Contrat** | Contrats divers | Parties, obligations, clauses |
| **Autre** | Documents non classés | Entités génériques |

## 🔧 Configuration

### Variables d'Environnement
```bash
# Base de données
POSTGRES_USER=notariat
POSTGRES_PASSWORD=notariat_pwd
POSTGRES_DB=notariat

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

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

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

## 📊 Pipeline de Traitement

```mermaid
graph TD
    A[Upload Document] --> B[Validation Format]
    B --> C[OCR & Extraction Texte]
    C --> D[Classification Document]
    D --> E[Extraction Entités]
    E --> F[Vérifications Externes]
    F --> G[Calcul Score Vraisemblance]
    G --> H[Analyse LLM]
    H --> I[Rapport Final]
```

### Étapes Détaillées

1. **Upload & Validation** : Vérification du format et génération d'un ID unique
2. **OCR** : Extraction de texte avec correction lexicale notariale
3. **Classification** : Détection du type via règles + LLM
4. **Extraction** : Identification des entités (identités, adresses, biens)
5. **Vérifications** : Appels aux APIs externes (Cadastre, Géorisques, etc.)
6. **Score** : Calcul du score de vraisemblance (0-1)
7. **Analyse** : Synthèse contextuelle et recommandations via LLM

## 🛠️ Utilisation

### Interface Web
1. **Upload** : Glissez-déposez votre document
2. **Configuration** : Renseignez les métadonnées (dossier, étude, utilisateur)
3. **Traitement** : Suivez la progression en temps réel
4. **Analyse** : Consultez les résultats et recommandations

### API REST
```bash
# 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"

# Récupération de l'analyse
curl "http://localhost:8000/api/notary/document/{document_id}/analysis"
```

## 📈 Performance

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

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

## 🔒 Sécurité

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

### Conformité
- **RGPD** : Anonymisation des données
- **Audit trail** : Traçabilité complète
- **Rétention** : Gestion configurable des données

## 🚨 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
```bash
# Logs de l'API
tail -f logs/api.log

# Logs des services Docker
docker-compose logs -f

# Logs de tous les services
make logs
```

## 📚 Documentation

- **[API Documentation](docs/API-NOTARIALE.md)** : Documentation complète de l'API
- **[Tests](tests/)** : Suite de tests complète
- **[Configuration](infra/)** : Fichiers de configuration Docker
- **[Interface Web](services/web_interface/)** : Code de l'interface utilisateur

## 🔄 Mise à Jour

```bash
# Mise à jour du code
git pull origin main
pip install -r docker/host-api/requirements.txt

# Redémarrage
./stop_notary_system.sh
./start_notary_system.sh
```

## 📞 Support

### Ressources
- **Documentation** : `docs/` directory
- **Tests** : `tests/` directory
- **Issues** : git.4nkweb.com Issues

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

## 🏗️ Architecture Technique

### Stack Technologique
- **Backend** : FastAPI (Python 3.11+)
- **Frontend** : HTML5, CSS3, JavaScript (Bootstrap 5)
- **Base de données** : PostgreSQL
- **Cache** : Redis
- **Stockage** : MinIO (S3-compatible)
- **LLM** : Ollama (Llama 3, Mistral)
- **OCR** : Tesseract + OpenCV
- **Conteneurisation** : Docker & Docker Compose

### Services
- **host-api** : API principale FastAPI
- **worker** : Tâches de traitement asynchrones
- **postgres** : Base de données relationnelle
- **redis** : Cache et queues
- **minio** : Stockage objet
- **ollama** : Modèles LLM locaux
- **anythingllm** : Interface LLM (optionnel)

## 📊 Monitoring

### Métriques Disponibles
- **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
```

## 🎯 Roadmap

### Version 1.1
- [ ] Support de nouveaux types de documents
- [ ] Amélioration de la précision OCR
- [ ] Intégration de nouvelles APIs externes
- [ ] Interface mobile responsive

### Version 1.2
- [ ] Machine Learning pour l'amélioration continue
- [ ] Support multi-langues
- [ ] Intégration avec les systèmes notariaux existants
- [ ] API GraphQL

---

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

## 🚀 Démarrage Immédiat

```bash
# Cloner et démarrer en une commande
git clone <repository> && cd 4NK_IA && ./start_notary_system.sh
```

**Votre système de traitement de documents notariaux est prêt en quelques minutes !** 🎉