# Procédure d'extraction — gazetteer paranames

## Vue d'ensemble

Le script `scripts/build_paranames_gazetteer.py` télécharge le dataset
paranames depuis HuggingFace, filtre les entités de type PER, normalise
les noms (NFKD UPPERCASE A-Z) et produit deux gazetteers compressés.

## Pré-requis

- Python ≥ 3.10
- Venv du projet activé : `source .venv/bin/activate`
- Paquets : `datasets`, `huggingface_hub`, `pyarrow`, `pandas`
  (déjà présents dans `requirements.txt`).
- Connexion réseau pour le premier téléchargement (~1.33 GB).
- ~3 GB de cache HuggingFace disponibles.
- ~1 GB de RAM (le script lit le parquet par batches de 64 K lignes).

## Lancement

```bash
cd /home/dom/ai/anonymisation
source .venv/bin/activate
python scripts/build_paranames_gazetteer.py
```

Options :
- `--hf-cache /chemin` : forcer un cache custom (défaut : `~/.cache/huggingface`).
- `--limit N` : ne traiter que N lignes (debug uniquement).

## Étapes internes du script

1. **Téléchargement** via `huggingface_hub.hf_hub_download` du parquet
   `data/train.parquet` du repo `imvladikon/paranames`. Le cache HF est
   réutilisé (idempotent).
2. **Chargement** du BDPM stop-words (`data/bdpm/medicaments_stopwords.txt`,
   7 312 tokens normalisés en UPPER A-Z) pour filtrer les noms qui sont en
   fait des médicaments.
3. **Itération par batches** (`pyarrow.parquet.ParquetFile.iter_batches`)
   sur les colonnes `name` et `type` uniquement. Filtre `type == "PER"`.
4. **Split** de chaque `name` sur espaces et séparateurs courants
   (`SPLIT_CHARS`).
5. **Heuristique nom/prénom** :
   - dernier token → **nom de famille candidat**
   - tokens précédents → **prénoms candidats**
   - cas mononyme (1 seul token) : considéré comme nom de famille.
6. **Normalisation** : NFKD → strip diacritiques → UPPER → conserver
   uniquement A-Z (chars latins de base).
7. **Filtres anti-bruit** :
   - longueur ≥ 3 caractères
   - longueur ≤ 25 caractères
   - non présent dans la BDPM stop-words.
8. **Écriture** triée alphabétique en `.txt.gz` compresslevel=9.

## Volumes attendus (ordre de grandeur)

- Lignes parquet totales : ~124 M
- Lignes PER après filtre : ~82 M
- Noms famille uniques (après dédup + normalisation) : quelques centaines
  de milliers à quelques millions.
- Prénoms uniques : idem.

## Régénération (mise à jour)

Si une nouvelle version de paranames est publiée, supprimer le cache HF
correspondant :

```bash
rm -rf ~/.cache/huggingface/datasets--imvladikon--paranames/
python scripts/build_paranames_gazetteer.py
```

ou supprimer simplement les `.txt.gz` cibles et relancer (le download
réutilise le cache si la version est inchangée).

## Vérification rapide

```bash
zcat data/paranames/noms_famille_world.txt.gz | wc -l
zcat data/paranames/prenoms_world.txt.gz   | wc -l
zcat data/paranames/noms_famille_world.txt.gz | grep -E "^(OYARCABAL|EJNAINI|NGUYEN|SCHMIDT|OBAMA)$"
```

## Licence

paranames est sous **CC BY 4.0**. Les fichiers dérivés (`*.txt.gz`)
héritent de cette licence et doivent être redistribués avec attribution
(voir README.md).