sprint54: A.II.2.2 Layout F1 par type — couche de calcul (clôture A.II.2)

Dernière brique de l'axe A.II.2 (métriques structurelles). Pour les
manuscrits glosés ou les journaux multi-colonnes, c'est la métrique
qui répond à "le moteur sépare-t-il bien le texte principal de la
glose ?".

Nouveau picarones/core/layout.py
- dataclass Region(id, type, bbox) avec validation (bbox strictement
positive). bbox = (x, y, width, height), origine en haut à gauche
(convention ALTO/PAGE).
- _iou_bbox calcule l'IoU de deux rectangles.
- _align_regions apparie GT ↔ hypothèse en greedy par IoU
décroissant, same type required (case-insensitive). Pattern
identique au NER (Sprint 38).
- compute_layout_metrics(refs, hyps, iou_threshold=0.5) retourne :
- global : precision/recall/F1
- per_type : breakdown par type de région
- missed_regions (FN GT non matchées)
- hallucinated_regions (FP hyp non matchées)
- layout_f1 : raccourci pour le F1 global.

Conventions ICDAR : seuil IoU 0.5 par défaut, comparaison de type
insensible à la casse, coercion dict → Region acceptée pour les
utilisateurs qui parsent eux-mêmes ALTO/PAGE.

Pas d'enregistrement registre typé pour ce sprint — la métrique
suppose un parsing préalable (extraction des régions avec types et
bbox depuis l'ALTO/PAGE) qui ne s'inscrit pas directement dans le
pattern (ArtifactType, ArtifactType). L'enregistrement suivra quand
le parser ALTO/PAGE standard sera livré.

Tests : +20 dans test_sprint54_layout.py couvrant :
- validation Region (bbox invalide → ValueError, area)
- IoU mathématique (identité, disjoint, partiel)
- cas standards : layout parfait, mauvais type sur même bbox,
hallucination, région ratée, IoU sous le seuil, IoU au-dessus
- multi-type breakdown (TextRegion, MarginNote, Header, Footer)
- alignement greedy : 2 hyps pour 1 GT → best-IoU wins, l'autre FP
- dégénérés : 2 vides, 1 vide, None, dict input coerced
- type case-insensitive (TextRegion vs textregion match)
- shortcut layout_f1 équivalent
Suite complète : 1978 → 1998 passed, 2 skipped, 0 failed.

L'axe A.II.2 (métriques structurelles) du plan d'évolution est
intégralement livré côté couche de calcul :
- A.II.2.1 Reading order F1 ICDAR (Sprint 53)
- A.II.2.2 Layout F1 par type (Sprint 54)
- A.II.2.3 Différence Flesch (Sprint 52)

CHANGELOG.md

@@ -16,6 +16,38 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ### Ajouté
 
+- **Sprint 54 — A.II.2.2 Layout F1 par type de région : couche de
+  calcul (clôture A.II.2 côté calcul).** Dernière brique de l'axe
+  A.II.2 (métriques structurelles).  Pour les manuscrits glosés
+  (texte principal vs glose) ou les journaux multi-colonnes, c'est
+  la métrique qui répond à *« le moteur sépare-t-il bien le texte
+  principal de la glose ? »*.
+  - Nouveau module `picarones/core/layout.py` :
+    - dataclass `Region(id, type, bbox)` avec validation (bbox
+      strictement positive)
+    - `_iou_bbox` calcule l'IoU de deux rectangles (origine en haut
+      à gauche, convention ALTO/PAGE)
+    - `_align_regions` apparie GT ↔ hypothèse en greedy par IoU
+      décroissant, **same type required** (case-insensitive),
+      pattern identique au NER (Sprint 38)
+    - `compute_layout_metrics(refs, hyps, iou_threshold=0.5)`
+      retourne global F1 + per_type + listes
+      ``missed_regions`` (FN) et ``hallucinated_regions`` (FP)
+    - `layout_f1` : raccourci pour le F1 global
+  - Conventions : seuil IoU par défaut à 0,5 (convention ICDAR),
+    coercion automatique dict → ``Region``, comparaison de type
+    insensible à la casse.
+  - Pas d'enregistrement registre typé pour ce sprint — la métrique
+    suppose un parsing préalable (extraction des régions avec types
+    et bbox depuis l'ALTO/PAGE) qui ne s'inscrit pas directement
+    dans le pattern `(ArtifactType, ArtifactType)`.  L'enregistrement
+    suivra quand le parser ALTO standard sera livré.
+  - +20 tests dans `test_sprint54_layout.py` (validation Region,
+    IoU mathématique, cas standards : parfait, mauvais type,
+    hallucination, FN, IoU sous/sur seuil, multi-type breakdown,
+    alignement greedy avec best-IoU wins, dégénérés, type
+    case-insensitive, shortcut).
+
 - **Sprint 53 — A.II.2.1 Reading order F1 (ICDAR 2015) : couche de
   calcul.** Suite du Sprint 52 dans l'axe A.II.2 (métriques
   structurelles).  Sur un manuscrit glosé ou un journal multi-colonnes,
@@ -684,16 +716,18 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ### Tests
 
-- 1478 → 1978 tests (+17 Sprint 32, +23 Sprint 33, +21 Sprint 34,
+- 1478 → 1998 tests (+17 Sprint 32, +23 Sprint 33, +21 Sprint 34,
   +27 Sprint 35, +22 Sprint 36, +42 Sprint 37, +19 Sprint 38,
   +32 Sprint 39, +16 Sprint 40, +38 Sprint 41, +17 Sprint 42,
   +43 Sprint 43, +15 Sprint 44, +16 Sprint 45, +38 Sprint 46,
   +9 Sprint 47, +14 Sprint 48, +17 Sprint 49, +17 Sprint 50,
-  +16 Sprint 51, +25 Sprint 52, +16 Sprint 53). Aucune régression.
-  **Phase 0 close ; Étape 2 du plan d'évolution intégralement
-  livrée ; Étape 3 démarrée :** Flesch (A.II.2.3, Sprint 52) et
-  Reading order F1 ICDAR 2015 (A.II.2.1, Sprint 53) couches de
-  calcul livrées.
+  +16 Sprint 51, +25 Sprint 52, +16 Sprint 53, +20 Sprint 54).
+  Aucune régression. **Phase 0 close ; Étape 2 du plan d'évolution
+  intégralement livrée ; Étape 3 / axe A.II.2 (métriques
+  structurelles) couches de calcul intégralement livrées :**
+  Flesch (A.II.2.3, Sprint 52), Reading order F1 ICDAR 2015
+  (A.II.2.1, Sprint 53) et Layout F1 par type (A.II.2.2,
+  Sprint 54).
 
 ---
 

CLAUDE.md

@@ -207,6 +207,7 @@ AZURE_DOC_INTEL_KEY=...
 | 33 | **Sprint 2 du plan d'évolution 2026 — Phase 0.2 : interface module générique**. Nouveau module `picarones/core/modules.py` avec l'enum `ArtifactType` (IMAGE, TEXT, ALTO, PAGE, ENTITIES, READING_ORDER) et la classe abstraite `BaseModule` qui déclare `input_types`/`output_types`, `execution_mode` (`"io"`/`"cpu"`), une méthode `process(dict[ArtifactType, Any]) → dict[ArtifactType, Any]`, et des helpers `validate_inputs`/`validate_outputs`. `BaseOCREngine` (`picarones/engines/base.py`) hérite désormais de `BaseModule` avec `input_types=(IMAGE,)` et `output_types=(TEXT,)` ; sa nouvelle méthode `process` wrappe l'API historique `run()`. Aucun adaptateur OCR existant n'est touché — `test_engines.py` passe à 20/20 sans modification. +23 tests dans `test_sprint33_module_interface.py` (contrat, validation, MockModule TEXT→ALTO démonstratif comme demandé par le plan, délégation `BaseOCREngine.process → run`, cohérence ArtifactType/GTLevel). **Verrou levé** : un même runner peut maintenant exécuter un OCR (image→texte), un mappeur VLM→ALTO, un rewriter ALTO→ALTO, un module NER (texte→entités), etc. — fondation directe pour l'axe B du plan. |
 | 34 | **Sprint 3 du plan d'évolution 2026 — Phase 0.3 : registre typé de métriques (clôture Phase 0)**. Nouveaux modules `picarones/core/metric_registry.py` (`MetricSpec`, `@register_metric`, `select_metrics`, `compute_at_junction`) et `picarones/core/builtin_metrics.py` qui enregistre `cer`, `wer`, `mer`, `wil` sur `(TEXT, TEXT)` plus un stub `text_preservation_after_reconstruction` sur `(TEXT, ALTO)` comme preuve de concept de jonction hétérogène. **Approche strictement additive** : ni `metrics.py` ni `compute_metrics` ne sont modifiés, le rapport HTML reste identique octet par octet. La sélection par signature de types est exacte (pas de coercion). +21 tests dans `test_sprint34_metric_registry.py`, dont une parité numérique CER/WER/MER/WIL avec `compute_metrics` legacy à 1e-9 près sur 4 paires de textes. **Verrou levé** : le runner d'une pipeline composée peut maintenant calculer automatiquement la métrique adéquate à chaque jonction de son DAG selon les types d'artefacts produits/attendus — fondation directe pour la métrique d'absorption d'erreur (acte B.3) et toutes les métriques structurelles à venir (Layout F1, reading order F1, NER). |
 | 35 | **Sprint 4 du plan d'évolution 2026 — Étape 2 / axe A : métriques inter-moteurs (couche de calcul)**. Nouveau module `picarones/core/inter_engine.py` qui répond à deux questions distinctes mais liées : *(a) à quel point les moteurs font-ils des erreurs de natures différentes ?* via `kl_divergence`, `jensen_shannon_divergence` (symétrique, bornée `[0, 1]`), et `taxonomy_divergence_matrix` qui construit la matrice triangulaire inter-moteurs ; *(b) quel CER serait atteignable si on combinait les moteurs ?* via `oracle_token_recall` (proxy bag-of-words, borne supérieure du recall atteignable), `complementarity_gap` (oracle vs meilleur moteur seul, gap absolu/relatif), et `pairwise_disagreement_rate`. Fonctions pures, sans I/O ni intégration runner — la couche de calcul est livrée indépendamment, le câblage narratif (`ENSEMBLE_OPPORTUNITY`) et HTML (matrice de divergence, badge oracle) suit au Sprint 36. +27 tests couvrant les invariants mathématiques (KL ≥ 0, KL(p,p) = 0, JS symétrique et bornée, oracle ≥ best_single, multiplicité respectée), les cas concrets (deux moteurs spécialisés sortent comme candidats ensemble, complémentarité parfaite atteint oracle = 1), et les garde-fous (référence vide, hypothèses vides, métrique inconnue). |
+| 54 | **Sprint 23 du plan d'évolution 2026 — Étape 3 / axe A.II.2.2 : Layout F1 par type de région (couche de calcul, clôture A.II.2 côté calcul)**. Dernière brique de l'axe A.II.2. Pour les manuscrits glosés ou journaux multi-colonnes, répond à « le moteur sépare-t-il bien texte principal et glose ? ». Module `picarones/core/layout.py` : dataclass `Region(id, type, bbox)` avec validation, `_iou_bbox` (IoU de rectangles), `_align_regions` greedy par IoU décroissant avec same-type-required (pattern identique au NER Sprint 38), `compute_layout_metrics(refs, hyps, iou_threshold=0.5)` retourne global F1 + per_type + `missed_regions` (FN) + `hallucinated_regions` (FP). Type case-insensitive, coercion dict → Region, seuil ICDAR 0.5 par défaut. Pas d'enregistrement registre typé : la métrique suppose un parser ALTO/PAGE en amont (qui suivra dans un sprint dédié). +20 tests (validation Region, IoU math, cas standards : parfait, type incorrect, hallucination, FN, IoU sous/sur seuil, multi-type, greedy best-IoU wins, dégénérés, case-insensitive, shortcut). **Verrou levé** : un benchmark dont le corpus a une GT ALTO/PAGE peut désormais classer les moteurs sur leur fidélité au layout par type — métrique critique pour les médiévistes (séparation texte/glose) et les journaux multi-colonnes. |
 | 53 | **Sprint 22 du plan d'évolution 2026 — Étape 3 / axe A.II.2.1 : Reading order F1 ICDAR 2015 (couche de calcul)**. Métrique standard d'Antonacopoulos et al. : sur un manuscrit glosé ou un journal multi-colonnes, un moteur peut avoir un excellent CER caractère et un ordre de lecture catastrophique. Le module `picarones/core/reading_order.py` expose `compute_reading_order_metrics(ref_order, hyp_order)` qui calcule, pour chaque paire `(a, b)` où `a` précède `b` dans la GT, si `a` précède aussi `b` dans l'hypothèse — retourne precision/recall/F1 + détails (TP/FP/FN, régions communes vs disjointes). Conventions : doublons traités à la première occurrence, vide/None → F1 = 0 (pas de récompense gratuite), single region → 0 paire émise. Format compatible direct avec `ReadingOrderGT.region_order` du Sprint 32. `reading_order_f1` enregistré dans le registre typé Sprint 34 pour la jonction `(READING_ORDER, READING_ORDER)`. +16 tests dans `test_sprint53_reading_order.py` (canoniques : identique→1, inversé→0, permutation locale, insertion, suppression ; dégénérés : vide, single, doublons, None ; comptages ; registre). **Verrou levé** : un benchmark dont le corpus a une GT `reading_order` peut désormais classer les moteurs sur leur fidélité à l'ordre de lecture des régions ALTO/PAGE — métrique critique pour les manuscrits glosés et les journaux multi-colonnes. |
 | 52 | **Sprint 21 du plan d'évolution 2026 — Étape 3 / axe A.II.2.3 : différence de score Flesch (couche de calcul)**. Premier sprint de l'Étape 3 (métriques structurelles), démarré après la clôture de l'Étape 2. Nouveau module `picarones/core/readability.py` : `count_syllables_word` (heuristique groupes de voyelles + diacritiques FR/EN), `count_words`/`count_sentences`, `flesch_score(text, lang)` avec coefficients FR (Kandel-Moles 1958) et EN (Flesch 1948), score borné `[0, 100]`. `flesch_delta(reference, hypothesis, lang)` retourne `Flesch(OCR) - Flesch(GT)` — **positif = signal d'over-normalisation LLM**. **Aucun alignement caractère/mot requis** : la métrique reste calculable même quand l'OCR est très dégradé, ce qui en fait l'outil le plus fiable pour repérer les VLM/LLM hallucinant du texte moderne plausible mais déconnecté de la GT. `flesch_delta_fr` et `flesch_delta_en` enregistrés dans le registre typé Sprint 34 pour la jonction `(TEXT, TEXT)`. +25 tests dans `test_sprint52_readability.py` (compteurs avec cas limites, score borné, FR/EN cohérents, **cas réaliste de modernisation LLM → delta > 10 pts**, intégration registre typé). **Verrou levé** : les détecteurs narratifs futurs peuvent maintenant signaler automatiquement une over-normalisation par LLM via le delta Flesch, sans dépendre de l'alignement OCR/GT (métrique robuste aux pires cas). |
 | 51 | **Sprint 20 du plan d'évolution 2026 — Étape 2 / adaptation engines : Azure DI expose `Word.confidence` (clôture de l'adaptation engines)**. Suite directe des Sprints 47-50. La réponse Azure expose `analyzeResult.pages[].words[]` avec `content` et `confidence` ∈ [0, 1]. Refactor : `_run_ocr_with_result(image_path) → (text, analyze_result_dict)` centralise les deux chemins (SDK `azure-ai-documentintelligence` et REST direct via `urllib` avec polling Azure asynchrone). `_sdk_result_to_dict` convertit l'objet SDK en dict normalisé identique au REST. `_extract_token_confidences_from_result` parcourt `pages[].words[]`, filtre les confidences None/négatives et contenus vides. Texte préservé octet par octet (extraction depuis `pages[].lines[]`). Flag `expose_confidences: false`. API appelée une seule fois. +16 tests dans `test_sprint51_azure_confidences.py` (extraction multi-pages, filtrage 4 cas, cas dégénérés 4 cas, conversion SDK → dict, surcharge `run()` avec mock, échec API, intégration runner). **Verrou levé** : tous les 5 adapters OCR (Tesseract, Pero OCR, Mistral OCR, Google Vision, Azure DI) exposent désormais leurs `token_confidences` natifs — l'utilisateur obtient automatiquement ECE/MCE/reliability dans le rapport quel que soit le moteur. **L'Étape 2 du plan d'évolution 2026 est intégralement livrée bout-en-bout.** |
@@ -271,7 +272,7 @@ au template `_narrative_summary.html` (placé entre `_header.html` et `_critical
 ## Contexte développement
 
 - **Environnement** : GitHub Codespaces (`/workspaces/Picarones`), Python 3.12
-- **Tests** : 1978 passed, 2 skipped (Sprints 32-34 = Phase 0 close ; Sprints 35-37 = inter-moteurs livrés bout-en-bout ; Sprints 38+40+41 = NER livré bout-en-bout ; Sprints 39+42+43 = calibration livrée bout-en-bout côté rapport ; Sprint 44 = médiane par défaut ; Sprints 45+46 = stratification A.III livrée bout-en-bout ; Sprints 47-51 = les 5 adapters OCR exposent leurs confidences natives ; **Étape 2 close** ; Sprints 52-53 = Flesch + Reading order F1 ICDAR couches de calcul (Étape 3 / axe A.II.2 démarrée))
+- **Tests** : 1998 passed, 2 skipped (Sprints 32-34 = Phase 0 close ; Sprints 35-37 = inter-moteurs livrés bout-en-bout ; Sprints 38+40+41 = NER livré bout-en-bout ; Sprints 39+42+43 = calibration livrée bout-en-bout côté rapport ; Sprint 44 = médiane par défaut ; Sprints 45+46 = stratification A.III livrée bout-en-bout ; Sprints 47-51 = les 5 adapters OCR exposent leurs confidences natives ; **Étape 2 close** ; Sprints 52-54 = axe A.II.2 (métriques structurelles) couches de calcul intégralement livrées : Flesch + Reading order F1 ICDAR + Layout F1 par type)
 - **Plan d'évolution actif** : [`docs/roadmap/evolution-2026.md`](docs/roadmap/evolution-2026.md)
 - **Branche active** : `claude/analyze-project-evolution-KOA56`
 - **Transcript de la conversation de développement** :

picarones/core/layout.py

@@ -0,0 +1,280 @@
+"""Layout F1 par type de région — Sprint 54.
+
+Sprint 54 — A.II.2.2 du plan d'évolution 2026.
+
+Pourquoi ce module
+------------------
+Un médiéviste qui édite un manuscrit glosé veut savoir : *« le moteur
+sépare-t-il bien le texte principal de la glose ? »*.  Le score de
+structure global de Picarones (Sprint 5) agrège fusion/fragmentation
+de lignes en un seul nombre — utile mais non typé.  Ce module
+discrimine par **type de région** ALTO/PAGE (``TextRegion``,
+``MarginNote``, ``Header``, ``Footer``, ``Drop-Cap``...) en
+appliquant le pattern ICDAR layout standard :
+
+- **TP** : région GT et région hypothèse de **même type** avec
+  chevauchement IoU ≥ seuil (alignement greedy par IoU décroissant),
+- **FN** : région GT non matchée,
+- **FP** : région hypothèse non matchée,
+- F1 calculé global et par type.
+
+Le pattern d'alignement est le même que pour le NER (Sprint 38) — on
+réutilise une approche éprouvée plutôt que d'en inventer une nouvelle.
+
+Stratégie de découpage
+----------------------
+Cohérente avec NER (Sprint 38), Flesch (Sprint 52), Reading order F1
+(Sprint 53) : couche de calcul pure d'abord.  L'utilisateur fournit
+deux listes de ``Region`` (typiquement extraites de ALTO/PAGE par un
+parser amont — le parser ALTO/PAGE standard de Picarones suivra
+dans un sprint dédié).  Pas de câblage runner ni de vue HTML ici.
+
+Convention de coordonnées
+-------------------------
+Une bbox est un tuple ``(x, y, width, height)`` en pixels (origine
+en haut à gauche, axe y vers le bas — convention ALTO et PAGE
+standard).  L'IoU est calculée sur l'aire d'intersection / union des
+rectangles.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Iterable
+
+logger = logging.getLogger(__name__)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Modèle de données
+# ──────────────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class Region:
+    """Une région ALTO/PAGE alignable sur sa GT.
+
+    Attributs
+    ---------
+    id:
+        Identifiant unique au sein de la séquence (ex. ``"r_1"``,
+        ``"region_main"``).  Informatif — l'alignement se fait par IoU,
+        pas par ID.
+    type:
+        Catégorie de la région (``"TextRegion"``, ``"MarginNote"``,
+        ``"Header"``, etc.).  Comparaison **case-insensitive**.
+    bbox:
+        Rectangle ``(x, y, width, height)`` en pixels, origine en haut
+        à gauche.  Doit avoir width > 0 et height > 0.
+    """
+
+    id: str
+    type: str
+    bbox: tuple[int, int, int, int]
+
+    def __post_init__(self) -> None:
+        x, y, w, h = self.bbox
+        if w <= 0 or h <= 0:
+            raise ValueError(
+                f"Region {self.id!r} : bbox invalide (w={w}, h={h}). "
+                "width et height doivent être strictement positifs."
+            )
+
+    @property
+    def area(self) -> int:
+        _, _, w, h = self.bbox
+        return w * h
+
+
+def _to_region(obj: Region | dict) -> Region:
+    """Coerce un dict en ``Region`` (clés ``id``, ``type``, ``bbox``)."""
+    if isinstance(obj, Region):
+        return obj
+    return Region(
+        id=str(obj["id"]),
+        type=str(obj["type"]),
+        bbox=tuple(obj["bbox"]),  # type: ignore[arg-type]
+    )
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# IoU + alignement greedy
+# ──────────────────────────────────────────────────────────────────────────
+
+
+def _iou_bbox(a: Region, b: Region) -> float:
+    """Intersection-over-Union de deux bboxes ``(x, y, w, h)``."""
+    ax, ay, aw, ah = a.bbox
+    bx, by, bw, bh = b.bbox
+    inter_x = max(ax, bx)
+    inter_y = max(ay, by)
+    inter_x_end = min(ax + aw, bx + bw)
+    inter_y_end = min(ay + ah, by + bh)
+    inter_w = max(0, inter_x_end - inter_x)
+    inter_h = max(0, inter_y_end - inter_y)
+    inter = inter_w * inter_h
+    if inter == 0:
+        return 0.0
+    union = a.area + b.area - inter
+    if union <= 0:
+        return 0.0
+    return inter / union
+
+
+def _align_regions(
+    references: list[Region],
+    hypotheses: list[Region],
+    iou_threshold: float,
+) -> tuple[list[tuple[int, int, float]], set[int], set[int]]:
+    """Appareillage greedy par IoU décroissant ; same type requis.
+
+    Renvoie ``(matches, unmatched_refs, unmatched_hyps)`` —
+    ``matches`` est une liste de ``(idx_ref, idx_hyp, iou)``.
+    """
+    candidates: list[tuple[float, int, int]] = []
+    for i, r in enumerate(references):
+        for j, h in enumerate(hypotheses):
+            if r.type.casefold() != h.type.casefold():
+                continue
+            iou = _iou_bbox(r, h)
+            if iou >= iou_threshold:
+                candidates.append((iou, i, j))
+
+    # Tri stable : IoU décroissant, puis indices croissants pour
+    # déterminisme sur égalités.
+    candidates.sort(key=lambda t: (-t[0], t[1], t[2]))
+
+    matched_refs: set[int] = set()
+    matched_hyps: set[int] = set()
+    matches: list[tuple[int, int, float]] = []
+    for iou, i, j in candidates:
+        if i in matched_refs or j in matched_hyps:
+            continue
+        matched_refs.add(i)
+        matched_hyps.add(j)
+        matches.append((i, j, iou))
+
+    unmatched_refs = set(range(len(references))) - matched_refs
+    unmatched_hyps = set(range(len(hypotheses))) - matched_hyps
+    return matches, unmatched_refs, unmatched_hyps
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# Métrique principale
+# ──────────────────────────────────────────────────────────────────────────
+
+
+def _prf(tp: int, fp: int, fn: int) -> dict[str, float]:
+    p = tp / (tp + fp) if (tp + fp) > 0 else 0.0
+    r = tp / (tp + fn) if (tp + fn) > 0 else 0.0
+    f1 = 2 * p * r / (p + r) if (p + r) > 0 else 0.0
+    return {"precision": p, "recall": r, "f1": f1, "support": tp + fn}
+
+
+def compute_layout_metrics(
+    reference_regions: Iterable[Region | dict] | None,
+    hypothesis_regions: Iterable[Region | dict] | None,
+    iou_threshold: float = 0.5,
+) -> dict:
+    """Calcule precision/recall/F1 sur le layout par type de région.
+
+    Parameters
+    ----------
+    reference_regions:
+        Liste de régions GT (``Region`` ou dict ``{id, type, bbox}``).
+    hypothesis_regions:
+        Liste de régions produites par le moteur OCR/HTR ou un
+        layout-detector.
+    iou_threshold:
+        Seuil de chevauchement minimal pour déclarer un appariement
+        (défaut : 0,5 — convention ICDAR).
+
+    Returns
+    -------
+    dict
+        ``{
+            "global": {"precision", "recall", "f1", "support"},
+            "per_type": {type_name: {"precision", ...}},
+            "true_positives": int,
+            "false_positives": int,
+            "false_negatives": int,
+            "missed_regions": list[dict],          # GT non matchées
+            "hallucinated_regions": list[dict],    # hyp non matchées
+            "iou_threshold": float,
+        }``
+
+    Cas dégénérés
+    -------------
+    - Deux listes vides → F1 = 0 et tous compteurs à 0.
+    - GT vide + hyp non-vide → F1 = 0 (toutes hyp = FP).
+    - hyp vide + GT non-vide → F1 = 0 (toutes GT = FN).
+    """
+    refs = [_to_region(r) for r in (reference_regions or [])]
+    hyps = [_to_region(h) for h in (hypothesis_regions or [])]
+
+    matches, unmatched_refs, unmatched_hyps = _align_regions(
+        refs, hyps, iou_threshold,
+    )
+
+    tp = len(matches)
+    fn = len(unmatched_refs)
+    fp = len(unmatched_hyps)
+
+    cat_tp: dict[str, int] = {}
+    cat_fn: dict[str, int] = {}
+    cat_fp: dict[str, int] = {}
+    for i, _j, _iou in matches:
+        cat = refs[i].type
+        cat_tp[cat] = cat_tp.get(cat, 0) + 1
+    for i in unmatched_refs:
+        cat = refs[i].type
+        cat_fn[cat] = cat_fn.get(cat, 0) + 1
+    for j in unmatched_hyps:
+        cat = hyps[j].type
+        cat_fp[cat] = cat_fp.get(cat, 0) + 1
+
+    all_categories = sorted(set(cat_tp) | set(cat_fn) | set(cat_fp))
+    per_type = {
+        cat: _prf(
+            cat_tp.get(cat, 0),
+            cat_fp.get(cat, 0),
+            cat_fn.get(cat, 0),
+        )
+        for cat in all_categories
+    }
+
+    return {
+        "global": _prf(tp, fp, fn),
+        "per_type": per_type,
+        "true_positives": tp,
+        "false_positives": fp,
+        "false_negatives": fn,
+        "missed_regions": [
+            {"id": refs[i].id, "type": refs[i].type, "bbox": list(refs[i].bbox)}
+            for i in sorted(unmatched_refs)
+        ],
+        "hallucinated_regions": [
+            {"id": hyps[j].id, "type": hyps[j].type, "bbox": list(hyps[j].bbox)}
+            for j in sorted(unmatched_hyps)
+        ],
+        "iou_threshold": iou_threshold,
+    }
+
+
+def layout_f1(
+    reference_regions: Iterable[Region | dict] | None,
+    hypothesis_regions: Iterable[Region | dict] | None,
+    iou_threshold: float = 0.5,
+) -> float:
+    """Raccourci : F1 global du layout."""
+    return compute_layout_metrics(
+        reference_regions, hypothesis_regions, iou_threshold,
+    )["global"]["f1"]
+
+
+__all__ = [
+    "Region",
+    "compute_layout_metrics",
+    "layout_f1",
+]

tests/test_sprint54_layout.py

@@ -0,0 +1,254 @@
+"""Tests Sprint 54 — Layout F1 par type de région.
+
+Couvre :
+
+1. ``Region`` validation (bbox invalide → ValueError, area calculée).
+2. ``_iou_bbox`` mathématique (identité, disjoint, partiel).
+3. **Cas standards** :
+   - Layout parfait → F1 = 1
+   - Mauvais type sur la même bbox → 0 TP pour ce type
+   - Hallucination (région inventée) → FP
+   - Région ratée (manquante) → FN
+   - IoU sous le seuil → pas d'appariement
+4. **Multi-type** : breakdown per_type cohérent avec les comptages
+   globaux.
+5. **Alignement greedy** : 2 hypothèses pour 1 GT → la meilleure
+   gagne, l'autre devient FP.
+6. **Cas dégénérés** : listes vides, None, IoU custom.
+7. ``layout_f1`` raccourci équivalent à ``compute_layout_metrics["f1"]``.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from picarones.core.layout import (
+    Region,
+    _iou_bbox,
+    compute_layout_metrics,
+    layout_f1,
+)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 1. Region validation
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestRegionDataclass:
+    def test_valid_construction(self) -> None:
+        r = Region("r1", "TextRegion", (0, 0, 100, 200))
+        assert r.id == "r1"
+        assert r.area == 20_000
+
+    def test_invalid_bbox_raises(self) -> None:
+        with pytest.raises(ValueError, match="bbox invalide"):
+            Region("r1", "TextRegion", (0, 0, 0, 100))
+        with pytest.raises(ValueError, match="bbox invalide"):
+            Region("r1", "TextRegion", (0, 0, 100, -5))
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 2. IoU bbox
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestIouBbox:
+    def test_identical_bbox_iou_one(self) -> None:
+        a = Region("a", "X", (0, 0, 100, 100))
+        assert _iou_bbox(a, a) == pytest.approx(1.0)
+
+    def test_disjoint_bbox_iou_zero(self) -> None:
+        a = Region("a", "X", (0, 0, 100, 100))
+        b = Region("b", "X", (200, 200, 50, 50))
+        assert _iou_bbox(a, b) == 0.0
+
+    def test_partial_overlap(self) -> None:
+        # a = [0,0,100,100], b = [50,50,100,100]
+        # intersection : 50x50 = 2500
+        # union : 10000 + 10000 - 2500 = 17500
+        # iou = 2500/17500 ≈ 0.143
+        a = Region("a", "X", (0, 0, 100, 100))
+        b = Region("b", "X", (50, 50, 100, 100))
+        assert _iou_bbox(a, b) == pytest.approx(2500 / 17500)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 3. Cas standards
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestStandardCases:
+    def test_perfect_layout(self) -> None:
+        ref = [
+            Region("r1", "TextRegion", (0, 0, 100, 100)),
+            Region("r2", "MarginNote", (200, 0, 50, 100)),
+        ]
+        m = compute_layout_metrics(ref, list(ref))
+        assert m["global"]["f1"] == pytest.approx(1.0)
+        assert m["true_positives"] == 2
+        assert m["false_positives"] == 0
+        assert m["false_negatives"] == 0
+
+    def test_wrong_type_breaks_match(self) -> None:
+        # Même bbox mais type différent → pas d'appariement
+        ref = [Region("r1", "TextRegion", (0, 0, 100, 100))]
+        hyp = [Region("r1", "MarginNote", (0, 0, 100, 100))]
+        m = compute_layout_metrics(ref, hyp)
+        assert m["true_positives"] == 0
+        assert m["false_negatives"] == 1
+        assert m["false_positives"] == 1
+
+    def test_hallucinated_region_is_fp(self) -> None:
+        ref = [Region("r1", "TextRegion", (0, 0, 100, 100))]
+        hyp = [
+            Region("r1", "TextRegion", (0, 0, 100, 100)),
+            Region("rX", "TextRegion", (500, 500, 50, 50)),  # inventée
+        ]
+        m = compute_layout_metrics(ref, hyp)
+        assert m["true_positives"] == 1
+        assert m["false_positives"] == 1
+        assert m["hallucinated_regions"][0]["id"] == "rX"
+
+    def test_missing_region_is_fn(self) -> None:
+        ref = [
+            Region("r1", "TextRegion", (0, 0, 100, 100)),
+            Region("r2", "TextRegion", (200, 0, 100, 100)),
+        ]
+        hyp = [Region("r1", "TextRegion", (0, 0, 100, 100))]
+        m = compute_layout_metrics(ref, hyp)
+        assert m["true_positives"] == 1
+        assert m["false_negatives"] == 1
+        assert m["missed_regions"][0]["id"] == "r2"
+
+    def test_iou_below_threshold_no_match(self) -> None:
+        # Recouvrement IoU = 2500/17500 ≈ 0.14 < 0.5
+        ref = [Region("r1", "TextRegion", (0, 0, 100, 100))]
+        hyp = [Region("r1", "TextRegion", (50, 50, 100, 100))]
+        m = compute_layout_metrics(ref, hyp, iou_threshold=0.5)
+        assert m["true_positives"] == 0
+
+    def test_iou_above_threshold_matches(self) -> None:
+        # Recouvrement IoU = 6400/13600 ≈ 0.47, sous 0.5 mais sur 0.4
+        ref = [Region("r1", "TextRegion", (0, 0, 100, 100))]
+        hyp = [Region("r1", "TextRegion", (20, 20, 100, 100))]
+        m_strict = compute_layout_metrics(ref, hyp, iou_threshold=0.5)
+        m_loose = compute_layout_metrics(ref, hyp, iou_threshold=0.4)
+        assert m_strict["true_positives"] == 0
+        assert m_loose["true_positives"] == 1
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 4. Multi-type breakdown
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestPerTypeBreakdown:
+    def test_per_type_metrics(self) -> None:
+        ref = [
+            Region("r1", "TextRegion",  (0, 0, 100, 100)),
+            Region("r2", "TextRegion",  (200, 0, 100, 100)),
+            Region("r3", "MarginNote",  (0, 200, 100, 50)),
+            Region("r4", "Header",      (0, 300, 200, 30)),
+        ]
+        hyp = [
+            Region("r1", "TextRegion",  (0, 0, 100, 100)),       # match
+            # r2 manquante → FN TextRegion
+            Region("r3", "MarginNote",  (0, 200, 100, 50)),      # match
+            Region("rX", "Footer",      (0, 400, 200, 30)),      # FP Footer
+            # r4 Header manquante → FN Header
+        ]
+        m = compute_layout_metrics(ref, hyp)
+        per_type = m["per_type"]
+        # TextRegion : 1 TP + 1 FN → P=1, R=0.5, F1=2/3
+        assert per_type["TextRegion"]["true_positives" if False else "f1"] == pytest.approx(2 / 3)
+        # MarginNote : 1 TP, parfait
+        assert per_type["MarginNote"]["f1"] == pytest.approx(1.0)
+        # Header : 1 FN → P=0, R=0, F1=0
+        assert per_type["Header"]["f1"] == 0.0
+        # Footer : 1 FP → P=0, R=0
+        assert per_type["Footer"]["f1"] == 0.0
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 5. Alignement greedy
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestGreedyAlignment:
+    def test_best_iou_wins(self) -> None:
+        # GT : 1 région.  Hypothèse : 2 régions, l'une parfaite,
+        # l'autre faiblement chevauchante.  La meilleure gagne.
+        ref = [Region("r1", "TextRegion", (0, 0, 100, 100))]
+        hyp = [
+            Region("h_weak",   "TextRegion", (60, 60, 100, 100)),  # faible IoU
+            Region("h_strong", "TextRegion", (0, 0, 100, 100)),    # parfait
+        ]
+        m = compute_layout_metrics(ref, hyp, iou_threshold=0.1)
+        # Le strong gagne, le weak devient FP
+        assert m["true_positives"] == 1
+        assert m["false_positives"] == 1
+        assert m["hallucinated_regions"][0]["id"] == "h_weak"
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 6. Cas dégénérés
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestDegenerateCases:
+    def test_both_empty(self) -> None:
+        m = compute_layout_metrics([], [])
+        assert m["global"]["f1"] == 0.0
+        assert m["per_type"] == {}
+
+    def test_only_reference_empty(self) -> None:
+        m = compute_layout_metrics([], [Region("r1", "X", (0, 0, 10, 10))])
+        assert m["false_positives"] == 1
+        assert m["true_positives"] == 0
+
+    def test_only_hypothesis_empty(self) -> None:
+        m = compute_layout_metrics([Region("r1", "X", (0, 0, 10, 10))], [])
+        assert m["false_negatives"] == 1
+        assert m["true_positives"] == 0
+
+    def test_none_inputs(self) -> None:
+        m = compute_layout_metrics(None, None)
+        assert m["global"]["f1"] == 0.0
+
+    def test_dict_input_coerced(self) -> None:
+        # L'utilisateur peut passer des dicts au format {id, type, bbox}
+        ref = [{"id": "r1", "type": "TextRegion", "bbox": (0, 0, 100, 100)}]
+        hyp = [{"id": "r1", "type": "TextRegion", "bbox": (0, 0, 100, 100)}]
+        assert layout_f1(ref, hyp) == pytest.approx(1.0)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 7. Type matching case-insensitive
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestTypeNormalization:
+    def test_type_case_insensitive(self) -> None:
+        ref = [Region("r1", "TextRegion", (0, 0, 100, 100))]
+        hyp = [Region("r1", "textregion", (0, 0, 100, 100))]
+        assert layout_f1(ref, hyp) == pytest.approx(1.0)
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 8. Shortcut layout_f1
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestShortcut:
+    def test_shortcut_matches_full_call(self) -> None:
+        ref = [
+            Region("r1", "TextRegion", (0, 0, 100, 100)),
+            Region("r2", "MarginNote", (200, 0, 50, 100)),
+        ]
+        hyp = [
+            Region("r1", "TextRegion", (0, 0, 100, 100)),
+            # r2 manquante
+        ]
+        full = compute_layout_metrics(ref, hyp)
+        assert layout_f1(ref, hyp) == pytest.approx(full["global"]["f1"])