feat(6-volet1): pipelines/over_normalization.py → evaluation/metrics/

Phase 6 volet 1 — la détection de sur-normalisation LLM (classe 10
de la taxonomie d'erreurs) est relocalisée depuis ``pipelines/``
vers la couche canonique ``evaluation/metrics/``.

Le module est pur Python (juste ``dataclass`` + ``Optional``) —
aucune dépendance externe, donc 100 % compatible avec la whitelist
d'imports d'``evaluation/``.

Modifications
-------------
- Création de ``picarones/evaluation/metrics/over_normalization.py``
(121 LOC, copie identique du legacy + en-tête Phase 6).
- ``picarones/pipelines/over_normalization.py`` réduit à un shim
de 30 lignes avec ``DeprecationWarning`` à l'import et
ré-export explicite de ``OverNormalizationResult``,
``detect_over_normalization``, ``aggregate_over_normalization``.
- ``picarones/fixtures.py`` (1 import) : caller migré vers le
canonique.
- ``picarones/measurements/runner/document.py`` (1 import lazy) :
caller migré.
- ``picarones/evaluation/metrics/taxonomy.py`` : référence dans
la docstring mise à jour (``pipelines/`` → ``evaluation/metrics/``).
- ``tests/engines/test_sprint3_llm_pipelines.py`` : 5 imports
migrés vers le canonique (les tests ``OCRLLMPipeline`` du même
fichier restent inchangés — ils relèvent du volet 2).

Architecture
------------
- ``BOOTSTRAP_BASELINE`` de
``tests/architecture/test_legacy_canonical_parity.py`` abaissé
de 104 à 101 (3 symboles publics sortent de la dette : la
``OverNormalizationResult`` et les 2 fonctions module-level).

Volet 2 reporté
---------------
La migration de ``pipelines/base.OCRLLMPipeline`` vers des
``PipelineSpec`` YAML composés reste à faire (3 modes,
``inputs_from`` cross-step, refactor de ``web/benchmark_utils.py``
+ ``measurements/runner/orchestration.py``). Le plan maître estime
3-5 jours d'effort — sortira d'un commit séparé sous ``6-volet2``.

Bilan
-----
- ``pytest tests/`` : 4715 passed, 0 failed.
- ``ruff check`` : clean.
- 1 fichier canonique créé, 5 callers migrés, 1 shim conservé.

https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP

picarones/evaluation/metrics/over_normalization.py

@@ -0,0 +1,128 @@
+"""Détection de la sur-normalisation LLM — Classe 10 de la taxonomie des erreurs.
+
+Phase 6 (mai 2026) — module relocalisé depuis
+``picarones/pipelines/over_normalization.py`` vers
+``picarones/evaluation/metrics/over_normalization.py``.
+
+Le shim ``pipelines/over_normalization.py`` reste exécutable le temps
+que les callers externes migrent ; il sera supprimé en 2.0.
+
+La sur-normalisation désigne le cas où le LLM « corrige » à tort des passages
+déjà bien transcrits par l'OCR, en particulier :
+- modernisation de graphies médiévales légitimes (nostre → notre, faict → fait)
+- normalisation de variantes orthographiques historiques authentiques
+- modification de noms propres ou de termes rares sans erreur OCR initiale
+
+Mesure :
+    score = nombre de mots (OCR correct → LLM modifié) / nombre de mots OCR corrects
+
+Un score élevé indique que le prompt doit être affiné pour mieux préserver
+la graphie originale.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class OverNormalizationResult:
+    """Résultat de la détection de sur-normalisation pour un document."""
+
+    total_correct_ocr_words: int
+    over_normalized_count: int
+    over_normalized_passages: list[dict] = field(default_factory=list)
+    # Chaque entrée : {"gt": str, "ocr": str, "llm": str}
+
+    @property
+    def score(self) -> float:
+        """Score de sur-normalisation entre 0 (aucune dégradation) et 1 (tout dégradé)."""
+        if self.total_correct_ocr_words == 0:
+            return 0.0
+        return round(self.over_normalized_count / self.total_correct_ocr_words, 4)
+
+    def as_dict(self) -> dict:
+        return {
+            "score": self.score,
+            "total_correct_ocr_words": self.total_correct_ocr_words,
+            "over_normalized_count": self.over_normalized_count,
+            "over_normalized_passages": self.over_normalized_passages[:20],
+        }
+
+
+def detect_over_normalization(
+    ground_truth: str,
+    ocr_text: str,
+    llm_text: str,
+    *,
+    max_examples: int = 20,
+) -> OverNormalizationResult:
+    """Détecte la sur-normalisation LLM au niveau des mots.
+
+    Algorithme (alignement positionnel simple, adapté aux textes courts) :
+    Pour chaque position i dans min(len(GT), len(OCR), len(LLM)) :
+      - Si ocr[i] == gt[i]  → le mot était correct dans l'OCR
+      - Si llm[i] != gt[i]  → le LLM a dégradé ce mot correct → sur-normalisation
+
+    Parameters
+    ----------
+    ground_truth:
+        Transcription de référence.
+    ocr_text:
+        Sortie brute du moteur OCR (avant correction LLM).
+    llm_text:
+        Sortie après correction par le LLM.
+    max_examples:
+        Nombre maximal d'exemples de sur-normalisation conservés.
+
+    Returns
+    -------
+    OverNormalizationResult
+    """
+    gt_words = ground_truth.split()
+    ocr_words = ocr_text.split()
+    llm_words = llm_text.split()
+
+    n = min(len(gt_words), len(ocr_words), len(llm_words))
+
+    correct_ocr = 0
+    over_norm = 0
+    passages: list[dict] = []
+
+    for i in range(n):
+        gt_w = gt_words[i]
+        ocr_w = ocr_words[i]
+        llm_w = llm_words[i]
+
+        if ocr_w == gt_w:
+            correct_ocr += 1
+            if llm_w != gt_w and len(passages) < max_examples:
+                over_norm += 1
+                passages.append({"gt": gt_w, "ocr": ocr_w, "llm": llm_w})
+            elif llm_w != gt_w:
+                over_norm += 1
+
+    return OverNormalizationResult(
+        total_correct_ocr_words=correct_ocr,
+        over_normalized_count=over_norm,
+        over_normalized_passages=passages,
+    )
+
+
+def aggregate_over_normalization(results: list[Optional[OverNormalizationResult]]) -> dict:
+    """Agrège les résultats de sur-normalisation sur un ensemble de documents."""
+    valid = [r for r in results if r is not None]
+    if not valid:
+        return {"score": None, "total_correct_ocr_words": 0, "over_normalized_count": 0}
+
+    total_correct = sum(r.total_correct_ocr_words for r in valid)
+    total_over = sum(r.over_normalized_count for r in valid)
+    score = round(total_over / total_correct, 4) if total_correct > 0 else 0.0
+
+    return {
+        "score": score,
+        "total_correct_ocr_words": total_correct,
+        "over_normalized_count": total_over,
+        "document_count": len(valid),
+    }

picarones/evaluation/metrics/taxonomy.py

@@ -14,9 +14,9 @@ la taxonomie Picarones :
 | 7      | segmentation_error| Fusion ou fragmentation de tokens (mots/lignes)    |
 | 8      | oov_character     | Caractère hors-vocabulaire du moteur               |
 | 9      | lacuna            | Texte présent dans le GT absent de l'OCR           |
-| 10     | over_normalization| Sur-normalisation LLM (voir pipelines/)            |
+| 10     | over_normalization| Sur-normalisation LLM (voir evaluation/metrics/)   |
 
-Note : la classe 10 est calculée par picarones/pipelines/over_normalization.py.
+Note : la classe 10 est calculée par picarones/evaluation/metrics/over_normalization.py.
 """
 
 from __future__ import annotations

picarones/fixtures.py

@@ -15,7 +15,7 @@ import zlib
 
 from picarones.evaluation.metric_result import MetricsResult
 from picarones.evaluation.benchmark_result import BenchmarkResult, DocumentResult, EngineReport
-from picarones.pipelines.over_normalization import detect_over_normalization
+from picarones.evaluation.metrics.over_normalization import detect_over_normalization
 # Sprint 5 — métriques avancées
 from picarones.evaluation.metrics.confusion import build_confusion_matrix
 from picarones.evaluation.metrics.char_scores import compute_ligature_score, compute_diacritic_score

picarones/measurements/runner/document.py

@@ -101,7 +101,7 @@ def _compute_document_result(
         }
         if ocr_intermediate is not None and ocr_result.success:
             try:
-                from picarones.pipelines.over_normalization import detect_over_normalization
+                from picarones.evaluation.metrics.over_normalization import detect_over_normalization
                 over_norm = detect_over_normalization(
                     ground_truth=ground_truth,
                     ocr_text=ocr_intermediate,

picarones/pipelines/over_normalization.py

@@ -1,121 +1,30 @@
-"""Détection de la sur-normalisation LLM — Classe 10 de la taxonomie des erreurs.
+"""Shim de compatibilité — détection de sur-normalisation LLM.
 
-La sur-normalisation désigne le cas où le LLM « corrige » à tort des passages
-déjà bien transcrits par l'OCR, en particulier :
-- modernisation de graphies médiévales légitimes (nostre → notre, faict → fait)
-- normalisation de variantes orthographiques historiques authentiques
-- modification de noms propres ou de termes rares sans erreur OCR initiale
-
-Mesure :
-    score = nombre de mots (OCR correct → LLM modifié) / nombre de mots OCR corrects
-
-Un score élevé indique que le prompt doit être affiné pour mieux préserver
-la graphie originale.
+Phase 6 (mai 2026) — l'implémentation canonique vit désormais dans
+``picarones.evaluation.metrics.over_normalization``.  Ce shim ré-exporte
+l'API publique avec un ``DeprecationWarning`` et sera supprimé en 2.0.
 """
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
-from typing import Optional
-
-
-@dataclass
-class OverNormalizationResult:
-    """Résultat de la détection de sur-normalisation pour un document."""
-
-    total_correct_ocr_words: int
-    over_normalized_count: int
-    over_normalized_passages: list[dict] = field(default_factory=list)
-    # Chaque entrée : {"gt": str, "ocr": str, "llm": str}
-
-    @property
-    def score(self) -> float:
-        """Score de sur-normalisation entre 0 (aucune dégradation) et 1 (tout dégradé)."""
-        if self.total_correct_ocr_words == 0:
-            return 0.0
-        return round(self.over_normalized_count / self.total_correct_ocr_words, 4)
-
-    def as_dict(self) -> dict:
-        return {
-            "score": self.score,
-            "total_correct_ocr_words": self.total_correct_ocr_words,
-            "over_normalized_count": self.over_normalized_count,
-            "over_normalized_passages": self.over_normalized_passages[:20],
-        }
-
-
-def detect_over_normalization(
-    ground_truth: str,
-    ocr_text: str,
-    llm_text: str,
-    *,
-    max_examples: int = 20,
-) -> OverNormalizationResult:
-    """Détecte la sur-normalisation LLM au niveau des mots.
-
-    Algorithme (alignement positionnel simple, adapté aux textes courts) :
-    Pour chaque position i dans min(len(GT), len(OCR), len(LLM)) :
-      - Si ocr[i] == gt[i]  → le mot était correct dans l'OCR
-      - Si llm[i] != gt[i]  → le LLM a dégradé ce mot correct → sur-normalisation
-
-    Parameters
-    ----------
-    ground_truth:
-        Transcription de référence.
-    ocr_text:
-        Sortie brute du moteur OCR (avant correction LLM).
-    llm_text:
-        Sortie après correction par le LLM.
-    max_examples:
-        Nombre maximal d'exemples de sur-normalisation conservés.
-
-    Returns
-    -------
-    OverNormalizationResult
-    """
-    gt_words = ground_truth.split()
-    ocr_words = ocr_text.split()
-    llm_words = llm_text.split()
-
-    n = min(len(gt_words), len(ocr_words), len(llm_words))
-
-    correct_ocr = 0
-    over_norm = 0
-    passages: list[dict] = []
-
-    for i in range(n):
-        gt_w = gt_words[i]
-        ocr_w = ocr_words[i]
-        llm_w = llm_words[i]
-
-        if ocr_w == gt_w:
-            correct_ocr += 1
-            if llm_w != gt_w and len(passages) < max_examples:
-                over_norm += 1
-                passages.append({"gt": gt_w, "ocr": ocr_w, "llm": llm_w})
-            elif llm_w != gt_w:
-                over_norm += 1
-
-    return OverNormalizationResult(
-        total_correct_ocr_words=correct_ocr,
-        over_normalized_count=over_norm,
-        over_normalized_passages=passages,
-    )
-
-
-def aggregate_over_normalization(results: list[Optional[OverNormalizationResult]]) -> dict:
-    """Agrège les résultats de sur-normalisation sur un ensemble de documents."""
-    valid = [r for r in results if r is not None]
-    if not valid:
-        return {"score": None, "total_correct_ocr_words": 0, "over_normalized_count": 0}
-
-    total_correct = sum(r.total_correct_ocr_words for r in valid)
-    total_over = sum(r.over_normalized_count for r in valid)
-    score = round(total_over / total_correct, 4) if total_correct > 0 else 0.0
-
-    return {
-        "score": score,
-        "total_correct_ocr_words": total_correct,
-        "over_normalized_count": total_over,
-        "document_count": len(valid),
-    }
+import warnings
+
+warnings.warn(
+    "picarones.pipelines.over_normalization est obsolète et sera supprimé en 2.0. "
+    "Utiliser picarones.evaluation.metrics.over_normalization à la place.",
+    DeprecationWarning,
+    stacklevel=2,
+)
+
+from picarones.evaluation.metrics.over_normalization import *  # noqa: F401, F403, E402
+from picarones.evaluation.metrics.over_normalization import (  # noqa: E402
+    OverNormalizationResult,
+    aggregate_over_normalization,
+    detect_over_normalization,
+)
+
+__all__ = [
+    "OverNormalizationResult",
+    "aggregate_over_normalization",
+    "detect_over_normalization",
+]

tests/architecture/test_legacy_canonical_parity.py

@@ -73,7 +73,7 @@ LEGACY_PACKAGES: tuple[str, ...] = (
 #: :data:`LEGACY_PARITY` sans faire échouer le test.  À diminuer
 #: à chaque session de migration : on cible 0 quand le retrait
 #: est complet.
-BOOTSTRAP_BASELINE = 104
+BOOTSTRAP_BASELINE = 101
 
 
 # ──────────────────────────────────────────────────────────────────

tests/engines/test_sprint3_llm_pipelines.py

@@ -22,7 +22,7 @@ import pytest
 class TestOverNormalization:
 
     def test_no_over_normalization(self):
-        from picarones.pipelines.over_normalization import detect_over_normalization
+        from picarones.evaluation.metrics.over_normalization import detect_over_normalization
         gt  = "nostre seigneur le roy"
         ocr = "noltre seigneur le roy"   # erreur OCR sur 'nostre'
         llm = "nostre seigneur le roy"   # LLM corrige → correct
@@ -31,7 +31,7 @@ class TestOverNormalization:
         assert result.over_normalized_count == 0
 
     def test_perfect_llm_no_over_norm(self):
-        from picarones.pipelines.over_normalization import detect_over_normalization
+        from picarones.evaluation.metrics.over_normalization import detect_over_normalization
         gt  = "nostre seigneur le roy"
         ocr = "nostre seigneur le roy"   # OCR correct
         llm = "nostre seigneur le roy"   # LLM conserve
@@ -40,7 +40,7 @@ class TestOverNormalization:
         assert result.total_correct_ocr_words == 4
 
     def test_over_normalization_detected(self):
-        from picarones.pipelines.over_normalization import detect_over_normalization
+        from picarones.evaluation.metrics.over_normalization import detect_over_normalization
         gt  = "nostre seigneur le roy"
         ocr = "nostre seigneur le roy"   # OCR correct
         llm = "notre seigneur le roy"    # LLM modifie 'nostre' → 'notre' : sur-normalisation
@@ -54,7 +54,7 @@ class TestOverNormalization:
         assert passage["llm"] == "notre"
 
     def test_over_normalization_score_formula(self):
-        from picarones.pipelines.over_normalization import detect_over_normalization
+        from picarones.evaluation.metrics.over_normalization import detect_over_normalization
         # 4 mots, OCR correct sur tous, LLM modifie 2 → score = 2/4 = 0.5
         gt  = "maistre jehan nostre dame"
         ocr = "maistre jehan nostre dame"
@@ -65,7 +65,7 @@ class TestOverNormalization:
         assert result.score == pytest.approx(0.5)
 
     def test_as_dict_keys(self):
-        from picarones.pipelines.over_normalization import detect_over_normalization
+        from picarones.evaluation.metrics.over_normalization import detect_over_normalization
         result = detect_over_normalization("foo bar", "foo baz", "foo baz")
         d = result.as_dict()
         assert "score" in d
@@ -74,12 +74,12 @@ class TestOverNormalization:
         assert "over_normalized_passages" in d
 
     def test_empty_texts(self):
-        from picarones.pipelines.over_normalization import detect_over_normalization
+        from picarones.evaluation.metrics.over_normalization import detect_over_normalization
         result = detect_over_normalization("", "", "")
         assert result.score == 0.0
 
     def test_aggregate_over_normalization(self):
-        from picarones.pipelines.over_normalization import (
+        from picarones.evaluation.metrics.over_normalization import (
             OverNormalizationResult,
             aggregate_over_normalization,
         )