anonymisation/.kiro/specs/anonymization-quality-optimization/requirements.md

# Requirements - Optimisation de la Qualité d'Anonymisation

## 1. Contexte et Objectifs

### 1.1 Contexte Métier
Le système d'anonymisation de documents PDF médicaux doit garantir une conformité RGPD stricte tout en préservant la lisibilité des documents pour un usage médical (recherche, formation, archivage).

**Corpus de travail** :
- 59 dossiers OGC (Opération Gros Calibre) dans `/home/dom/Téléchargements/II-1 Ctrl_T2A_2025_CHCB_DocJustificatifs (1)/`
- 130 fichiers PDF déjà anonymisés avec audits `.audit.jsonl` dans le sous-dossier `anonymise/`
- Documents médicaux réels (comptes-rendus hospitaliers, dossiers patients)

### 1.2 Problématique Actuelle
Le système actuel combine **4 couches de détection** :

**1. Extraction multi-passes (5 méthodes)** :
- pdfplumber → pdfminer → PyMuPDF → docTR OCR → tesseract OCR

**2. Détection par regex** :
- EMAIL, TEL, NIR, IBAN, IPP, FINESS, RPPS, OGC, dates, adresses
- Patterns contextuels (Dr., Patient:, etc.)
- Extraction de champs structurés (Trackare)

**3. VLM (Vision Language Model)** :
- Ollama avec qwen2.5vl:7b pour analyse visuelle des PDF scannés
- Détecte 20+ catégories de PII visuellement (manuscrit, mal orienté)
- Matching flou pour identifiants numériques manuscrits
- Masquage total des pages manuscrites (< 100 mots OCR)

**4. NER (Named Entity Recognition)** :
- EDS-Pseudo (AP-HP, F1=0.97) via edsnlp - 13 labels
- Fallback CamemBERT-NER ONNX
- Appliqué sur le narratif après regex

**5. Consolidation globale** :
- Propagation des PII sur toutes les pages
- Détection de "noms compagnons" (mots adjacents)
- Rescan sélectif des PII critiques

**Problèmes identifiés** :
- Faux négatifs (PII non détectés) → Risque RGPD critique
- Faux positifs (termes médicaux masqués) → Documents illisibles
- Pas de métriques de qualité mesurables
- Pas de validation post-anonymisation
- Pas de ground truth pour évaluer les performances
- VLM peut halluciner sur pages manuscrites complexes
- Pas d'optimisation GPU pour le VLM (Ollama local)

### 1.3 Objectifs de Qualité

**Objectif principal** : Équilibre optimal entre rappel et précision

**Métriques cibles** :
- **Rappel (Recall)** : ≥ 99.5% (maximum 0.5% de PII manqués)
- **Précision (Precision)** : ≥ 97% (maximum 3% de faux positifs)
- **F1-Score** : ≥ 0.98
- **Taux de documents sûrs** : ≥ 98% (documents avec 0 faux négatif)

**Contraintes matérielles** :
- **CPU** : AMD Ryzen 9 9950X (16 cœurs / 32 threads) - Excellent pour parallélisation
- **RAM** : 128 GB - Aucune contrainte mémoire
- **GPU** : NVIDIA GeForce RTX 5070 (12 GB VRAM) - Accélération NER possible
- **CUDA** : PyTorch 2.10.0 avec CUDA disponible
- Temps de traitement cible : < 10 secondes par PDF (avec GPU)

---

## 2. Exigences Fonctionnelles

### 2.1 Création d'un Dataset de Test Annoté

**REQ-001 : Annotation Manuelle de Documents Réels**
- **Priorité** : CRITIQUE
- **Description** : Créer un corpus de test avec annotations manuelles des PII sur les documents réels existants
- **Critères d'acceptation** :
  - Minimum 30 documents PDF annotés (représentatifs des 59 dossiers OGC)
  - Annotations au format JSON structuré
  - Chaque PII annoté avec : type, texte, page, bbox, contexte, criticité
  - Distinction entre PII obligatoires (RGPD) et optionnels
  - Termes médicaux à préserver explicitement listés
- **Contraintes** :
  - Utiliser uniquement les documents réels du corpus existant
  - Pas de données synthétiques ou mockées
  - Annotations validées par au moins 2 personnes (inter-annotator agreement)

**REQ-002 : Structure du Dataset de Test**
- **Priorité** : CRITIQUE
- **Description** : Organiser le dataset de test de manière exploitable
- **Critères d'acceptation** :
  ```
  tests/ground_truth/
  ├── pdf_001.pdf                    # PDF original
  ├── pdf_001.annotations.json       # Annotations manuelles
  ├── pdf_002.pdf
  ├── pdf_002.annotations.json
  └── ...
  ```
  - Format d'annotation standardisé et documenté
  - Métadonnées : difficulté, type de document, nombre de pages
  - Répartition équilibrée : documents simples, moyens, complexes

---

### 2.2 Système d'Évaluation de la Qualité

**REQ-003 : Évaluateur Automatique**
- **Priorité** : CRITIQUE
- **Description** : Outil d'évaluation comparant les détections avec les annotations manuelles
- **Critères d'acceptation** :
  - Calcul automatique de : Précision, Rappel, F1-Score
  - Identification des faux négatifs (PII manqués) avec contexte
  - Identification des faux positifs (sur-détection) avec contexte
  - Rapport détaillé par type de PII (NOM, TEL, EMAIL, etc.)
  - Rapport détaillé par document
  - Export des résultats en JSON et HTML

**REQ-004 : Scanner de Fuite de PII**
- **Priorité** : CRITIQUE
- **Description** : Vérifier qu'aucun PII ne subsiste dans les PDF anonymisés
- **Critères d'acceptation** :
  - Extraction du texte du PDF anonymisé (OCR si nécessaire)
  - Détection de PII résiduels (regex + NER)
  - Vérification que les PII originaux ne sont plus présents
  - Scan des métadonnées PDF (author, creator, etc.)
  - Rapport de fuite avec niveau de sévérité (CRITIQUE, HAUTE, MOYENNE)
  - Validation : document sûr = 0 fuite détectée

**REQ-005 : Benchmark de Performance**
- **Priorité** : HAUTE
- **Description** : Mesurer les performances du système actuel et des améliorations
- **Critères d'acceptation** :
  - Temps de traitement par document
  - Temps de traitement par page
  - Utilisation CPU/RAM
  - Métriques de qualité (Précision, Rappel, F1)
  - Comparaison avant/après optimisation
  - Export des résultats en format tabulaire

---

### 2.3 Amélioration de la Détection

**REQ-006 : Amélioration des Regex**
- **Priorité** : HAUTE
- **Description** : Renforcer les regex pour réduire les faux négatifs
- **Critères d'acceptation** :
  - Téléphones fragmentés sur plusieurs lignes détectés
  - Emails avec domaines médicaux (chu-, aphp-, etc.) détectés
  - Adresses avec compléments (Bât., Appt., etc.) détectées
  - NIR avec espaces variables détectés
  - Noms avec caractères spéciaux (O'Brien, D'Angelo, Müller) détectés
  - Tests unitaires exhaustifs pour chaque regex (≥ 20 cas par pattern)

**REQ-007 : Détection Contextuelle Renforcée**
- **Priorité** : HAUTE
- **Description** : Améliorer la détection des noms par analyse contextuelle
- **Critères d'acceptation** :
  - Détection des noms après "Dr.", "Pr.", "Patient:", etc.
  - Détection des noms en MAJUSCULES (hors termes médicaux)
  - Détection des noms dans les listes virgulées ("Dr. X, Y, DUPONT")
  - Détection des noms du personnel ("Aide : Marie-Paule BORDABERRY")
  - Filtrage des faux positifs via liste de stopwords médicaux enrichie
  - Niveau de confiance associé à chaque détection

**REQ-008 : Approche Hybride Multi-Détecteurs**
- **Priorité** : HAUTE
- **Description** : Combiner plusieurs méthodes de détection en cascade
- **Critères d'acceptation** :
  - Pipeline en 5 étapes : Regex → VLM (si scanné) → EDS-Pseudo → CamemBERT-NER → Contextuel
  - Masquage progressif pour éviter les doublons
  - Fusion intelligente des résultats (dédoplication, résolution de conflits)
  - Traçabilité : chaque PII détecté indique la méthode de détection (REGEX, VLM, EDS, NER, CONTEXT)
  - Configuration activable/désactivable par méthode
  - VLM appliqué uniquement sur PDFs scannés (ocr_used=True)
  - Gestion des pages manuscrites (masquage total si < 100 mots OCR)

---

### 2.4 Validation et Reporting

**REQ-009 : Validation Post-Anonymisation**
- **Priorité** : CRITIQUE
- **Description** : Valider automatiquement chaque document anonymisé
- **Critères d'acceptation** :
  - Exécution automatique après chaque anonymisation
  - Scan de fuite de PII (texte + métadonnées)
  - Vérification de la lisibilité (pas trop de masquage)
  - Génération d'un certificat de conformité si validation OK
  - Blocage de la sortie si fuite détectée (mode strict)

**REQ-010 : Rapport de Qualité Détaillé**
- **Priorité** : HAUTE
- **Description** : Générer un rapport de qualité pour chaque batch traité
- **Critères d'acceptation** :
  - Statistiques globales : nombre de documents, PII détectés, temps total
  - Métriques de qualité : Précision, Rappel, F1-Score
  - Liste des faux négatifs (si dataset annoté disponible)
  - Liste des faux positifs (si dataset annoté disponible)
  - Répartition des PII par type (graphique)
  - Export HTML + JSON

---

### 2.5 Amélioration Continue

**REQ-011 : Tests de Régression Automatiques**
- **Priorité** : HAUTE
- **Description** : Suite de tests automatiques pour éviter les régressions
- **Critères d'acceptation** :
  - Exécution sur le dataset de test annoté
  - Vérification que les métriques ne se dégradent pas
  - Alerte si Rappel < 99.5% ou Précision < 97%
  - Intégration possible en CI/CD
  - Temps d'exécution < 10 minutes

**REQ-013 : Optimisation et Validation du VLM**
- **Priorité** : HAUTE
- **Description** : Améliorer la fiabilité et les performances du VLM pour les PDF scannés
- **Critères d'acceptation** :
  - Prompt VLM optimisé pour réduire les hallucinations
  - Validation croisée VLM ↔ NER (rejeter si conflit majeur)
  - Seuil de confiance configurable (défaut: 0.5)
  - Gestion intelligente des pages manuscrites (seuil OCR configurable)
  - Timeout configurable (défaut: 180s)
  - Métriques spécifiques VLM : taux d'hallucination, temps par page
  - Support GPU pour Ollama si disponible
  - Fallback gracieux si Ollama indisponible

**REQ-014 : Amélioration du Matching Flou VLM**
- **Priorité** : MOYENNE
- **Description** : Améliorer le matching des identifiants numériques manuscrits détectés par le VLM
- **Critères d'acceptation** :
  - Matching flou basé sur séquences de chiffres (ratio configurable, défaut: 0.7)
  - Support des identifiants partiellement lisibles
  - Validation par distance de Levenshtein pour les noms
  - Tests unitaires avec identifiants manuscrits réels

---

## 3. Exigences Non-Fonctionnelles

### 3.1 Performance

**NFR-001 : Temps de Traitement**
- Temps de traitement : < 10 secondes par PDF (moyenne) avec GPU
- Temps de traitement : < 2 secondes par page avec GPU
- Temps de traitement : < 30 secondes par PDF en mode CPU-only (fallback)
- Pas de dégradation > 20% par rapport à la version actuelle

**NFR-002 : Utilisation des Ressources**
- Utilisation GPU : Accélération CUDA pour les modèles NER (EDS-Pseudo, CamemBERT)
- Utilisation RAM : < 32 GB par processus (128 GB disponibles)
- Utilisation VRAM : < 10 GB (12 GB disponibles sur RTX 5070)
- Support du traitement par lots (batch) avec parallélisation sur 16 cœurs CPU
- Traitement parallèle de plusieurs PDFs simultanément (jusqu'à 8 workers)

### 3.2 Maintenabilité

**NFR-003 : Code Qualité**
- Code modulaire et testable
- Couverture de tests : ≥ 80% pour les fonctions critiques
- Documentation des fonctions (docstrings)
- Type hints Python partout

**NFR-004 : Configuration**
- Configuration externalisée (YAML)
- Activation/désactivation des détecteurs par configuration
- Seuils de confiance configurables
- Pas de valeurs en dur dans le code

### 3.3 Sécurité et Conformité

**NFR-005 : Conformité RGPD**
- Aucun PII ne doit fuiter (rappel ≥ 99.5%)
- Traçabilité complète (audit trail)
- Validation post-anonymisation obligatoire
- Métadonnées PDF nettoyées

**NFR-006 : Sécurité des Données**
- Pas de transmission de données vers des services externes
- Traitement local uniquement
- Pas de logs contenant des PII
- Suppression sécurisée des fichiers temporaires

---

## 4. Critères de Succès

### 4.1 Critères Quantitatifs

**Métriques de qualité** :
- ✅ Rappel ≥ 99.5% sur le dataset de test
- ✅ Précision ≥ 97% sur le dataset de test
- ✅ F1-Score ≥ 0.98 sur le dataset de test
- ✅ Taux de documents sûrs ≥ 98%

**Métriques de performance** :
- ✅ Temps de traitement < 30s par PDF
- ✅ Utilisation RAM < 4 GB
- ✅ Pas de dégradation > 20% vs version actuelle

### 4.2 Critères Qualitatifs

- ✅ Dataset de test annoté créé (≥ 30 documents)
- ✅ Système d'évaluation automatique fonctionnel
- ✅ Scanner de fuite opérationnel
- ✅ Tests de régression en place
- ✅ Documentation complète

### 4.3 Validation Finale

**Test d'acceptation** :
1. Exécuter le système sur les 59 dossiers OGC complets
2. Valider que 0 fuite critique n'est détectée
3. Vérifier que les documents restent lisibles (validation manuelle sur échantillon)
4. Comparer les métriques avec la baseline actuelle
5. Validation par un expert médical (échantillon de 10 documents)

---

## 5. Contraintes et Risques

### 5.1 Contraintes

**Contraintes techniques** :
- GPU NVIDIA RTX 5070 avec CUDA disponible (accélération recommandée)
- Fallback CPU si GPU indisponible
- RAM abondante (128 GB) - pas de contrainte mémoire
- Pas de dépendances externes nécessitant internet en production

**Contraintes métier** :
- Utilisation de documents réels uniquement (pas de mocks)
- Conformité RGPD stricte
- Préservation de la lisibilité médicale

### 5.2 Risques

| Risque | Probabilité | Impact | Mitigation |
|--------|-------------|--------|------------|
| Annotation manuelle trop longue | HAUTE | MOYEN | Prioriser 30 documents représentatifs, automatiser partiellement |
| Faux négatifs résiduels | MOYENNE | CRITIQUE | Validation post-anonymisation obligatoire, scanner de fuite |
| Dégradation des performances | FAIBLE | MOYEN | Benchmark continu, optimisation GPU, parallélisation |
| Sur-masquage (trop de faux positifs) | MOYENNE | MOYEN | Enrichissement liste stopwords, validation manuelle échantillon |
| Saturation VRAM GPU | FAIBLE | FAIBLE | Batch sizing dynamique, fallback CPU si nécessaire |

---

## 6. Dépendances et Prérequis

### 6.1 Dépendances Techniques

**Existantes** :
- Python 3.12
- **VLM** : Ollama (qwen2.5vl:7b ou qwen3-vl:8b) - analyse visuelle
- **NER** : EDS-Pseudo (AP-HP/eds-pseudo-public) via edsnlp
- **NER fallback** : CamemBERT-NER (Jean-Baptiste/camembert-ner) ONNX
- **OCR** : docTR (deep learning) + tesseract (fallback)
- **PDF** : PyMuPDF, pdfplumber, pdfminer.six
- **Runtime** : ONNX Runtime, transformers, optimum

**Nouvelles** :
- `pytest` (tests)
- `pytest-cov` (couverture)
- `pydantic` (validation config)
- `structlog` (logging structuré)
- `jinja2` (rapports HTML)
- `matplotlib` ou `plotly` (graphiques)

### 6.2 Données Requises

- ✅ 59 dossiers OGC existants
- ✅ 130 fichiers anonymisés + audits existants
- ⏳ 30 documents annotés manuellement (à créer)
- ⏳ Liste enrichie de stopwords médicaux (à compléter)

---

## 7. Livrables Attendus

1. **Dataset de test annoté** (30+ documents)
2. **Système d'évaluation automatique** (évaluateur + scanner + benchmark)
3. **Détecteurs améliorés** (regex + contextuel + hybride)
4. **Suite de tests de régression**
5. **Rapports de qualité** (HTML + JSON)
6. **Documentation** (guide d'utilisation, guide d'annotation)
7. **Métriques de baseline** (avant optimisation)
8. **Métriques finales** (après optimisation)

---

## 8. Planning Indicatif

**Phase 1 - Mesure (2 semaines)** :
- Création dataset annoté (30 docs)
- Système d'évaluation
- Métriques baseline

**Phase 2 - Amélioration (3 semaines)** :
- Amélioration regex
- Détection contextuelle
- Approche hybride

**Phase 3 - Validation (1 semaine)** :
- Tests de régression
- Validation sur corpus complet
- Documentation

**Total** : 6 semaines