docs/reference/normalization-profiles.md

Profils de calcul — chantier 2 post-Sprint 97

Picarones expose 7 profils de calcul qui modulent les métriques calculées par le runner selon le use case. Chaque profil active un sous-ensemble des 12 hooks document-level et 12 agrégateurs corpus-level du registre central (picarones/evaluation/metric_hooks.py).

Synoptique

Profil	Hooks doc	Cible	CLI dédiée
minimal	0	Tests rapides, bench massif (CER/WER seuls)	—
standard (défaut)	12	Comportement historique, rétrocompat	picarones run
philological	12	Édition critique, paléographie	picarones edition
diagnostics	12	Comprendre pourquoi un moteur produit ses résultats	picarones diagnose
economics	12	Décision budget : pages/h utilisable, coût marginal	picarones economics
pipeline	12	Bench de pipelines composées (axe B)	picarones pipeline run
full	12	R&D — tout ce qui peut être calculé	—

Note rétrocompat : aujourd'hui les profils philological, diagnostics, economics, pipeline et full activent le même ensemble que standard côté hooks calculés. Ce qui change, c'est la vue HTML rendue : chaque profil active des sous-sections différentes du rapport (cf. docs/reference/views.md). Les profils sont volontairement génériques pour permettre aux contributeurs futurs d'ajouter des hooks spécifiques sans casser l'API.

Détail des hooks par profil

minimal

Aucun hook. Le runner calcule uniquement les métriques de base (cer, wer, mer, wil via compute_metrics). Les DocumentResult n'ont aucun champ confusion_matrix, taxonomy, calibration, etc.

Cas d'usage : bench de régression sur 10 000 documents pour mesurer le CER d'une mise à jour de modèle, sans avoir besoin du diagnostic philologique. Réduit drastiquement le temps de calcul (∼5× plus rapide).

picarones run --corpus ./corpus --profile minimal

standard (défaut)

Active les 12 hooks document-level historiques :

Hook	Sprint	Champ DocumentResult	Notes
confusion	5	confusion_matrix	Matrice unicode
char_scores	5	char_scores	Ligatures + diacritiques
taxonomy	5	taxonomy	9 classes d'erreurs
structure	5	structure	Lignes / blocs / mots
image_quality	5	image_quality	Contraste, bruit, flou…
line_metrics	10	line_metrics	Distribution CER + Gini
hallucination	10	hallucination_metrics	Détection VLM
calibration	42	calibration_metrics	ECE/MCE (si confidences)
philological	61	philological_metrics	6 modules (Sprints 55-60)
searchability	86	searchability_metrics	Fuzzy recall (Sprint 84)
numerical_sequences	86	numerical_sequence_metrics	Sprint 85
readability	87	readability_metrics	Δ Flesch (Sprint 52)

12 agrégateurs corpus-level correspondants remplissent les attributs aggregated_* de chaque EngineReport.

philological (édition critique)

Active les 12 hooks standard + déclenchera (chantiers futurs) l'enrichissement par des hooks dédiés à la paléographie médiévale, l'imprimé ancien et les archives modernes (déjà calculés via le module philological du standard, mais valorisés différemment dans la vue HTML « Taxonomie avancée »).

picarones edition --corpus ./manuscrits --engines tesseract,pero_ocr

Vue HTML supplémentaire activée : view_advanced_taxonomy.html avec diagramme miroir leader vs runner-up, classes par récupérabilité éditoriale.

diagnostics (analyse approfondie)

Identique à standard côté hooks. Déclenche la vue HTML « Diagnostic approfondi » avec leviers d'amélioration factuels (jamais prescriptifs) calculés par picarones.domain.levers.detect_levers().

picarones diagnose --corpus ./corpus --engines tess,pero

Vue HTML supplémentaire : view_diagnostics.html avec :

• Leviers d'amélioration (dominant_recoverable_class, pareto_concentration, etc.).
• Profil d'image du corpus (complexité paléographique + homogénéité, opt-in).
• Comparaison historique (baseline, opt-in si historique SQLite).

economics (décision budget)

Active la vue HTML « Coût et performance » avec throughput effectif calculé selon la formule HTR-United (5 s/erreur de correction humaine). Discrimine entre un moteur cloud rapide mais imprécis (drag élevé) et un local lent mais fiable.

picarones economics --corpus ./corpus --engines mistral_ocr,tesseract

pipeline (axe B)

Profil utilisé par picarones pipeline run pour les benchmarks de pipelines composées (Sprints 32-34, 53-54, 63-68, 94-97 + chantier 1). La vue HTML produite contient le DAG visuel de la pipeline, l'absorption d'erreur par jonction, et la comparaison incrémentale par slot.

picarones pipeline run examples/pipelines/ocr_to_alto.yaml --corpus DIR

full

Active tous les hooks et toutes les vues. Coût maximal mais reproductibilité scientifique maximale.

Comment ajouter un hook personnalisé

Voir docs/explanation/narrative-engine.md pour le détail. Pattern de base :

from picarones.evaluation.metric_hooks import (
    register_document_metric, PROFILE_DIAGNOSTICS, PROFILE_FULL,
)

@register_document_metric(
    name="my_metric",
    attribute="my_metric",       # nom du champ DocumentResult
    profiles=(PROFILE_DIAGNOSTICS, PROFILE_FULL),
    requires_success=True,
)
def my_hook(*, ground_truth, hypothesis, image_path, corpus_lang, ocr_result):
    from my_module import compute_my_metric
    return compute_my_metric(ground_truth, hypothesis)

Code source

• picarones/evaluation/metric_hooks.py — registre, profils, run_document_hooks(), run_corpus_aggregators().
• picarones/evaluation/metrics/builtin_hooks.py — les 12 hooks doc + 12 agrégateurs natifs Picarones.
• tests/test_metric_hooks.py — tests unitaires + rétrocompat profil standard.