Data Cleaner

Data Cleaner Agent — Nettoyage & Structuration

Principes fondamentaux

1. Jamais modifier en place — créer colonne/table temporaire, valider, puis remplacer
2. Idempotent — chaque opération relançable sans effet de bord
3. Traçable — loguer chaque transformation (avant/après, nb lignes)
4. Batch first — jamais de row-by-row, toujours UPDATE ... FROM ou COPY
5. Valider avant d'écrire — Zod (TS) ou Pydantic (Python) sur chaque output

Workflow en 6 étapes

1. Audit de qualité (diagnostic)

Avant toute action, mesurer l'état actuel. Voir references/audit-template.md.

2. Déduplication

Ordre de priorité :

1. Doublons exacts — GROUP BY toutes colonnes, garder min(id)
2. Doublons sémantiques — normaliser puis dédupliquer ("Assoc." = "Association")
3. Doublons fuzzy — pg_trgm similarity seuil 0.8

DELETE FROM table a USING table b
WHERE a.col1 = b.col1 AND a.col2 = b.col2 AND a.id > b.id;

3. Normalisation textuelle

Appliquer dans cet ordre :

1. trim(both from col)
2. regexp_replace(col, '\s+', ' ', 'g') (collapse spaces)
3. NFD unicode normalization (pour index de recherche)
4. upper() pour codes, initcap() pour noms propres
5. regexp_replace(col, '[\x00-\x1F]', '', 'g') (caractères de contrôle)

4. Mapping référentiels

Toujours via tables de mapping statiques. Voir references/referentiels.md.

5. Validation des formats

-- Identifier invalides AVANT correction
SELECT siren, count(*) FROM table WHERE siren !~ '^\d{9}$' GROUP BY siren;

6. Enrichissement croisé

Après nettoyage, croiser les sources pour combler les trous. Voir references/enrichissement.md.

Anti-patterns

• UPDATE sans WHERE
• DELETE sans backup (CREATE TABLE backup AS SELECT * FROM ...)
• Regex trop permissives — valider sur échantillon 100 lignes
• Normalisation destructive — garder colonne originale, créer colonne _clean
• Import sans staging table temporaire

Métriques à reporter

[CLEAN] table.col : X lignes modifiées / Y total (Z%)
[DEDUP] table : X doublons supprimés (Y restants)
[VALID] table.col : X invalides (patterns: ...)
[ENRICH] table.col : X valeurs comblées depuis source Y

Libs déterministes (pallier l'imprévisibilité LLM)

Toujours préférer un script déterministe à une réponse LLM pour les transformations de données.

Validation (exécuter scripts/validate_column.py)

# Valider SIREN
python3 scripts/validate_column.py dl_entities siren --type siren

# Valider avec regex custom
python3 scripts/validate_column.py dl_entities "nafCode" --pattern '^\d{2}\.\d{2}[A-Z]$'

Python — libs fiables (pip install)

TypeScript — libs fiables (pnpm add)

PostgreSQL — extensions utiles

Pattern : script > LLM

Pour chaque opération de nettoyage, l'agent doit :

1. Écrire un script Python/SQL déterministe
2. Le tester sur un échantillon (LIMIT 100)
3. Vérifier le résultat avec validate_column.py
4. Appliquer en batch sur la table complète
5. Reporter les métriques [CLEAN] [DEDUP] [VALID] [ENRICH]

Ne jamais laisser le LLM "deviner" une transformation — toujours coder un script reproductible.