phaseE: séparation core/ (Cercle 1) + measurements/ (Cercle 2)

Cinquième phase de la refonte en 3 cercles. Cible : isoler
physiquement le **noyau invariant** (abstractions du domaine,
orchestration) de toutes les **mesures officielles** qui s'empilaient
historiquement dans ``picarones/core/``.

Distinction conceptuelle (alignement DDD)
-----------------------------------------
- **Cercle 1 (``core/``)** : abstractions du domaine + orchestration.
Indépendantes de l'interface utilisateur. API publique stable, ne
cassent pas entre versions mineures.
- **Cercle 2 (``measurements/``)** : mesures et analyses au-delà du
noyau. Maintenues mais peuvent évoluer.

Critère de la doc ``architecture-cercles.md`` corrigé : le précédent
critère « si on supprime ce module, le produit reste viable » mêlait
deux questions distinctes. Remplacé par le critère DDD propre
(domaine vs adapters/présentation).

Migration physique
------------------
**41 modules métriques** déplacés de ``picarones/core/`` vers
``picarones/measurements/`` :

- baseline_comparison, builtin_hooks, calibration, char_scores,
confusion, cost_projection, difficulty, equivalence_profile,
error_absorption, hallucination, history, image_quality,
incremental_comparison, inter_engine, layout, levers, line_metrics,
longitudinal, marginal_cost, ner, ner_backends, normalization,
numerical_sequences, numerical_sequences_runner, pricing,
rare_tokens, readability, readability_runner, reading_order,
reliability, robustness, robustness_projection, searchability,
searchability_runner, specialization, statistics, structure,
taxonomy, taxonomy_comparison, throughput, worst_lines.

**Sous-package narrative/** (4 modules + 6 familles de détecteurs +
helper + templates) déplacé vers ``picarones/measurements/narrative/`` :

- facts, registry, arbiter, renderer (4 modules)
- detectors/{_helpers,ranking,pareto,stratum,quality,history,ensemble}.py
(7 fichiers)
- templates/{fr,en}.yaml (2 fichiers data, copiés en l'état)

Imports internes du sous-package narrative mis à jour pour pointer
vers ``picarones.measurements.narrative.X`` au lieu de
``picarones.core.narrative.X`` (self-contained, ne dépend plus des
shims).

53 shims rétrocompat dans ``picarones/core/``
---------------------------------------------
- 41 shims pour les modules métriques (1 par module).
- 4 shims pour les modules narrative top-level.
- 7 shims pour les détecteurs des 6 familles.
- 1 shim pour ``narrative/__init__.py``.
- 1 shim pour ``narrative/detectors/__init__.py``.

Total : 53 fichiers-shims de 16 lignes chacun. Comportement
strictement identique (réexport via wildcard ``import *``).

Bonus : correction d'un bug préexistant
---------------------------------------
``_mean_duration_per_engine`` était utilisé par ``detect_speed_winner``
mais absent de ``_helpers.py`` depuis le découpage du chantier 5
(narrative/detectors.py 1229L → 6 familles). Réintroduit dans
``measurements/narrative/detectors/_helpers.py``. ``detect_speed_winner``
fonctionne à nouveau sans warning ``fonctionnalité dégradée``.

État final ``picarones/core/``
------------------------------
14 modules Cercle 1 strict :

alto_metrics.py, builtin_metrics.py, corpus.py, jobs.py,
metric_hooks.py, metric_registry.py, metrics.py, modules.py,
pipeline_benchmark.py, pipeline_comparison.py, pipeline_runner.py,
pipeline_spec_loader.py, results.py, runner.py.

+ 55 shims rétrocompat (incluant les shims des phases A et B).

État final ``picarones/measurements/``
--------------------------------------
42 modules + sous-package narrative complet (15 fichiers Python
+ 2 fichiers YAML data).

Validation (sandbox sans pytest)
--------------------------------
- ``import picarones.core.X`` fonctionne pour tous les modules
déplacés (paramétrage 20 cas testés).
- Identité préservée : ``shim.f is measurements.f`` (3 paires testées,
dont ``Fact`` du moteur narratif).
- 18 détecteurs accessibles via ``picarones.core.narrative.detectors``
(rétrocompat tests Sprint 20, 23, 29, 36, 44, 46, 73).
- 12 hooks document-level + 12 agrégateurs corpus-level enregistrés.
- Métriques (ALTO, ALTO) découvrables via le registre typé.
- ``build_synthesis()`` produit des phrases factuelles.
- Vues du chantier 3 (``advanced_taxonomy``) produisent du HTML.

Tests
-----
+275 lignes dans tests/test_phaseE_migration.py organisés en 8 classes :
TestMeasurementsRetrocompat (parametrize sur 20 modules),
TestNarrativePackageMigration, TestIdentityThroughShim,
TestCoreIsLean (parametrize sur les 13 modules Cercle 1 stricts),
TestHooksStillRegistered, TestNarrativeIntegration,
TestChantier3ViewsAfterPhaseE, TestArchitectureCerclesDocUpdated.

Bilan cumulé phases A + B + C + E
---------------------------------
- ``picarones/core/`` : 66 modules → 14 modules réels + 55 shims.
- ``picarones/extras/`` : 24 modules + 6 renderers (Cercle 3).
- ``picarones/measurements/`` : 42 modules + sous-package narrative
complet (Cercle 2).
- ``picarones/importers/`` : 6 shims (vers extras/importers/).
- Aucune fonctionnalité supprimée. Aucun import historique cassé.

Phase suivante (D)
------------------
- ``docs/api-stable.md`` listant l'API publique du Cercle 1.
- ``test_public_api.py`` qui échoue si un nom du Cercle 1 disparaît.
- Statuer sur la version : ``2.0.0`` (refonte architecturale)
ou ``1.3.0`` (extension non-breaking) selon politique semver.

docs/architecture-cercles.md

@@ -156,17 +156,40 @@ elles-mêmes dans `report/views/`, donc Cercle 2).
 
 ## Distinguer un module Cercle 1 vs Cercle 2
 
-Test concret : si on supprime ce module, est-ce que la phrase
-*« Picarones est un banc d'essai pour pipelines OCR/HTR/VLM »* reste
-vraie ?
-
-- **Oui** → Cercle 2 (le produit existe sans ce module).
-- **Non** → Cercle 1 (le module participe à la définition même).
+Critère **corrigé** (alignement architecture hexagonale / DDD) :
+
+> **Cercle 1 = abstractions et logique métier du domaine,
+> indépendantes de l'interface utilisateur. Stables entre versions
+> mineures.**
+>
+> **Cercle 2 = adapters concrets (engines, LLM, modules de référence),
+> couches d'interface (report, cli, web), et mesures au-delà du noyau
+> (measurements). Maintenus mais peuvent évoluer.**
+
+Le critère « si on supprime ce module, le produit reste viable »
+mélange deux questions distinctes (« est-ce indispensable ? » et
+« est-ce une abstraction stable ? »). On préfère le critère DDD :
+
+- **Cercle 1** : abstractions et orchestration qui définissent ce
+  que Picarones *est* logiquement (corpus, BaseModule, registres,
+  runner). Indépendant de l'interface utilisateur.
+- **Cercle 2** : ce qui rend le domaine utilisable concrètement
+  (adapters, mesures, présentation HTML, CLI).
 
 Exemple :
-- Sans `corpus.py` : impossible de charger un corpus → Cercle 1.
-- Sans `confusion.py` : on a toujours un bench fonctionnel sans
-  matrice de confusion → Cercle 2.
+- `corpus.py` → Cercle 1 (abstraction du domaine).
+- `runner.py` → Cercle 1 (orchestration du domaine).
+- `confusion.py` → Cercle 2 (mesure au-delà du noyau, dans
+  ``measurements/``).
+- `report/generator.py` → Cercle 2 (couche de présentation, même si
+  essentielle à l'usage pratique).
+- `engines/tesseract.py` → Cercle 2 (adapter concret).
+
+> Note : la convention « `base.py` dans le dossier du concept »
+> (`engines/base.py`, `llm/base.py`) reste dans son dossier d'origine.
+> Ces contrats sont logiquement Cercle 1 (API publique stable) mais
+> physiquement co-localisés avec leurs implémentations, comme dans
+> Django, SQLAlchemy, FastAPI. Convention universelle Python.
 - Sans `taxonomy_intra_doc.py` : on a toujours un bench complet et
   utile → Cercle 3.
 

picarones/core/baseline_comparison.py

@@ -1,229 +1,19 @@
-"""Comparaison à la baseline historique — Sprint 73 (A.I.3).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.baseline_comparison`.
 
-Sprint 73 — chantier 2 d'A.I.3 du plan d'évolution 2026.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.baseline_comparison import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-L'historique SQLite (``picarones/core/history.py``, Sprint 8)
-existe mais aucun détecteur narratif ne le lit.  Ce module fournit
-la couche de calcul qui répond à *« comment ce moteur se
-comporte-t-il sur ce corpus, **par rapport à ses runs précédents
-de mon institution** ? »*.
-
-Sortie typique
---------------
-Un dict par moteur :
-
-.. code-block:: python
-
-    {
-        "engine_name": "tesseract",
-        "cer_current": 0.052,
-        "cer_historical_mean": 0.041,
-        "cer_historical_median": 0.040,
-        "n_runs": 12,
-        "absolute_delta": 0.011,
-        "relative_delta": 0.268,        # +26,8 % vs moyenne
-        "off_baseline": True,
-    }
-
-Le détecteur narratif ``engine_off_baseline`` (Sprint 73)
-consomme cette structure pour émettre des Facts.
-
-Garde-fous
-----------
-- ``min_runs`` (défaut 5) : si l'historique pour le moteur×corpus
-  contient moins de runs, on retourne ``None`` plutôt que de
-  comparer à un échantillon trop petit.
-- ``corpus_name`` est utilisé pour ne comparer qu'aux runs **du
-  même corpus** (sinon on compare des pommes et des oranges :
-  registres paroissiaux vs imprimés modernes).
-- Le run courant lui-même n'est pas inclus dans la baseline (on
-  passe le ``current_run_id`` à exclure).
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-import statistics
-from typing import Optional
-
-logger = logging.getLogger(__name__)
-
-
-def compute_engine_baseline(
-    history,
-    engine_name: str,
-    corpus_name: str,
-    current_cer: float,
-    *,
-    current_run_id: Optional[str] = None,
-    min_runs: int = 5,
-    relative_delta_threshold: float = 0.20,
-) -> Optional[dict]:
-    """Compare le CER courant d'un moteur à sa moyenne historique
-    sur le **même corpus**.
-
-    Parameters
-    ----------
-    history:
-        Instance de ``BenchmarkHistory`` (ou compatible : doit
-        exposer une méthode ``query(engine, corpus, limit)``
-        retournant une liste d'``HistoryEntry`` avec attribut
-        ``cer_mean`` et ``run_id``).
-    engine_name:
-        Nom du moteur dont on calcule la baseline.
-    corpus_name:
-        Nom du corpus — limite la comparaison aux runs antérieurs
-        sur ce même corpus.
-    current_cer:
-        CER moyen observé dans le run courant.
-    current_run_id:
-        Si fourni, le run portant cet identifiant est exclu de la
-        baseline (utile quand le run courant est déjà enregistré
-        dans l'historique avant d'appeler ce calcul).
-    min_runs:
-        Nombre minimum de runs historiques pour que la
-        comparaison soit considérée fiable.  Sous ce seuil, on
-        retourne ``None``.
-    relative_delta_threshold:
-        Seuil au-delà duquel ``off_baseline`` vaut ``True``
-        (défaut : 0,20 = 20 % d'écart relatif).
-
-    Returns
-    -------
-    Optional[dict]
-        ``None`` si :
-        - moins de ``min_runs`` runs historiques disponibles
-        - ``current_cer`` est ``None`` ou négatif
-        - tous les CER historiques sont ``None``
-
-        Sinon, dict avec les champs documentés dans le module.
-    """
-    if current_cer is None or current_cer < 0:
-        return None
-    try:
-        entries = history.query(
-            engine=engine_name, corpus=corpus_name, limit=1000,
-        )
-    except Exception as exc:  # pragma: no cover — défense
-        logger.warning(
-            "[baseline_comparison] query history a levé : %s", exc,
-        )
-        return None
-
-    historical_cers: list[float] = []
-    for entry in entries:
-        if current_run_id is not None and entry.run_id == current_run_id:
-            continue
-        cer = entry.cer_mean
-        if cer is None or cer < 0:
-            continue
-        historical_cers.append(float(cer))
-
-    if len(historical_cers) < min_runs:
-        return None
-
-    mean = statistics.fmean(historical_cers)
-    median = statistics.median(historical_cers)
-    absolute_delta = current_cer - mean
-    if mean > 0:
-        relative_delta = absolute_delta / mean
-    elif current_cer == 0:
-        relative_delta = 0.0
-    else:
-        # Baseline à 0 mais CER courant > 0 : écart infini —
-        # convention : on signale comme off_baseline avec
-        # relative_delta = None.
-        relative_delta = None
-
-    off_baseline = (
-        relative_delta is not None
-        and abs(relative_delta) > relative_delta_threshold
-    )
-
-    return {
-        "engine_name": engine_name,
-        "corpus_name": corpus_name,
-        "cer_current": float(current_cer),
-        "cer_historical_mean": mean,
-        "cer_historical_median": median,
-        "n_runs": len(historical_cers),
-        "absolute_delta": absolute_delta,
-        "relative_delta": relative_delta,
-        "off_baseline": off_baseline,
-    }
-
-
-def compute_corpus_difficulty_percentile(
-    history,
-    current_difficulty: float,
-    *,
-    min_runs: int = 5,
-) -> Optional[dict]:
-    """Place la difficulté du corpus courant dans la distribution
-    des difficultés historiques.
-
-    Lit les difficultés stockées dans ``HistoryEntry.metadata``
-    sous la clé ``difficulty`` (convention de
-    ``picarones/core/difficulty.py``).
-
-    Returns
-    -------
-    Optional[dict]
-        ``{
-            "current_difficulty": float,
-            "percentile": float,            # 0..100
-            "n_runs": int,
-            "median_historical": float,
-            "harder_than_usual": bool,      # percentile > 75
-            "easier_than_usual": bool,      # percentile < 25
-        }``
-        ou ``None`` si moins de ``min_runs`` runs historiques ont
-        une difficulté enregistrée.
-    """
-    if current_difficulty is None:
-        return None
-    try:
-        entries = history.query(limit=1000)
-    except Exception as exc:  # pragma: no cover
-        logger.warning(
-            "[baseline_comparison] query history a levé : %s", exc,
-        )
-        return None
-
-    historical_difficulties: list[float] = []
-    for entry in entries:
-        diff = entry.metadata.get("difficulty") if entry.metadata else None
-        if diff is None:
-            continue
-        try:
-            historical_difficulties.append(float(diff))
-        except (TypeError, ValueError):
-            continue
-
-    if len(historical_difficulties) < min_runs:
-        return None
-
-    sorted_diff = sorted(historical_difficulties)
-    n = len(sorted_diff)
-    # Percentile = % de corpus historiques de difficulté ≤
-    # current_difficulty.  Convention courante (P_i = i/n × 100).
-    n_below = sum(1 for d in sorted_diff if d <= current_difficulty)
-    percentile = (n_below / n) * 100.0
-    median = statistics.median(sorted_diff)
-
-    return {
-        "current_difficulty": float(current_difficulty),
-        "percentile": percentile,
-        "n_runs": n,
-        "median_historical": median,
-        "harder_than_usual": percentile > 75.0,
-        "easier_than_usual": percentile < 25.0,
-    }
-
+from picarones.measurements.baseline_comparison import *  # noqa: F401, F403
 
-__all__ = [
-    "compute_engine_baseline",
-    "compute_corpus_difficulty_percentile",
-]
+import picarones.measurements.baseline_comparison as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/builtin_hooks.py

@@ -1,582 +1,19 @@
-"""Enregistrement des hooks de métriques natifs de Picarones.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.builtin_hooks`.
 
-Chantier 2 du plan d'évolution post-Sprint 97.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.builtin_hooks import ...``) de continuer
+à fonctionner sans modification.
 
-Ce module **migre** les 12 hooks document-level et 12 agrégateurs
-corpus-level qui étaient codés en dur dans
-``picarones.core.runner._compute_document_result`` et autour de la
-boucle d'agrégation (lignes 794-827 du runner pré-chantier-2).
-
-Approche additive — rétrocompat stricte
----------------------------------------
-Tous les hooks sont enregistrés sur les profils ``standard``,
-``philological``, ``diagnostics`` et ``full`` (i.e. activés par
-défaut quand le runner est appelé sans paramètre ``profile``). Le
-profil ``minimal`` n'active aucun hook (pour bench massif où seul
-CER/WER comptent). Les profils ``economics`` et ``pipeline`` sont
-réservés pour des hooks futurs.
-
-L'import de ce module **suffit** à peupler les registres :
-:mod:`picarones.core.metric_hooks` se contente d'exposer les
-décorateurs ; le runner ne dépend que d'une seule fonction —
-``select_document_hooks(profile)`` — pour découvrir les hooks actifs.
-
-Liste complète des hooks (Sprint d'origine)
--------------------------------------------
-**Document-level** (12) :
-
-- ``confusion``           (Sprint 5)  — ``confusion_matrix``
-- ``char_scores``         (Sprint 5)  — ``char_scores``
-- ``taxonomy``            (Sprint 5)  — ``taxonomy``
-- ``structure``           (Sprint 5)  — ``structure``
-- ``image_quality``       (Sprint 5)  — ``image_quality``
-- ``line_metrics``        (Sprint 10) — ``line_metrics``
-- ``hallucination``       (Sprint 10) — ``hallucination_metrics``
-- ``calibration``         (Sprint 42) — ``calibration_metrics``
-- ``philological``        (Sprint 61) — ``philological_metrics``
-- ``searchability``       (Sprint 86) — ``searchability_metrics``
-- ``numerical_sequences`` (Sprint 86) — ``numerical_sequence_metrics``
-- ``readability``         (Sprint 87) — ``readability_metrics``
-
-**Corpus-level** (12) : un agrégateur par hook documentaire,
-remplissant le champ ``aggregated_*`` correspondant du
-``EngineReport``.
-
-Le hook ``ner`` (Sprint 40) reste hors de ce mécanisme : il dépend
-d'un ``EntityExtractor`` injecté à la main par l'utilisateur, ce
-qui n'entre pas dans la sémantique des profils.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-from collections import Counter
-from typing import Any, Optional
-
-from picarones.core.metric_hooks import (
-    PROFILE_DIAGNOSTICS,
-    PROFILE_FULL,
-    PROFILE_PHILOLOGICAL,
-    PROFILE_STANDARD,
-    register_corpus_aggregator,
-    register_document_metric,
-)
-
-logger = logging.getLogger(__name__)
-
-
-# Profils dans lesquels les 12 hooks "standard" s'activent. Égalent
-# par construction le comportement runner pré-chantier-2 ; le profil
-# ``minimal`` est volontairement absent.
-_STANDARD_PROFILES = (
-    PROFILE_STANDARD,
-    PROFILE_PHILOLOGICAL,
-    PROFILE_DIAGNOSTICS,
-    PROFILE_FULL,
-)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Helper de calibration (déplacé depuis runner.py — chantier 2)
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def calibration_from_engine_result(
-    ground_truth: str,
-    token_confidences: list,
-) -> Optional[dict]:
-    """Aligne les ``token_confidences`` du moteur sur la GT (bag-of-words)
-    pour produire les listes parallèles ``confidences`` / ``is_correct``,
-    puis appelle ``compute_calibration_metrics`` (Sprint 39).
-
-    Convention d'alignement (proxy bag-of-words avec multiplicité, comme
-    ``oracle_token_recall`` du Sprint 35) : un token de l'hypothèse est
-    "correct" si la GT contient encore une occurrence de ce token.
-
-    Les confidences ``> 1.0`` sont supposées en pourcentage et
-    normalisées à ``[0, 1]``. Les confidences négatives (Tesseract met
-    -1 pour les non-mots) sont ignorées.
-    """
-    from picarones.core.calibration import compute_calibration_metrics
-
-    if not token_confidences:
-        return None
-
-    gt_counter = Counter((ground_truth or "").split())
-    confidences: list[float] = []
-    is_correct: list[int] = []
-
-    for tc in token_confidences:
-        if not isinstance(tc, dict):
-            continue
-        token = str(tc.get("token", ""))
-        if not token:
-            continue
-        try:
-            conf = float(tc.get("confidence"))
-        except (TypeError, ValueError):
-            continue
-        if conf < 0:
-            continue
-        if conf > 1.0:
-            conf = conf / 100.0
-        if not 0.0 <= conf <= 1.0:
-            continue
-        if gt_counter[token] > 0:
-            is_correct.append(1)
-            gt_counter[token] -= 1
-        else:
-            is_correct.append(0)
-        confidences.append(conf)
-
-    if not confidences:
-        return None
-    return compute_calibration_metrics(confidences, is_correct)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Document-level hooks (12)
-# ──────────────────────────────────────────────────────────────────────────
-
-
-@register_document_metric(
-    name="confusion",
-    attribute="confusion_matrix",
-    profiles=_STANDARD_PROFILES,
-    requires_success=True,
-)
-def _confusion_hook(*, ground_truth, hypothesis, **_):
-    from picarones.core.confusion import build_confusion_matrix
-    return build_confusion_matrix(ground_truth, hypothesis).as_dict()
-
-
-@register_document_metric(
-    name="char_scores",
-    attribute="char_scores",
-    profiles=_STANDARD_PROFILES,
-    requires_success=True,
-)
-def _char_scores_hook(*, ground_truth, hypothesis, **_):
-    from picarones.core.char_scores import (
-        compute_diacritic_score,
-        compute_ligature_score,
-    )
-    lig = compute_ligature_score(ground_truth, hypothesis)
-    diac = compute_diacritic_score(ground_truth, hypothesis)
-    return {"ligature": lig.as_dict(), "diacritic": diac.as_dict()}
-
-
-@register_document_metric(
-    name="taxonomy",
-    attribute="taxonomy",
-    profiles=_STANDARD_PROFILES,
-    requires_success=True,
-)
-def _taxonomy_hook(*, ground_truth, hypothesis, **_):
-    from picarones.core.taxonomy import classify_errors
-    return classify_errors(ground_truth, hypothesis).as_dict()
-
-
-@register_document_metric(
-    name="structure",
-    attribute="structure",
-    profiles=_STANDARD_PROFILES,
-    requires_success=True,
-)
-def _structure_hook(*, ground_truth, hypothesis, **_):
-    from picarones.core.structure import analyze_structure
-    return analyze_structure(ground_truth, hypothesis).as_dict()
-
-
-@register_document_metric(
-    name="line_metrics",
-    attribute="line_metrics",
-    profiles=_STANDARD_PROFILES,
-    requires_success=True,
-)
-def _line_metrics_hook(*, ground_truth, hypothesis, **_):
-    from picarones.core.line_metrics import compute_line_metrics
-    return compute_line_metrics(ground_truth, hypothesis).as_dict()
-
-
-@register_document_metric(
-    name="hallucination",
-    attribute="hallucination_metrics",
-    profiles=_STANDARD_PROFILES,
-    requires_success=True,
-)
-def _hallucination_hook(*, ground_truth, hypothesis, **_):
-    from picarones.core.hallucination import compute_hallucination_metrics
-    return compute_hallucination_metrics(ground_truth, hypothesis).as_dict()
-
-
-@register_document_metric(
-    name="calibration",
-    attribute="calibration_metrics",
-    profiles=_STANDARD_PROFILES,
-    requires_token_confidences=True,
-)
-def _calibration_hook(*, ground_truth, ocr_result, **_):
-    return calibration_from_engine_result(
-        ground_truth, ocr_result.token_confidences,
-    )
-
-
-@register_document_metric(
-    name="image_quality",
-    attribute="image_quality",
-    profiles=_STANDARD_PROFILES,
-    # Pas de requires_success : on analyse l'image quel que soit le
-    # résultat OCR (pour comparer un échec OCR à la qualité image).
-)
-def _image_quality_hook(*, image_path, **_):
-    from picarones.core.image_quality import analyze_image_quality
-    iq = analyze_image_quality(image_path)
-    if iq.error is not None:
-        return None
-    return iq.as_dict()
-
-
-@register_document_metric(
-    name="philological",
-    attribute="philological_metrics",
-    profiles=_STANDARD_PROFILES,
-    # Pas de requires_success : le runner pré-chantier-2 calculait
-    # même sur échec OCR (avec hyp=""). Les modules philologiques
-    # retournent ``None`` quand la GT n'a pas de signal exploitable
-    # — comportement adaptive intact.
-)
-def _philological_hook(*, ground_truth, hypothesis, **_):
-    from picarones.core.philological_runner import compute_philological_metrics
-    return compute_philological_metrics(ground_truth, hypothesis)
-
-
-@register_document_metric(
-    name="searchability",
-    attribute="searchability_metrics",
-    profiles=_STANDARD_PROFILES,
-)
-def _searchability_hook(*, ground_truth, hypothesis, **_):
-    from picarones.core.searchability_runner import compute_searchability_metrics
-    return compute_searchability_metrics(ground_truth, hypothesis)
-
-
-@register_document_metric(
-    name="numerical_sequences",
-    attribute="numerical_sequence_metrics",
-    profiles=_STANDARD_PROFILES,
-)
-def _numerical_sequences_hook(*, ground_truth, hypothesis, **_):
-    from picarones.core.numerical_sequences_runner import (
-        compute_numerical_sequence_metrics_adaptive,
-    )
-    return compute_numerical_sequence_metrics_adaptive(ground_truth, hypothesis)
-
-
-@register_document_metric(
-    name="readability",
-    attribute="readability_metrics",
-    profiles=_STANDARD_PROFILES,
-)
-def _readability_hook(*, ground_truth, hypothesis, corpus_lang, **_):
-    from picarones.core.readability_runner import compute_readability_metrics
-    return compute_readability_metrics(ground_truth, hypothesis, lang=corpus_lang)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Corpus-level aggregators (12)
-# ──────────────────────────────────────────────────────────────────────────
-
-
-@register_corpus_aggregator(
-    name="confusion",
-    attribute="aggregated_confusion",
-    profiles=_STANDARD_PROFILES,
-)
-def _aggregate_confusion(doc_results: list) -> Optional[dict]:
-    from picarones.core.confusion import (
-        ConfusionMatrix, aggregate_confusion_matrices,
-    )
-    matrices = [
-        ConfusionMatrix(**dr.confusion_matrix)
-        for dr in doc_results
-        if dr.confusion_matrix is not None
-    ]
-    if not matrices:
-        return None
-    return aggregate_confusion_matrices(matrices).as_compact_dict(min_count=2)
-
-
-@register_corpus_aggregator(
-    name="char_scores",
-    attribute="aggregated_char_scores",
-    profiles=_STANDARD_PROFILES,
-)
-def _aggregate_char_scores(doc_results: list) -> Optional[dict]:
-    from picarones.core.char_scores import (
-        DiacriticScore,
-        LigatureScore,
-        aggregate_diacritic_scores,
-        aggregate_ligature_scores,
-    )
-    lig_scores = [
-        LigatureScore(**dr.char_scores["ligature"])
-        for dr in doc_results
-        if dr.char_scores is not None
-    ]
-    diac_scores = [
-        DiacriticScore(**dr.char_scores["diacritic"])
-        for dr in doc_results
-        if dr.char_scores is not None
-    ]
-    if not lig_scores:
-        return None
-    return {
-        "ligature": aggregate_ligature_scores(lig_scores),
-        "diacritic": aggregate_diacritic_scores(diac_scores),
-    }
-
-
-@register_corpus_aggregator(
-    name="taxonomy",
-    attribute="aggregated_taxonomy",
-    profiles=_STANDARD_PROFILES,
-)
-def _aggregate_taxonomy(doc_results: list) -> Optional[dict]:
-    from picarones.core.taxonomy import TaxonomyResult, aggregate_taxonomy
-    results = [
-        TaxonomyResult.from_dict(dr.taxonomy)
-        for dr in doc_results
-        if dr.taxonomy is not None
-    ]
-    if not results:
-        return None
-    return aggregate_taxonomy(results)
-
-
-@register_corpus_aggregator(
-    name="structure",
-    attribute="aggregated_structure",
-    profiles=_STANDARD_PROFILES,
-)
-def _aggregate_structure(doc_results: list) -> Optional[dict]:
-    from picarones.core.structure import StructureResult, aggregate_structure
-    results = [
-        StructureResult.from_dict(dr.structure)
-        for dr in doc_results
-        if dr.structure is not None
-    ]
-    if not results:
-        return None
-    return aggregate_structure(results)
-
-
-@register_corpus_aggregator(
-    name="image_quality",
-    attribute="aggregated_image_quality",
-    profiles=_STANDARD_PROFILES,
-)
-def _aggregate_image_quality(doc_results: list) -> Optional[dict]:
-    from picarones.core.image_quality import (
-        ImageQualityResult, aggregate_image_quality,
-    )
-    results = [
-        ImageQualityResult.from_dict(dr.image_quality)
-        for dr in doc_results
-        if dr.image_quality is not None
-    ]
-    if not results:
-        return None
-    return aggregate_image_quality(results)
-
-
-@register_corpus_aggregator(
-    name="line_metrics",
-    attribute="aggregated_line_metrics",
-    profiles=_STANDARD_PROFILES,
-)
-def _aggregate_line_metrics(doc_results: list) -> Optional[dict]:
-    from picarones.core.line_metrics import (
-        LineMetrics, aggregate_line_metrics,
-    )
-    results = [
-        LineMetrics.from_dict(dr.line_metrics)
-        for dr in doc_results
-        if dr.line_metrics is not None
-    ]
-    if not results:
-        return None
-    return aggregate_line_metrics(results)
-
-
-@register_corpus_aggregator(
-    name="hallucination",
-    attribute="aggregated_hallucination",
-    profiles=_STANDARD_PROFILES,
-)
-def _aggregate_hallucination(doc_results: list) -> Optional[dict]:
-    from picarones.core.hallucination import (
-        HallucinationMetrics, aggregate_hallucination_metrics,
-    )
-    results = [
-        HallucinationMetrics.from_dict(dr.hallucination_metrics)
-        for dr in doc_results
-        if dr.hallucination_metrics is not None
-    ]
-    if not results:
-        return None
-    return aggregate_hallucination_metrics(results)
-
-
-@register_corpus_aggregator(
-    name="calibration",
-    attribute="aggregated_calibration",
-    profiles=_STANDARD_PROFILES,
-)
-def _aggregate_calibration(doc_results: list) -> Optional[dict]:
-    """Agrège la calibration micro sur tous les docs.
-
-    Recalcule ECE/MCE à partir de la **somme des bins** de chaque
-    document : pour chaque bin, on additionne ``count``, on agrège la
-    confiance moyenne pondérée par count, et on agrège l'accuracy
-    pondérée par count. L'ECE micro est ensuite la moyenne pondérée
-    par bin de ``|conf - acc|``.
-
-    Comportement déplacé verbatim depuis ``runner._aggregate_calibration``
-    (chantier 2 — rétrocompat octet par octet du sérialisé).
-    """
-    relevant = [
-        dr for dr in doc_results
-        if dr.calibration_metrics is not None
-        and (dr.calibration_metrics.get("bins") or [])
-    ]
-    if not relevant:
-        return None
-
-    n_bins = relevant[0].calibration_metrics.get("n_bins", 10)
-    sum_conf: list[float] = [0.0] * n_bins
-    sum_acc: list[float] = [0.0] * n_bins
-    counts: list[int] = [0] * n_bins
-    bin_lows: list[float] = [
-        b["bin_low"] for b in relevant[0].calibration_metrics["bins"]
-    ]
-    bin_highs: list[float] = [
-        b["bin_high"] for b in relevant[0].calibration_metrics["bins"]
-    ]
-
-    for dr in relevant:
-        m = dr.calibration_metrics
-        if m.get("n_bins") != n_bins:
-            logger.warning(
-                "[aggregate_calibration] %s : n_bins=%s ≠ %s — ignoré",
-                dr.doc_id, m.get("n_bins"), n_bins,
-            )
-            continue
-        for k, b in enumerate(m["bins"]):
-            n = int(b.get("count") or 0)
-            if n == 0:
-                continue
-            counts[k] += n
-            sum_conf[k] += float(b.get("avg_confidence") or 0.0) * n
-            sum_acc[k] += float(b.get("accuracy") or 0.0) * n
-
-    total = sum(counts)
-    if total == 0:
-        return None
-
-    bins: list[dict] = []
-    ece = 0.0
-    mce = 0.0
-    for k in range(n_bins):
-        n = counts[k]
-        if n == 0:
-            bins.append({
-                "bin_low": bin_lows[k] if k < len(bin_lows) else k / n_bins,
-                "bin_high": bin_highs[k] if k < len(bin_highs) else (k + 1) / n_bins,
-                "avg_confidence": None,
-                "accuracy": None,
-                "count": 0,
-                "gap": None,
-            })
-            continue
-        avg_conf = sum_conf[k] / n
-        accuracy = sum_acc[k] / n
-        gap = abs(avg_conf - accuracy)
-        bins.append({
-            "bin_low": bin_lows[k] if k < len(bin_lows) else k / n_bins,
-            "bin_high": bin_highs[k] if k < len(bin_highs) else (k + 1) / n_bins,
-            "avg_confidence": avg_conf,
-            "accuracy": accuracy,
-            "count": n,
-            "gap": gap,
-        })
-        ece += (n / total) * gap
-        if gap > mce:
-            mce = gap
-
-    overall_acc = sum(sum_acc) / total
-    overall_conf = sum(sum_conf) / total
-
-    return {
-        "ece": ece,
-        "mce": mce,
-        "n_bins": n_bins,
-        "n_predictions": total,
-        "overall_accuracy": overall_acc,
-        "overall_confidence": overall_conf,
-        "bins": bins,
-        "doc_count": len(relevant),
-    }
-
-
-@register_corpus_aggregator(
-    name="philological",
-    attribute="aggregated_philological",
-    profiles=_STANDARD_PROFILES,
-)
-def _aggregate_philological(doc_results: list) -> Optional[dict]:
-    from picarones.core.philological_runner import aggregate_philological_metrics
-    return aggregate_philological_metrics(
-        [dr.philological_metrics for dr in doc_results],
-    )
-
-
-@register_corpus_aggregator(
-    name="searchability",
-    attribute="aggregated_searchability",
-    profiles=_STANDARD_PROFILES,
-)
-def _aggregate_searchability(doc_results: list) -> Optional[dict]:
-    from picarones.core.searchability_runner import aggregate_searchability_metrics
-    return aggregate_searchability_metrics(
-        [dr.searchability_metrics for dr in doc_results],
-    )
-
-
-@register_corpus_aggregator(
-    name="numerical_sequences",
-    attribute="aggregated_numerical_sequences",
-    profiles=_STANDARD_PROFILES,
-)
-def _aggregate_numerical_sequences(doc_results: list) -> Optional[dict]:
-    from picarones.core.numerical_sequences_runner import (
-        aggregate_numerical_sequence_metrics,
-    )
-    return aggregate_numerical_sequence_metrics(
-        [dr.numerical_sequence_metrics for dr in doc_results],
-    )
-
-
-@register_corpus_aggregator(
-    name="readability",
-    attribute="aggregated_readability",
-    profiles=_STANDARD_PROFILES,
-)
-def _aggregate_readability(doc_results: list) -> Optional[dict]:
-    from picarones.core.readability_runner import aggregate_readability_metrics
-    return aggregate_readability_metrics(
-        [dr.readability_metrics for dr in doc_results],
-    )
-
+from picarones.measurements.builtin_hooks import *  # noqa: F401, F403
 
-__all__ = ["calibration_from_engine_result"]
+import picarones.measurements.builtin_hooks as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/calibration.py

@@ -1,323 +1,19 @@
-"""Calibration des moteurs : ECE, MCE, reliability diagram.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.calibration`.
 
-Sprint 39 — A.II.1.b du plan d'évolution 2026 : couche de calcul pure.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.calibration import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-Tous les moteurs OCR cibles fournissent une confidence par token ou par
-ligne (Tesseract via le ``tsv``, Pero OCR via le ``PageLayout``,
-Mistral OCR via ``confidence``, Google Vision via ``Word.confidence``).
-La question naturelle pour un workflow patrimonial est : *« quand le
-moteur dit qu'il est sûr, est-il vraiment sûr ? »*.  Pour une équipe
-qui doit vérifier humainement un corpus de 50 000 pages, la différence
-entre vérifier 100 % vs 15 % du volume est l'effet de la calibration.
-
-Ce module fournit les trois mesures classiques :
-
-- **Expected Calibration Error (ECE)** — moyenne pondérée par bin de
-  l'écart absolu entre confiance moyenne et précision moyenne.
-  ``ECE = 0`` ↔ moteur parfaitement calibré ; ``ECE`` élevé ↔ écart
-  systématique entre confiance affichée et fiabilité réelle.
-- **Maximum Calibration Error (MCE)** — max de cet écart sur les bins.
-  Utile pour repérer le pire mensonge du moteur (ex. il dit toujours
-  95 % de confiance et il a tort une fois sur deux).
-- **Reliability diagram** — table ``[(bin_low, bin_high, avg_conf,
-  accuracy, count)]`` qui peut être rendue en SVG côté serveur ou en
-  Chart.js côté navigateur dans un sprint suivant.
-
-Stratégie de découpage
-----------------------
-Comme pour le NER (Sprint 38) et la divergence (Sprints 35-37),
-on découpe :
-
-- **Sprint 39** (ici) — couche de calcul pure : entrée = deux listes
-  parallèles ``confidences`` (∈ [0, 1]) et ``is_correct`` (bool/0-1).
-  Aucune dépendance externe.
-- **Sprint à venir** — exposition de ``token_confidences`` sur
-  ``EngineResult``, alignement caractère/token avec la GT pour produire
-  ``is_correct``, intégration dans le runner et vue HTML reliability.
-
-Ce qui est explicitement hors scope
------------------------------------
-Ce sprint ne touche **aucun adaptateur OCR**.  Aucune confiance n'est
-extraite ; on calcule uniquement à partir de séquences de prédictions
-fournies en entrée.  C'est ce qui permet de tester rigoureusement les
-invariants mathématiques (ECE = 0 ↔ calibré, ECE = |bias| pour bias
-constant, etc.) sans dépendre d'un backend.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-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 CalibrationBin:
-    """Un bin du reliability diagram.
-
-    Attributs
-    ---------
-    bin_low, bin_high:
-        Bornes du bin sur l'axe de confiance (``[bin_low, bin_high)`` —
-        sauf le dernier bin qui inclut ``1.0``).
-    avg_confidence:
-        Moyenne des confidences des prédictions tombées dans le bin.
-        ``None`` si le bin est vide.
-    accuracy:
-        Fraction de prédictions correctes dans le bin (``∈ [0, 1]``).
-        ``None`` si le bin est vide.
-    count:
-        Nombre de prédictions dans le bin.
-    """
-
-    bin_low: float
-    bin_high: float
-    avg_confidence: float | None
-    accuracy: float | None
-    count: int
-
-    @property
-    def gap(self) -> float | None:
-        """Écart absolu ``|confidence - accuracy|`` ou ``None`` si vide."""
-        if self.avg_confidence is None or self.accuracy is None:
-            return None
-        return abs(self.avg_confidence - self.accuracy)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Validation
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def _validate_inputs(
-    confidences: list[float],
-    is_correct: list[bool | int],
-) -> None:
-    if len(confidences) != len(is_correct):
-        raise ValueError(
-            f"Longueurs incompatibles : confidences={len(confidences)} "
-            f"vs is_correct={len(is_correct)}"
-        )
-    for i, c in enumerate(confidences):
-        if not (0.0 <= float(c) <= 1.0):
-            raise ValueError(
-                f"Confiance hors [0, 1] à l'index {i} : {c!r}"
-            )
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Reliability diagram (binning)
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def reliability_diagram(
-    confidences: Iterable[float],
-    is_correct: Iterable[bool | int],
-    n_bins: int = 10,
-) -> list[CalibrationBin]:
-    """Découpe les prédictions en ``n_bins`` bins équidistants par confiance
-    et calcule pour chacun la confiance moyenne, la précision et le compte.
-
-    Parameters
-    ----------
-    confidences:
-        Confidences des prédictions, ``∈ [0, 1]``.
-    is_correct:
-        Indicateur booléen (1 = prédiction correcte, 0 = incorrecte).
-    n_bins:
-        Nombre de bins (défaut : 10).  Bornes : ``[k/n_bins, (k+1)/n_bins)``
-        sauf le dernier bin qui inclut ``1.0``.
-
-    Returns
-    -------
-    list[CalibrationBin]
-        Liste de ``n_bins`` bins, dans l'ordre croissant des confidences.
-    """
-    if n_bins < 1:
-        raise ValueError(f"n_bins doit être ≥ 1 — reçu {n_bins}")
-
-    confs = [float(c) for c in confidences]
-    correct = [int(bool(x)) for x in is_correct]
-    _validate_inputs(confs, correct)
-
-    bin_width = 1.0 / n_bins
-    sums: list[float] = [0.0] * n_bins
-    correct_counts: list[int] = [0] * n_bins
-    counts: list[int] = [0] * n_bins
-
-    for c, ok in zip(confs, correct):
-        # Calcul du bin index par multiplication ``c * n_bins`` plutôt que
-        # division ``c / bin_width`` pour éviter les pièges de
-        # représentation flottante (ex. ``0.6 / 0.1 = 5.999…`` en IEEE 754
-        # qui placerait 0.6 dans le bin [0.5, 0.6) au lieu de [0.6, 0.7)).
-        if c >= 1.0:
-            idx = n_bins - 1
-        else:
-            idx = int(c * n_bins)
-            # Garde-fou en cas d'arrondi flottant
-            if idx >= n_bins:
-                idx = n_bins - 1
-            elif idx < 0:
-                idx = 0
-        sums[idx] += c
-        correct_counts[idx] += ok
-        counts[idx] += 1
-
-    bins: list[CalibrationBin] = []
-    for k in range(n_bins):
-        low = k * bin_width
-        high = (k + 1) * bin_width
-        n = counts[k]
-        if n == 0:
-            bins.append(CalibrationBin(low, high, None, None, 0))
-        else:
-            bins.append(CalibrationBin(
-                bin_low=low,
-                bin_high=high,
-                avg_confidence=sums[k] / n,
-                accuracy=correct_counts[k] / n,
-                count=n,
-            ))
-    return bins
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# ECE et MCE
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def expected_calibration_error(
-    confidences: Iterable[float],
-    is_correct: Iterable[bool | int],
-    n_bins: int = 10,
-) -> float:
-    """Expected Calibration Error : moyenne pondérée par bin de l'écart
-    absolu confiance ↔ précision.
-
-    ``ECE = sum_k (n_k / N) * |avg_conf_k - accuracy_k|``
-
-    où la somme porte sur les bins non vides.
-
-    Returns
-    -------
-    float
-        ``∈ [0, 1]``.  ``0`` ↔ calibration parfaite.
-    """
-    bins = reliability_diagram(confidences, is_correct, n_bins=n_bins)
-    total = sum(b.count for b in bins)
-    if total == 0:
-        return 0.0
-    ece = 0.0
-    for b in bins:
-        if b.count == 0 or b.gap is None:
-            continue
-        ece += (b.count / total) * b.gap
-    return ece
-
-
-def maximum_calibration_error(
-    confidences: Iterable[float],
-    is_correct: Iterable[bool | int],
-    n_bins: int = 10,
-) -> float:
-    """Maximum Calibration Error : pire écart confiance ↔ précision sur
-    tous les bins non vides.
-
-    Utile pour repérer un mensonge ponctuel du moteur (ex. il dit 95 %
-    de confiance et il a tort une fois sur deux dans ce bin).
-
-    Returns
-    -------
-    float
-        ``∈ [0, 1]``.  ``0`` ↔ calibration parfaite.
-    """
-    bins = reliability_diagram(confidences, is_correct, n_bins=n_bins)
-    gaps = [b.gap for b in bins if b.gap is not None]
-    return max(gaps) if gaps else 0.0
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Vue agrégée
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def compute_calibration_metrics(
-    confidences: Iterable[float],
-    is_correct: Iterable[bool | int],
-    n_bins: int = 10,
-) -> dict:
-    """Calcule l'ensemble des métriques de calibration en un appel.
-
-    Returns
-    -------
-    dict
-        ``{
-            "ece":   float,
-            "mce":   float,
-            "n_bins": int,
-            "n_predictions": int,
-            "overall_accuracy": float,
-            "overall_confidence": float,
-            "bins": [
-                {"bin_low", "bin_high", "avg_confidence",
-                 "accuracy", "count", "gap"},
-                ...
-            ],
-        }``
-    """
-    confs = list(confidences)
-    correct = list(is_correct)
-    bins = reliability_diagram(confs, correct, n_bins=n_bins)
-    total = sum(b.count for b in bins)
-    overall_acc = (
-        sum(int(bool(x)) for x in correct) / total if total > 0 else 0.0
-    )
-    overall_conf = (
-        sum(float(c) for c in confs) / total if total > 0 else 0.0
-    )
-
-    ece = 0.0
-    if total > 0:
-        for b in bins:
-            if b.gap is None:
-                continue
-            ece += (b.count / total) * b.gap
-    mce = max((b.gap for b in bins if b.gap is not None), default=0.0)
-
-    return {
-        "ece": ece,
-        "mce": mce,
-        "n_bins": n_bins,
-        "n_predictions": total,
-        "overall_accuracy": overall_acc,
-        "overall_confidence": overall_conf,
-        "bins": [
-            {
-                "bin_low": b.bin_low,
-                "bin_high": b.bin_high,
-                "avg_confidence": b.avg_confidence,
-                "accuracy": b.accuracy,
-                "count": b.count,
-                "gap": b.gap,
-            }
-            for b in bins
-        ],
-    }
-
+from picarones.measurements.calibration import *  # noqa: F401, F403
 
-__all__ = [
-    "CalibrationBin",
-    "reliability_diagram",
-    "expected_calibration_error",
-    "maximum_calibration_error",
-    "compute_calibration_metrics",
-]
+import picarones.measurements.calibration as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/char_scores.py

@@ -1,370 +1,19 @@
-"""Scores de reconnaissance des ligatures et des diacritiques.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.char_scores`.
 
-Ces métriques sont spécifiques aux documents patrimoniaux (manuscrits, imprimés
-anciens) où ligatures et diacritiques jouent un rôle paléographique essentiel.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.char_scores import ...``) de continuer
+à fonctionner sans modification.
 
-Ligatures
----------
-Caractères encodés comme une séquence unique dans Unicode mais représentant
-deux ou plusieurs glyphes fusionnés : fi (fi), fl (fl), œ, æ, etc.
-
-Pour chaque ligature présente dans le GT, on vérifie si l'OCR a produit
-soit le caractère Unicode équivalent, soit la séquence décomposée équivalente.
-
-Diacritiques
------------
-Accents, cédilles, trémas et autres signes diacritiques. Pour chaque caractère
-accentué dans le GT, on vérifie si l'OCR a conservé le diacritique ou l'a
-remplacé par la lettre de base.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import Optional
-
-import unicodedata
-
-
-# ---------------------------------------------------------------------------
-# Tables de ligatures (char ligature → séquences équivalentes acceptées)
-# ---------------------------------------------------------------------------
-
-#: Table principale des ligatures et leurs équivalents acceptés.
-#: Clé = caractère ligature Unicode ; valeur = liste de séquences équivalentes.
-LIGATURE_TABLE: dict[str, list[str]] = {
-    # Ligatures typographiques latines (Unicode Letterlike Symbols / Alphabetic Presentation Forms)
-    "\uFB00": ["ff"],           # ff ff
-    "\uFB01": ["fi"],           # fi fi
-    "\uFB02": ["fl"],           # fl fl
-    "\uFB03": ["ffi"],          # ffi ffi
-    "\uFB04": ["ffl"],          # ffl ffl
-    "\uFB05": ["st", "\u017Ft"], # ſt st / ſt
-    "\uFB06": ["st"],           # st st (variante)
-    # Ligatures latines patrimoniales (Unicode Latin Extended Additional)
-    "\u0153": ["oe"],           # œ oe
-    "\u00E6": ["ae"],           # æ ae
-    "\u0152": ["OE"],           # ΠOE
-    "\u00C6": ["AE"],           # Æ AE
-    # Abréviations latines / médiévales
-    "\uA751": ["per", "p\u0332"],  # ꝑ per / p̲
-    "\uA753": ["pro"],          # ꝓ pro
-    "\uA757": ["que"],          # ꝗ que
-    # Ligatures germaniques
-    "\u00DF": ["ss"],           # ß ss
-    "\u1E9E": ["SS"],           # ẞ SS
-}
-
-# Ensemble de toutes les ligatures pour recherche rapide
-_ALL_LIGATURES: frozenset[str] = frozenset(LIGATURE_TABLE)
-
-# Mapping inverse : séquence → ligature
-_SEQ_TO_LIGATURE: dict[str, str] = {}
-for _lig, _seqs in LIGATURE_TABLE.items():
-    for _seq in _seqs:
-        _SEQ_TO_LIGATURE[_seq] = _lig
-
-
-# ---------------------------------------------------------------------------
-# Table des caractères diacritiques
-# ---------------------------------------------------------------------------
-
-def _build_diacritic_map() -> dict[str, str]:
-    """Construit automatiquement la table diacritique depuis l'Unicode."""
-    table: dict[str, str] = {}
-    for codepoint in range(0x00C0, 0x0250):  # Latin Étendu A + B
-        ch = chr(codepoint)
-        nfd = unicodedata.normalize("NFD", ch)
-        if len(nfd) > 1:  # le caractère est décomposable
-            base = nfd[0]  # lettre de base
-            if base.isalpha() and base != ch:
-                table[ch] = base
-    # Compléments manuels
-    table.update({
-        "\u0107": "c",  # ć
-        "\u0119": "e",  # ę
-        "\u0142": "l",  # ł
-        "\u0144": "n",  # ń
-        "\u015B": "s",  # ś
-        "\u017A": "z",  # ź
-        "\u017C": "z",  # ż
-    })
-    return table
-
-
-DIACRITIC_MAP: dict[str, str] = _build_diacritic_map()
-_ALL_DIACRITICS: frozenset[str] = frozenset(DIACRITIC_MAP)
-
-# Ligatures qui NE sont PAS des diacritiques (pour éviter les doublons)
-_LIGATURE_SET: frozenset[str] = frozenset(LIGATURE_TABLE)
-
-
-# ---------------------------------------------------------------------------
-# Résultats structurés
-# ---------------------------------------------------------------------------
-
-@dataclass
-class LigatureScore:
-    """Score de reconnaissance des ligatures pour une paire (GT, OCR)."""
-
-    total_in_gt: int = 0
-    """Nombre de ligatures présentes dans le GT."""
-    correctly_recognized: int = 0
-    """Nombre de ligatures correctement transcrites (unicode ou équivalent)."""
-    score: float = 0.0
-    """Taux de reconnaissance = correctly_recognized / total_in_gt. 1.0 si total=0."""
-    per_ligature: dict[str, dict] = field(default_factory=dict)
-    """Détail par ligature : {'fi': {'gt_count': 5, 'ocr_correct': 3, 'score': 0.6}}"""
-
-    def as_dict(self) -> dict:
-        return {
-            "total_in_gt": self.total_in_gt,
-            "correctly_recognized": self.correctly_recognized,
-            "score": round(self.score, 4),
-            "per_ligature": {
-                k: {kk: round(vv, 4) if isinstance(vv, float) else vv for kk, vv in v.items()}
-                for k, v in self.per_ligature.items()
-            },
-        }
-
-
-@dataclass
-class DiacriticScore:
-    """Score de conservation des diacritiques pour une paire (GT, OCR)."""
-
-    total_in_gt: int = 0
-    """Nombre de caractères accentués dans le GT."""
-    correctly_recognized: int = 0
-    """Nombre de diacritiques correctement conservés."""
-    score: float = 0.0
-    """Taux de conservation = correctly_recognized / total_in_gt. 1.0 si total=0."""
-    per_diacritic: dict[str, dict] = field(default_factory=dict)
-    """Détail par caractère diacritique."""
-
-    def as_dict(self) -> dict:
-        return {
-            "total_in_gt": self.total_in_gt,
-            "correctly_recognized": self.correctly_recognized,
-            "score": round(self.score, 4),
-            "per_diacritic": {
-                k: {kk: round(vv, 4) if isinstance(vv, float) else vv for kk, vv in v.items()}
-                for k, v in self.per_diacritic.items()
-            },
-        }
-
-
-# ---------------------------------------------------------------------------
-# Calcul des scores
-# ---------------------------------------------------------------------------
-
-def compute_ligature_score(ground_truth: str, hypothesis: str) -> LigatureScore:
-    """Calcule le score de reconnaissance des ligatures.
-
-    Pour chaque ligature dans le GT, on vérifie si l'OCR a produit :
-    - Exactement le même caractère ligature Unicode (ex. fi → fi)
-    - Ou la séquence de lettres équivalente (ex. fi → fi)
-
-    Les deux sont considérés comme corrects — ce qui correspond à la pratique
-    éditoriale patrimoniaux (certains éditeurs développent les ligatures).
-
-    Parameters
-    ----------
-    ground_truth:
-        Texte de référence.
-    hypothesis:
-        Texte produit par l'OCR.
-
-    Returns
-    -------
-    LigatureScore
-    """
-    if not ground_truth:
-        return LigatureScore(score=1.0)
-
-    # Construire un index de position dans l'hypothèse pour recherche rapide
-    hyp_norm = unicodedata.normalize("NFC", hypothesis)
-    gt_norm = unicodedata.normalize("NFC", ground_truth)
-
-    per_lig: dict[str, dict] = {}
-    total = 0
-    correct = 0
-
-    # Trouver toutes les ligatures dans le GT
-    i = 0
-    while i < len(gt_norm):
-        ch = gt_norm[i]
-        if ch in _ALL_LIGATURES:
-            total += 1
-            equivalents = [ch] + LIGATURE_TABLE[ch]  # unicode direct ou séquences équivalentes
-
-            # Vérifier si la position correspondante dans l'OCR contient l'équivalent
-            is_correct = _check_char_at_context(gt_norm, hyp_norm, i, ch, equivalents)
-            if is_correct:
-                correct += 1
-
-            if ch not in per_lig:
-                per_lig[ch] = {"gt_count": 0, "ocr_correct": 0, "score": 0.0}
-            per_lig[ch]["gt_count"] += 1
-            if is_correct:
-                per_lig[ch]["ocr_correct"] += 1
-        i += 1
-
-    # Calculer les scores individuels
-    for lig_data in per_lig.values():
-        lig_data["score"] = (
-            lig_data["ocr_correct"] / lig_data["gt_count"]
-            if lig_data["gt_count"] > 0
-            else 1.0
-        )
-
-    score = correct / total if total > 0 else 1.0
-    return LigatureScore(
-        total_in_gt=total,
-        correctly_recognized=correct,
-        score=score,
-        per_ligature=per_lig,
-    )
-
-
-def compute_diacritic_score(ground_truth: str, hypothesis: str) -> DiacriticScore:
-    """Calcule le score de conservation des diacritiques.
-
-    Pour chaque caractère accentué dans le GT, on vérifie si l'OCR a produit
-    le même caractère (conservation) ou a substitué la lettre de base (perte).
-    On accepte aussi les formes NFD équivalentes.
-
-    Parameters
-    ----------
-    ground_truth:
-        Texte de référence.
-    hypothesis:
-        Texte produit par l'OCR.
-
-    Returns
-    -------
-    DiacriticScore
-    """
-    if not ground_truth:
-        return DiacriticScore(score=1.0)
-
-    gt_norm = unicodedata.normalize("NFC", ground_truth)
-    hyp_norm = unicodedata.normalize("NFC", hypothesis)
-
-    per_diac: dict[str, dict] = {}
-    total = 0
-    correct = 0
-
-    # Utiliser difflib pour l'alignement
-    import difflib
-    matcher = difflib.SequenceMatcher(None, gt_norm, hyp_norm, autojunk=False)
-    gt_to_hyp: dict[int, Optional[int]] = {}
-
-    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
-        if tag == "equal":
-            for k in range(i2 - i1):
-                gt_to_hyp[i1 + k] = j1 + k
-        elif tag == "replace" and (i2 - i1) == (j2 - j1):
-            for k in range(i2 - i1):
-                gt_to_hyp[i1 + k] = j1 + k
-        else:
-            # delete ou replace de longueurs différentes
-            for k in range(i1, i2):
-                gt_to_hyp[k] = None
-
-    for i, ch in enumerate(gt_norm):
-        if ch in _ALL_DIACRITICS and ch not in _LIGATURE_SET:
-            total += 1
-            hyp_pos = gt_to_hyp.get(i)
-            is_correct = False
-            if hyp_pos is not None and hyp_pos < len(hyp_norm):
-                hyp_ch = hyp_norm[hyp_pos]
-                is_correct = (hyp_ch == ch)
-            if is_correct:
-                correct += 1
-
-            if ch not in per_diac:
-                per_diac[ch] = {"gt_count": 0, "ocr_correct": 0, "score": 0.0}
-            per_diac[ch]["gt_count"] += 1
-            if is_correct:
-                per_diac[ch]["ocr_correct"] += 1
-
-    for diac_data in per_diac.values():
-        diac_data["score"] = (
-            diac_data["ocr_correct"] / diac_data["gt_count"]
-            if diac_data["gt_count"] > 0
-            else 1.0
-        )
-
-    score = correct / total if total > 0 else 1.0
-    return DiacriticScore(
-        total_in_gt=total,
-        correctly_recognized=correct,
-        score=score,
-        per_diacritic=per_diac,
-    )
-
-
-def _check_char_at_context(
-    gt: str,
-    hyp: str,
-    gt_pos: int,
-    gt_char: str,
-    equivalents: list[str],
-) -> bool:
-    """Vérifie si la position correspondante dans l'hypothèse contient un équivalent.
-
-    Cherche dans une fenêtre de ±5 caractères autour de la position estimée
-    pour tolérer les décalages d'alignement OCR.
-    """
-    # Position estimée dans l'hypothèse (ratio proportionnel)
-    if len(gt) == 0:
-        return False
-    est_pos = int(gt_pos * len(hyp) / len(gt)) if len(gt) > 0 else 0
-    window = 5
-    start = max(0, est_pos - window)
-    end = min(len(hyp), est_pos + window + len(gt_char))
-    context = hyp[start:end]
-    for equiv in equivalents:
-        if equiv in context:
-            return True
-    return False
-
-
-def aggregate_ligature_scores(scores: list[LigatureScore]) -> dict:
-    """Agrège les scores de ligatures sur un corpus."""
-    total_gt = sum(s.total_in_gt for s in scores)
-    total_correct = sum(s.correctly_recognized for s in scores)
-    score = total_correct / total_gt if total_gt > 0 else 1.0
-
-    # Agrégation par ligature
-    per_lig: dict[str, dict] = {}
-    for s in scores:
-        for lig, data in s.per_ligature.items():
-            if lig not in per_lig:
-                per_lig[lig] = {"gt_count": 0, "ocr_correct": 0}
-            per_lig[lig]["gt_count"] += data["gt_count"]
-            per_lig[lig]["ocr_correct"] += data["ocr_correct"]
-    for lig_data in per_lig.values():
-        lig_data["score"] = (
-            lig_data["ocr_correct"] / lig_data["gt_count"]
-            if lig_data["gt_count"] > 0 else 1.0
-        )
-
-    return {
-        "score": round(score, 4),
-        "total_in_gt": total_gt,
-        "correctly_recognized": total_correct,
-        "per_ligature": per_lig,
-    }
-
+from picarones.measurements.char_scores import *  # noqa: F401, F403
 
-def aggregate_diacritic_scores(scores: list[DiacriticScore]) -> dict:
-    """Agrège les scores diacritiques sur un corpus."""
-    total_gt = sum(s.total_in_gt for s in scores)
-    total_correct = sum(s.correctly_recognized for s in scores)
-    score = total_correct / total_gt if total_gt > 0 else 1.0
-    return {
-        "score": round(score, 4),
-        "total_in_gt": total_gt,
-        "correctly_recognized": total_correct,
-    }
+import picarones.measurements.char_scores as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/confusion.py

@@ -1,268 +1,19 @@
-"""Matrice de confusion unicode pour l'analyse fine des erreurs OCR.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.confusion`.
 
-Pour chaque moteur, on calcule quels caractères du GT sont transcrits par
-quels caractères OCR (substitutions). Cette "empreinte d'erreur" est
-caractéristique de chaque moteur ou pipeline.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.confusion import ...``) de continuer
+à fonctionner sans modification.
 
-Méthode
--------
-L'alignement caractère par caractère utilise les opérations d'édition
-de la distance de Levenshtein (via difflib.SequenceMatcher), ce qui permet
-d'identifier les substitutions, insertions et suppressions.
-
-La matrice est stockée comme un dict de dict :
-    ``{gt_char: {ocr_char: count}}``
-
-La valeur spéciale ``"∅"`` (U+2205) représente un caractère vide :
-- ``{"a": {"∅": 3}}`` → 'a' supprimé 3 fois dans l'OCR
-- ``{"∅": {"x": 2}}`` → 'x' inséré 2 fois dans l'OCR (absent du GT)
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import difflib
-from collections import defaultdict
-from dataclasses import dataclass, field
-
-# Symbole représentant un caractère absent (insertion / suppression)
-EMPTY_CHAR = "∅"
-
-# Caractères non pertinents à ignorer dans la matrice (espaces, sauts de ligne)
-_WHITESPACE = set(" \t\n\r")
-
-
-@dataclass
-class ConfusionMatrix:
-    """Matrice de confusion unicode pour une paire (GT, OCR)."""
-
-    matrix: dict[str, dict[str, int]] = field(default_factory=dict)
-    """Clé externe = char GT ; clé interne = char OCR ; valeur = count."""
-
-    total_substitutions: int = 0
-    total_insertions: int = 0
-    total_deletions: int = 0
-
-    @property
-    def total_errors(self) -> int:
-        return self.total_substitutions + self.total_insertions + self.total_deletions
-
-    def top_confusions(self, n: int = 20) -> list[dict]:
-        """Retourne les n confusions les plus fréquentes (substitutions uniquement)."""
-        pairs: list[tuple[str, str, int]] = []
-        for gt_char, ocr_counts in self.matrix.items():
-            if gt_char == EMPTY_CHAR:
-                continue  # insertions
-            for ocr_char, count in ocr_counts.items():
-                if ocr_char == EMPTY_CHAR:
-                    continue  # suppressions
-                if gt_char != ocr_char:
-                    pairs.append((gt_char, ocr_char, count))
-        pairs.sort(key=lambda x: -x[2])
-        return [
-            {"gt": gt, "ocr": ocr, "count": cnt}
-            for gt, ocr, cnt in pairs[:n]
-        ]
-
-    def as_compact_dict(self, min_count: int = 1) -> dict:
-        """Sérialise la matrice en éliminant les entrées rares."""
-        compact: dict[str, dict[str, int]] = {}
-        for gt_char, ocr_counts in self.matrix.items():
-            filtered = {
-                oc: cnt for oc, cnt in ocr_counts.items()
-                if cnt >= min_count
-            }
-            if filtered:
-                compact[gt_char] = filtered
-        return {
-            "matrix": compact,
-            "total_substitutions": self.total_substitutions,
-            "total_insertions": self.total_insertions,
-            "total_deletions": self.total_deletions,
-        }
-
-    def as_dict(self) -> dict:
-        return self.as_compact_dict(min_count=1)
-
-
-def build_confusion_matrix(
-    ground_truth: str,
-    hypothesis: str,
-    ignore_whitespace: bool = True,
-    ignore_correct: bool = True,
-) -> ConfusionMatrix:
-    """Construit la matrice de confusion unicode pour une paire GT/OCR.
-
-    Parameters
-    ----------
-    ground_truth:
-        Texte de référence (vérité terrain).
-    hypothesis:
-        Texte produit par l'OCR.
-    ignore_whitespace:
-        Si True, ignore les espaces, tabulations et sauts de ligne.
-    ignore_correct:
-        Si True, n'enregistre pas les paires identiques (gt_char == ocr_char).
-        Par défaut True pour réduire la taille de la matrice.
-
-    Returns
-    -------
-    ConfusionMatrix
-    """
-    matrix: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
-    n_subs = n_ins = n_dels = 0
-
-    if not ground_truth and not hypothesis:
-        return ConfusionMatrix(dict(matrix), 0, 0, 0)
-
-    # SequenceMatcher sur listes de chars pour un alignement précis
-    matcher = difflib.SequenceMatcher(None, ground_truth, hypothesis, autojunk=False)
-
-    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
-        if tag == "equal":
-            if not ignore_correct:
-                for ch in ground_truth[i1:i2]:
-                    if ignore_whitespace and ch in _WHITESPACE:
-                        continue
-                    matrix[ch][ch] += 1
-        elif tag == "replace":
-            # Aligner char par char les séquences de longueurs différentes
-            gt_seg = ground_truth[i1:i2]
-            oc_seg = hypothesis[j1:j2]
-            _align_segments(gt_seg, oc_seg, matrix, ignore_whitespace)
-            # Substitutions = longueur commune, surplus = insertions ou suppressions
-            n_subs += min(len(gt_seg), len(oc_seg))
-            surplus = abs(len(gt_seg) - len(oc_seg))
-            if len(gt_seg) > len(oc_seg):
-                n_dels += surplus
-            else:
-                n_ins += surplus
-        elif tag == "delete":
-            for ch in ground_truth[i1:i2]:
-                if ignore_whitespace and ch in _WHITESPACE:
-                    continue
-                matrix[ch][EMPTY_CHAR] += 1
-                n_dels += 1
-        elif tag == "insert":
-            for ch in hypothesis[j1:j2]:
-                if ignore_whitespace and ch in _WHITESPACE:
-                    continue
-                matrix[EMPTY_CHAR][ch] += 1
-                n_ins += 1
-
-    # Convertir defaultdict en dict normal
-    result_matrix: dict[str, dict[str, int]] = {
-        k: dict(v) for k, v in matrix.items()
-    }
-
-    return ConfusionMatrix(
-        matrix=result_matrix,
-        total_substitutions=n_subs,
-        total_insertions=n_ins,
-        total_deletions=n_dels,
-    )
-
-
-def _align_segments(
-    gt_seg: str,
-    oc_seg: str,
-    matrix: dict,
-    ignore_whitespace: bool,
-) -> None:
-    """Aligne deux segments de longueurs potentiellement différentes."""
-    if not gt_seg:
-        for ch in oc_seg:
-            if ignore_whitespace and ch in _WHITESPACE:
-                continue
-            matrix[EMPTY_CHAR][ch] += 1
-        return
-    if not oc_seg:
-        for ch in gt_seg:
-            if ignore_whitespace and ch in _WHITESPACE:
-                continue
-            matrix[ch][EMPTY_CHAR] += 1
-        return
-
-    if len(gt_seg) == len(oc_seg):
-        # Substitutions 1-pour-1
-        for g, o in zip(gt_seg, oc_seg):
-            if ignore_whitespace and (g in _WHITESPACE or o in _WHITESPACE):
-                continue
-            matrix[g][o] += 1
-    else:
-        # Longueurs différentes : utiliser SequenceMatcher récursif sur segments courts
-        sub = difflib.SequenceMatcher(None, gt_seg, oc_seg, autojunk=False)
-        for tag2, i1, i2, j1, j2 in sub.get_opcodes():
-            if tag2 == "equal":
-                pass
-            elif tag2 == "replace":
-                # Régression simple : aligner par troncature
-                for g, o in zip(gt_seg[i1:i2], oc_seg[j1:j2]):
-                    if ignore_whitespace and (g in _WHITESPACE or o in _WHITESPACE):
-                        continue
-                    matrix[g][o] += 1
-            elif tag2 == "delete":
-                for g in gt_seg[i1:i2]:
-                    if ignore_whitespace and g in _WHITESPACE:
-                        continue
-                    matrix[g][EMPTY_CHAR] += 1
-            elif tag2 == "insert":
-                for o in oc_seg[j1:j2]:
-                    if ignore_whitespace and o in _WHITESPACE:
-                        continue
-                    matrix[EMPTY_CHAR][o] += 1
-
-
-def aggregate_confusion_matrices(matrices: list[ConfusionMatrix]) -> ConfusionMatrix:
-    """Agrège plusieurs matrices de confusion en une seule.
-
-    Utile pour obtenir la matrice agrégée sur l'ensemble du corpus.
-    """
-    combined: dict[str, dict[str, int]] = defaultdict(lambda: defaultdict(int))
-    total_subs = total_ins = total_dels = 0
-
-    for cm in matrices:
-        for gt_char, ocr_counts in cm.matrix.items():
-            for ocr_char, count in ocr_counts.items():
-                combined[gt_char][ocr_char] += count
-        total_subs += cm.total_substitutions
-        total_ins += cm.total_insertions
-        total_dels += cm.total_deletions
-
-    return ConfusionMatrix(
-        matrix={k: dict(v) for k, v in combined.items()},
-        total_substitutions=total_subs,
-        total_insertions=total_ins,
-        total_deletions=total_dels,
-    )
-
-
-def top_confused_chars(
-    matrix: ConfusionMatrix,
-    n: int = 15,
-    exclude_empty: bool = True,
-) -> list[dict]:
-    """Retourne les caractères GT les plus souvent confondus.
-
-    Retourne une liste triée par nombre total d'erreurs décroissant :
-    ``[{"char": "ſ", "total_errors": 47, "top_substitutes": [...]}, ...]``
-    """
-    char_stats: dict[str, dict] = {}
-    for gt_char, ocr_counts in matrix.matrix.items():
-        if exclude_empty and gt_char == EMPTY_CHAR:
-            continue
-        error_count = sum(
-            cnt for oc, cnt in ocr_counts.items()
-            if (oc != gt_char) and (not exclude_empty or oc != EMPTY_CHAR)
-        )
-        if error_count > 0:
-            top_subs = sorted(
-                [{"ocr": oc, "count": cnt} for oc, cnt in ocr_counts.items() if oc != gt_char],
-                key=lambda x: -x["count"],
-            )[:5]
-            char_stats[gt_char] = {
-                "char": gt_char,
-                "total_errors": error_count,
-                "top_substitutes": top_subs,
-            }
+from picarones.measurements.confusion import *  # noqa: F401, F403
 
-    return sorted(char_stats.values(), key=lambda x: -x["total_errors"])[:n]
+import picarones.measurements.confusion as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/cost_projection.py

@@ -1,169 +1,19 @@
-"""Projection de coût en volume cible — Sprint 79 (A.I.6).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.cost_projection`.
 
-Sprint 79 — A.I.6 du plan d'évolution 2026.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.cost_projection import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-La vue Pareto (Sprint 20) trace CER vs coût mais le coût est par
-unité (1 000 pages).  Pour décider business-side, il faut projeter
-ce coût sur le **volume cible** que l'utilisateur prévoit de
-traiter — payer 50 € de plus sur 50 pages est trivial, sur
-5 millions ça change tout.
-
-Sortie typique
---------------
-*« Pour vos 80 000 pages BMS — Tesseract = 3 €, Pero = 0 € (local
-amorti), Mistral OCR = 280 €, GPT-4o post-correction = 600 €. »*
-
-Aucun seuil arbitraire imposé : le module fournit les chiffres,
-le chercheur arbitre selon son budget.
-
-Dépendance
-----------
-S'appuie sur ``picarones.core.pricing`` (Sprint 20) qui expose
-``EngineCost.cost_per_1k_pages_eur`` et
-``co2_per_1k_pages_g``.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-from dataclasses import dataclass
-from typing import Optional
-
-from picarones.core.pricing import EngineCost
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass(frozen=True)
-class ProjectedCost:
-    """Coût total projeté d'un moteur pour un volume cible."""
-    engine_key: str
-    target_pages: int
-    cost_total_eur: Optional[float]
-    co2_total_g: Optional[float]
-    cost_per_1k_pages_eur: Optional[float]
-    co2_per_1k_pages_g: Optional[float]
-    type: str  # "local" / "cloud_api" / "unknown"
-
-    def as_dict(self) -> dict:
-        return {
-            "engine_key": self.engine_key,
-            "target_pages": self.target_pages,
-            "cost_total_eur": self.cost_total_eur,
-            "co2_total_g": self.co2_total_g,
-            "cost_per_1k_pages_eur": self.cost_per_1k_pages_eur,
-            "co2_per_1k_pages_g": self.co2_per_1k_pages_g,
-            "type": self.type,
-        }
-
-
-def project_cost_total(
-    engine_cost: EngineCost, target_pages: int,
-) -> Optional[float]:
-    """Coût total projeté en euros pour ``target_pages`` pages.
-
-    Retourne ``None`` si ``cost_per_1k_pages_eur`` est ``None``
-    (données insuffisantes) ou si ``target_pages`` est négatif.
-    """
-    if target_pages < 0:
-        return None
-    if engine_cost.cost_per_1k_pages_eur is None:
-        return None
-    return engine_cost.cost_per_1k_pages_eur * target_pages / 1000.0
-
-
-def project_co2_total(
-    engine_cost: EngineCost, target_pages: int,
-) -> Optional[float]:
-    """Empreinte CO₂ totale en grammes pour ``target_pages`` pages."""
-    if target_pages < 0:
-        return None
-    if engine_cost.co2_per_1k_pages_g is None:
-        return None
-    return engine_cost.co2_per_1k_pages_g * target_pages / 1000.0
-
-
-def project_engine(
-    engine_cost: EngineCost, target_pages: int,
-) -> ProjectedCost:
-    """Retourne le ``ProjectedCost`` complet pour un moteur."""
-    return ProjectedCost(
-        engine_key=engine_cost.engine_key,
-        target_pages=int(target_pages),
-        cost_total_eur=project_cost_total(engine_cost, target_pages),
-        co2_total_g=project_co2_total(engine_cost, target_pages),
-        cost_per_1k_pages_eur=engine_cost.cost_per_1k_pages_eur,
-        co2_per_1k_pages_g=engine_cost.co2_per_1k_pages_g,
-        type=engine_cost.type,
-    )
-
-
-def project_all_engines(
-    engine_costs: dict[str, EngineCost],
-    target_pages: int,
-) -> dict[str, ProjectedCost]:
-    """Projette les coûts de plusieurs moteurs sur le volume cible.
-
-    Retourne un dict ``{engine_name: ProjectedCost}`` avec entrée
-    pour chaque moteur, y compris ceux sans données de coût (où
-    ``cost_total_eur`` sera ``None``).
-    """
-    if target_pages < 0:
-        raise ValueError("target_pages doit être ≥ 0")
-    return {
-        name: project_engine(cost, target_pages)
-        for name, cost in engine_costs.items()
-    }
-
-
-def cost_gap_table(
-    projections: dict[str, ProjectedCost],
-    baseline_engine: str,
-) -> dict[str, dict[str, Optional[float]]]:
-    """Pour chaque moteur, écart de coût total vs baseline.
-
-    Retourne ``{engine: {"total": float, "delta_abs": float,
-    "delta_rel": float}}`` où :
-
-    - ``delta_abs`` = ``cost - cost_baseline`` (None si l'un des
-      deux est None)
-    - ``delta_rel`` = ``delta_abs / cost_baseline`` (None si
-      baseline = 0 ou None)
-
-    Lève ``KeyError`` si la baseline est inconnue.
-    """
-    if baseline_engine not in projections:
-        raise KeyError(
-            f"baseline {baseline_engine!r} absente des projections",
-        )
-    baseline_total = projections[baseline_engine].cost_total_eur
-    out: dict[str, dict[str, Optional[float]]] = {}
-    for name, proj in projections.items():
-        total = proj.cost_total_eur
-        if total is None or baseline_total is None:
-            delta_abs: Optional[float] = None
-            delta_rel: Optional[float] = None
-        else:
-            delta_abs = total - baseline_total
-            if baseline_total != 0:
-                delta_rel = delta_abs / baseline_total
-            else:
-                delta_rel = None
-        out[name] = {
-            "total": total,
-            "delta_abs": delta_abs,
-            "delta_rel": delta_rel,
-        }
-    return out
-
+from picarones.measurements.cost_projection import *  # noqa: F401, F403
 
-__all__ = [
-    "ProjectedCost",
-    "project_cost_total",
-    "project_co2_total",
-    "project_engine",
-    "project_all_engines",
-    "cost_gap_table",
-]
+import picarones.measurements.cost_projection as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/difficulty.py

@@ -1,202 +1,19 @@
-"""Score de difficulté intrinsèque par document.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.difficulty`.
 
-Le score est indépendant des moteurs OCR : il mesure la difficulté
-*objective* d'un document, indépendamment de la qualité des transcriptions.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.difficulty import ...``) de continuer
+à fonctionner sans modification.
 
-Formule
--------
-  difficulty = w_variance * variance_norm
-             + w_quality  * (1 - image_quality_score)
-             + w_density  * special_char_density
-
-où :
-  - variance_norm   : variance inter-moteurs du CER, normalisée [0, 1]
-  - image_quality   : score de qualité image [0, 1] (netteté, contraste…)
-  - special_chars   : densité de caractères spéciaux dans la GT [0, 1]
-
-Les poids sont configurables (défaut : 0.4 / 0.35 / 0.25).
-
-Score final : [0, 1] — 0 = document facile, 1 = très difficile.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-from typing import Optional
-
-
-# Poids par défaut
-_W_VARIANCE = 0.40
-_W_QUALITY  = 0.35
-_W_DENSITY  = 0.25
-
-# Caractères spéciaux patrimoniaux (ligatures, abréviations, diacritiques rares)
-_SPECIAL_CHARS_RE = re.compile(
-    r"[ſœæꝑꝓ&]"              # ligatures / abréviations médiévales
-    r"|[ḁ-ỿ]"                # Latin Étendu Additionnel (diacritiques rares)
-    r"|[\u0300-\u036f]"       # Diacritiques combinants
-    r"|[\ufb00-\ufb06]"       # Formes de présentation latines (fi, fl…)
-    r"|[IVXLCDM]{3,}"         # Chiffres romains (3+ caractères)
-)
-
-
-@dataclass
-class DifficultyScore:
-    """Score de difficulté intrinsèque d'un document."""
-    doc_id: str
-    score: float
-    """Score global [0, 1] — plus élevé = plus difficile."""
-    variance_component: float
-    """Composante variance inter-moteurs [0, 1]."""
-    quality_component: float
-    """Composante qualité image inversée [0, 1]."""
-    density_component: float
-    """Composante densité caractères spéciaux [0, 1]."""
-    cer_variance: float
-    """Variance brute du CER entre moteurs."""
-    image_quality_score: float
-    """Score de qualité image (si disponible, sinon 0.5)."""
-    special_char_ratio: float
-    """Ratio caractères spéciaux / longueur GT."""
-
-    def as_dict(self) -> dict:
-        return {
-            "doc_id": self.doc_id,
-            "score": round(self.score, 4),
-            "variance_component": round(self.variance_component, 4),
-            "quality_component": round(self.quality_component, 4),
-            "density_component": round(self.density_component, 4),
-            "cer_variance": round(self.cer_variance, 6),
-            "image_quality_score": round(self.image_quality_score, 4),
-            "special_char_ratio": round(self.special_char_ratio, 4),
-        }
-
-
-def _special_char_density(text: str) -> float:
-    """Ratio de caractères spéciaux patrimoniaux dans le texte."""
-    if not text:
-        return 0.0
-    matches = len(_SPECIAL_CHARS_RE.findall(text))
-    return min(1.0, matches / len(text))
-
-
-def _variance(values: list[float]) -> float:
-    """Variance d'une liste de valeurs."""
-    if len(values) < 2:
-        return 0.0
-    mu = sum(values) / len(values)
-    return sum((v - mu) ** 2 for v in values) / len(values)
-
-
-def compute_difficulty_score(
-    doc_id: str,
-    ground_truth: str,
-    cer_per_engine: list[float],
-    image_quality_score: Optional[float] = None,
-    weights: tuple[float, float, float] = (_W_VARIANCE, _W_QUALITY, _W_DENSITY),
-) -> DifficultyScore:
-    """Calcule le score de difficulté intrinsèque pour un document.
-
-    Parameters
-    ----------
-    doc_id             : identifiant du document
-    ground_truth       : texte de référence
-    cer_per_engine     : liste des CER (un par moteur concurrent)
-    image_quality_score: score de qualité image [0, 1] (None → 0.5 neutre)
-    weights            : (w_variance, w_quality, w_density)
-
-    Returns
-    -------
-    DifficultyScore
-    """
-    w_var, w_qual, w_den = weights
-
-    # 1. Variance inter-moteurs (normalisée sur [0, 1] — variance max ≈ 0.25)
-    cer_var = _variance(cer_per_engine)
-    variance_norm = min(1.0, cer_var / 0.25)
-
-    # 2. Qualité image inversée
-    iq = image_quality_score if image_quality_score is not None else 0.5
-    iq = max(0.0, min(1.0, iq))
-    quality_component = 1.0 - iq
-
-    # 3. Densité de caractères spéciaux
-    density = _special_char_density(ground_truth)
-    # Amplifier légèrement (la densité brute est souvent faible)
-    density_component = min(1.0, density * 3.0)
-
-    # Score combiné
-    score = (
-        w_var  * variance_norm
-        + w_qual * quality_component
-        + w_den  * density_component
-    )
-    score = max(0.0, min(1.0, score))
-
-    return DifficultyScore(
-        doc_id=doc_id,
-        score=score,
-        variance_component=variance_norm,
-        quality_component=quality_component,
-        density_component=density_component,
-        cer_variance=cer_var,
-        image_quality_score=iq,
-        special_char_ratio=density,
-    )
-
-
-def compute_all_difficulties(
-    doc_ids: list[str],
-    ground_truths: dict[str, str],
-    cer_map: dict[str, dict[str, float]],
-    image_quality_map: Optional[dict[str, float]] = None,
-) -> dict[str, DifficultyScore]:
-    """Calcule les scores de difficulté pour tous les documents d'un corpus.
-
-    Parameters
-    ----------
-    doc_ids            : liste des identifiants de documents
-    ground_truths      : {doc_id → gt_text}
-    cer_map            : {doc_id → {engine_name → cer}}
-    image_quality_map  : {doc_id → quality_score} (facultatif)
-
-    Returns
-    -------
-    {doc_id → DifficultyScore}
-    """
-    result = {}
-    for doc_id in doc_ids:
-        gt = ground_truths.get(doc_id, "")
-        engine_cers = list(cer_map.get(doc_id, {}).values())
-        iq = (image_quality_map or {}).get(doc_id)
-        result[doc_id] = compute_difficulty_score(
-            doc_id=doc_id,
-            ground_truth=gt,
-            cer_per_engine=engine_cers,
-            image_quality_score=iq,
-        )
-    return result
-
-
-def difficulty_label(score: float) -> str:
-    """Retourne un label lisible pour un score de difficulté."""
-    if score < 0.25:
-        return "Facile"
-    if score < 0.50:
-        return "Modéré"
-    if score < 0.75:
-        return "Difficile"
-    return "Très difficile"
-
+from picarones.measurements.difficulty import *  # noqa: F401, F403
 
-def difficulty_color(score: float) -> str:
-    """Retourne une couleur CSS pour un score de difficulté."""
-    from picarones.core.colors import COLOR_GREEN, COLOR_YELLOW, COLOR_ORANGE, COLOR_RED
-    if score < 0.25:
-        return COLOR_GREEN
-    if score < 0.50:
-        return COLOR_YELLOW
-    if score < 0.75:
-        return COLOR_ORANGE
-    return COLOR_RED
+import picarones.measurements.difficulty as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/equivalence_profile.py

@@ -1,199 +1,19 @@
-"""Équivalences diplomatiques granulaires — Sprint 78 (A.I.5).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.equivalence_profile`.
 
-Sprint 78 — A.I.5 du plan d'évolution 2026.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.equivalence_profile import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-Aujourd'hui les profils de ``picarones/core/normalization.py``
-(``medieval_french``, ``early_modern_french``, etc.) appliquent un
-**bloc entier** de transformations.  Mais un éditeur peut vouloir
-nuancer : *« je tolère ``ſ → s`` mais pas ``u → v`` »* — par
-exemple parce qu'il édite un imprimé du XVIᵉ où u/v sont
-distinctes mais où le s long doit être normalisé.
-
-Ce module **éclate** chaque profil en règles d'équivalence
-**nommées et indépendantes** que l'utilisateur peut activer ou
-désactiver une par une.  La couche de calcul retourne le CER
-recalculé avec un sous-ensemble personnalisé.
-
-Format
-------
-Chaque règle a :
-
-- ``name`` : identifiant stable utilisé dans les URLs et l'UX
-  (ex. ``"longs_s"``, ``"u_eq_v"``)
-- ``source`` : caractère ou séquence à remplacer
-- ``target`` : caractère ou séquence cible
-- ``description`` : phrase courte FR destinée à l'utilisateur
-- ``profile_tag`` : nom du profil dont elle est issue (utile pour
-  grouper dans l'UX)
-
-Stratégie de découpage
-----------------------
-Couche de calcul d'abord (pattern Sprint 71/75/76).  L'UX panneau
-avancé (cases à cocher + recalcul JS client + URL state) suivra
-dans un sprint dédié — la couche calcul livrée ici est une
-fondation suffisante pour qu'un développeur frontend câble la vue.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-from dataclasses import dataclass
-from typing import Iterable, Optional
-
-from picarones.core.normalization import (
-    DIPLOMATIC_EN_EARLY_MODERN,
-    DIPLOMATIC_FR_EARLY_MODERN,
-    DIPLOMATIC_LATIN_MEDIEVAL,
-    DIPLOMATIC_MINIMAL,
-)
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass(frozen=True)
-class EquivalenceRule:
-    """Une équivalence diplomatique nommée et indépendante."""
-    name: str
-    source: str
-    target: str
-    description: str
-    profile_tag: str
-
-
-# Catalogue : on dérive des profils existants en attribuant un nom
-# stable à chaque transformation.  Les doublons (ex. ``ſ → s``
-# présent dans plusieurs profils) sont fusionnés sous un nom unique
-# (le premier rencontré).
-def _build_catalog() -> dict[str, EquivalenceRule]:
-    catalog: dict[str, EquivalenceRule] = {}
-
-    # Noms canoniques pour les transformations courantes
-    canonical_names: dict[tuple[str, str], tuple[str, str]] = {
-        ("ſ", "s"):  ("longs_s", "s long ſ → s"),
-        ("u", "v"):  ("u_eq_v", "u/v interchangeables (vpon → upon)"),
-        ("i", "j"):  ("i_eq_j", "i/j interchangeables (ioy → joy)"),
-        ("y", "i"):  ("y_eq_i", "y → i (Latin médiéval)"),
-        ("vv", "w"): ("vv_eq_w", "vv → w (anglais moderne)"),
-        ("æ", "ae"): ("ae_ligature", "æ → ae"),
-        ("œ", "oe"): ("oe_ligature", "œ → oe"),
-        ("þ", "th"): ("thorn_th", "þ (thorn) → th"),
-        ("ð", "th"): ("eth_th", "ð (eth) → th"),
-        ("ȝ", "y"):  ("yogh_y", "ȝ (yogh) → y"),
-        ("&", "et"): ("ampersand_et", "& → et (esperluette)"),
-        ("ỹ", "yn"): ("y_tilde_yn", "ỹ → yn"),
-        ("ꝑ", "per"): ("p_per", "ꝑ → per (abréviation Capelli)"),
-        ("ꝓ", "pro"): ("p_pro", "ꝓ → pro (abréviation Capelli)"),
-        ("ꝗ", "que"): ("q_que", "ꝗ → que (q barré)"),
-    }
-
-    sources = [
-        ("medieval_french", DIPLOMATIC_LATIN_MEDIEVAL),
-        ("early_modern_french", DIPLOMATIC_FR_EARLY_MODERN),
-        ("early_modern_english", DIPLOMATIC_EN_EARLY_MODERN),
-        ("minimal", DIPLOMATIC_MINIMAL),
-    ]
-
-    for profile_tag, profile_dict in sources:
-        for source, target in profile_dict.items():
-            key = (source, target)
-            if key in canonical_names:
-                name, desc = canonical_names[key]
-            else:
-                # Fallback : générer un nom à partir des codepoints
-                name = f"{source}_to_{target}".replace(" ", "_")
-                desc = f"{source} → {target}"
-            if name in catalog:
-                # On garde le profile_tag du premier rencontré, mais
-                # on note que la règle est partagée.
-                continue
-            catalog[name] = EquivalenceRule(
-                name=name,
-                source=source,
-                target=target,
-                description=desc,
-                profile_tag=profile_tag,
-            )
-    return catalog
-
-
-BUILTIN_EQUIVALENCES: dict[str, EquivalenceRule] = _build_catalog()
-
-
-def list_equivalences_by_profile(
-    profile_name: Optional[str] = None,
-) -> list[EquivalenceRule]:
-    """Liste les règles d'équivalence disponibles.
-
-    Si ``profile_name`` est fourni, ne retourne que les règles dont
-    ``profile_tag == profile_name`` (ou les règles dérivées de
-    plusieurs profils dont au moins un est ``profile_name``).
-    """
-    if profile_name is None:
-        return list(BUILTIN_EQUIVALENCES.values())
-    return [
-        rule for rule in BUILTIN_EQUIVALENCES.values()
-        if rule.profile_tag == profile_name
-    ]
-
-
-def apply_selected_equivalences(
-    text: Optional[str],
-    selected_names: Iterable[str],
-) -> str:
-    """Applique uniquement les règles dont le nom est dans
-    ``selected_names``.
-
-    L'ordre d'application est l'ordre du catalogue interne — les
-    transformations sont appliquées séquentiellement sur le texte.
-    Les règles inconnues sont silencieusement ignorées (avec
-    warning).
-    """
-    if not text:
-        return text or ""
-    selected_set = set(selected_names)
-    if not selected_set:
-        return text
-    out = text
-    for name, rule in BUILTIN_EQUIVALENCES.items():
-        if name not in selected_set:
-            continue
-        out = out.replace(rule.source, rule.target)
-    # Détection des règles inconnues (pour logger explicite)
-    unknown = selected_set - set(BUILTIN_EQUIVALENCES.keys())
-    if unknown:
-        logger.warning(
-            "[equivalence_profile] règles inconnues ignorées : %s",
-            sorted(unknown),
-        )
-    return out
-
-
-def compute_cer_with_equivalences(
-    reference: Optional[str],
-    hypothesis: Optional[str],
-    selected_names: Iterable[str],
-) -> float:
-    """Calcule le CER après application des équivalences sélectionnées
-    sur les **deux** côtés (GT et hypothèse).
-
-    Utilise ``picarones.core.metrics.compute_metrics`` et extrait
-    le champ ``cer`` du résultat.
-    """
-    from picarones.core.metrics import compute_metrics
-
-    selected_list = list(selected_names)
-    ref = apply_selected_equivalences(reference or "", selected_list)
-    hyp = apply_selected_equivalences(hypothesis or "", selected_list)
-    result = compute_metrics(ref, hyp)
-    return result.cer
-
+from picarones.measurements.equivalence_profile import *  # noqa: F401, F403
 
-__all__ = [
-    "EquivalenceRule",
-    "BUILTIN_EQUIVALENCES",
-    "list_equivalences_by_profile",
-    "apply_selected_equivalences",
-    "compute_cer_with_equivalences",
-]
+import picarones.measurements.equivalence_profile as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/error_absorption.py

@@ -1,276 +1,19 @@
-"""Métrique d'absorption d'erreur — Sprint 94 (B.3).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.error_absorption`.
 
-Sprint 94 — B.3 du plan d'évolution 2026.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.error_absorption import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-Quand un module de post-correction LLM aplatit les différences
-entre OCR amont, ce n'est pas qu'il « améliore » tous les
-moteurs — c'est qu'il introduit ses propres biais qui dominent
-ceux de l'OCR.  Mesurer la dégradation par étape ne suffit
-pas : il faut **séparer** les deux flux.
-
-À chaque jonction où un module transforme un artefact, on
-mesure :
-
-- **Taux de correction** : parmi les erreurs présentes en
-  entrée du module, combien sont corrigées en sortie ?
-- **Taux d'introduction** : parmi les erreurs présentes en
-  sortie, combien sont **nouvelles** (absentes en entrée) ?
-
-C'est la généralisation du score de sur-normalisation
-(chantier A.I.7) à toute jonction.  La formule s'applique
-uniformément à OCR→LLM, OCR→reconstructor, VLM→ALTO_mapper —
-toute jonction qui transforme un artefact en un autre du même
-type.
-
-Méthode (token-level)
----------------------
-On split en tokens whitespace ``reference``, ``before``,
-``after``.  On compare en **multiset** (un token GT consommé
-au plus une fois) :
-
-- ``errors_before`` = tokens GT non retrouvés dans ``before``
-- ``errors_after``  = tokens GT non retrouvés dans ``after``
-- ``corrected``     = ``errors_before \\ errors_after``
-  (présents avant, absents après → corrigés)
-- ``introduced``    = ``errors_after \\ errors_before``
-  (absents avant, présents après → introduits)
-
-Garde-fou : le module ne classe pas les erreurs (visuelles,
-abréviations, etc.) — c'est une métrique d'**absorption de
-volume**, pas de qualité éditoriale.  L'intersection sémantique
-avec ``taxonomy`` (Sprint 5) est documentée dans le glossaire.
-
-Sortie
-------
-``compute_error_absorption(reference, before, after)`` retourne :
-
-.. code-block:: text
-
-    {
-        "n_gt_tokens": int,
-        "n_errors_before": int,
-        "n_errors_after": int,
-        "n_corrected": int,
-        "n_introduced": int,
-        "n_kept_wrong": int,
-        "correction_rate": float | None,    # n_corrected / n_errors_before
-        "introduction_rate": float | None,  # n_introduced / n_errors_after
-        "net_improvement": int,             # n_corrected - n_introduced
-        "corrected_tokens": list[str],
-        "introduced_tokens": list[str],
-    }
-
-``aggregate_error_absorption(per_doc_results)`` somme les
-compteurs corpus-wide et recalcule les taux *micro*.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-from collections import Counter
-from typing import Iterable, Optional
-
-logger = logging.getLogger(__name__)
-
-
-def _split_words(text: Optional[str]) -> list[str]:
-    if not text:
-        return []
-    return text.split()
-
-
-def _missing_tokens(
-    reference: list[str], hypothesis: list[str],
-) -> Counter:
-    """Tokens GT manquants en hypothèse au sens multiset.
-
-    Un token GT compte plusieurs fois s'il apparaît plusieurs
-    fois ; chaque occurrence en hypothèse en absorbe au plus
-    une.  Retourne un Counter ``{token: nb_occurrences_manquees}``.
-    """
-    ref_count = Counter(reference)
-    hyp_count = Counter(hypothesis)
-    missing: Counter = Counter()
-    for token, n_ref in ref_count.items():
-        n_hyp = hyp_count.get(token, 0)
-        if n_hyp < n_ref:
-            missing[token] = n_ref - n_hyp
-    return missing
-
-
-def compute_error_absorption(
-    reference: Optional[str],
-    before: Optional[str],
-    after: Optional[str],
-    *,
-    case_sensitive: bool = False,
-) -> Optional[dict]:
-    """Mesure l'absorption d'erreur entre ``before`` et ``after``.
-
-    Parameters
-    ----------
-    reference:
-        GT (vérité terrain).
-    before:
-        Sortie de l'étape précédente (typiquement OCR amont).
-    after:
-        Sortie de l'étape courante (typiquement post-correction LLM).
-    case_sensitive:
-        Si False (défaut), match case-insensitive — la sortie
-        ``corrected_tokens``/``introduced_tokens`` reste en casse
-        GT originale.
-
-    Returns
-    -------
-    dict | None
-        ``None`` si la GT est vide ou ne contient aucun token.
-    """
-    ref_tokens = _split_words(reference)
-    if not ref_tokens:
-        return None
-    before_tokens = _split_words(before)
-    after_tokens = _split_words(after)
-
-    if case_sensitive:
-        ref_match = list(ref_tokens)
-        before_match = list(before_tokens)
-        after_match = list(after_tokens)
-    else:
-        ref_match = [t.lower() for t in ref_tokens]
-        before_match = [t.lower() for t in before_tokens]
-        after_match = [t.lower() for t in after_tokens]
-
-    # Map case-insensitive token → liste de casses GT originales
-    ref_orig_by_match: dict[str, list[str]] = {}
-    for orig, m in zip(ref_tokens, ref_match):
-        ref_orig_by_match.setdefault(m, []).append(orig)
-
-    missing_before = _missing_tokens(ref_match, before_match)
-    missing_after = _missing_tokens(ref_match, after_match)
-
-    n_errors_before = sum(missing_before.values())
-    n_errors_after = sum(missing_after.values())
-
-    # Calcul corrigé / introduit en multiset
-    corrected_counter: Counter = Counter()
-    introduced_counter: Counter = Counter()
-    kept_wrong_counter: Counter = Counter()
-    all_tokens = set(missing_before) | set(missing_after)
-    for tok in all_tokens:
-        nb = missing_before.get(tok, 0)
-        na = missing_after.get(tok, 0)
-        if nb > na:
-            corrected_counter[tok] = nb - na
-            kept_wrong_counter[tok] = na
-        elif na > nb:
-            introduced_counter[tok] = na - nb
-            kept_wrong_counter[tok] = nb
-        else:
-            kept_wrong_counter[tok] = nb
-
-    n_corrected = sum(corrected_counter.values())
-    n_introduced = sum(introduced_counter.values())
-    n_kept_wrong = sum(kept_wrong_counter.values())
-
-    correction_rate = (
-        n_corrected / n_errors_before
-        if n_errors_before > 0 else None
-    )
-    introduction_rate = (
-        n_introduced / n_errors_after
-        if n_errors_after > 0 else None
-    )
-
-    def _expand(counter: Counter) -> list[str]:
-        out: list[str] = []
-        for tok, count in counter.items():
-            origs = ref_orig_by_match.get(tok, [tok])
-            # Ne renvoie que la casse représentative GT
-            display = origs[0] if origs else tok
-            out.extend([display] * count)
-        return out
-
-    return {
-        "n_gt_tokens": len(ref_tokens),
-        "n_errors_before": n_errors_before,
-        "n_errors_after": n_errors_after,
-        "n_corrected": n_corrected,
-        "n_introduced": n_introduced,
-        "n_kept_wrong": n_kept_wrong,
-        "correction_rate": correction_rate,
-        "introduction_rate": introduction_rate,
-        "net_improvement": n_corrected - n_introduced,
-        "corrected_tokens": _expand(corrected_counter),
-        "introduced_tokens": _expand(introduced_counter),
-    }
-
-
-def aggregate_error_absorption(
-    per_doc: Iterable[Optional[dict]],
-    *,
-    sample_tokens: int = 50,
-) -> Optional[dict]:
-    """Agrège les compteurs corpus-wide et recalcule les taux
-    *micro*.
-
-    Parameters
-    ----------
-    per_doc:
-        Itérable de sorties de ``compute_error_absorption`` (ou
-        ``None`` pour les docs sans GT).
-    sample_tokens:
-        Nombre maximal de tokens corrigés/introduits gardés dans
-        l'échantillon (cap pour ne pas exploser le JSON).
-
-    Returns
-    -------
-    dict | None
-        ``None`` si aucune entry valide.
-    """
-    docs = [d for d in per_doc if d]
-    if not docs:
-        return None
-    n_gt = sum(int(d.get("n_gt_tokens") or 0) for d in docs)
-    n_errors_before = sum(int(d.get("n_errors_before") or 0) for d in docs)
-    n_errors_after = sum(int(d.get("n_errors_after") or 0) for d in docs)
-    n_corrected = sum(int(d.get("n_corrected") or 0) for d in docs)
-    n_introduced = sum(int(d.get("n_introduced") or 0) for d in docs)
-    n_kept_wrong = sum(int(d.get("n_kept_wrong") or 0) for d in docs)
-    correction_rate = (
-        n_corrected / n_errors_before if n_errors_before > 0 else None
-    )
-    introduction_rate = (
-        n_introduced / n_errors_after if n_errors_after > 0 else None
-    )
-    corrected_sample: list[str] = []
-    introduced_sample: list[str] = []
-    for d in docs:
-        corrected_sample.extend(d.get("corrected_tokens") or [])
-        introduced_sample.extend(d.get("introduced_tokens") or [])
-        if (
-            len(corrected_sample) >= sample_tokens
-            and len(introduced_sample) >= sample_tokens
-        ):
-            break
-    return {
-        "n_docs": len(docs),
-        "n_gt_tokens": n_gt,
-        "n_errors_before": n_errors_before,
-        "n_errors_after": n_errors_after,
-        "n_corrected": n_corrected,
-        "n_introduced": n_introduced,
-        "n_kept_wrong": n_kept_wrong,
-        "correction_rate": correction_rate,
-        "introduction_rate": introduction_rate,
-        "net_improvement": n_corrected - n_introduced,
-        "corrected_tokens_sample": corrected_sample[:sample_tokens],
-        "introduced_tokens_sample": introduced_sample[:sample_tokens],
-    }
-
+from picarones.measurements.error_absorption import *  # noqa: F401, F403
 
-__all__ = [
-    "compute_error_absorption",
-    "aggregate_error_absorption",
-]
+import picarones.measurements.error_absorption as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/hallucination.py

@@ -1,331 +1,19 @@
-"""Détection des hallucinations VLM/LLM — Sprint 10.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.hallucination`.
 
-Métriques calculées
--------------------
-- Taux d'insertion net    : mots/caractères ajoutés absents du GT, distinct du WIL existant
-- Ratio de longueur       : len(hyp) / len(gt) — ratio > 1.2 → hallucination potentielle
-- Score d'ancrage         : proportion des n-grammes (trigrammes) de la sortie présents dans le GT
-- Blocs hallucinés        : segments continus de la sortie sans correspondance GT au-delà d'un seuil
-- Badge hallucination     : True si ancrage faible ou ratio de longueur anormal
-"""
-
-from __future__ import annotations
-
-import re
-from dataclasses import dataclass
-
-
-# ---------------------------------------------------------------------------
-# Helpers texte
-# ---------------------------------------------------------------------------
-
-def _tokenize(text: str) -> list[str]:
-    """Découpe en mots (minuscules, sans ponctuation)."""
-    return re.findall(r"[^\s]+", text.lower())
-
-
-def _ngrams(tokens: list[str], n: int) -> list[tuple[str, ...]]:
-    """Génère les n-grammes d'une liste de tokens."""
-    if len(tokens) < n:
-        return [tuple(tokens)] if tokens else []
-    return [tuple(tokens[i:i + n]) for i in range(len(tokens) - n + 1)]
-
-
-# ---------------------------------------------------------------------------
-# Blocs hallucinés (segments continus sans ancrage)
-# ---------------------------------------------------------------------------
-
-@dataclass
-class HallucinatedBlock:
-    """Segment continu de la sortie sans correspondance dans le GT."""
-    start_token: int
-    end_token: int
-    text: str
-    length: int  # nombre de tokens
-
-    def as_dict(self) -> dict:
-        return {
-            "start_token": self.start_token,
-            "end_token": self.end_token,
-            "text": self.text,
-            "length": self.length,
-        }
-
-
-def _detect_hallucinated_blocks(
-    hyp_tokens: list[str],
-    gt_token_set: set[str],
-    tolerance: int = 3,
-    min_block_length: int = 4,
-) -> list[HallucinatedBlock]:
-    """Détecte les blocs de tokens hypothèse sans correspondance dans le GT.
-
-    Un bloc est un segment contigu de tokens hypothèse dont aucun n'est présent
-    dans le vocabulaire GT. Une tolérance de ``tolerance`` tokens connus interrompus
-    est acceptée avant de clore un bloc.
-
-    Parameters
-    ----------
-    hyp_tokens:
-        Tokens de la sortie OCR/VLM.
-    gt_token_set:
-        Ensemble des tokens du GT (pour recherche O(1)).
-    tolerance:
-        Nombre de tokens connus consécutifs interrompant un bloc avant de le clore.
-    min_block_length:
-        Longueur minimale (tokens) pour qu'un bloc soit signalé.
-
-    Returns
-    -------
-    list[HallucinatedBlock]
-    """
-    blocks: list[HallucinatedBlock] = []
-    if not hyp_tokens:
-        return blocks
-
-    in_block = False
-    block_start = 0
-    consecutive_known = 0
-
-    for i, tok in enumerate(hyp_tokens):
-        is_unknown = tok not in gt_token_set
-        if is_unknown:
-            if not in_block:
-                in_block = True
-                block_start = i
-                consecutive_known = 0
-            else:
-                consecutive_known = 0
-        else:
-            if in_block:
-                consecutive_known += 1
-                if consecutive_known >= tolerance:
-                    # Clore le bloc
-                    end = i - consecutive_known
-                    length = end - block_start + 1
-                    if length >= min_block_length:
-                        text = " ".join(hyp_tokens[block_start:end + 1])
-                        blocks.append(HallucinatedBlock(
-                            start_token=block_start,
-                            end_token=end,
-                            text=text,
-                            length=length,
-                        ))
-                    in_block = False
-                    consecutive_known = 0
-
-    # Bloc non terminé
-    if in_block:
-        end = len(hyp_tokens) - 1
-        length = end - block_start + 1
-        if length >= min_block_length:
-            text = " ".join(hyp_tokens[block_start:end + 1])
-            blocks.append(HallucinatedBlock(
-                start_token=block_start,
-                end_token=end,
-                text=text,
-                length=length,
-            ))
-
-    return blocks
-
-
-# ---------------------------------------------------------------------------
-# Résultat structuré
-# ---------------------------------------------------------------------------
-
-@dataclass
-class HallucinationMetrics:
-    """Métriques de détection des hallucinations pour une paire (GT, hypothèse)."""
-
-    net_insertion_rate: float
-    """Taux d'insertion nette : tokens hypothèse absents du GT / total tokens hypothèse."""
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.hallucination import ...``) de continuer
+à fonctionner sans modification.
 
-    length_ratio: float
-    """Ratio de longueur : len(hyp) / len(gt) en caractères. > 1.2 = signal d'hallucination."""
-
-    anchor_score: float
-    """Score d'ancrage : proportion des trigrammes hypothèse présents dans les trigrammes GT.
-    Score élevé → l'hypothèse s'ancre bien dans le GT. Score faible → hallucinations probables."""
-
-    hallucinated_blocks: list[HallucinatedBlock]
-    """Segments continus de la sortie sans correspondance GT (au-dessus du seuil de tolérance)."""
-
-    is_hallucinating: bool
-    """True si anchor_score < anchor_threshold OU length_ratio > length_ratio_threshold."""
-
-    # Détails supplémentaires
-    gt_word_count: int = 0
-    hyp_word_count: int = 0
-    net_inserted_words: int = 0
-    anchor_threshold_used: float = 0.5
-    length_ratio_threshold_used: float = 1.2
-    ngram_size_used: int = 3
-
-    def as_dict(self) -> dict:
-        return {
-            "net_insertion_rate": round(self.net_insertion_rate, 6),
-            "length_ratio": round(self.length_ratio, 6),
-            "anchor_score": round(self.anchor_score, 6),
-            "hallucinated_blocks": [b.as_dict() for b in self.hallucinated_blocks],
-            "is_hallucinating": self.is_hallucinating,
-            "gt_word_count": self.gt_word_count,
-            "hyp_word_count": self.hyp_word_count,
-            "net_inserted_words": self.net_inserted_words,
-            "anchor_threshold_used": self.anchor_threshold_used,
-            "length_ratio_threshold_used": self.length_ratio_threshold_used,
-            "ngram_size_used": self.ngram_size_used,
-        }
-
-    @classmethod
-    def from_dict(cls, d: dict) -> "HallucinationMetrics":
-        blocks = [
-            HallucinatedBlock(**b) for b in d.get("hallucinated_blocks", [])
-        ]
-        return cls(
-            net_insertion_rate=d.get("net_insertion_rate", 0.0),
-            length_ratio=d.get("length_ratio", 1.0),
-            anchor_score=d.get("anchor_score", 1.0),
-            hallucinated_blocks=blocks,
-            is_hallucinating=d.get("is_hallucinating", False),
-            gt_word_count=d.get("gt_word_count", 0),
-            hyp_word_count=d.get("hyp_word_count", 0),
-            net_inserted_words=d.get("net_inserted_words", 0),
-            anchor_threshold_used=d.get("anchor_threshold_used", 0.5),
-            length_ratio_threshold_used=d.get("length_ratio_threshold_used", 1.2),
-            ngram_size_used=d.get("ngram_size_used", 3),
-        )
-
-
-# ---------------------------------------------------------------------------
-# Calcul principal
-# ---------------------------------------------------------------------------
-
-def compute_hallucination_metrics(
-    reference: str,
-    hypothesis: str,
-    n: int = 3,
-    length_ratio_threshold: float = 1.2,
-    anchor_threshold: float = 0.5,
-    block_tolerance: int = 3,
-    min_block_length: int = 4,
-) -> HallucinationMetrics:
-    """Calcule les métriques de détection des hallucinations VLM/LLM.
-
-    Parameters
-    ----------
-    reference:
-        Texte de vérité terrain (GT).
-    hypothesis:
-        Texte produit par le modèle.
-    n:
-        Taille des n-grammes pour le score d'ancrage (défaut : trigrammes).
-    length_ratio_threshold:
-        Seuil de ratio de longueur au-dessus duquel on signale une hallucination potentielle.
-    anchor_threshold:
-        Seuil de score d'ancrage en dessous duquel on signale une hallucination potentielle.
-    block_tolerance:
-        Nombre de tokens connus consécutifs acceptés dans un bloc halluciné.
-    min_block_length:
-        Longueur minimale (tokens) pour signaler un bloc halluciné.
-
-    Returns
-    -------
-    HallucinationMetrics
-    """
-    gt_tokens = _tokenize(reference)
-    hyp_tokens = _tokenize(hypothesis)
-
-    gt_len_chars = len(reference.strip())
-    hyp_len_chars = len(hypothesis.strip())
-
-    # ── Ratio de longueur ────────────────────────────────────────────────
-    if gt_len_chars == 0:
-        length_ratio = 1.0 if hyp_len_chars == 0 else float("inf")
-    else:
-        length_ratio = hyp_len_chars / gt_len_chars
-
-    # ── Taux d'insertion nette ───────────────────────────────────────────
-    gt_token_set = set(gt_tokens)
-    hyp_token_count = len(hyp_tokens)
-
-    if hyp_token_count == 0:
-        net_insertion_rate = 0.0
-        net_inserted_words = 0
-    else:
-        net_inserted = [t for t in hyp_tokens if t not in gt_token_set]
-        net_inserted_words = len(net_inserted)
-        net_insertion_rate = net_inserted_words / hyp_token_count
-
-    # ── Score d'ancrage (n-grammes) ────────────────────���─────────────────
-    gt_ngrams = set(_ngrams(gt_tokens, n))
-    hyp_ngrams = _ngrams(hyp_tokens, n)
-
-    if not hyp_ngrams:
-        # Pas de n-grammes dans l'hypothèse → ancrage parfait (hypothèse vide ou trop courte)
-        anchor_score = 1.0 if not gt_ngrams else 0.0
-    elif not gt_ngrams:
-        anchor_score = 0.0
-    else:
-        anchored = sum(1 for ng in hyp_ngrams if ng in gt_ngrams)
-        anchor_score = anchored / len(hyp_ngrams)
-
-    # ── Blocs hallucinés ─────────────────────────────────────────────────
-    blocks = _detect_hallucinated_blocks(
-        hyp_tokens=hyp_tokens,
-        gt_token_set=gt_token_set,
-        tolerance=block_tolerance,
-        min_block_length=min_block_length,
-    )
-
-    # ── Badge hallucination ──────────────────────────────────────────────
-    is_hallucinating = (
-        anchor_score < anchor_threshold
-        or length_ratio > length_ratio_threshold
-    )
-
-    return HallucinationMetrics(
-        net_insertion_rate=net_insertion_rate,
-        length_ratio=min(length_ratio, 9.99),  # plafonner pour la sérialisation
-        anchor_score=anchor_score,
-        hallucinated_blocks=blocks,
-        is_hallucinating=is_hallucinating,
-        gt_word_count=len(gt_tokens),
-        hyp_word_count=hyp_token_count,
-        net_inserted_words=net_inserted_words,
-        anchor_threshold_used=anchor_threshold,
-        length_ratio_threshold_used=length_ratio_threshold,
-        ngram_size_used=n,
-    )
-
-
-# ---------------------------------------------------------------------------
-# Agrégation sur un corpus
-# ---------------------------------------------------------------------------
-
-def aggregate_hallucination_metrics(results: list[HallucinationMetrics]) -> dict:
-    """Agrège les métriques d'hallucination sur un corpus.
-
-    Returns
-    -------
-    dict
-        Statistiques agrégées : anchor_score moyen, taux de documents hallucinés…
-    """
-    if not results:
-        return {}
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
+"""
 
-    n = len(results)
-    anchor_values = [r.anchor_score for r in results]
-    ratio_values = [r.length_ratio for r in results]
-    insertion_values = [r.net_insertion_rate for r in results]
-    hallucinating_count = sum(1 for r in results if r.is_hallucinating)
+from picarones.measurements.hallucination import *  # noqa: F401, F403
 
-    return {
-        "anchor_score_mean": round(sum(anchor_values) / n, 6),
-        "anchor_score_min": round(min(anchor_values), 6),
-        "length_ratio_mean": round(sum(ratio_values) / n, 6),
-        "net_insertion_rate_mean": round(sum(insertion_values) / n, 6),
-        "hallucinating_doc_count": hallucinating_count,
-        "hallucinating_doc_rate": round(hallucinating_count / n, 6),
-        "document_count": n,
-    }
+import picarones.measurements.hallucination as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/history.py

@@ -1,615 +1,19 @@
-"""Suivi longitudinal des benchmarks — base SQLite optionnelle.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.history`.
 
-Fonctionnement
---------------
-- Chaque run de benchmark est enregistré dans une table SQLite avec horodatage,
-  corpus, moteurs, métriques agrégées.
-- L'historique permet de tracer des courbes d'évolution du CER dans le temps.
-- La détection de régression compare le dernier run à une baseline configurable.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.history import ...``) de continuer
+à fonctionner sans modification.
 
-Structure de la base
---------------------
-Table ``runs`` :
-    run_id      TEXT PRIMARY KEY  — UUID ou hash du run
-    timestamp   TEXT              — ISO 8601
-    corpus_name TEXT
-    engine_name TEXT
-    cer_mean    REAL
-    wer_mean    REAL
-    doc_count   INTEGER
-    metadata    TEXT              — JSON
-
-Usage
------
->>> from picarones.core.history import BenchmarkHistory
->>> history = BenchmarkHistory("~/.picarones/history.db")
->>> history.record(benchmark_result)
->>> df = history.query(engine="tesseract", corpus="chroniques")
->>> regression = history.detect_regression(engine="tesseract", threshold=0.02)
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import json
-import logging
-import sqlite3
-import uuid
-from dataclasses import dataclass, field
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import TYPE_CHECKING, Optional
-
-if TYPE_CHECKING:
-    from picarones.core.results import BenchmarkResult
-
-logger = logging.getLogger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# Structures de données
-# ---------------------------------------------------------------------------
-
-@dataclass
-class HistoryEntry:
-    """Un enregistrement dans l'historique des benchmarks."""
-    run_id: str
-    timestamp: str
-    corpus_name: str
-    engine_name: str
-    cer_mean: Optional[float]
-    wer_mean: Optional[float]
-    doc_count: int
-    metadata: dict = field(default_factory=dict)
-
-    @property
-    def cer_percent(self) -> Optional[float]:
-        return self.cer_mean * 100 if self.cer_mean is not None else None
-
-    def as_dict(self) -> dict:
-        return {
-            "run_id": self.run_id,
-            "timestamp": self.timestamp,
-            "corpus_name": self.corpus_name,
-            "engine_name": self.engine_name,
-            "cer_mean": self.cer_mean,
-            "wer_mean": self.wer_mean,
-            "doc_count": self.doc_count,
-            "metadata": self.metadata,
-        }
-
-
-@dataclass
-class RegressionResult:
-    """Résultat d'une détection de régression."""
-    engine_name: str
-    corpus_name: str
-    baseline_run_id: str
-    baseline_timestamp: str
-    baseline_cer: Optional[float]
-    current_run_id: str
-    current_timestamp: str
-    current_cer: Optional[float]
-    delta_cer: Optional[float]
-    """Delta CER (current - baseline). Positif = régression."""
-    is_regression: bool
-    threshold: float
-
-    def as_dict(self) -> dict:
-        return {
-            "engine_name": self.engine_name,
-            "corpus_name": self.corpus_name,
-            "baseline_run_id": self.baseline_run_id,
-            "baseline_timestamp": self.baseline_timestamp,
-            "baseline_cer": self.baseline_cer,
-            "current_run_id": self.current_run_id,
-            "current_timestamp": self.current_timestamp,
-            "current_cer": self.current_cer,
-            "delta_cer": self.delta_cer,
-            "is_regression": self.is_regression,
-            "threshold": self.threshold,
-        }
-
-
-# ---------------------------------------------------------------------------
-# BenchmarkHistory
-# ---------------------------------------------------------------------------
-
-class BenchmarkHistory:
-    """Gestionnaire de l'historique des benchmarks dans SQLite.
-
-    Parameters
-    ----------
-    db_path:
-        Chemin vers le fichier SQLite. Utiliser ``":memory:"`` pour les tests.
-
-    Examples
-    --------
-    >>> history = BenchmarkHistory("~/.picarones/history.db")
-    >>> history.record(benchmark)
-    >>> entries = history.query(engine="tesseract")
-    >>> for e in entries:
-    ...     print(e.timestamp, f"CER={e.cer_percent:.2f}%")
-    """
-
-    _CREATE_TABLE = """
-    CREATE TABLE IF NOT EXISTS runs (
-        run_id      TEXT PRIMARY KEY,
-        timestamp   TEXT NOT NULL,
-        corpus_name TEXT NOT NULL,
-        engine_name TEXT NOT NULL,
-        cer_mean    REAL,
-        wer_mean    REAL,
-        doc_count   INTEGER,
-        metadata    TEXT
-    );
-    CREATE INDEX IF NOT EXISTS idx_engine ON runs (engine_name);
-    CREATE INDEX IF NOT EXISTS idx_corpus ON runs (corpus_name);
-    CREATE INDEX IF NOT EXISTS idx_timestamp ON runs (timestamp);
-    """
-
-    def __init__(self, db_path: str = "~/.picarones/history.db") -> None:
-        if db_path != ":memory:":
-            path = Path(db_path).expanduser()
-            path.parent.mkdir(parents=True, exist_ok=True)
-            self.db_path = str(path)
-        else:
-            self.db_path = ":memory:"
-        self._conn: Optional[sqlite3.Connection] = None
-        self._init_db()
-
-    def _connect(self) -> sqlite3.Connection:
-        if self._conn is None:
-            self._conn = sqlite3.connect(self.db_path)
-            self._conn.row_factory = sqlite3.Row
-        return self._conn
-
-    def _init_db(self) -> None:
-        conn = self._connect()
-        conn.executescript(self._CREATE_TABLE)
-        conn.commit()
-
-    def close(self) -> None:
-        """Ferme la connexion SQLite."""
-        if self._conn:
-            self._conn.close()
-            self._conn = None
-
-    # ------------------------------------------------------------------
-    # Enregistrement
-    # ------------------------------------------------------------------
-
-    def record(
-        self,
-        benchmark_result: "BenchmarkResult",
-        run_id: Optional[str] = None,
-        extra_metadata: Optional[dict] = None,
-    ) -> str:
-        """Enregistre les résultats d'un benchmark dans l'historique.
-
-        Parameters
-        ----------
-        benchmark_result:
-            Résultats à enregistrer (``BenchmarkResult``).
-        run_id:
-            Identifiant du run (auto-généré si None).
-        extra_metadata:
-            Métadonnées supplémentaires à stocker.
-
-        Returns
-        -------
-        str
-            L'identifiant du run enregistré.
-        """
-        if run_id is None:
-            run_id = str(uuid.uuid4())
-
-        timestamp = datetime.now(timezone.utc).isoformat()
-        conn = self._connect()
-
-        for report in benchmark_result.engine_reports:
-            ranking = benchmark_result.ranking()
-            engine_entry = next(
-                (r for r in ranking if r["engine"] == report.engine_name),
-                None,
-            )
-            cer_mean = engine_entry["mean_cer"] if engine_entry else None
-            wer_mean = engine_entry["mean_wer"] if engine_entry else None
-
-            meta = {
-                "engine_version": report.engine_version,
-                "engine_config": report.engine_config,
-                "picarones_version": benchmark_result.metadata.get("picarones_version", ""),
-                **(extra_metadata or {}),
-            }
-
-            conn.execute(
-                """
-                INSERT OR REPLACE INTO runs
-                    (run_id, timestamp, corpus_name, engine_name,
-                     cer_mean, wer_mean, doc_count, metadata)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-                """,
-                (
-                    f"{run_id}_{report.engine_name}",
-                    timestamp,
-                    benchmark_result.corpus_name,
-                    report.engine_name,
-                    cer_mean,
-                    wer_mean,
-                    benchmark_result.document_count,
-                    json.dumps(meta, ensure_ascii=False),
-                ),
-            )
-
-        conn.commit()
-        logger.info("Benchmark enregistré dans l'historique : run_id=%s", run_id)
-        return run_id
-
-    def record_single(
-        self,
-        run_id: str,
-        corpus_name: str,
-        engine_name: str,
-        cer_mean: Optional[float],
-        wer_mean: Optional[float],
-        doc_count: int,
-        timestamp: Optional[str] = None,
-        metadata: Optional[dict] = None,
-    ) -> str:
-        """Enregistre manuellement une entrée dans l'historique.
-
-        Utile pour les tests, les imports de données externes, ou pour
-        enregistrer des résultats calculés en dehors de Picarones.
-
-        Returns
-        -------
-        str
-            run_id enregistré.
-        """
-        if timestamp is None:
-            timestamp = datetime.now(timezone.utc).isoformat()
-
-        conn = self._connect()
-        conn.execute(
-            """
-            INSERT OR REPLACE INTO runs
-                (run_id, timestamp, corpus_name, engine_name,
-                 cer_mean, wer_mean, doc_count, metadata)
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-            """,
-            (
-                run_id,
-                timestamp,
-                corpus_name,
-                engine_name,
-                cer_mean,
-                wer_mean,
-                doc_count,
-                json.dumps(metadata or {}, ensure_ascii=False),
-            ),
-        )
-        conn.commit()
-        return run_id
-
-    # ------------------------------------------------------------------
-    # Requêtes
-    # ------------------------------------------------------------------
-
-    def query(
-        self,
-        engine: Optional[str] = None,
-        corpus: Optional[str] = None,
-        since: Optional[str] = None,
-        limit: int = 100,
-    ) -> list[HistoryEntry]:
-        """Retourne l'historique des runs, avec filtres optionnels.
-
-        Parameters
-        ----------
-        engine:
-            Filtre sur le nom du moteur.
-        corpus:
-            Filtre sur le nom du corpus.
-        since:
-            Date ISO 8601 minimale (``"2025-01-01"``).
-        limit:
-            Nombre maximum d'entrées retournées.
-
-        Returns
-        -------
-        list[HistoryEntry]
-            Entrées triées par timestamp croissant.
-        """
-        clauses: list[str] = []
-        params: list = []
-
-        if engine:
-            clauses.append("engine_name = ?")
-            params.append(engine)
-        if corpus:
-            clauses.append("corpus_name = ?")
-            params.append(corpus)
-        if since:
-            clauses.append("timestamp >= ?")
-            params.append(since)
-
-        where = f"WHERE {' AND '.join(clauses)}" if clauses else ""
-        params.append(limit)
-
-        conn = self._connect()
-        rows = conn.execute(
-            f"SELECT * FROM runs {where} ORDER BY timestamp ASC LIMIT ?",
-            params,
-        ).fetchall()
-
-        return [
-            HistoryEntry(
-                run_id=row["run_id"],
-                timestamp=row["timestamp"],
-                corpus_name=row["corpus_name"],
-                engine_name=row["engine_name"],
-                cer_mean=row["cer_mean"],
-                wer_mean=row["wer_mean"],
-                doc_count=row["doc_count"],
-                metadata=json.loads(row["metadata"] or "{}"),
-            )
-            for row in rows
-        ]
-
-    def list_engines(self) -> list[str]:
-        """Retourne la liste des moteurs présents dans l'historique."""
-        conn = self._connect()
-        rows = conn.execute(
-            "SELECT DISTINCT engine_name FROM runs ORDER BY engine_name"
-        ).fetchall()
-        return [row[0] for row in rows]
-
-    def list_corpora(self) -> list[str]:
-        """Retourne la liste des corpus présents dans l'historique."""
-        conn = self._connect()
-        rows = conn.execute(
-            "SELECT DISTINCT corpus_name FROM runs ORDER BY corpus_name"
-        ).fetchall()
-        return [row[0] for row in rows]
-
-    def count(self) -> int:
-        """Nombre total d'entrées dans l'historique."""
-        conn = self._connect()
-        return conn.execute("SELECT COUNT(*) FROM runs").fetchone()[0]
-
-    # ------------------------------------------------------------------
-    # Courbes d'évolution
-    # ------------------------------------------------------------------
-
-    def get_cer_curve(
-        self,
-        engine: str,
-        corpus: Optional[str] = None,
-    ) -> list[dict]:
-        """Retourne les données pour tracer la courbe d'évolution du CER.
-
-        Parameters
-        ----------
-        engine:
-            Nom du moteur.
-        corpus:
-            Corpus spécifique (None = tous les corpus pour ce moteur).
-
-        Returns
-        -------
-        list[dict]
-            Chaque dict contient ``{"timestamp": str, "cer": float, "run_id": str}``.
-        """
-        entries = self.query(engine=engine, corpus=corpus, limit=1000)
-        return [
-            {
-                "timestamp": e.timestamp,
-                "cer": e.cer_mean,
-                "cer_percent": e.cer_percent,
-                "run_id": e.run_id,
-                "corpus_name": e.corpus_name,
-            }
-            for e in entries
-            if e.cer_mean is not None
-        ]
-
-    # ------------------------------------------------------------------
-    # Détection de régression
-    # ------------------------------------------------------------------
-
-    def detect_regression(
-        self,
-        engine: str,
-        corpus: Optional[str] = None,
-        threshold: float = 0.01,
-        baseline_run_id: Optional[str] = None,
-    ) -> Optional[RegressionResult]:
-        """Détecte une régression du CER entre deux runs.
-
-        Compare le run le plus récent à une baseline (le run précédent ou
-        un run spécifique).
-
-        Parameters
-        ----------
-        engine:
-            Nom du moteur à surveiller.
-        corpus:
-            Corpus spécifique (None = tous).
-        threshold:
-            Seuil de régression en points absolus de CER (ex : 0.01 = 1%).
-            Si delta_cer > threshold → régression détectée.
-        baseline_run_id:
-            run_id de référence. Si None, utilise l'avant-dernier run.
-
-        Returns
-        -------
-        RegressionResult | None
-            None si moins de 2 runs disponibles.
-        """
-        entries = self.query(engine=engine, corpus=corpus, limit=1000)
-        if len(entries) < 2:
-            logger.info("Pas assez de runs pour détecter une régression (moteur=%s)", engine)
-            return None
-
-        current = entries[-1]
-
-        if baseline_run_id:
-            baseline_list = [e for e in entries[:-1] if e.run_id == baseline_run_id]
-            baseline = baseline_list[0] if baseline_list else entries[-2]
-        else:
-            baseline = entries[-2]
-
-        delta = None
-        is_regression = False
-        if current.cer_mean is not None and baseline.cer_mean is not None:
-            delta = current.cer_mean - baseline.cer_mean
-            is_regression = delta > threshold
-
-        return RegressionResult(
-            engine_name=engine,
-            corpus_name=corpus or "tous",
-            baseline_run_id=baseline.run_id,
-            baseline_timestamp=baseline.timestamp,
-            baseline_cer=baseline.cer_mean,
-            current_run_id=current.run_id,
-            current_timestamp=current.timestamp,
-            current_cer=current.cer_mean,
-            delta_cer=delta,
-            is_regression=is_regression,
-            threshold=threshold,
-        )
-
-    def detect_all_regressions(
-        self,
-        threshold: float = 0.01,
-    ) -> list[RegressionResult]:
-        """Détecte les régressions pour tous les moteurs et corpus connus.
-
-        Parameters
-        ----------
-        threshold:
-            Seuil de régression.
-
-        Returns
-        -------
-        list[RegressionResult]
-            Uniquement les moteurs où une régression est détectée.
-        """
-        results: list[RegressionResult] = []
-        engines = self.list_engines()
-        corpora = self.list_corpora()
-
-        for engine in engines:
-            for corpus in corpora:
-                result = self.detect_regression(engine, corpus, threshold)
-                if result and result.is_regression:
-                    results.append(result)
-
-        return results
-
-    # ------------------------------------------------------------------
-    # Export
-    # ------------------------------------------------------------------
-
-    def export_json(self, output_path: str) -> Path:
-        """Exporte l'historique complet en JSON.
-
-        Parameters
-        ----------
-        output_path:
-            Chemin du fichier JSON de sortie.
-
-        Returns
-        -------
-        Path
-            Chemin vers le fichier créé.
-        """
-        entries = self.query(limit=100_000)
-        path = Path(output_path)
-        data = {
-            "picarones_history": True,
-            "exported_at": datetime.now(timezone.utc).isoformat(),
-            "total_runs": len(entries),
-            "engines": self.list_engines(),
-            "corpora": self.list_corpora(),
-            "runs": [e.as_dict() for e in entries],
-        }
-        path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
-        return path
-
-    def __repr__(self) -> str:
-        return f"BenchmarkHistory(db='{self.db_path}', runs={self.count()})"
-
-
-# ---------------------------------------------------------------------------
-# Données de démonstration longitudinale
-# ---------------------------------------------------------------------------
-
-def generate_demo_history(
-    db: BenchmarkHistory,
-    n_runs: int = 8,
-    seed: int = 42,
-) -> None:
-    """Insère des données fictives de suivi longitudinal pour la démo.
-
-    Simule l'amélioration progressive d'un modèle tesseract sur 8 runs,
-    avec une légère régression au run 5.
-
-    Parameters
-    ----------
-    db:
-        Base d'historique à remplir.
-    n_runs:
-        Nombre de runs à générer.
-    seed:
-        Graine aléatoire.
-    """
-    import random
-    rng = random.Random(seed)
-
-    engines = ["tesseract", "pero_ocr", "ancien_moteur"]
-    corpus = "Chroniques médiévales"
-
-    # Trajectoires de CER simulées (amélioration progressive + bruit)
-    base_cers = {
-        "tesseract": 0.15,
-        "pero_ocr": 0.09,
-        "ancien_moteur": 0.28,
-    }
-    improvements = {
-        "tesseract": -0.008,   # améliore de ~0.8% par run
-        "pero_ocr": -0.005,    # améliore de ~0.5% par run
-        "ancien_moteur": -0.003,
-    }
-
-    from datetime import timedelta
-    base_date = datetime(2024, 9, 1, tzinfo=timezone.utc)
-
-    for run_idx in range(n_runs):
-        run_date = base_date + timedelta(weeks=run_idx * 2)
-        run_id = f"demo_run_{run_idx + 1:02d}"
-
-        for engine in engines:
-            cer = base_cers[engine] + improvements[engine] * run_idx
-            # Ajouter du bruit + régression au run 5
-            noise = rng.gauss(0, 0.005)
-            if run_idx == 4 and engine == "tesseract":
-                noise += 0.02  # régression simulée
-            cer = max(0.01, min(0.5, cer + noise))
-
-            wer = cer * 1.8 + rng.gauss(0, 0.01)
-            wer = max(0.01, min(0.9, wer))
+from picarones.measurements.history import *  # noqa: F401, F403
 
-            db.record_single(
-                run_id=f"{run_id}_{engine}",
-                corpus_name=corpus,
-                engine_name=engine,
-                cer_mean=round(cer, 4),
-                wer_mean=round(wer, 4),
-                doc_count=12,
-                timestamp=run_date.isoformat(),
-                metadata={
-                    "note": f"Run de démonstration #{run_idx + 1}",
-                    "engine_version": f"5.{run_idx}.0" if engine == "tesseract" else "0.7.2",
-                },
-            )
+import picarones.measurements.history as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/image_quality.py

@@ -1,391 +1,19 @@
-"""Analyse automatique de la qualité des images de documents numérisés.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.image_quality`.
 
-Métriques
----------
-- **Score de netteté** : variance du laplacien (plus élevé = plus net)
-- **Niveau de bruit** : écart-type des résidus haute-fréquence
-- **Angle de rotation résiduel** : estimé par projection horizontale
-- **Score de contraste** : ratio Michelson entre zones sombres (encre) et claires (fond)
-- **Score de qualité global** : combinaison normalisée des métriques ci-dessus
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.image_quality import ...``) de continuer
+à fonctionner sans modification.
 
-Ces calculs sont réalisés en pur Python + bibliothèques stdlib ou Pillow.
-NumPy est utilisé si disponible (calculs plus rapides), mais les méthodes
-de fallback n'en dépendent pas.
-
-Note
-----
-Pour les images placeholder (fixtures), des valeurs fictives cohérentes
-sont générées via `generate_mock_quality_scores()`.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-import math
-import statistics
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Optional
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class ImageQualityResult:
-    """Métriques de qualité d'une image de document."""
-
-    sharpness_score: float = 0.0
-    """Score de netteté [0, 1]. Basé sur la variance du laplacien normalisée."""
-
-    noise_level: float = 0.0
-    """Niveau de bruit [0, 1]. 0 = pas de bruit, 1 = très bruité."""
-
-    rotation_degrees: float = 0.0
-    """Angle de rotation résiduel estimé en degrés (positif = sens horaire)."""
-
-    contrast_score: float = 0.0
-    """Score de contraste [0, 1]. Ratio Michelson encre/fond."""
-
-    quality_score: float = 0.0
-    """Score de qualité global [0, 1]. Combinaison pondérée des autres métriques."""
-
-    analysis_method: str = "none"
-    """Méthode d'analyse utilisée : 'pillow', 'numpy', 'mock'."""
-
-    error: Optional[str] = None
-    """Erreur si l'analyse a échoué."""
-
-    @property
-    def is_good_quality(self) -> bool:
-        """Vrai si le score de qualité global est ≥ 0.7."""
-        return self.quality_score >= 0.7
-
-    @property
-    def quality_tier(self) -> str:
-        """Catégorie de qualité : 'good', 'medium', 'poor'."""
-        if self.quality_score >= 0.7:
-            return "good"
-        elif self.quality_score >= 0.4:
-            return "medium"
-        return "poor"
-
-    def as_dict(self) -> dict:
-        d = {
-            "sharpness_score": round(self.sharpness_score, 4),
-            "noise_level": round(self.noise_level, 4),
-            "rotation_degrees": round(self.rotation_degrees, 2),
-            "contrast_score": round(self.contrast_score, 4),
-            "quality_score": round(self.quality_score, 4),
-            "quality_tier": self.quality_tier,
-            "analysis_method": self.analysis_method,
-        }
-        if self.error:
-            d["error"] = self.error
-        return d
-
-    @classmethod
-    def from_dict(cls, data: dict) -> "ImageQualityResult":
-        return cls(
-            sharpness_score=data.get("sharpness_score", 0.0),
-            noise_level=data.get("noise_level", 0.0),
-            rotation_degrees=data.get("rotation_degrees", 0.0),
-            contrast_score=data.get("contrast_score", 0.0),
-            quality_score=data.get("quality_score", 0.0),
-            analysis_method=data.get("analysis_method", "none"),
-            error=data.get("error"),
-        )
-
-
-def analyze_image_quality(image_path: str | Path) -> ImageQualityResult:
-    """Analyse la qualité d'une image de document numérisé.
-
-    Essaie successivement :
-    1. Pillow + NumPy (méthode complète)
-    2. Pillow seul (méthode simplifiée)
-    3. Fallback : retourne un résultat vide avec erreur
-
-    Parameters
-    ----------
-    image_path:
-        Chemin vers l'image (JPG, PNG, TIFF…).
-
-    Returns
-    -------
-    ImageQualityResult
-    """
-    path = Path(image_path)
-    if not path.exists():
-        return ImageQualityResult(
-            error=f"Fichier image introuvable : {image_path}",
-            analysis_method="none",
-        )
-
-    # Essai avec Pillow + NumPy
-    try:
-        import numpy as np
-        from PIL import Image
-        return _analyze_with_numpy(path, np, Image)
-    except ImportError:
-        pass
-
-    # Essai avec Pillow seul
-    try:
-        from PIL import Image
-        return _analyze_with_pillow(path, Image)
-    except ImportError:
-        pass
-
-    return ImageQualityResult(
-        error="Pillow non disponible (pip install Pillow)",
-        analysis_method="none",
-        quality_score=0.5,  # valeur neutre
-    )
-
-
-def _analyze_with_numpy(path: Path, np, Image) -> ImageQualityResult:
-    """Analyse complète avec NumPy."""
-    img = Image.open(path).convert("L")  # niveaux de gris
-    arr = np.array(img, dtype=np.float32)
-
-    # 1. Netteté : variance du laplacien
-    laplacian = _laplacian_variance_numpy(arr, np)
-    # Normalisation empirique : variance > 500 = très net, < 50 = flou
-    sharpness = min(1.0, laplacian / 500.0)
-
-    # 2. Bruit : écart-type des résidus (différence image - image lissée)
-    noise = _noise_level_numpy(arr, np)
-
-    # 3. Rotation : angle d'inclinaison estimé
-    rotation = _estimate_rotation_numpy(arr, np)
-
-    # 4. Contraste : ratio Michelson
-    contrast = _contrast_score_numpy(arr, np)
-
-    # 5. Score global pondéré
-    quality = _global_quality_score(sharpness, noise, abs(rotation), contrast)
-
-    return ImageQualityResult(
-        sharpness_score=float(sharpness),
-        noise_level=float(noise),
-        rotation_degrees=float(rotation),
-        contrast_score=float(contrast),
-        quality_score=float(quality),
-        analysis_method="numpy",
-    )
-
-
-def _analyze_with_pillow(path: Path, Image) -> ImageQualityResult:
-    """Analyse simplifiée avec Pillow seul (sans NumPy)."""
-    img = Image.open(path).convert("L")
-    pixels = list(img.tobytes())  # mode "L" = 1 byte/pixel
-    w, h = img.size
-
-    if not pixels:
-        return ImageQualityResult(quality_score=0.5, analysis_method="pillow")
-
-    # Contraste : étendue des valeurs
-    min_val = min(pixels)
-    max_val = max(pixels)
-    if max_val + min_val > 0:
-        contrast = (max_val - min_val) / (max_val + min_val)
-    else:
-        contrast = 0.0
-
-    # Netteté approximée : variance globale des pixels
-    try:
-        variance = statistics.variance(pixels)
-    except statistics.StatisticsError:
-        variance = 0.0
-    sharpness = min(1.0, math.sqrt(variance) / 128.0)
-
-    # Bruit : approximation grossière
-    noise = min(1.0, statistics.stdev(pixels[:min(1000, len(pixels))]) / 64.0) if len(pixels) > 1 else 0.0
-
-    quality = _global_quality_score(sharpness, noise, 0.0, contrast)
-
-    return ImageQualityResult(
-        sharpness_score=sharpness,
-        noise_level=noise,
-        rotation_degrees=0.0,  # non calculé sans NumPy
-        contrast_score=contrast,
-        quality_score=quality,
-        analysis_method="pillow",
-    )
-
-
-def _laplacian_variance_numpy(arr, np) -> float:
-    """Calcule la variance du laplacien (mesure de netteté)."""
-    # Convolution laplacien 3x3 via slicing (bordures ignorées)
-    h, w = arr.shape
-    if h < 3 or w < 3:
-        return float(np.var(arr))
-
-    # Utiliser une convolution rapide avec slicing
-    center = arr[1:-1, 1:-1]
-    top    = arr[:-2,  1:-1]
-    bottom = arr[2:,   1:-1]
-    left   = arr[1:-1, :-2]
-    right  = arr[1:-1, 2:]
-    lap = top + bottom + left + right - 4 * center
-
-    return float(np.var(lap))
-
-
-def _noise_level_numpy(arr, np) -> float:
-    """Estime le niveau de bruit par la MAD (Median Absolute Deviation) des gradients."""
-    h, w = arr.shape
-    if h < 2 or w < 2:
-        return 0.0
-    # Différences horizontales et verticales
-    diff_h = np.abs(arr[:, 1:] - arr[:, :-1])
-    diff_v = np.abs(arr[1:, :] - arr[:-1, :])
-    noise_std = float(np.median(np.concatenate([diff_h.ravel(), diff_v.ravel()])))
-    # Normaliser : 0 = pas de bruit, 1 = très bruité (seuil à ~30)
-    return min(1.0, noise_std / 30.0)
-
-
-def _estimate_rotation_numpy(arr, np) -> float:
-    """Estime l'angle de rotation par projection horizontale simplifiée.
-
-    Retourne l'angle estimé en degrés [-45, 45].
-    """
-    # Méthode simplifiée : analyse de la variance des projections à différents angles
-    # Limiter à quelques angles pour la performance
-    h, w = arr.shape
-    if h < 20 or w < 20:
-        return 0.0
-
-    # Sous-échantillonnage pour la performance
-    step = max(1, h // 100)
-    sample = arr[::step, :]
-
-    best_angle = 0.0
-    best_var = -1.0
-
-    for angle_deg in range(-5, 6):  # ±5 degrés, pas de 1°
-        angle_rad = math.radians(angle_deg)
-        # Projection horizontale après rotation approximative
-        # (approximation linéaire rapide)
-        offsets = np.round(
-            np.arange(sample.shape[0]) * math.tan(angle_rad)
-        ).astype(int)
-        offsets = np.clip(offsets, 0, w - 1)
-
-        # Variance des sommes de lignes décalées
-        try:
-            row_sums = np.array([
-                float(np.sum(sample[i, max(0, offsets[i]):min(w, offsets[i]+w)]))
-                for i in range(sample.shape[0])
-            ])
-            var = float(np.var(row_sums))
-            if var > best_var:
-                best_var = var
-                best_angle = float(angle_deg)
-        except Exception as e:
-            logger.warning(
-                "[image_quality] projection à %d° indisponible : %s",
-                angle_deg, e,
-            )
-
-    return best_angle
-
-
-def _contrast_score_numpy(arr, np) -> float:
-    """Score de contraste Michelson [0, 1]."""
-    p5 = float(np.percentile(arr, 5))   # fond clair
-    p95 = float(np.percentile(arr, 95))  # encre sombre
-    if p5 + p95 == 0:
-        return 0.0
-    # Michelson : (Imax - Imin) / (Imax + Imin)
-    return float((p95 - p5) / (p95 + p5))
-
-
-def _global_quality_score(
-    sharpness: float,
-    noise: float,
-    rotation_abs: float,
-    contrast: float,
-) -> float:
-    """Calcule le score de qualité global pondéré."""
-    # Poids : netteté (40%), contraste (30%), bruit (20%), rotation (10%)
-    score = (
-        0.40 * sharpness
-        + 0.30 * contrast
-        + 0.20 * (1.0 - noise)  # moins de bruit = mieux
-        + 0.10 * max(0.0, 1.0 - rotation_abs / 10.0)  # ±10° max
-    )
-    return round(min(1.0, max(0.0, score)), 4)
-
-
-# ---------------------------------------------------------------------------
-# Données fictives pour les fixtures de démo
-# ---------------------------------------------------------------------------
-
-def generate_mock_quality_scores(
-    doc_id: str,
-    seed: Optional[int] = None,
-) -> ImageQualityResult:
-    """Génère des métriques de qualité fictives mais cohérentes pour un document.
-
-    Utilisé par les fixtures de démo pour simuler une diversité réaliste
-    de qualités d'image (bonne, moyenne, dégradée).
-
-    Parameters
-    ----------
-    doc_id:
-        Identifiant du document (utilisé pour la reproductibilité).
-    seed:
-        Graine aléatoire optionnelle.
-    """
-    import random
-    rng = random.Random(seed or hash(doc_id) % 2**32)
-
-    # Générer une qualité cohérente : certains docs sont plus difficiles
-    base_quality = 0.3 + rng.random() * 0.6  # 0.3 à 0.9
-
-    sharpness = max(0.1, min(1.0, base_quality + rng.gauss(0, 0.1)))
-    noise = max(0.0, min(1.0, (1.0 - base_quality) * 0.8 + rng.gauss(0, 0.05)))
-    rotation = rng.gauss(0, 1.5)  # ±1.5° typique
-    contrast = max(0.2, min(1.0, base_quality + rng.gauss(0, 0.15)))
-
-    quality = _global_quality_score(sharpness, noise, abs(rotation), contrast)
-
-    return ImageQualityResult(
-        sharpness_score=round(sharpness, 4),
-        noise_level=round(noise, 4),
-        rotation_degrees=round(rotation, 2),
-        contrast_score=round(contrast, 4),
-        quality_score=round(quality, 4),
-        analysis_method="mock",
-    )
-
-
-def aggregate_image_quality(results: list[ImageQualityResult]) -> dict:
-    """Agrège les métriques de qualité image sur un corpus."""
-    if not results:
-        return {}
-
-    valid = [r for r in results if r.error is None]
-    if not valid:
-        return {"error": "Aucune analyse réussie"}
-
-    def _mean(vals: list[float]) -> float:
-        return round(statistics.mean(vals), 4) if vals else 0.0
-
-    quality_scores = [r.quality_score for r in valid]
-    sharpness_scores = [r.sharpness_score for r in valid]
-    noise_levels = [r.noise_level for r in valid]
-
-    # Distribution par tier
-    tiers = {"good": 0, "medium": 0, "poor": 0}
-    for r in valid:
-        tiers[r.quality_tier] += 1
+from picarones.measurements.image_quality import *  # noqa: F401, F403
 
-    return {
-        "mean_quality_score": _mean(quality_scores),
-        "mean_sharpness": _mean(sharpness_scores),
-        "mean_noise_level": _mean(noise_levels),
-        "quality_distribution": tiers,
-        "document_count": len(valid),
-        "scores": [r.quality_score for r in valid],  # pour scatter plot
-    }
+import picarones.measurements.image_quality as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/incremental_comparison.py

@@ -1,253 +1,19 @@
-"""Comparaison incrémentale de pipelines composées — Sprint 96 (B.5).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.incremental_comparison`.
 
-Sprint 96 — B.5 du plan d'évolution 2026.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.incremental_comparison import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-Avec 5 OCR × 3 reconstructeurs × 4 post-correcteurs × 3
-mappeurs = 180 pipelines à comparer, le rapport noie
-l'information.  Il faut un mécanisme de **comparaison
-contrôlée** type design d'expérience.
-
-Méthode
--------
-Pour mesurer l'effet isolé d'un slot ``varying`` :
-
-1. Fixer les valeurs des autres slots (``fixed``).
-2. Pour chaque combinaison des fixed, comparer les pipelines
-   qui ne diffèrent que sur le slot varying.
-3. Agréger : pour chaque valeur du slot varying, calculer
-   sa moyenne, son écart-type, son rang moyen sur les groupes.
-
-C'est presque un Latin square automatisé.  Sans ça, le
-rapport sur 180 pipelines est inutilisable.
-
-Pas de tests statistiques scipy
--------------------------------
-On ne reconstruit pas Friedman/Nemenyi (déjà dans Sprint 18) ;
-on agrège ici les données nécessaires pour qu'un
-tests statistique externe puisse les consommer.  Le rapport
-existant reste libre de brancher
-``picarones.core.statistics.friedman_test`` sur la sortie de
-ce module.
-
-Sortie
-------
-``compare_isolated_effect(runs, varying_slot)`` retourne :
-
-.. code-block:: text
-
-    {
-        "varying_slot": str,
-        "n_runs": int,
-        "n_groups": int,                    # combinaisons fixed distinctes
-        "values": list[str],                # valeurs distinctes du slot
-        "per_value": {value: {
-            "n_observations": int,
-            "mean": float | None,
-            "stdev": float | None,
-            "min": float, "max": float,
-            "mean_rank": float | None,
-        }},
-        "best_value": str | None,
-        "worst_value": str | None,
-        "groups": list[dict],               # détail par groupe
-    }
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-import statistics
-from dataclasses import dataclass
-from typing import Optional
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass(frozen=True)
-class PipelineRun:
-    """Un run de pipeline composée pour la comparaison contrôlée.
-
-    Attributes
-    ----------
-    name:
-        Nom du run (libre — informatif uniquement).
-    slots:
-        Map ``{slot_name: module_name}`` décrivant la pipeline
-        (ex. ``{"ocr": "tess", "llm": "gpt-4o"}``).
-    score:
-        Métrique numérique à comparer (CER moyen typiquement).
-        Plus bas = meilleur par convention sauf si
-        ``higher_is_better=True`` est passé à
-        ``compare_isolated_effect``.
-    """
-
-    name: str
-    slots: dict[str, str]
-    score: float
-
-    def as_dict(self) -> dict:
-        return {
-            "name": self.name,
-            "slots": dict(self.slots),
-            "score": self.score,
-        }
-
-
-def _normalise_runs(runs) -> list[PipelineRun]:
-    """Accepte une liste de ``PipelineRun`` ou de dicts compatibles."""
-    out: list[PipelineRun] = []
-    for r in runs:
-        if isinstance(r, PipelineRun):
-            out.append(r)
-            continue
-        if not isinstance(r, dict):
-            continue
-        slots = r.get("slots") or {}
-        if not isinstance(slots, dict):
-            continue
-        try:
-            score = float(r.get("score"))
-        except (TypeError, ValueError):
-            continue
-        out.append(PipelineRun(
-            name=str(r.get("name") or ""),
-            slots={str(k): str(v) for k, v in slots.items()},
-            score=score,
-        ))
-    return out
-
-
-def compare_isolated_effect(
-    runs,
-    varying_slot: str,
-    *,
-    higher_is_better: bool = False,
-) -> Optional[dict]:
-    """Mesure l'effet isolé du slot ``varying_slot``.
-
-    Parameters
-    ----------
-    runs:
-        Liste de ``PipelineRun`` (ou dicts compatibles).
-    varying_slot:
-        Nom du slot dont on veut isoler l'effet.  Les autres
-        slots constituent les groupes de contrôle.
-    higher_is_better:
-        Si ``True``, on inverse la convention de classement
-        (rang 1 = score le plus haut).  Défaut ``False`` =
-        rang 1 = score le plus bas (CER).
-
-    Returns
-    -------
-    dict | None
-        ``None`` si moins de 2 runs ou si ``varying_slot``
-        n'est présent dans aucun run.
-    """
-    runs_list = _normalise_runs(runs)
-    if len(runs_list) < 2:
-        return None
-    runs_list = [r for r in runs_list if varying_slot in r.slots]
-    if not runs_list:
-        return None
-
-    # Constitue les groupes par valeurs des slots fixed
-    groups: dict[tuple, list[PipelineRun]] = {}
-    fixed_slot_names: list[str] = []
-    for r in runs_list:
-        other_slots = sorted(k for k in r.slots if k != varying_slot)
-        if not fixed_slot_names:
-            fixed_slot_names = other_slots
-        # Skip runs avec un schéma de slots incompatible
-        if other_slots != fixed_slot_names:
-            continue
-        key = tuple((k, r.slots[k]) for k in other_slots)
-        groups.setdefault(key, []).append(r)
-
-    if not groups:
-        return None
-
-    # Pour chaque groupe : ranking des runs par score
-    per_value: dict[str, dict] = {}
-    group_details: list[dict] = []
-    for key, members in groups.items():
-        members_sorted = sorted(
-            members, key=lambda x: x.score, reverse=higher_is_better,
-        )
-        # Rangs : runs ex aequo partagent la moyenne des rangs
-        ranks: dict[str, float] = {}
-        i = 0
-        while i < len(members_sorted):
-            j = i
-            while (
-                j + 1 < len(members_sorted)
-                and members_sorted[j + 1].score == members_sorted[i].score
-            ):
-                j += 1
-            avg_rank = (i + 1 + j + 1) / 2
-            for k in range(i, j + 1):
-                value = members_sorted[k].slots[varying_slot]
-                ranks[value] = avg_rank
-            i = j + 1
-
-        for r in members:
-            value = r.slots[varying_slot]
-            slot = per_value.setdefault(value, {
-                "scores": [],
-                "ranks": [],
-            })
-            slot["scores"].append(r.score)
-            slot["ranks"].append(ranks[value])
-        group_details.append({
-            "fixed_slots": dict(key),
-            "n_members": len(members),
-            "values": [r.slots[varying_slot] for r in members_sorted],
-            "scores": [r.score for r in members_sorted],
-        })
-
-    # Calcul mean/stdev/min/max + rang moyen par valeur
-    summary: dict[str, dict] = {}
-    for value, slot in per_value.items():
-        scores = slot["scores"]
-        ranks = slot["ranks"]
-        summary[value] = {
-            "n_observations": len(scores),
-            "mean": statistics.fmean(scores) if scores else None,
-            "stdev": (
-                statistics.stdev(scores) if len(scores) >= 2 else None
-            ),
-            "min": min(scores),
-            "max": max(scores),
-            "mean_rank": (
-                statistics.fmean(ranks) if ranks else None
-            ),
-        }
-
-    # Best/worst : sur la mean (convention CER : plus bas = meilleur)
-    by_mean = sorted(
-        ((v, d["mean"]) for v, d in summary.items()
-         if d["mean"] is not None),
-        key=lambda kv: kv[1],
-        reverse=higher_is_better,
-    )
-    best_value = by_mean[0][0] if by_mean else None
-    worst_value = by_mean[-1][0] if by_mean else None
-
-    return {
-        "varying_slot": varying_slot,
-        "n_runs": len(runs_list),
-        "n_groups": len(groups),
-        "values": sorted(per_value.keys()),
-        "per_value": summary,
-        "best_value": best_value,
-        "worst_value": worst_value,
-        "groups": group_details,
-        "higher_is_better": higher_is_better,
-    }
-
+from picarones.measurements.incremental_comparison import *  # noqa: F401, F403
 
-__all__ = [
-    "PipelineRun",
-    "compare_isolated_effect",
-]
+import picarones.measurements.incremental_comparison as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/inter_engine.py

@@ -1,484 +1,19 @@
-"""Métriques inter-moteurs (Sprint 35 — Étape 2 du plan d'évolution).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.inter_engine`.
 
-Deux familles de mesures qui répondent à des questions différentes mais
-liées :
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.inter_engine import ...``) de continuer
+à fonctionner sans modification.
 
-1. **Divergence taxonomique** (`kl_divergence`, `jensen_shannon_divergence`,
-   `taxonomy_divergence_matrix`) — *à quel point les moteurs font-ils des
-   erreurs de natures différentes ?*  Une divergence élevée signale des
-   moteurs spécialisés sur des classes d'erreurs distinctes (visual vs
-   abréviation vs casse) et donc des candidats pour un voting ensemble.
-
-2. **Complémentarité** (`oracle_token_recall`, `complementarity_gap`,
-   `pairwise_disagreement_rate`) — *quel CER serait atteignable si on
-   combinait les moteurs ?*  La borne inférieure du CER atteignable par
-   un voting majoritaire token-level est ``1 - oracle_token_recall``.
-   Si elle est très inférieure au CER du meilleur moteur seul, l'effort
-   d'un pipeline d'ensemble se justifie.  Sinon non.
-
-Convention de typage
---------------------
-Toutes les fonctions sont enregistrables dans le registre Sprint 34 si
-on les wrappe par un adaptateur ``(input_types=(TEXT, TEXT))``.  Pour
-limiter le bruit, on ne les enregistre **pas** automatiquement : ce sont
-des métriques d'agrégation (multi-moteurs ou multi-documents) qui ne
-correspondent pas au modèle « une jonction = une métrique » du runner.
-Elles sont consommées par les détecteurs narratifs et le rapport HTML.
-
-Note sur l'oracle
------------------
-La métrique ``oracle_token_recall`` retournée ici utilise un alignement
-bag-of-words pondéré par multiplicité.  Ce n'est **pas** une vraie
-borne atteignable par voting majoritaire séquentiel — c'est une borne
-supérieure (proxy optimiste).  La vraie borne demanderait un
-alignement séquentiel des hypothèses, ce qui est plus coûteux.  Pour
-le diagnostic « ensemble vaut-il le coup ? », le proxy suffit
-largement ; on documente clairement la limite dans le glossaire et le
-rapport.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-import math
-from collections import Counter
-
-logger = logging.getLogger(__name__)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Divergence taxonomique (KL / Jensen-Shannon)
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def _smoothed_distribution(
-    distribution: dict[str, float],
-    keys: list[str],
-    epsilon: float = 1e-12,
-) -> list[float]:
-    """Aligne une distribution sur l'ordre de ``keys`` et lisse les zéros.
-
-    Le lissage évite ``log(0)`` dans la KL.  ``epsilon`` est volontairement
-    minuscule pour ne pas modifier le résultat de manière sensible.
-    """
-    smoothed = [max(distribution.get(k, 0.0), epsilon) for k in keys]
-    total = sum(smoothed)
-    return [v / total for v in smoothed]
-
-
-def kl_divergence(p: dict[str, float], q: dict[str, float]) -> float:
-    """KL-divergence ``D(P||Q)`` en bits, sur l'union des clés.
-
-    Les distributions n'ont pas besoin de partager exactement les mêmes
-    clés ; les clés manquantes sont lissées à ``epsilon`` puis
-    renormalisées.
-
-    Returns
-    -------
-    float
-        ``D(P||Q) ≥ 0``.  Vaut 0 si et seulement si P == Q.  N'est pas
-        symétrique : ``kl(p, q) != kl(q, p)`` en général.
-    """
-    keys = sorted(set(p.keys()) | set(q.keys()))
-    if not keys:
-        return 0.0
-    p_vec = _smoothed_distribution(p, keys)
-    q_vec = _smoothed_distribution(q, keys)
-    return sum(pi * math.log2(pi / qi) for pi, qi in zip(p_vec, q_vec))
-
-
-def jensen_shannon_divergence(
-    p: dict[str, float],
-    q: dict[str, float],
-) -> float:
-    """JS-divergence symétrique en bits, bornée dans ``[0, 1]``.
-
-    ``JS(P, Q) = ½ D(P||M) + ½ D(Q||M)`` avec ``M = (P + Q) / 2``.
-    Symétrique et bornée — préférable à la KL pour construire une
-    matrice triangulaire de divergences entre moteurs.
-    """
-    keys = sorted(set(p.keys()) | set(q.keys()))
-    if not keys:
-        return 0.0
-    p_vec = _smoothed_distribution(p, keys)
-    q_vec = _smoothed_distribution(q, keys)
-    m_vec = [(pi + qi) / 2.0 for pi, qi in zip(p_vec, q_vec)]
-
-    def _kl(a: list[float], b: list[float]) -> float:
-        return sum(ai * math.log2(ai / bi) for ai, bi in zip(a, b) if ai > 0)
-
-    js = 0.5 * _kl(p_vec, m_vec) + 0.5 * _kl(q_vec, m_vec)
-    # Borne théorique : JS ∈ [0, 1] en bits.  Clamp pour absorber les
-    # erreurs d'arrondi flottant.
-    return max(0.0, min(1.0, js))
-
-
-def taxonomy_divergence_matrix(
-    distributions: dict[str, dict[str, float]],
-    metric: str = "js",
-) -> dict[str, dict[str, float]]:
-    """Construit la matrice de divergence triangulaire entre moteurs.
-
-    Parameters
-    ----------
-    distributions:
-        ``{engine_name: {error_class: probability}}``.  Chaque
-        distribution doit sommer à environ 1 (pas de validation stricte
-        — les distributions taxonomiques de Picarones sont déjà
-        normalisées par ``aggregate_taxonomy``).
-    metric:
-        ``"js"`` (défaut, symétrique) ou ``"kl"`` (asymétrique).
-
-    Returns
-    -------
-    dict[str, dict[str, float]]
-        Matrice ``{engine_a: {engine_b: divergence}}`` symétrique pour
-        ``js``, asymétrique pour ``kl``.  La diagonale vaut 0.
-    """
-    if metric not in ("js", "kl"):
-        raise ValueError(f"metric doit être 'js' ou 'kl' — reçu {metric!r}")
-    fn = jensen_shannon_divergence if metric == "js" else kl_divergence
-
-    engines = sorted(distributions.keys())
-    matrix: dict[str, dict[str, float]] = {a: {} for a in engines}
-    for a in engines:
-        for b in engines:
-            if a == b:
-                matrix[a][b] = 0.0
-            elif metric == "js" and b in matrix and a in matrix[b]:
-                # Symétrique : recopie pour éviter de recalculer
-                matrix[a][b] = matrix[b][a]
-            else:
-                matrix[a][b] = fn(distributions[a], distributions[b])
-    return matrix
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Complémentarité (oracle token recall)
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def _word_multiset(text: str) -> Counter[str]:
-    """Décomposition en multiset de tokens (séparateur whitespace)."""
-    return Counter(tok for tok in text.split() if tok)
-
-
-def oracle_token_recall(
-    reference: str,
-    hypotheses: dict[str, str],
-) -> float:
-    """Borne supérieure (proxy bag-of-words) du token-recall atteignable
-    par un voting majoritaire entre tous les moteurs fournis.
-
-    Pour chaque token de la référence (avec sa multiplicité), on
-    considère qu'il est "préservé" par l'ensemble si au moins un moteur
-    en produit une occurrence non encore comptée.  Le score est le ratio
-    d'occurrences GT préservées sur le total.
-
-    Parameters
-    ----------
-    reference:
-        Texte GT.
-    hypotheses:
-        ``{engine_name: hypothesis_text}``.
-
-    Returns
-    -------
-    float
-        Ratio dans ``[0, 1]``.  ``1.0`` = chaque token GT est présent
-        dans au moins une hypothèse à hauteur de sa multiplicité.
-
-    Note
-    ----
-    Cette borne est **optimiste** (supérieure à la vraie borne par
-    voting séquentiel) car elle ignore l'ordre d'apparition.  Pour le
-    diagnostic « un voting vaut-il l'effort ? » le proxy suffit ; pour
-    une vraie borne il faudrait un alignement séquentiel.
-    """
-    ref_counter = _word_multiset(reference)
-    if not ref_counter or not hypotheses:
-        return 1.0 if not ref_counter else 0.0
-
-    hyp_counters = [_word_multiset(h) for h in hypotheses.values()]
-    total_ref = sum(ref_counter.values())
-    preserved = 0
-    for token, gt_count in ref_counter.items():
-        # Pour chaque moteur, le nombre d'occurrences disponibles, plafonné
-        # à la multiplicité GT.  L'oracle prend le max sur les moteurs.
-        best = max((min(gt_count, hc.get(token, 0)) for hc in hyp_counters), default=0)
-        preserved += best
-    return preserved / total_ref
-
-
-def complementarity_gap(
-    reference: str,
-    hypotheses: dict[str, str],
-) -> dict[str, float]:
-    """Compare l'oracle au meilleur moteur seul.
-
-    Returns
-    -------
-    dict
-        ``{
-            "oracle_recall": float,        # bag-of-words recall de l'oracle
-            "best_single_recall": float,   # meilleur recall token d'un moteur seul
-            "best_engine": str,            # nom du moteur correspondant
-            "absolute_gap": float,         # oracle - best_single (toujours ≥ 0)
-            "relative_gap": float,         # absolute_gap / (1 - best_single + ε)
-                                           # = fraction des erreurs encore évitables
-                                           # par un ensemble
-        }``
-    """
-    ref_counter = _word_multiset(reference)
-    total = sum(ref_counter.values())
-    if not total:
-        return {
-            "oracle_recall": 1.0,
-            "best_single_recall": 1.0,
-            "best_engine": "",
-            "absolute_gap": 0.0,
-            "relative_gap": 0.0,
-        }
-
-    def _single_recall(hyp_text: str) -> float:
-        hc = _word_multiset(hyp_text)
-        preserved = sum(min(gt, hc.get(tok, 0)) for tok, gt in ref_counter.items())
-        return preserved / total
-
-    if not hypotheses:
-        return {
-            "oracle_recall": 0.0,
-            "best_single_recall": 0.0,
-            "best_engine": "",
-            "absolute_gap": 0.0,
-            "relative_gap": 0.0,
-        }
-
-    per_engine = {name: _single_recall(h) for name, h in hypotheses.items()}
-    best_engine, best_recall = max(per_engine.items(), key=lambda kv: kv[1])
-    oracle = oracle_token_recall(reference, hypotheses)
-
-    absolute_gap = max(0.0, oracle - best_recall)
-    # relative_gap : fraction des erreurs du meilleur moteur que l'ensemble
-    # serait théoriquement capable de récupérer (∈ [0, 1])
-    headroom = max(1.0 - best_recall, 1e-12)
-    relative_gap = min(1.0, absolute_gap / headroom)
-
-    return {
-        "oracle_recall": oracle,
-        "best_single_recall": best_recall,
-        "best_engine": best_engine,
-        "absolute_gap": absolute_gap,
-        "relative_gap": relative_gap,
-    }
-
-
-def pairwise_disagreement_rate(
-    reference: str,
-    hyp_a: str,
-    hyp_b: str,
-) -> float:
-    """Fraction de tokens GT pour lesquels A et B sont en désaccord.
-
-    Un désaccord = (l'un préserve le token, l'autre non) OU
-    (les deux le ratent mais avec des substitutions différentes — non
-    capturé ici, on reste sur la version simple présence/absence).
-
-    Returns
-    -------
-    float
-        Ratio dans ``[0, 1]``.  ``0`` = A et B font les mêmes choix
-        (pas de gain d'ensemble).  ``1`` = A et B sont toujours en
-        désaccord (gain d'ensemble maximal).
-    """
-    ref_counter = _word_multiset(reference)
-    if not ref_counter:
-        return 0.0
-    a = _word_multiset(hyp_a)
-    b = _word_multiset(hyp_b)
-    total = sum(ref_counter.values())
-    disagree = 0
-    for tok, gt_count in ref_counter.items():
-        a_pres = min(gt_count, a.get(tok, 0))
-        b_pres = min(gt_count, b.get(tok, 0))
-        # Compte les positions où A et B donnent une réponse différente
-        disagree += abs(a_pres - b_pres)
-    return disagree / total
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Agrégation au niveau benchmark (Sprint 36)
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def compute_inter_engine_analysis(
-    *,
-    per_engine_outputs: dict[str, dict[str, str]],
-    ground_truths: dict[str, str],
-    taxonomy_distributions: dict[str, dict[str, float]] | None = None,
-    divergence_metric: str = "js",
-) -> dict:
-    """Agrège les métriques inter-moteurs sur l'ensemble du corpus.
-
-    Parameters
-    ----------
-    per_engine_outputs:
-        ``{engine_name: {doc_id: hypothesis_text}}``.  Une entrée par
-        moteur, avec une hypothèse par document.  Les documents absents
-        d'un moteur (échecs, timeouts) sont simplement ignorés pour ce
-        moteur — l'oracle est calculé sur les moteurs qui ont produit
-        une sortie pour le doc.
-    ground_truths:
-        ``{doc_id: ground_truth_text}``.  La GT est la même pour tous
-        les moteurs ; on la passe une seule fois.
-    taxonomy_distributions:
-        ``{engine_name: {error_class: probability}}`` — typiquement
-        ``EngineReport.aggregated_taxonomy["class_distribution"]``.  Si
-        ``None`` ou vide, la divergence taxonomique n'est pas calculée.
-    divergence_metric:
-        ``"js"`` (défaut, symétrique) ou ``"kl"``.
-
-    Returns
-    -------
-    dict
-        Structure stable consommable par les détecteurs narratifs et le
-        rapport HTML :
-        ``{
-            "complementarity": {
-                "oracle_recall": float,
-                "best_single_recall": float,
-                "best_engine": str,
-                "absolute_gap": float,
-                "relative_gap": float,
-                "doc_count": int,
-                "per_doc": [{doc_id, oracle, best, gap}, ...]   # max 50 docs
-            },
-            "taxonomy_divergence": {
-                "metric": "js"|"kl",
-                "matrix": {engine_a: {engine_b: divergence}},
-                "max_pair": [engine_a, engine_b, value]   # paire la plus divergente
-            } | None,
-            "engines": [...],   # liste des moteurs analysés (ordre stable)
-        }``
-    """
-    engines = sorted(per_engine_outputs.keys())
-    result: dict = {"engines": engines}
-
-    # ── Complémentarité agrégée doc par doc ──────────────────────────────
-    if not engines:
-        result["complementarity"] = None
-    else:
-        total_oracle_preserved = 0
-        total_ref_tokens = 0
-        per_engine_preserved: dict[str, int] = {name: 0 for name in engines}
-        per_doc_records: list[dict] = []
-
-        for doc_id, gt in ground_truths.items():
-            ref_counter = _word_multiset(gt)
-            ref_total = sum(ref_counter.values())
-            if not ref_total:
-                continue
-            total_ref_tokens += ref_total
-
-            doc_hyps: dict[str, str] = {}
-            for name in engines:
-                hyp = per_engine_outputs.get(name, {}).get(doc_id)
-                if hyp is not None:
-                    doc_hyps[name] = hyp
-
-            if not doc_hyps:
-                continue
-
-            hyp_counters = {n: _word_multiset(h) for n, h in doc_hyps.items()}
-
-            doc_oracle = 0
-            doc_best_per_engine: dict[str, int] = {n: 0 for n in doc_hyps}
-            for tok, gt_count in ref_counter.items():
-                # Oracle : meilleur des moteurs sur ce token
-                best_for_token = 0
-                for name, hc in hyp_counters.items():
-                    preserved = min(gt_count, hc.get(tok, 0))
-                    doc_best_per_engine[name] += preserved
-                    if preserved > best_for_token:
-                        best_for_token = preserved
-                doc_oracle += best_for_token
-
-            total_oracle_preserved += doc_oracle
-            for name, count in doc_best_per_engine.items():
-                per_engine_preserved[name] += count
-
-            doc_best = max(doc_best_per_engine.values()) if doc_best_per_engine else 0
-            per_doc_records.append({
-                "doc_id": doc_id,
-                "oracle_recall": doc_oracle / ref_total,
-                "best_single_recall": doc_best / ref_total,
-                "absolute_gap": (doc_oracle - doc_best) / ref_total,
-            })
-
-        if total_ref_tokens == 0:
-            result["complementarity"] = None
-        else:
-            oracle_recall = total_oracle_preserved / total_ref_tokens
-            recalls = {
-                name: per_engine_preserved[name] / total_ref_tokens
-                for name in engines
-            }
-            best_engine, best_recall = max(recalls.items(), key=lambda kv: kv[1])
-            absolute_gap = max(0.0, oracle_recall - best_recall)
-            headroom = max(1.0 - best_recall, 1e-12)
-            relative_gap = min(1.0, absolute_gap / headroom)
-
-            # Garder les ``per_doc_records`` les plus instructifs : tri par
-            # gap absolu décroissant, top 50.  Les détecteurs narratifs
-            # n'en consomment que quelques-uns.
-            per_doc_records.sort(key=lambda r: r["absolute_gap"], reverse=True)
-            per_doc_top = per_doc_records[:50]
-
-            result["complementarity"] = {
-                "oracle_recall": oracle_recall,
-                "best_single_recall": best_recall,
-                "best_engine": best_engine,
-                "absolute_gap": absolute_gap,
-                "relative_gap": relative_gap,
-                "doc_count": len(per_doc_records),
-                "per_engine_recall": recalls,
-                "per_doc": per_doc_top,
-            }
-
-    # ── Divergence taxonomique ─────────────────────────────────────────
-    if not taxonomy_distributions:
-        result["taxonomy_divergence"] = None
-    else:
-        matrix = taxonomy_divergence_matrix(
-            taxonomy_distributions,
-            metric=divergence_metric,
-        )
-        # Cherche la paire la plus divergente (utile pour la synthèse
-        # narrative qui veut nommer les deux moteurs candidats à
-        # l'ensemble).
-        max_pair: tuple[str, str, float] = ("", "", 0.0)
-        names = sorted(matrix.keys())
-        for i, a in enumerate(names):
-            for b in names[i + 1:]:
-                v = matrix[a][b]
-                if v > max_pair[2]:
-                    max_pair = (a, b, v)
-
-        result["taxonomy_divergence"] = {
-            "metric": divergence_metric,
-            "matrix": matrix,
-            "max_pair": list(max_pair) if max_pair[2] > 0 else None,
-        }
-
-    return result
-
+from picarones.measurements.inter_engine import *  # noqa: F401, F403
 
-__all__ = [
-    "kl_divergence",
-    "jensen_shannon_divergence",
-    "taxonomy_divergence_matrix",
-    "oracle_token_recall",
-    "complementarity_gap",
-    "pairwise_disagreement_rate",
-    "compute_inter_engine_analysis",
-]
+import picarones.measurements.inter_engine as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/layout.py

@@ -1,280 +1,19 @@
-"""Layout F1 par type de région — Sprint 54.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.layout`.
 
-Sprint 54 — A.II.2.2 du plan d'évolution 2026.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.layout import ...``) de continuer
+à fonctionner sans modification.
 
-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.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-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"]
-
+from picarones.measurements.layout import *  # noqa: F401, F403
 
-__all__ = [
-    "Region",
-    "compute_layout_metrics",
-    "layout_f1",
-]
+import picarones.measurements.layout as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/levers.py

@@ -1,561 +1,19 @@
-"""Section « Leviers d'amélioration » — Sprint 82 (A.I.9).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.levers`.
 
-Sprint 82 — A.I.9 du plan d'évolution 2026.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.levers import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-Le moteur narratif (Sprint 19) émet des `Fact` qui décrivent **ce
-qui s'est passé** dans le benchmark : qui gagne, qui s'effondre,
-qui est fragile.  Ce sprint répond à une question
-complémentaire : **sur quelle dimension le bénéfice attendu d'une
-amélioration serait-il le plus visible ?**
-
-Pas de prescription
--------------------
-Picarones est un **outil de recherche**, pas un atelier de
-production.  Le module ne dit jamais *« faites X »* ni
-*« utilisez le moteur Y »* ; il agrège des **observations
-factuelles** déjà calculées dans d'autres modules (Sprints 75-81)
-et les présente comme un récapitulatif compact en bas du rapport.
-Le chercheur lit, juge et arbitre.
-
-Exemples de leviers émis
-------------------------
-- *« 65 % des erreurs de Tesseract sont de classe récupérable
-  (case_error, ligature_error, abbreviation_error) — un
-  post-processing trivial absorberait une partie. »*
-- *« 12 % de vos documents concentrent 78 % du CER total
-  (Pareto-CER). »*
-- *« Le déficit projeté du moteur le plus fragile sur le corpus
-  réel est de 4,2 points de CER (Sprint 81). »*
-- *« Le top-3 des tokens GT systématiquement modernisés est
-  maistre, nostre, veoir (Sprint 80). »*
-
-Structure
----------
-Module parallèle au registre narratif Sprint 19 : `Lever` est la
-dataclass équivalente à `Fact`, `LeverImportance` reprend la
-sémantique de `FactImportance`, `@register_lever` indexe les
-détecteurs.  Garde-fou anti-hallucination identique : chaque
-nombre rendu doit être présent dans le `payload` du `Lever`.
-
-Les détecteurs lisent **uniquement** des structures déjà
-construites par le pipeline du benchmark — ils ne calculent rien
-de nouveau, ils synthétisent.  C'est pourquoi le module est
-résolument optionnel : si un benchmark n'expose pas
-`taxonomy_aggregated`, `inter_engine_analysis`, `corpus_difficulty`,
-`lexical_modernization` ou `robustness_projection`, le détecteur
-correspondant retourne tout simplement `[]`.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-import threading
-from dataclasses import dataclass
-from enum import Enum
-from typing import Callable
-
-logger = logging.getLogger(__name__)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Modèle
-# ──────────────────────────────────────────────────────────────────────────
-
-
-class LeverType(str, Enum):
-    """Types de leviers détectés."""
-
-    DOMINANT_RECOVERABLE_CLASS = "dominant_recoverable_class"
-    """Une part importante des erreurs d'un moteur est dans des classes
-    catégorisées « récupérables » (Sprint 77)."""
-
-    PARETO_CONCENTRATION = "pareto_concentration"
-    """Une fraction minoritaire de documents concentre une fraction
-    majoritaire du CER total — l'inspection ciblée est rentable."""
-
-    COMPLEMENTARITY_OBSERVATION = "complementarity_observation"
-    """Le `complementarity_gap` (Sprint 35) entre l'oracle et le
-    meilleur moteur seul est non négligeable — observation factuelle,
-    aucune recommandation d'ensemble."""
-
-    LEXICAL_MODERNIZATION_OBSERVATION = "lexical_modernization_observation"
-    """Top-N des tokens GT systématiquement modernisés (Sprint 80)."""
-
-    ROBUSTNESS_PROJECTION_OBSERVATION = "robustness_projection_observation"
-    """Déficit projeté global le plus important pour un moteur sur
-    le corpus réel (Sprint 81)."""
-
-
-class LeverImportance(int, Enum):
-    """Importance éditoriale d'un levier."""
-
-    HIGH = 70
-    MEDIUM = 40
-    LOW = 10
-
-
-@dataclass
-class Lever:
-    """Observation factuelle synthétisable en encart « Leviers ».
-
-    Attributes
-    ----------
-    type:
-        Le type de levier (voir `LeverType`).
-    importance:
-        Score qui décide l'ordre d'affichage.
-    payload:
-        Données brutes — **tout chiffre rendu dans le HTML doit
-        provenir d'ici**, jamais d'un calcul du renderer.
-    engines_involved:
-        Noms des moteurs concernés (peut être vide pour un levier
-        corpus-wide).
-    """
-
-    type: LeverType
-    importance: LeverImportance
-    payload: dict
-    engines_involved: tuple[str, ...] = ()
-
-    def as_dict(self) -> dict:
-        return {
-            "type": self.type.value,
-            "importance": int(self.importance),
-            "payload": self.payload,
-            "engines_involved": list(self.engines_involved),
-        }
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Registre
-# ──────────────────────────────────────────────────────────────────────────
-
-
-LeverDetectorFn = Callable[[dict], list[Lever]]
-
-
-@dataclass(frozen=True)
-class LeverDetectorEntry:
-    lever_type: LeverType
-    fn: LeverDetectorFn
-    priority: int
-
-
-_LEVER_REGISTRY: dict[LeverType, LeverDetectorEntry] = {}
-_LEVER_REGISTRY_LOCK = threading.Lock()
-
-
-def register_lever(
-    lever_type: LeverType,
-    *,
-    priority: int,
-) -> Callable[[LeverDetectorFn], LeverDetectorFn]:
-    """Décorateur : enregistre un détecteur de levier.
-
-    Une seule fonction par type — réenregistrer lève `ValueError`.
-    """
-    def _decorator(fn: LeverDetectorFn) -> LeverDetectorFn:
-        with _LEVER_REGISTRY_LOCK:
-            if lever_type in _LEVER_REGISTRY:
-                raise ValueError(
-                    f"Détecteur déjà enregistré pour {lever_type.value!r} : "
-                    f"{_LEVER_REGISTRY[lever_type].fn.__name__}."
-                )
-            _LEVER_REGISTRY[lever_type] = LeverDetectorEntry(
-                lever_type=lever_type, fn=fn, priority=int(priority),
-            )
-        return fn
-    return _decorator
-
-
-def unregister_lever(lever_type: LeverType) -> None:
-    with _LEVER_REGISTRY_LOCK:
-        _LEVER_REGISTRY.pop(lever_type, None)
-
-
-def iter_lever_detectors() -> list[LeverDetectorEntry]:
-    with _LEVER_REGISTRY_LOCK:
-        entries = list(_LEVER_REGISTRY.values())
-    entries.sort(key=lambda e: e.priority)
-    return entries
-
-
-def detect_levers(benchmark_data: dict) -> list[Lever]:
-    """Applique tous les détecteurs enregistrés et trie par importance
-    décroissante puis priorité d'enregistrement croissante."""
-    levers: list[Lever] = []
-    for entry in iter_lever_detectors():
-        try:
-            result = entry.fn(benchmark_data)
-        except Exception as e:
-            logger.warning(
-                "[levers.detector.%s] fonctionnalité dégradée : %s",
-                entry.lever_type.value, e,
-            )
-            continue
-        if result:
-            levers.extend(result)
-    # Tri stable : importance décroissante d'abord
-    levers.sort(key=lambda lv: -int(lv.importance))
-    return levers
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Détecteurs
-# ──────────────────────────────────────────────────────────────────────────
-
-
-# Catégorisation reprise du Sprint 77 (taxonomy_comparison.py).
-# Volontairement dupliquée ici pour ne pas introduire d'import
-# circulaire — la sémantique est gelée.
-_RECOVERABILITY: dict[str, str] = {
-    "case_error":         "recoverable",
-    "ligature_error":     "recoverable",
-    "abbreviation_error": "recoverable",
-    "diacritic_error":    "difficult",
-    "visual_confusion":   "difficult",
-    "hapax":              "difficult",
-    "lacuna":             "irrecoverable",
-    "oov_character":      "irrecoverable",
-    "segmentation_error": "irrecoverable",
-}
-
-
-@register_lever(LeverType.DOMINANT_RECOVERABLE_CLASS, priority=10)
-def detect_dominant_recoverable_class(
-    benchmark_data: dict,
-    *,
-    threshold: float = 0.30,
-) -> list[Lever]:
-    """Émet un levier si ≥ `threshold` des erreurs d'un moteur sont
-    classifiées récupérables (catégorisation Sprint 77).
-
-    Lit `benchmark_data["engines"][i]["aggregated_taxonomy"]` —
-    structure produite par le runner historique. Si absent, retourne
-    [].
-    """
-    engines = benchmark_data.get("engines") or []
-    out: list[Lever] = []
-    for engine in engines:
-        taxonomy = engine.get("aggregated_taxonomy")
-        if not taxonomy:
-            continue
-        # `taxonomy` peut être {class_name: int} ou un dict avec une
-        # sous-clé "counts" — on accepte les deux conventions.
-        counts = taxonomy.get("counts") if isinstance(taxonomy, dict) and "counts" in taxonomy else taxonomy
-        if not isinstance(counts, dict) or not counts:
-            continue
-        try:
-            int_counts = {k: int(v) for k, v in counts.items() if isinstance(v, (int, float))}
-        except (TypeError, ValueError):
-            continue
-        total = sum(int_counts.values())
-        if total <= 0:
-            continue
-        recoverable_total = sum(
-            v for k, v in int_counts.items()
-            if _RECOVERABILITY.get(k) == "recoverable"
-        )
-        share = recoverable_total / total
-        if share < threshold:
-            continue
-        # Classes récupérables non vides triées par count décroissant
-        breakdown = sorted(
-            (
-                (k, v) for k, v in int_counts.items()
-                if _RECOVERABILITY.get(k) == "recoverable" and v > 0
-            ),
-            key=lambda kv: -kv[1],
-        )
-        importance = (
-            LeverImportance.HIGH if share >= 0.50 else LeverImportance.MEDIUM
-        )
-        out.append(Lever(
-            type=LeverType.DOMINANT_RECOVERABLE_CLASS,
-            importance=importance,
-            payload={
-                "engine": engine.get("name") or "?",
-                "share_recoverable": share,
-                "share_recoverable_pct": round(share * 100, 1),
-                "n_recoverable": recoverable_total,
-                "n_total_errors": total,
-                "top_classes": [
-                    {"class": k, "count": v} for k, v in breakdown[:3]
-                ],
-            },
-            engines_involved=(engine.get("name") or "?",),
-        ))
-    return out
-
-
-@register_lever(LeverType.PARETO_CONCENTRATION, priority=20)
-def detect_pareto_concentration(
-    benchmark_data: dict,
-    *,
-    top_share: float = 0.20,
-    cer_share_threshold: float = 0.50,
-) -> list[Lever]:
-    """Émet un levier si une fraction minoritaire de documents
-    (`top_share`) concentre plus de `cer_share_threshold` du CER
-    total cumulé sur le moteur leader.
-
-    Lit `benchmark_data["per_doc_cer"][engine_name]` ou tente de
-    reconstruire depuis `benchmark_data["engines"][...]["per_doc"]`.
-    Si rien d'exploitable, retourne [].
-    """
-    ranking = benchmark_data.get("ranking") or []
-    if not ranking:
-        return []
-    leader = ranking[0]
-    leader_name = leader.get("engine")
-    if not leader_name:
-        return []
-
-    per_doc_cer: list[float] = []
-    # Voie 1 : structure plate "per_doc_cer"
-    flat = benchmark_data.get("per_doc_cer") or {}
-    if isinstance(flat, dict) and leader_name in flat and isinstance(flat[leader_name], list):
-        per_doc_cer = [float(x) for x in flat[leader_name] if isinstance(x, (int, float))]
-    else:
-        # Voie 2 : engine.per_doc liste de dicts {cer: float}
-        for engine in benchmark_data.get("engines") or []:
-            if engine.get("name") != leader_name:
-                continue
-            per_doc = engine.get("per_doc") or []
-            for entry in per_doc:
-                if isinstance(entry, dict) and isinstance(entry.get("cer"), (int, float)):
-                    per_doc_cer.append(float(entry["cer"]))
-            break
-
-    if not per_doc_cer:
-        return []
-    total_cer = sum(per_doc_cer)
-    if total_cer <= 0:
-        return []
-
-    sorted_cer = sorted(per_doc_cer, reverse=True)
-    n = len(sorted_cer)
-    n_top = max(1, int(round(top_share * n)))
-    top_cer_sum = sum(sorted_cer[:n_top])
-    share_of_total = top_cer_sum / total_cer
-    if share_of_total < cer_share_threshold:
-        return []
-    importance = (
-        LeverImportance.HIGH if share_of_total >= 0.75
-        else LeverImportance.MEDIUM
-    )
-    return [Lever(
-        type=LeverType.PARETO_CONCENTRATION,
-        importance=importance,
-        payload={
-            "engine": leader_name,
-            "n_docs": n,
-            "n_docs_top": n_top,
-            "top_share_pct": round((n_top / n) * 100, 1),
-            "cer_share_of_total": share_of_total,
-            "cer_share_pct": round(share_of_total * 100, 1),
-        },
-        engines_involved=(leader_name,),
-    )]
-
-
-@register_lever(LeverType.COMPLEMENTARITY_OBSERVATION, priority=30)
-def detect_complementarity_observation(
-    benchmark_data: dict,
-    *,
-    min_relative_gap: float = 0.20,
-) -> list[Lever]:
-    """Reformule factuellement le `complementarity_gap` (Sprint 35).
-
-    Lit `benchmark_data["inter_engine_analysis"]`. Garde-fou : ne
-    déclenche que si `relative_gap` ≥ `min_relative_gap`. **Aucune
-    recommandation d'ensemble** — le levier dit factuellement
-    « X points séparent l'oracle du meilleur moteur », c'est tout.
-    """
-    inter = benchmark_data.get("inter_engine_analysis") or {}
-    cgap = inter.get("complementarity_gap") or {}
-    relative_gap = cgap.get("relative_gap")
-    absolute_gap = cgap.get("absolute_gap")
-    if relative_gap is None or absolute_gap is None:
-        return []
-    try:
-        rg = float(relative_gap)
-        ag = float(absolute_gap)
-    except (TypeError, ValueError):
-        return []
-    if rg < min_relative_gap:
-        return []
-    importance = (
-        LeverImportance.HIGH if rg >= 0.50 else LeverImportance.MEDIUM
-    )
-    payload: dict = {
-        "absolute_gap": ag,
-        "absolute_gap_pct": round(ag * 100, 1),
-        "relative_gap": rg,
-        "relative_gap_pct": round(rg * 100, 1),
-    }
-    best_engine = cgap.get("best_engine") or inter.get("best_engine")
-    best_recall = cgap.get("best_recall") or inter.get("best_engine_recall")
-    oracle_recall = cgap.get("oracle_recall") or inter.get("oracle_recall")
-    engines_involved: tuple[str, ...] = ()
-    if best_engine:
-        payload["best_engine"] = str(best_engine)
-        engines_involved = (str(best_engine),)
-    if isinstance(best_recall, (int, float)):
-        payload["best_recall"] = float(best_recall)
-    if isinstance(oracle_recall, (int, float)):
-        payload["oracle_recall"] = float(oracle_recall)
-    return [Lever(
-        type=LeverType.COMPLEMENTARITY_OBSERVATION,
-        importance=importance,
-        payload=payload,
-        engines_involved=engines_involved,
-    )]
-
-
-@register_lever(LeverType.LEXICAL_MODERNIZATION_OBSERVATION, priority=40)
-def detect_lexical_modernization_observation(
-    benchmark_data: dict,
-    *,
-    top_n: int = 3,
-    min_total: int = 3,
-    min_rate: float = 0.50,
-) -> list[Lever]:
-    """Pour chaque moteur disposant de `lexical_modernization`,
-    émet un levier listant les `top_n` tokens GT les plus modernisés.
-
-    Lit `benchmark_data["engines"][i]["lexical_modernization"]` qui
-    suit la forme produite par `compute_lexical_modernization` du
-    Sprint 80 (`{"n_gt_tokens": int, "tokens": dict}`).
-    """
-    out: list[Lever] = []
-    for engine in benchmark_data.get("engines") or []:
-        data = engine.get("lexical_modernization")
-        if not isinstance(data, dict):
-            continue
-        tokens = data.get("tokens") or {}
-        if not isinstance(tokens, dict) or not tokens:
-            continue
-        candidates: list[tuple[str, dict]] = []
-        for gt_token, slot in tokens.items():
-            if not isinstance(slot, dict):
-                continue
-            n_total = slot.get("n_total")
-            rate = slot.get("rate_modernized")
-            if not isinstance(n_total, (int, float)) or not isinstance(rate, (int, float)):
-                continue
-            if int(n_total) < min_total:
-                continue
-            if float(rate) < min_rate:
-                continue
-            candidates.append((gt_token, dict(slot)))
-        if not candidates:
-            continue
-        candidates.sort(
-            key=lambda kv: (-float(kv[1].get("rate_modernized", 0.0)),
-                            -int(kv[1].get("n_total", 0)),
-                            kv[0]),
-        )
-        top = candidates[:top_n]
-        engine_name = engine.get("name") or "?"
-        max_rate = max(float(slot.get("rate_modernized", 0.0)) for _, slot in top)
-        importance = (
-            LeverImportance.HIGH if max_rate >= 0.90 else LeverImportance.MEDIUM
-        )
-        out.append(Lever(
-            type=LeverType.LEXICAL_MODERNIZATION_OBSERVATION,
-            importance=importance,
-            payload={
-                "engine": engine_name,
-                "top_tokens": [
-                    {
-                        "gt_token": gt,
-                        "n_total": int(slot.get("n_total", 0)),
-                        "rate_modernized": float(slot.get("rate_modernized", 0.0)),
-                        "rate_modernized_pct": round(
-                            float(slot.get("rate_modernized", 0.0)) * 100, 1,
-                        ),
-                    }
-                    for gt, slot in top
-                ],
-            },
-            engines_involved=(engine_name,),
-        ))
-    return out
-
-
-@register_lever(LeverType.ROBUSTNESS_PROJECTION_OBSERVATION, priority=50)
-def detect_robustness_projection_observation(
-    benchmark_data: dict,
-    *,
-    min_total_deficit: float = 0.02,
-) -> list[Lever]:
-    """Lit l'agrégation par moteur de la projection de robustesse
-    (Sprint 81). Émet le levier pour le moteur dont
-    `total_expected_deficit` est ≥ `min_total_deficit` (par défaut
-    2 points de CER).
-
-    Lit `benchmark_data["robustness_projection_aggregated"]` —
-    structure produite par `aggregate_projection_per_engine`.
-    """
-    agg = benchmark_data.get("robustness_projection_aggregated") or {}
-    if not isinstance(agg, dict) or not agg:
-        return []
-    out: list[Lever] = []
-    for engine_name, info in agg.items():
-        if not isinstance(info, dict):
-            continue
-        total_deficit = info.get("total_expected_deficit")
-        worst_type = info.get("worst_degradation_type")
-        worst_deficit = info.get("worst_degradation_deficit")
-        if not isinstance(total_deficit, (int, float)):
-            continue
-        if float(total_deficit) < min_total_deficit:
-            continue
-        importance = (
-            LeverImportance.HIGH if float(total_deficit) >= 0.05
-            else LeverImportance.MEDIUM
-        )
-        payload: dict = {
-            "engine": engine_name,
-            "total_expected_deficit": float(total_deficit),
-            "total_expected_deficit_pct": round(float(total_deficit) * 100, 1),
-            "n_degradation_types": int(info.get("n_degradation_types") or 0),
-        }
-        if isinstance(worst_type, str):
-            payload["worst_degradation_type"] = worst_type
-        if isinstance(worst_deficit, (int, float)):
-            payload["worst_degradation_deficit"] = float(worst_deficit)
-            payload["worst_degradation_deficit_pct"] = round(
-                float(worst_deficit) * 100, 1,
-            )
-        out.append(Lever(
-            type=LeverType.ROBUSTNESS_PROJECTION_OBSERVATION,
-            importance=importance,
-            payload=payload,
-            engines_involved=(engine_name,),
-        ))
-    # Tri par déficit décroissant pour stabilité d'affichage.
-    out.sort(
-        key=lambda lv: -float(lv.payload.get("total_expected_deficit") or 0.0),
-    )
-    return out
-
+from picarones.measurements.levers import *  # noqa: F401, F403
 
-__all__ = [
-    "Lever",
-    "LeverImportance",
-    "LeverType",
-    "LeverDetectorEntry",
-    "register_lever",
-    "unregister_lever",
-    "iter_lever_detectors",
-    "detect_levers",
-    "detect_dominant_recoverable_class",
-    "detect_pareto_concentration",
-    "detect_complementarity_observation",
-    "detect_lexical_modernization_observation",
-    "detect_robustness_projection_observation",
-]
+import picarones.measurements.levers as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/line_metrics.py

@@ -1,286 +1,19 @@
-"""Distribution des erreurs CER par ligne — Sprint 10.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.line_metrics`.
 
-Métriques calculées
--------------------
-- CER par ligne    : distance d'édition caractère/longueur GT sur chaque paire de lignes
-- Percentiles      : p50, p75, p90, p95, p99 sur la distribution des CER ligne
-- Taux catastrophiques : % de lignes dépassant des seuils configurables (30 %, 50 %, 100 %)
-- Coefficient de Gini  : concentration des erreurs (0 = uniformes, 1 = toutes concentrées)
-- Carte thermique      : CER moyen par tranche de position dans le document
-"""
-
-from __future__ import annotations
-
-import unicodedata
-from dataclasses import dataclass
-from typing import Optional
-
-
-# ---------------------------------------------------------------------------
-# CER d'une paire de lignes (distance d'édition Levenshtein normalisée)
-# ---------------------------------------------------------------------------
-
-def _edit_distance(a: str, b: str) -> int:
-    """Distance de Levenshtein entre deux chaînes."""
-    if not a:
-        return len(b)
-    if not b:
-        return len(a)
-    prev = list(range(len(b) + 1))
-    for i, ca in enumerate(a, 1):
-        curr = [i]
-        for j, cb in enumerate(b, 1):
-            cost = 0 if ca == cb else 1
-            curr.append(min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost))
-        prev = curr
-    return prev[-1]
-
-
-def _line_cer(ref_line: str, hyp_line: str) -> float:
-    """CER pour une paire de lignes.  Retourne 1.0 si le GT est vide et que l'hyp ne l'est pas."""
-    ref = unicodedata.normalize("NFC", ref_line.strip())
-    hyp = unicodedata.normalize("NFC", hyp_line.strip())
-    if not ref:
-        return 0.0 if not hyp else 1.0
-    dist = _edit_distance(ref, hyp)
-    return dist / len(ref)
-
-
-# ---------------------------------------------------------------------------
-# Percentiles (implémentation pur-Python, sans numpy)
-# ---------------------------------------------------------------------------
-
-def _percentile(sorted_values: list[float], p: float) -> float:
-    """Retourne le p-ième percentile (0 ≤ p ≤ 100) d'une liste triée."""
-    if not sorted_values:
-        return 0.0
-    n = len(sorted_values)
-    index = p / 100 * (n - 1)
-    lo = int(index)
-    hi = min(lo + 1, n - 1)
-    frac = index - lo
-    return sorted_values[lo] + frac * (sorted_values[hi] - sorted_values[lo])
-
-
-# ---------------------------------------------------------------------------
-# Coefficient de Gini
-# ---------------------------------------------------------------------------
-
-def _gini(values: list[float]) -> float:
-    """Coefficient de Gini des erreurs (0 = uniformes, 1 = toutes concentrées).
-
-    Formule : G = (2 * Σ i*x_i) / (n * Σ x_i) - (n+1)/n
-    sur les valeurs triées par ordre croissant.
-    """
-    if not values:
-        return 0.0
-    xs = sorted(max(v, 0.0) for v in values)
-    n = len(xs)
-    total = sum(xs)
-    if total == 0.0:
-        return 0.0
-    weighted_sum = sum((i + 1) * x for i, x in enumerate(xs))
-    return (2.0 * weighted_sum) / (n * total) - (n + 1) / n
-
-
-# ---------------------------------------------------------------------------
-# Résultat structuré
-# ---------------------------------------------------------------------------
-
-@dataclass
-class LineMetrics:
-    """Distribution des erreurs CER par ligne pour une paire (GT, hypothèse)."""
-
-    cer_per_line: list[float]
-    """CER de chaque ligne (longueur = nombre de lignes GT)."""
-
-    percentiles: dict[str, float]
-    """Percentiles : p50, p75, p90, p95, p99."""
-
-    catastrophic_rate: dict[str, float]
-    """Taux de lignes catastrophiques pour chaque seuil (ex. {0.3: 0.12, 0.5: 0.07, 1.0: 0.02})."""
-
-    gini: float
-    """Coefficient de Gini des erreurs (0 → uniforme, 1 → concentrées)."""
-
-    heatmap: list[float]
-    """CER moyen par tranche de position dans le document (longueur = heatmap_bins)."""
-
-    line_count: int
-    """Nombre de lignes GT traitées."""
-
-    mean_cer: float
-    """CER moyen sur l'ensemble des lignes."""
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.line_metrics import ...``) de continuer
+à fonctionner sans modification.
 
-    def as_dict(self) -> dict:
-        return {
-            "cer_per_line": [round(v, 6) for v in self.cer_per_line],
-            "percentiles": {k: round(v, 6) for k, v in self.percentiles.items()},
-            "catastrophic_rate": {str(k): round(v, 6) for k, v in self.catastrophic_rate.items()},
-            "gini": round(self.gini, 6),
-            "heatmap": [round(v, 6) for v in self.heatmap],
-            "line_count": self.line_count,
-            "mean_cer": round(self.mean_cer, 6),
-        }
-
-    @classmethod
-    def from_dict(cls, d: dict) -> "LineMetrics":
-        return cls(
-            cer_per_line=d.get("cer_per_line", []),
-            percentiles=d.get("percentiles", {}),
-            catastrophic_rate={float(k): v for k, v in d.get("catastrophic_rate", {}).items()},
-            gini=d.get("gini", 0.0),
-            heatmap=d.get("heatmap", []),
-            line_count=d.get("line_count", 0),
-            mean_cer=d.get("mean_cer", 0.0),
-        )
-
-
-# ---------------------------------------------------------------------------
-# Calcul principal
-# ---------------------------------------------------------------------------
-
-def compute_line_metrics(
-    reference: str,
-    hypothesis: str,
-    thresholds: Optional[list[float]] = None,
-    heatmap_bins: int = 10,
-) -> LineMetrics:
-    """Calcule la distribution des erreurs CER ligne par ligne.
-
-    Parameters
-    ----------
-    reference:
-        Texte de vérité terrain (GT) avec sauts de ligne.
-    hypothesis:
-        Texte produit par le moteur OCR.
-    thresholds:
-        Seuils CER pour le taux catastrophique. Défaut : [0.30, 0.50, 1.00].
-    heatmap_bins:
-        Nombre de tranches de position pour la carte thermique.
-
-    Returns
-    -------
-    LineMetrics
-    """
-    if thresholds is None:
-        thresholds = [0.30, 0.50, 1.00]
-
-    ref_lines = reference.splitlines()
-    hyp_lines = hypothesis.splitlines()
-
-    # Aligner les lignes GT / hypothèse — on prend au moins autant de lignes que le GT
-    n = len(ref_lines)
-    if n == 0:
-        # Pas de lignes : retourner des métriques neutres
-        return LineMetrics(
-            cer_per_line=[],
-            percentiles={f"p{p}": 0.0 for p in (50, 75, 90, 95, 99)},
-            catastrophic_rate={t: 0.0 for t in thresholds},
-            gini=0.0,
-            heatmap=[0.0] * heatmap_bins,
-            line_count=0,
-            mean_cer=0.0,
-        )
-
-    # Aligner en ignorant les lignes d'hypothèse supplémentaires
-    # Si l'hypothèse a moins de lignes, les lignes manquantes comptent comme supprimées (CER = 1.0)
-    cer_per_line: list[float] = []
-    for i, ref_line in enumerate(ref_lines):
-        hyp_line = hyp_lines[i] if i < len(hyp_lines) else ""
-        cer_per_line.append(min(_line_cer(ref_line, hyp_line), 1.0))
-
-    sorted_cer = sorted(cer_per_line)
-
-    # Percentiles
-    percentiles = {
-        f"p{p}": _percentile(sorted_cer, p)
-        for p in (50, 75, 90, 95, 99)
-    }
-
-    # Taux catastrophiques
-    catastrophic_rate: dict[float, float] = {}
-    for t in thresholds:
-        count = sum(1 for v in cer_per_line if v > t)
-        catastrophic_rate[t] = count / n
-
-    # Gini
-    gini = _gini(cer_per_line)
-
-    # Carte thermique par tranche de position
-    bins = heatmap_bins
-    heatmap: list[float] = []
-    for b in range(bins):
-        start = int(b * n / bins)
-        end = int((b + 1) * n / bins)
-        slice_ = cer_per_line[start:end]
-        heatmap.append(sum(slice_) / len(slice_) if slice_ else 0.0)
-
-    mean_cer = sum(cer_per_line) / n
-
-    return LineMetrics(
-        cer_per_line=cer_per_line,
-        percentiles=percentiles,
-        catastrophic_rate=catastrophic_rate,
-        gini=gini,
-        heatmap=heatmap,
-        line_count=n,
-        mean_cer=mean_cer,
-    )
-
-
-# ---------------------------------------------------------------------------
-# Agrégation sur un corpus
-# ---------------------------------------------------------------------------
-
-def aggregate_line_metrics(results: list[LineMetrics]) -> dict:
-    """Agrège les métriques de distribution par ligne sur un corpus.
-
-    Returns
-    -------
-    dict
-        Statistiques agrégées : Gini moyen, percentiles moyens, taux catastrophiques moyens.
-    """
-    if not results:
-        return {}
-
-    import statistics as _stats
-
-    gini_values = [r.gini for r in results]
-    mean_cer_values = [r.mean_cer for r in results]
-
-    # Percentiles moyens
-    pct_keys = ["p50", "p75", "p90", "p95", "p99"]
-    avg_percentiles = {}
-    for k in pct_keys:
-        vals = [r.percentiles.get(k, 0.0) for r in results]
-        avg_percentiles[k] = round(sum(vals) / len(vals), 6) if vals else 0.0
-
-    # Taux catastrophiques moyens (union des seuils)
-    all_thresholds: set[float] = set()
-    for r in results:
-        all_thresholds.update(r.catastrophic_rate.keys())
-    avg_catastrophic: dict[str, float] = {}
-    for t in sorted(all_thresholds):
-        vals = [r.catastrophic_rate.get(t, 0.0) for r in results]
-        avg_catastrophic[str(t)] = round(sum(vals) / len(vals), 6) if vals else 0.0
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
+"""
 
-    # Heatmap moyenne (longueur = max des longueurs)
-    if results and results[0].heatmap:
-        n_bins = len(results[0].heatmap)
-        heatmap_avg = []
-        for b in range(n_bins):
-            vals = [r.heatmap[b] for r in results if b < len(r.heatmap)]
-            heatmap_avg.append(round(sum(vals) / len(vals), 6) if vals else 0.0)
-    else:
-        heatmap_avg = []
+from picarones.measurements.line_metrics import *  # noqa: F401, F403
 
-    return {
-        "gini_mean": round(sum(gini_values) / len(gini_values), 6),
-        "gini_stdev": round(_stats.stdev(gini_values), 6) if len(gini_values) > 1 else 0.0,
-        "mean_cer_mean": round(sum(mean_cer_values) / len(mean_cer_values), 6),
-        "percentiles": avg_percentiles,
-        "catastrophic_rate": avg_catastrophic,
-        "heatmap": heatmap_avg,
-        "document_count": len(results),
-    }
+import picarones.measurements.line_metrics as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/longitudinal.py

@@ -1,373 +1,19 @@
-"""Métriques longitudinales — Sprint 92 (A.II.9).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.longitudinal`.
 
-Sprint 92 — A.II.9 du plan d'évolution 2026.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.longitudinal import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-L'historique SQLite (`core/history.py`, Sprint 8) collecte les
-résultats de chaque run de benchmark, mais aucune métrique
-n'en sortait dans le rapport.  Ce module exploite la série
-temporelle des CER d'un moteur pour répondre à deux
-questions :
-
-1. **Y a-t-il une tendance ?**  Régression linéaire simple
-   (méthode des moindres carrés) sur ``(t, CER)`` —  pente,
-   ordonnée à l'origine, R², n_runs.  Une pente > 0 signale
-   une régression progressive ; une pente < 0 une amélioration.
-
-2. **Y a-t-il un point de rupture ?**  Algorithme de
-   change-point pur Python (différence de moyennes maximale,
-   variante de Pettitt simplifiée).  Identifie l'index où la
-   série se sépare en deux segments avec moyennes les plus
-   différentes — typiquement le run où un modèle a changé de
-   comportement.
-
-Pas de scipy
-------------
-Pour rester sans dépendance lourde, on implémente :
-- la régression linéaire en pur Python (closed-form OLS) ;
-- le change-point par balayage exhaustif (O(N) pour de petits
-  N — l'historique d'une institution dépasse rarement quelques
-  centaines de runs).
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-import math
-import statistics
-from dataclasses import dataclass
-from datetime import datetime
-from typing import Iterable, Optional
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class LinearTrend:
-    """Résultat d'une régression linéaire sur une série CER."""
-    slope: float
-    """Pente (CER par jour). Positif = régression."""
-    intercept: float
-    """Ordonnée à l'origine."""
-    r_squared: float
-    """Qualité de l'ajustement, ∈ [0, 1]."""
-    n_runs: int
-    """Nombre de points utilisés."""
-
-    def as_dict(self) -> dict:
-        return {
-            "slope": self.slope,
-            "intercept": self.intercept,
-            "r_squared": self.r_squared,
-            "n_runs": self.n_runs,
-        }
-
-
-@dataclass
-class ChangePointResult:
-    """Résultat d'une détection de point de rupture."""
-    index: int
-    """Index de la rupture (0-based, le segment 1 est [0:index],
-    le segment 2 est [index:N])."""
-    timestamp: str
-    """Timestamp du run à la rupture."""
-    mean_before: float
-    mean_after: float
-    delta: float
-    """``mean_after - mean_before``. Positif = régression."""
-    n_before: int
-    n_after: int
-
-    def as_dict(self) -> dict:
-        return {
-            "index": self.index,
-            "timestamp": self.timestamp,
-            "mean_before": self.mean_before,
-            "mean_after": self.mean_after,
-            "delta": self.delta,
-            "n_before": self.n_before,
-            "n_after": self.n_after,
-        }
-
-
-def _parse_timestamp(ts: str) -> Optional[float]:
-    """Parse un ISO timestamp en jour ordinal float.
-
-    Tolère ``YYYY-MM-DD`` et ``YYYY-MM-DDTHH:MM:SS``.  Retourne
-    ``None`` si non parsable.
-    """
-    if not ts:
-        return None
-    formats = (
-        "%Y-%m-%dT%H:%M:%S.%f",
-        "%Y-%m-%dT%H:%M:%S",
-        "%Y-%m-%d %H:%M:%S",
-        "%Y-%m-%d",
-    )
-    for fmt in formats:
-        try:
-            dt = datetime.strptime(ts.split("+")[0].split("Z")[0], fmt)
-            return dt.toordinal() + (
-                dt.hour * 3600 + dt.minute * 60 + dt.second
-            ) / 86400.0
-        except ValueError:
-            continue
-    return None
-
-
-def compute_linear_trend(
-    cer_series: Iterable[tuple[str, float]],
-) -> Optional[LinearTrend]:
-    """Régression linéaire OLS sur une série temporelle de CER.
-
-    Parameters
-    ----------
-    cer_series:
-        Itérable de ``(timestamp_iso, cer)``.  Au moins 2 points
-        valides requis.
-
-    Returns
-    -------
-    LinearTrend | None
-        ``None`` si moins de 2 points ou si tous les timestamps
-        sont identiques (variance nulle sur t).
-    """
-    points: list[tuple[float, float]] = []
-    for ts, cer in cer_series:
-        t = _parse_timestamp(ts)
-        if t is None or cer is None:
-            continue
-        try:
-            cer_f = float(cer)
-        except (TypeError, ValueError):
-            continue
-        points.append((t, cer_f))
-    n = len(points)
-    if n < 2:
-        return None
-    xs = [p[0] for p in points]
-    ys = [p[1] for p in points]
-    x_mean = statistics.fmean(xs)
-    y_mean = statistics.fmean(ys)
-    sxx = sum((x - x_mean) ** 2 for x in xs)
-    sxy = sum((x - x_mean) * (y - y_mean) for x, y in zip(xs, ys))
-    if sxx == 0:
-        return None
-    slope = sxy / sxx
-    intercept = y_mean - slope * x_mean
-    syy = sum((y - y_mean) ** 2 for y in ys)
-    if syy == 0:
-        # Tous les CER sont égaux → R² mathématiquement indéfini ;
-        # on retourne 1.0 (parfaite "non-tendance").
-        r_squared = 1.0
-    else:
-        ss_res = sum(
-            (y - (slope * x + intercept)) ** 2
-            for x, y in zip(xs, ys)
-        )
-        r_squared = max(0.0, 1.0 - ss_res / syy)
-    return LinearTrend(
-        slope=slope,
-        intercept=intercept,
-        r_squared=r_squared,
-        n_runs=n,
-    )
-
-
-def detect_change_point(
-    cer_series: Iterable[tuple[str, float]],
-    min_segment_size: int = 3,
-) -> Optional[ChangePointResult]:
-    """Détecte le point de rupture maximisant l'écart de moyennes.
-
-    Algorithme : balayage des indices ``i`` où la série se
-    sépare en deux segments d'au moins ``min_segment_size``
-    points chacun ; on retient l'index où ``|mean_after -
-    mean_before|`` est maximal.  Variante simplifiée de Pettitt.
-
-    Parameters
-    ----------
-    cer_series:
-        Itérable de ``(timestamp_iso, cer)``.
-    min_segment_size:
-        Taille minimale des deux segments.  Défaut 3.
-
-    Returns
-    -------
-    ChangePointResult | None
-        ``None`` si la série a moins de ``2 × min_segment_size``
-        points valides.
-    """
-    points: list[tuple[str, float, float]] = []
-    for ts, cer in cer_series:
-        t = _parse_timestamp(ts)
-        if t is None or cer is None:
-            continue
-        try:
-            cer_f = float(cer)
-        except (TypeError, ValueError):
-            continue
-        points.append((ts, t, cer_f))
-    if len(points) < 2 * min_segment_size:
-        return None
-    points.sort(key=lambda p: p[1])
-    n = len(points)
-    best_index = -1
-    best_abs_delta = -1.0
-    best_delta = 0.0
-    best_mean_before = 0.0
-    best_mean_after = 0.0
-    for i in range(min_segment_size, n - min_segment_size + 1):
-        before = [p[2] for p in points[:i]]
-        after = [p[2] for p in points[i:]]
-        mean_b = statistics.fmean(before)
-        mean_a = statistics.fmean(after)
-        delta = mean_a - mean_b
-        abs_delta = abs(delta)
-        if abs_delta > best_abs_delta:
-            best_abs_delta = abs_delta
-            best_index = i
-            best_delta = delta
-            best_mean_before = mean_b
-            best_mean_after = mean_a
-    if best_index < 0:
-        return None
-    return ChangePointResult(
-        index=best_index,
-        timestamp=points[best_index][0],
-        mean_before=best_mean_before,
-        mean_after=best_mean_after,
-        delta=best_delta,
-        n_before=best_index,
-        n_after=n - best_index,
-    )
-
-
-def compute_engine_longitudinal(
-    history_entries: Iterable,
-    engine_name: str,
-    corpus_name: Optional[str] = None,
-    *,
-    min_runs_for_trend: int = 3,
-    min_segment_size: int = 3,
-    change_point_threshold: float = 0.01,
-) -> Optional[dict]:
-    """Calcule trend + change_point pour un moteur.
-
-    Parameters
-    ----------
-    history_entries:
-        Liste de ``HistoryEntry`` (ou dicts compatibles).
-    engine_name:
-        Filtre sur le nom du moteur.
-    corpus_name:
-        Filtre optionnel sur le corpus.  ``None`` (défaut) : tous
-        les corpus.
-    min_runs_for_trend:
-        Minimum de runs pour calculer une tendance.
-    min_segment_size:
-        Taille minimale des segments pour le change-point.
-    change_point_threshold:
-        Magnitude absolue minimale du delta (en CER) pour
-        retenir le change-point.  Défaut 0.01 (1 point de CER).
-
-    Returns
-    -------
-    dict | None
-        ``{
-            "engine_name", "corpus_name", "n_runs", "trend",
-            "change_point",  # ou None
-            "first_timestamp", "last_timestamp",
-            "first_cer", "last_cer", "absolute_delta_pct",
-        }`` ou ``None`` si moins de ``min_runs_for_trend`` runs.
-    """
-    series: list[tuple[str, float]] = []
-    for entry in history_entries:
-        if hasattr(entry, "as_dict"):
-            data = entry.as_dict()
-        else:
-            data = entry
-        if data.get("engine_name") != engine_name:
-            continue
-        if corpus_name is not None and data.get("corpus_name") != corpus_name:
-            continue
-        cer = data.get("cer_mean")
-        ts = data.get("timestamp")
-        if cer is None or ts is None:
-            continue
-        series.append((ts, float(cer)))
-    if len(series) < min_runs_for_trend:
-        return None
-    series.sort(key=lambda p: _parse_timestamp(p[0]) or 0.0)
-    trend = compute_linear_trend(series)
-    cp = detect_change_point(series, min_segment_size=min_segment_size)
-    if cp is not None and abs(cp.delta) < change_point_threshold:
-        cp = None
-    first_ts, first_cer = series[0]
-    last_ts, last_cer = series[-1]
-    return {
-        "engine_name": engine_name,
-        "corpus_name": corpus_name,
-        "n_runs": len(series),
-        "trend": trend.as_dict() if trend else None,
-        "change_point": cp.as_dict() if cp else None,
-        "first_timestamp": first_ts,
-        "last_timestamp": last_ts,
-        "first_cer": first_cer,
-        "last_cer": last_cer,
-        "absolute_delta": last_cer - first_cer,
-        "absolute_delta_pct": round((last_cer - first_cer) * 100, 2),
-    }
-
-
-def compute_corpus_longitudinal(
-    history_entries: Iterable,
-    corpus_name: Optional[str] = None,
-    *,
-    min_runs_for_trend: int = 3,
-    min_segment_size: int = 3,
-    change_point_threshold: float = 0.01,
-) -> list[dict]:
-    """Pour chaque moteur présent dans l'historique sur ``corpus_name``,
-    calcule trend + change_point.
-
-    Returns
-    -------
-    list[dict]
-        Une entrée par moteur (filtrée), liste vide si rien.
-    """
-    entries = list(history_entries)
-    engines: set[str] = set()
-    for entry in entries:
-        data = entry.as_dict() if hasattr(entry, "as_dict") else entry
-        if corpus_name is not None and data.get("corpus_name") != corpus_name:
-            continue
-        name = data.get("engine_name")
-        if name:
-            engines.add(name)
-    out: list[dict] = []
-    for engine in sorted(engines):
-        result = compute_engine_longitudinal(
-            entries, engine, corpus_name=corpus_name,
-            min_runs_for_trend=min_runs_for_trend,
-            min_segment_size=min_segment_size,
-            change_point_threshold=change_point_threshold,
-        )
-        if result is not None:
-            out.append(result)
-    return out
-
-
-__all__ = [
-    "LinearTrend",
-    "ChangePointResult",
-    "compute_linear_trend",
-    "detect_change_point",
-    "compute_engine_longitudinal",
-    "compute_corpus_longitudinal",
-]
-
+from picarones.measurements.longitudinal import *  # noqa: F401, F403
 
-# Marqueur d'évitement d'import inutilisé (math)
-_ = math
+import picarones.measurements.longitudinal as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/marginal_cost.py

@@ -1,142 +1,19 @@
-"""Coût marginal par erreur évitée — Sprint 91 (A.II.6 chantier 2).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.marginal_cost`.
 
-Sprint 91 — A.II.6 chantier 2 du plan d'évolution 2026.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.marginal_cost import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-La vue Pareto (Sprint 20) trace CER vs coût mais n'arbitre pas
-quel surcoût est *raisonnable* pour quelle réduction d'erreur.
-Une institution avec un budget contraint a besoin d'une
-réponse opérationnelle :
-
-    *« Passer de Tesseract à Mistral OCR coûte 0,83 € par
-    erreur évitée — décider selon votre budget par millier
-    d'erreurs corrigées. »*
-
-Formule
--------
-Pour deux moteurs A et B où B fait **moins** d'erreurs que A
-(donc B est plus précis) :
-
-.. code::
-
-    coût_marginal = (coût_B − coût_A) / (errors_A − errors_B)
-
-- Si ``cost_B > cost_A`` et ``errors_B < errors_A`` :
-  ``cost_per_avoided_error > 0`` (cas standard, B coûte plus
-  pour moins d'erreurs).
-- Si ``cost_B ≤ cost_A`` et ``errors_B < errors_A`` :
-  ``cost_per_avoided_error ≤ 0`` (cas idéal, B est strictement
-  meilleur).
-- Si ``errors_B ≥ errors_A`` : non comparable dans ce sens
-  (B n'évite pas d'erreur), retourne ``None``.
-
-Sortie
-------
-``compute_marginal_cost(cost_a, errors_a, cost_b, errors_b)``
-retourne ``{cost_per_avoided_error, n_errors_avoided,
-cost_delta, dominated}`` ou ``None`` si non comparable.
-
-``compute_marginal_cost_matrix(per_engine)`` retourne, pour
-chaque paire ordonnée ``(A → B)`` où B est plus précis, le
-coût marginal correspondant.  Trié par coût marginal croissant
-(meilleur ratio en tête).
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-from typing import Optional
-
-logger = logging.getLogger(__name__)
-
-
-def compute_marginal_cost(
-    cost_a: float,
-    errors_a: float,
-    cost_b: float,
-    errors_b: float,
-) -> Optional[dict]:
-    """Coût marginal du passage A → B (B plus précis).
-
-    Retourne ``None`` si :
-    - ``errors_b >= errors_a`` (B n'évite pas d'erreur) ;
-    - les valeurs ne sont pas finies.
-    """
-    try:
-        ca = float(cost_a)
-        cb = float(cost_b)
-        ea = float(errors_a)
-        eb = float(errors_b)
-    except (TypeError, ValueError):
-        return None
-    if ea <= eb:
-        # B ne fait pas mieux que A → pas de gain à mesurer.
-        return None
-    n_avoided = ea - eb
-    cost_delta = cb - ca
-    cost_per_avoided = cost_delta / n_avoided
-    dominated = cost_delta <= 0  # B aussi cher ou moins → cas idéal
-    return {
-        "cost_per_avoided_error": cost_per_avoided,
-        "n_errors_avoided": n_avoided,
-        "cost_delta": cost_delta,
-        "dominated": dominated,
-    }
-
-
-def compute_marginal_cost_matrix(
-    per_engine: dict[str, dict],
-) -> Optional[dict]:
-    """Pour chaque paire A → B où B fait moins d'erreurs, calcule
-    le coût marginal.
-
-    Parameters
-    ----------
-    per_engine:
-        Map ``{engine_name: {"cost": float, "errors": float}}``.
-
-    Returns
-    -------
-    dict | None
-        ``{
-            "pairs": list[
-                {"engine_a", "engine_b", "cost_per_avoided_error",
-                 "n_errors_avoided", "cost_delta", "dominated"}
-            ],  # triée par cost_per_avoided_error croissant
-        }``
-        ou ``None`` si moins de 2 moteurs.
-    """
-    if not per_engine or len(per_engine) < 2:
-        return None
-    engines = sorted(per_engine.keys())
-    pairs: list[dict] = []
-    for a in engines:
-        for b in engines:
-            if a == b:
-                continue
-            data_a = per_engine[a]
-            data_b = per_engine[b]
-            try:
-                ca = float(data_a.get("cost"))
-                ea = float(data_a.get("errors"))
-                cb = float(data_b.get("cost"))
-                eb = float(data_b.get("errors"))
-            except (TypeError, ValueError):
-                continue
-            result = compute_marginal_cost(ca, ea, cb, eb)
-            if result is None:
-                continue
-            entry = {"engine_a": a, "engine_b": b}
-            entry.update(result)
-            pairs.append(entry)
-    if not pairs:
-        return None
-    pairs.sort(key=lambda p: p["cost_per_avoided_error"])
-    return {"pairs": pairs}
-
+from picarones.measurements.marginal_cost import *  # noqa: F401, F403
 
-__all__ = [
-    "compute_marginal_cost",
-    "compute_marginal_cost_matrix",
-]
+import picarones.measurements.marginal_cost as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/narrative/__init__.py

@@ -1,78 +1,15 @@
-"""Moteur narratif factuel — génération de synthèse déterministe.
+"""Alias rétrocompat — package déplacé dans :mod:`picarones.measurements.narrative`.
 
-Extrait des faits saillants d'un ``BenchmarkResult`` et les rend en phrases
-courtes via des templates externes YAML. Aucun LLM : chaque nombre ou nom
-apparaissant dans la synthèse est traçable au JSON de résultats en entrée.
-
-API publique
-------------
-- ``Fact``, ``FactType``, ``FactImportance`` : modèle de données
-- ``DetectorRegistry``                        : registre des détecteurs
-- ``detect_all(data)``                        : applique le registre par défaut
-- ``select_facts(facts, max_facts=5)``        : arbitre de sélection
-- ``render_synthesis(facts, lang="fr")``      : rend en liste de phrases
-- ``build_synthesis(data, lang="fr")``        : pipeline complet (Sprint 4)
+Phase E du chantier de refonte en 3 cercles. Le moteur narratif
+(Cercle 2) vit désormais dans ``picarones.measurements.narrative``.
+Cet alias maintient la rétrocompat des imports historiques :
+``from picarones.core.narrative import build_synthesis``,
+``from picarones.core.narrative.facts import Fact``, etc.
 """
 
-from picarones.core.narrative.facts import (
-    Fact,
-    FactType,
-    FactImportance,
-    DetectorRegistry,
-    detect_all,
-    _DEFAULT_REGISTRY,
-)
-from picarones.core.narrative.arbiter import select_facts
-from picarones.core.narrative.renderer import (
-    render_fact,
-    render_synthesis,
-    extract_numbers,
-)
-from picarones.core.narrative.detectors import (
-    register_default_detectors,
-    DETECTORS_BY_TYPE,
-)
-
-
-# Activer le registre par défaut — Sprint 4
-register_default_detectors(_DEFAULT_REGISTRY)
-
-
-def build_synthesis(
-    benchmark_data: dict,
-    lang: str = "fr",
-    max_facts: int = 5,
-) -> dict:
-    """Pipeline complet : détection → arbitre → rendu.
-
-    Returns
-    -------
-    dict avec :
-      - ``sentences`` : liste de phrases prêtes à l'affichage
-      - ``facts``     : liste de dicts ``Fact.as_dict()`` pour traçabilité
-      - ``lang``      : langue utilisée
-    """
-    all_facts = detect_all(benchmark_data)
-    selected = select_facts(all_facts, max_facts=max_facts)
-    sentences = render_synthesis(selected, lang=lang)
-    return {
-        "sentences": sentences,
-        "facts": [f.as_dict() for f in selected],
-        "lang": lang,
-    }
-
+from picarones.measurements.narrative import *  # noqa: F401, F403
 
-__all__ = [
-    "Fact",
-    "FactType",
-    "FactImportance",
-    "DetectorRegistry",
-    "detect_all",
-    "select_facts",
-    "render_fact",
-    "render_synthesis",
-    "extract_numbers",
-    "build_synthesis",
-    "register_default_detectors",
-    "DETECTORS_BY_TYPE",
-]
+import picarones.measurements.narrative as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/narrative/arbiter.py

@@ -1,227 +1,13 @@
-"""Arbitre de sélection des faits narratifs.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.narrative.arbiter`.
 
-L'arbitre transforme une liste potentiellement longue de ``Fact`` détectés
-en une synthèse courte (3 à 5 phrases) adaptée à l'ouverture du rapport.
-
-Règles de sélection :
-  1. Tri par importance décroissante, puis par type (ordre canonique).
-  2. Non-redondance : un seul fait par moteur, sauf si les types sont
-     complémentaires (ex. ``GLOBAL_LEADER_CER`` + ``SIGNIFICANT_GAP``
-     concernent le leader mais apportent une information différente).
-  3. Limite : au maximum ``max_facts`` faits retenus (défaut 5).
-  4. Déterminisme : tri stable sur (−importance, ordre canonique du type,
-     noms des moteurs) pour garantir une sortie bit-à-bit identique.
-
-Les détecteurs peuvent émettre plusieurs faits du même type (ex. plusieurs
-``STATISTICAL_TIE`` si plusieurs groupes distincts). L'arbitre ne fusionne
-pas mais peut limiter par type.
+Phase E du chantier de refonte en 3 cercles. Le moteur narratif
+(Cercle 2 — measurements/) a quitté ``picarones.core.narrative``.
+Cet alias maintient la rétrocompat des imports historiques.
 """
 
-from __future__ import annotations
-
-from typing import Iterable, Sequence
-
-from picarones.core.narrative.facts import Fact, FactImportance, FactType
-
-
-# Ordre canonique des types pour départager les ex-aequo à l'importance égale.
-#
-# Politique éditoriale — exposée et documentée dans
-# ``docs/developer/narrative-engine.md`` § Editorial policy.
-# L'ordre encode quels faits sont remontés en priorité quand plusieurs ont
-# la même ``FactImportance``. Surchargeable via le paramètre ``type_order``
-# de ``select_facts`` sans patcher le code.
-#
-# Sprint 29 : la valeur n'est plus codée en dur ici — elle est dérivée du
-# registre déclaratif (``@register_detector(..., priority=N)``). Ajouter
-# un détecteur en bonne position se fait donc en éditant **un seul**
-# fichier (``detectors.py``) au lieu de quatre comme avant.
-def _compute_default_type_order() -> tuple[FactType, ...]:
-    # Import local pour éviter la dépendance circulaire au chargement.
-    from picarones.core.narrative.registry import default_type_order
-    order = default_type_order()
-    # Filet de sécurité : tant que les détecteurs n'ont pas été importés
-    # (cas des tests qui mockent le registre), on retombe sur un ordre
-    # canonique gravé pour ne pas planter ``select_facts``.
-    if not order:
-        return _FALLBACK_TYPE_ORDER
-    return order
-
-
-# Ordre statique gardé en mémoire : utilisé si jamais le registre est vide
-# au moment où ``arbiter`` est chargé (chargement partiel par les tests).
-_FALLBACK_TYPE_ORDER: tuple[FactType, ...] = (
-    FactType.GLOBAL_LEADER_CER,
-    FactType.STATISTICAL_TIE,
-    FactType.SIGNIFICANT_GAP,
-    FactType.STRATUM_WINNER,
-    # Sprint 46 — priority 45, juste après STRATUM_WINNER (40),
-    # avant STRATUM_COLLAPSE (50). La recommandation de stratification
-    # nuance directement les autres faits par strate.
-    FactType.STRATIFICATION_RECOMMENDED,
-    FactType.STRATUM_COLLAPSE,
-    FactType.ERROR_PROFILE_OUTLIER,
-    FactType.LLM_HALLUCINATION_FLAG,
-    FactType.ROBUSTNESS_FRAGILE,
-    FactType.PARETO_ALTERNATIVE,
-    FactType.SPEED_WINNER,
-    FactType.COST_OUTLIER,
-    FactType.CONFIDENCE_WARNING,
-    FactType.ENSEMBLE_OPPORTUNITY,
-    FactType.MEDIAN_MEAN_GAP_WARNING,
-    # Sprint 73 — priority 150, après MEDIAN_MEAN_GAP_WARNING (140).
-    # Le détecteur off-baseline donne le contexte historique, qui
-    # vient en fin de synthèse comme « note ».
-    FactType.ENGINE_OFF_BASELINE,
-    # Sprint 90 — priority 160, ferme la synthèse avec la mise en
-    # garde sur la reproductibilité.  Une instabilité multi-runs
-    # discrédite toute autre conclusion sur ce moteur ; on la
-    # remonte en dernier pour ne pas l'enterrer.
-    FactType.ENGINE_UNSTABLE,
-    # Sprint 92 — priority 170, après ENGINE_UNSTABLE.  La
-    # régression historique complète A.I.3 (off-baseline) en
-    # caractérisant la tendance : l'écart courant est-il une
-    # dégradation graduelle, une rupture brutale, ou un bruit ?
-    FactType.REGRESSION_IN_HISTORY,
-)
-
-
-# ``DEFAULT_TYPE_ORDER`` reste un attribut module accessible. On le calcule
-# à l'import si possible, sinon on prend le fallback ; ``select_facts``
-# recalcule à chaque appel pour absorber les ajouts de détecteurs après
-# l'import initial (extensions tierces).
-DEFAULT_TYPE_ORDER: tuple[FactType, ...] = _compute_default_type_order()
-
-# Alias rétro-compatible.
-_TYPE_ORDER = DEFAULT_TYPE_ORDER
-_TYPE_INDEX: dict[FactType, int] = {t: i for i, t in enumerate(DEFAULT_TYPE_ORDER)}
-
-
-# Paires de types qui ne sont PAS considérées comme redondantes même quand
-# elles concernent le même moteur. Tout autre couple → un seul fait retenu
-# pour le moteur (le plus important).
-_COMPLEMENTARY_PAIRS: frozenset[frozenset[FactType]] = frozenset({
-    frozenset({FactType.GLOBAL_LEADER_CER, FactType.SIGNIFICANT_GAP}),
-    frozenset({FactType.GLOBAL_LEADER_CER, FactType.SPEED_WINNER}),
-    frozenset({FactType.GLOBAL_LEADER_CER, FactType.CONFIDENCE_WARNING}),
-    frozenset({FactType.STATISTICAL_TIE, FactType.SPEED_WINNER}),
-    # Sprint 44 — l'avertissement d'asymétrie nuance le leader
-    # plutôt que de le doubler : on veut les deux phrases ensemble.
-    frozenset({FactType.GLOBAL_LEADER_CER, FactType.MEDIAN_MEAN_GAP_WARNING}),
-    # Sprint 46 — la recommandation de stratification est un méta-conseil
-    # qui s'ajoute au leader sans le contredire ; les deux peuvent
-    # cohabiter même quand ils concernent le même moteur.
-    frozenset({FactType.GLOBAL_LEADER_CER, FactType.STRATIFICATION_RECOMMENDED}),
-    # Sprint 90 — l'instabilité multi-runs nuance les conclusions
-    # sur le moteur leader sans les contredire : un moteur peut être
-    # leader **et** instable, et c'est précisément l'information
-    # critique pour la reproductibilité scientifique.
-    frozenset({FactType.GLOBAL_LEADER_CER, FactType.ENGINE_UNSTABLE}),
-    # Sprint 92 — la régression historique caractérise la tendance
-    # du leader : un leader peut être en régression progressive,
-    # info critique pour décider quand re-tester.
-    frozenset({FactType.GLOBAL_LEADER_CER, FactType.REGRESSION_IN_HISTORY}),
-    # Off-baseline (Sprint 73) dit "écart anormal sur ce corpus" ;
-    # regression-in-history (Sprint 92) dit "tendance dans le
-    # temps" — les deux se complètent sans se redonder.
-    frozenset({FactType.ENGINE_OFF_BASELINE, FactType.REGRESSION_IN_HISTORY}),
-})
-
-
-def _sort_key(fact: Fact, type_index: dict[FactType, int]) -> tuple:
-    """Clé de tri stable : importance (desc), type canonique, moteurs."""
-    return (
-        -int(fact.importance),
-        type_index.get(fact.type, len(type_index)),
-        tuple(sorted(fact.engines_involved)),
-        fact.stratum or "",
-    )
-
-
-def _is_redundant(candidate: Fact, kept: Fact) -> bool:
-    """Vrai si ``candidate`` apporte trop peu par rapport à ``kept``.
-
-    Deux faits sont redondants s'ils concernent exactement le même moteur,
-    ont le même type, et la même strate (s'il y en a une). Des types
-    différents sur le même moteur ne sont considérés redondants que s'ils
-    n'appartiennent pas aux paires complémentaires (ex : un leader peut
-    aussi être rapide ; c'est complémentaire).
-    """
-    if candidate.type == kept.type and candidate.stratum == kept.stratum:
-        return set(candidate.engines_involved) == set(kept.engines_involved)
-    if set(candidate.engines_involved) == set(kept.engines_involved):
-        pair = frozenset({candidate.type, kept.type})
-        return pair not in _COMPLEMENTARY_PAIRS
-    return False
-
-
-def _remove_contradictions(facts: list[Fact]) -> list[Fact]:
-    """Supprime les faits incohérents sur le plan statistique.
-
-    Règle centrale : si Nemenyi (post-hoc corrigé pour comparaisons multiples)
-    place deux moteurs dans le même groupe d'ex-aequo, alors un ``SIGNIFICANT_GAP``
-    basé sur Wilcoxon non corrigé entre ces deux mêmes moteurs est trompeur
-    pour un lecteur non statisticien. Nemenyi l'emporte.
-    """
-    tied_groups: list[set[str]] = []
-    for f in facts:
-        if f.type == FactType.STATISTICAL_TIE:
-            tied_groups.append(set(f.engines_involved))
-
-    def _is_contradicted(fact: Fact) -> bool:
-        if fact.type != FactType.SIGNIFICANT_GAP:
-            return False
-        pair = set(fact.engines_involved)
-        return any(pair <= group for group in tied_groups)
-
-    return [f for f in facts if not _is_contradicted(f)]
-
-
-def select_facts(
-    facts: Iterable[Fact],
-    max_facts: int = 5,
-    min_importance: FactImportance = FactImportance.MEDIUM,
-    type_order: Sequence[FactType] | None = None,
-) -> list[Fact]:
-    """Sélectionne la synthèse finale à partir d'une liste brute de faits.
-
-    Parameters
-    ----------
-    facts:
-        Liste de ``Fact`` brute issue de ``DetectorRegistry.run``.
-    max_facts:
-        Nombre maximal de faits retenus (défaut : 5).
-    min_importance:
-        Seuil minimal d'importance. Les faits ``LOW`` sont exclus par défaut.
-    type_order:
-        Surcharge optionnelle de l'ordre canonique des types pour départager
-        les faits d'égale importance. ``None`` (défaut) utilise
-        ``DEFAULT_TYPE_ORDER``. Une institution peut passer son propre ordre
-        sans patcher le code — voir ``docs/developer/narrative-engine.md``.
-
-    Returns
-    -------
-    Liste ordonnée, prête à être rendue. Toujours ≤ ``max_facts``.
-    """
-    if type_order is None:
-        # Sprint 29 — recalcul à chaque appel pour absorber les détecteurs
-        # enregistrés après l'import d'arbiter (extensions tierces qui
-        # font ``@register_detector`` dans un module utilisateur).
-        from picarones.core.narrative.registry import default_type_order
-        live_order = default_type_order() or _FALLBACK_TYPE_ORDER
-        type_index = {t: i for i, t in enumerate(live_order)}
-    else:
-        type_index = {t: i for i, t in enumerate(type_order)}
-
-    facts_list = [f for f in facts if int(f.importance) >= int(min_importance)]
-    facts_list = _remove_contradictions(facts_list)
-    ranked = sorted(facts_list, key=lambda f: _sort_key(f, type_index))
+from picarones.measurements.narrative.arbiter import *  # noqa: F401, F403
 
-    selected: list[Fact] = []
-    for fact in ranked:
-        if any(_is_redundant(fact, kept) for kept in selected):
-            continue
-        selected.append(fact)
-        if len(selected) >= max_facts:
-            break
-    return selected
+import picarones.measurements.narrative.arbiter as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/narrative/detectors/__init__.py

@@ -1,129 +1,13 @@
-"""Détecteurs narratifs — package thématique (chantier 5 post-Sprint 97).
+"""Alias rétrocompat — package déplacé dans :mod:`picarones.measurements.narrative.detectors`.
 
-Avant le chantier 5, ce module était un fichier monolithe de 1229 lignes
-(``narrative/detectors.py``) contenant 18 détecteurs. Pour aligner la
-structure de code avec celle du registre déclaratif (Sprint 29), les
-détecteurs ont été regroupés par **famille thématique** :
-
-- :mod:`ranking`   — global leader, statistical tie, significant gap,
-  speed winner, median/mean gap warning   (5 détecteurs)
-- :mod:`pareto`    — Pareto alternative, cost outlier   (2 détecteurs)
-- :mod:`stratum`   — stratum winner / collapse, stratification
-  recommended   (3 détecteurs)
-- :mod:`quality`   — error profile outlier, LLM hallucination flag,
-  robustness fragile, confidence warning   (4 détecteurs)
-- :mod:`history`   — engine off baseline, engine unstable, regression
-  in history   (3 détecteurs)
-- :mod:`ensemble`  — ensemble opportunity   (1 détecteur)
-
-Total : 18 détecteurs (≠ "12" mentionné dans CLAUDE.md historique —
-le chantier 5 corrige ce comptage).
-
-Rétrocompatibilité absolue
---------------------------
-Tous les noms exportés par l'ancien fichier ``detectors.py``
-(``detect_*``, ``DETECTORS_BY_TYPE``, ``register_default_detectors``)
-restent accessibles via ``from picarones.core.narrative.detectors
-import ...``. Les tests Sprints 20, 23, 29, 36, 44, 46, 73 importent
-directement ces noms et continuent à fonctionner sans modification.
-
-L'enregistrement automatique des détecteurs via ``@register_detector``
-se fait à l'import de ce package — chaque sous-module est importé ici
-en cascade.
+Phase E du chantier de refonte. Les 18 détecteurs en 6 familles
+(ranking, pareto, stratum, quality, history, ensemble) vivent
+désormais dans ``picarones.measurements.narrative.detectors/``.
 """
 
-from __future__ import annotations
-
-# Imports en cascade des 6 sous-modules : déclenche l'enregistrement
-# automatique via les décorateurs ``@register_detector`` au chargement.
-from picarones.core.narrative.detectors.ranking import (
-    detect_global_leader_cer,
-    detect_median_mean_gap_warning,
-    detect_significant_gap,
-    detect_speed_winner,
-    detect_statistical_tie,
-)
-from picarones.core.narrative.detectors.pareto import (
-    detect_cost_outlier,
-    detect_pareto_alternative,
-)
-from picarones.core.narrative.detectors.stratum import (
-    detect_stratification_recommended,
-    detect_stratum_collapse,
-    detect_stratum_winner,
-)
-from picarones.core.narrative.detectors.quality import (
-    detect_confidence_warning,
-    detect_error_profile_outlier,
-    detect_llm_hallucination_flag,
-    detect_robustness_fragile,
-)
-from picarones.core.narrative.detectors.history import (
-    detect_engine_off_baseline,
-    detect_engine_unstable,
-    detect_regression_in_history,
-)
-from picarones.core.narrative.detectors.ensemble import (
-    detect_ensemble_opportunity,
-)
-
-# Snapshot du registre + helper d'enregistrement legacy — déplacés
-# verbatim depuis l'ancien ``detectors.py`` (lignes 1193-1229).
-from picarones.core.narrative.facts import DetectorFn, FactType
-from picarones.core.narrative.registry import (
-    iter_detectors as _iter_detectors,
-    populate_legacy_registry as _populate_legacy_registry,
-)
-
-
-def _build_detectors_by_type() -> dict[FactType, DetectorFn]:
-    """Snapshot du registre déclaratif vers un dict ``{type: fn}``."""
-    return {entry.fact_type: entry.fn for entry in _iter_detectors()}
-
-
-# Vue figée à l'import — utile pour les tests qui parcourent les types
-# enregistrés sans instancier un ``DetectorRegistry``.
-DETECTORS_BY_TYPE = _build_detectors_by_type()
-
-
-def register_default_detectors(registry) -> None:
-    """Enregistre les détecteurs du registre déclaratif dans un
-    ``DetectorRegistry`` historique.
-
-    Sprint 29 : la source de vérité est maintenant le décorateur
-    ``@register_detector`` ; cette fonction se contente de pousser
-    le contenu du registre vers l'objet ``DetectorRegistry`` que les
-    consommateurs externes (``DetectorRegistry.run``) instancient.
-    """
-    _populate_legacy_registry(registry)
-
+from picarones.measurements.narrative.detectors import *  # noqa: F401, F403
 
-__all__ = [
-    # ranking
-    "detect_global_leader_cer",
-    "detect_median_mean_gap_warning",
-    "detect_significant_gap",
-    "detect_speed_winner",
-    "detect_statistical_tie",
-    # pareto
-    "detect_cost_outlier",
-    "detect_pareto_alternative",
-    # stratum
-    "detect_stratification_recommended",
-    "detect_stratum_collapse",
-    "detect_stratum_winner",
-    # quality
-    "detect_confidence_warning",
-    "detect_error_profile_outlier",
-    "detect_llm_hallucination_flag",
-    "detect_robustness_fragile",
-    # history
-    "detect_engine_off_baseline",
-    "detect_engine_unstable",
-    "detect_regression_in_history",
-    # ensemble
-    "detect_ensemble_opportunity",
-    # legacy
-    "DETECTORS_BY_TYPE",
-    "register_default_detectors",
-]
+import picarones.measurements.narrative.detectors as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/narrative/detectors/_helpers.py

@@ -1,31 +1,13 @@
-"""Helpers internes partagés par les détecteurs narratifs.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.narrative.detectors._helpers`.
 
-Chantier 5 du plan d'évolution post-Sprint 97 — découpage de
-``picarones/core/narrative/detectors.py`` (1229 lignes, 18 détecteurs)
-en 6 sous-modules thématiques + ce module d'helpers communs.
-
-Ces fonctions étaient privées (préfixe ``_``) au module historique.
-Elles sont conservées telles quelles ici ; les sous-modules les
-importent.
+Phase E du chantier de refonte en 3 cercles. Le moteur narratif
+(Cercle 2 — measurements/) a quitté ``picarones.core.narrative``.
+Cet alias maintient la rétrocompat des imports historiques.
 """
 
-from __future__ import annotations
-
-from typing import Optional
-
-
-def _engines_summary(data: dict) -> list[dict]:
-    """Accès normalisé à la liste des résumés moteur."""
-    return data.get("engines", []) or []
-
-
-def _engine_by_name(data: dict, name: str) -> Optional[dict]:
-    for e in _engines_summary(data):
-        if e.get("name") == name:
-            return e
-    return None
-
+from picarones.measurements.narrative.detectors._helpers import *  # noqa: F401, F403
 
-def _n_docs(data: dict) -> int:
-    meta = data.get("meta", {}) or {}
-    return int(meta.get("document_count") or 0)
+import picarones.measurements.narrative.detectors._helpers as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/narrative/detectors/ensemble.py

@@ -1,96 +1,13 @@
-"""Détecteurs narratifs liés à l'*opportunité d'ensemble inter-moteurs* (chantier 5).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.narrative.detectors.ensemble`.
 
-1 détecteur déplacé depuis ``narrative/detectors.py`` :
-
-- :func:`detect_ensemble_opportunity` (Sprint 36)
+Phase E du chantier de refonte en 3 cercles. Le moteur narratif
+(Cercle 2 — measurements/) a quitté ``picarones.core.narrative``.
+Cet alias maintient la rétrocompat des imports historiques.
 """
 
-from __future__ import annotations
-
-import statistics as _stats
-from typing import Optional
-
-from picarones.core.narrative.facts import Fact, FactImportance, FactType
-from picarones.core.narrative.registry import register_detector
-
-from picarones.core.narrative.detectors._helpers import (
-    _engine_by_name,
-    _engines_summary,
-    _n_docs,
-)
-
-
-@register_detector(
-    FactType.ENSEMBLE_OPPORTUNITY,
-    priority=130,
-    importance=FactImportance.MEDIUM,
-)
-def detect_ensemble_opportunity(benchmark_data: dict) -> list[Fact]:
-    """Deux moteurs très complémentaires : un voting majoritaire entre eux
-    pourrait améliorer significativement le CER token-level.
-
-    Lit la structure ``inter_engine_analysis`` produite par le runner
-    (Sprint 35-36) et déclenche si la fraction d'erreurs du meilleur
-    moteur récupérable par un ensemble dépasse 25 %.
-
-    L'importance monte à ``HIGH`` quand le gap relatif dépasse 50 %
-    (ensemble franchement profitable) — sinon reste à ``MEDIUM``.
-    """
-    iea = benchmark_data.get("inter_engine_analysis") or {}
-    comp = iea.get("complementarity") or {}
-    if not comp:
-        return []
-
-    relative_gap = float(comp.get("relative_gap") or 0.0)
-    if relative_gap < 0.25:
-        # En deçà de 25 %, l'ensemble n'apporterait quasi rien — on ne
-        # remonte pas le fait pour ne pas bruiter la synthèse.
-        return []
-
-    best_engine = comp.get("best_engine") or ""
-    if not best_engine:
-        return []
-
-    payload: dict = {
-        "best_engine": best_engine,
-        "best_recall_pct": round(float(comp.get("best_single_recall") or 0.0) * 100, 2),
-        "oracle_recall_pct": round(float(comp.get("oracle_recall") or 0.0) * 100, 2),
-        "absolute_gap_pct": round(float(comp.get("absolute_gap") or 0.0) * 100, 2),
-        "relative_gap_pct": round(relative_gap * 100, 1),
-        "doc_count": int(comp.get("doc_count") or 0),
-    }
-
-    # Paire la plus complémentaire — la divergence taxonomique, quand
-    # disponible, fournit deux moteurs « candidats naturels ».  Sinon on
-    # tombe sur le best + le second-best en recall individuel.
-    div = iea.get("taxonomy_divergence") or {}
-    pair = div.get("max_pair") or []
-    pair_a = ""
-    pair_b = ""
-    divergence_value: Optional[float] = None
-    if pair and len(pair) >= 3 and isinstance(pair[2], (int, float)) and pair[2] > 0:
-        pair_a, pair_b, divergence_value = str(pair[0]), str(pair[1]), float(pair[2])
-    else:
-        # Fallback : best engine + second-best engine par recall individuel
-        per_engine = comp.get("per_engine_recall") or {}
-        if len(per_engine) >= 2:
-            ranked = sorted(per_engine.items(), key=lambda kv: kv[1], reverse=True)
-            pair_a, pair_b = ranked[0][0], ranked[1][0]
-
-    payload["pair_a"] = pair_a
-    payload["pair_b"] = pair_b
-    payload["divergence"] = round(divergence_value, 3) if divergence_value is not None else 0.0
-    payload["divergence_metric"] = (div.get("metric") or "js")
+from picarones.measurements.narrative.detectors.ensemble import *  # noqa: F401, F403
 
-    importance = (
-        FactImportance.HIGH if relative_gap >= 0.5 else FactImportance.MEDIUM
-    )
-    engines_involved: tuple[str, ...] = (
-        (pair_a, pair_b) if pair_a and pair_b else (best_engine,)
-    )
-    return [Fact(
-        type=FactType.ENSEMBLE_OPPORTUNITY,
-        importance=importance,
-        payload=payload,
-        engines_involved=engines_involved,
-    )]
+import picarones.measurements.narrative.detectors.ensemble as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/narrative/detectors/history.py

@@ -1,280 +1,13 @@
-"""Détecteurs narratifs liés à *l'historique SQLite + multi-runs* (chantier 5).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.narrative.detectors.history`.
 
-3 détecteurs déplacés depuis ``narrative/detectors.py`` :
-
-- :func:`detect_engine_off_baseline`    (Sprint 73)
-- :func:`detect_engine_unstable`        (Sprint 90)
-- :func:`detect_regression_in_history`  (Sprint 92)
+Phase E du chantier de refonte en 3 cercles. Le moteur narratif
+(Cercle 2 — measurements/) a quitté ``picarones.core.narrative``.
+Cet alias maintient la rétrocompat des imports historiques.
 """
 
-from __future__ import annotations
-
-import statistics as _stats
-from typing import Optional
-
-from picarones.core.narrative.facts import Fact, FactImportance, FactType
-from picarones.core.narrative.registry import register_detector
-
-from picarones.core.narrative.detectors._helpers import (
-    _engine_by_name,
-    _engines_summary,
-    _n_docs,
-)
-
-
-@register_detector(
-    FactType.ENGINE_OFF_BASELINE,
-    priority=150,
-    importance=FactImportance.MEDIUM,
-)
-def detect_engine_off_baseline(benchmark_data: dict) -> list[Fact]:
-    """Émet un Fact pour chaque moteur dont le CER courant s'écarte
-    significativement de sa moyenne historique sur le **même corpus**.
-
-    Lit ``benchmark_data["baseline_comparisons"]`` (liste de dicts
-    produits par ``compute_engine_baseline`` du module
-    ``baseline_comparison`` Sprint 73).  Si la clé est absente ou
-    vide, le détecteur reste silencieux — typiquement le cas quand
-    aucun historique SQLite n'a été chargé.
-
-    Garde-fous :
-
-    - Si ``n_runs < 5`` (déjà filtré par ``compute_engine_baseline``
-      qui retourne ``None`` dans ce cas).
-    - Si ``relative_delta`` n'est pas calculable (baseline = 0).
-    - Importance ``HIGH`` si ``|relative_delta| ≥ 50 %``, sinon
-      ``MEDIUM``.
-    """
-    comparisons = benchmark_data.get("baseline_comparisons") or []
-    if not isinstance(comparisons, (list, tuple)):
-        return []
-    facts: list[Fact] = []
-    for comp in comparisons:
-        if not isinstance(comp, dict):
-            continue
-        if not comp.get("off_baseline"):
-            continue
-        rel = comp.get("relative_delta")
-        if rel is None:
-            continue
-        engine = comp.get("engine_name")
-        cer_current = comp.get("cer_current")
-        cer_hist_mean = comp.get("cer_historical_mean")
-        n_runs = comp.get("n_runs")
-        if engine is None or cer_current is None or cer_hist_mean is None:
-            continue
-        importance = (
-            FactImportance.HIGH if abs(float(rel)) >= 0.50
-            else FactImportance.MEDIUM
-        )
-        facts.append(Fact(
-            type=FactType.ENGINE_OFF_BASELINE,
-            importance=importance,
-            payload={
-                "engine": engine,
-                "cer_current_pct": round(float(cer_current) * 100, 2),
-                "cer_historical_mean_pct": round(
-                    float(cer_hist_mean) * 100, 2,
-                ),
-                "n_runs": int(n_runs or 0),
-                "relative_delta_pct": round(float(rel) * 100, 1),
-                "direction": "higher" if float(rel) > 0 else "lower",
-            },
-            engines_involved=(engine,),
-        ))
-    return facts
-
-
-@register_detector(
-    FactType.ENGINE_UNSTABLE,
-    priority=160,
-    importance=FactImportance.HIGH,
-)
-def detect_engine_unstable(benchmark_data: dict) -> list[Fact]:
-    """Émet un Fact pour chaque moteur dont la stabilité multi-runs
-    est insuffisante (Sprint 83 + 90).
-
-    Lit ``benchmark_data["multirun_stability"]`` : liste de dicts
-    avec ``engine_name`` + champs de ``compute_multirun_stability``
-    (cer_cv, identical_run_rate, n_runs, etc.).  Si la clé est
-    absente ou vide, le détecteur reste silencieux — typiquement
-    le cas quand l'utilisateur n'a pas exécuté `--repeats N`.
-
-    Garde-fous :
-
-    - ``n_runs ≥ 2`` (déjà filtré par
-      ``compute_multirun_stability`` qui retourne ``None``).
-    - Déclenche si ``cer_cv > 0.10`` (variance relative > 10 % du
-      CER moyen) **ou** ``identical_run_rate < 0.50`` (moins
-      d'une paire de runs sur deux est identique).
-    - Importance ``HIGH`` (l'instabilité discrédite les
-      conclusions).
-    """
-    stabilities = benchmark_data.get("multirun_stability") or []
-    if not isinstance(stabilities, (list, tuple)):
-        return []
-    facts: list[Fact] = []
-    for stab in stabilities:
-        if not isinstance(stab, dict):
-            continue
-        engine = stab.get("engine_name") or stab.get("engine")
-        if not engine:
-            continue
-        n_runs = stab.get("n_runs")
-        if not isinstance(n_runs, int) or n_runs < 2:
-            continue
-        cer_cv = stab.get("cer_cv")
-        identical_rate = stab.get("identical_run_rate")
-        # Critères de déclenchement
-        cv_high = (
-            isinstance(cer_cv, (int, float)) and float(cer_cv) > 0.10
-        )
-        runs_diverge = (
-            isinstance(identical_rate, (int, float))
-            and float(identical_rate) < 0.50
-        )
-        if not (cv_high or runs_diverge):
-            continue
-        payload: dict = {
-            "engine": engine,
-            "n_runs": int(n_runs),
-        }
-        if isinstance(cer_cv, (int, float)):
-            payload["cer_cv"] = float(cer_cv)
-            payload["cer_cv_pct"] = round(float(cer_cv) * 100, 1)
-        if isinstance(identical_rate, (int, float)):
-            payload["identical_run_rate"] = float(identical_rate)
-            payload["identical_run_rate_pct"] = round(
-                float(identical_rate) * 100, 1,
-            )
-        # Champs additionnels pour la phrase de synthèse
-        cer_mean = stab.get("cer_mean")
-        cer_stdev = stab.get("cer_stdev")
-        if isinstance(cer_mean, (int, float)):
-            payload["cer_mean_pct"] = round(float(cer_mean) * 100, 2)
-        if isinstance(cer_stdev, (int, float)):
-            payload["cer_stdev_pct"] = round(float(cer_stdev) * 100, 2)
-        n_distinct = stab.get("n_distinct_outputs")
-        if isinstance(n_distinct, int):
-            payload["n_distinct_outputs"] = int(n_distinct)
-        facts.append(Fact(
-            type=FactType.ENGINE_UNSTABLE,
-            importance=FactImportance.HIGH,
-            payload=payload,
-            engines_involved=(engine,),
-        ))
-    return facts
-
-
-@register_detector(
-    FactType.REGRESSION_IN_HISTORY,
-    priority=170,
-    importance=FactImportance.MEDIUM,
-)
-def detect_regression_in_history(benchmark_data: dict) -> list[Fact]:
-    """Émet un Fact pour chaque moteur dont l'historique montre
-    une dégradation : pente positive significative ou rupture
-    brutale (Sprint 92).
-
-    Lit ``benchmark_data["longitudinal_trends"]`` : liste de
-    dicts produits par ``compute_corpus_longitudinal`` du module
-    ``longitudinal``.  Si la clé est absente ou vide, le
-    détecteur reste silencieux — typiquement le cas quand
-    aucun historique n'a été chargé ou que la série est trop
-    courte.
-
-    Garde-fous :
+from picarones.measurements.narrative.detectors.history import *  # noqa: F401, F403
 
-    - ``n_runs ≥ 3`` (déjà filtré par
-      ``compute_engine_longitudinal``).
-    - Déclenche si **soit** ``trend.slope`` traduit une
-      régression d'au moins ``slope_threshold`` (en CER/jour,
-      défaut équivalent à +1 point CER sur 365 jours), **soit**
-      ``change_point.delta > change_threshold`` (défaut
-      0.01 = +1 point de CER d'un segment à l'autre).
-    - Importance ``HIGH`` si la dégradation cumulée
-      ``absolute_delta`` ≥ 5 points de CER.
-    """
-    trends = benchmark_data.get("longitudinal_trends") or []
-    if not isinstance(trends, (list, tuple)):
-        return []
-    slope_threshold = (
-        0.01 / 365.0  # +1 point de CER sur 365 jours minimum
-    )
-    change_threshold = 0.01
-    facts: list[Fact] = []
-    for entry in trends:
-        if not isinstance(entry, dict):
-            continue
-        engine = entry.get("engine_name")
-        if not engine:
-            continue
-        n_runs = entry.get("n_runs")
-        if not isinstance(n_runs, int) or n_runs < 3:
-            continue
-        trend = entry.get("trend") or {}
-        cp = entry.get("change_point")
-        slope = trend.get("slope")
-        slope_high = (
-            isinstance(slope, (int, float))
-            and float(slope) > slope_threshold
-        )
-        cp_high = (
-            isinstance(cp, dict)
-            and isinstance(cp.get("delta"), (int, float))
-            and float(cp["delta"]) > change_threshold
-        )
-        if not (slope_high or cp_high):
-            continue
-        absolute_delta = entry.get("absolute_delta") or 0.0
-        importance = (
-            FactImportance.HIGH
-            if isinstance(absolute_delta, (int, float))
-            and abs(float(absolute_delta)) >= 0.05
-            else FactImportance.MEDIUM
-        )
-        payload: dict = {
-            "engine": engine,
-            "n_runs": int(n_runs),
-            "absolute_delta_pct": round(
-                float(absolute_delta) * 100, 2,
-            ) if isinstance(absolute_delta, (int, float)) else 0.0,
-            "first_cer_pct": round(
-                float(entry.get("first_cer") or 0.0) * 100, 2,
-            ),
-            "last_cer_pct": round(
-                float(entry.get("last_cer") or 0.0) * 100, 2,
-            ),
-        }
-        if slope_high:
-            payload["slope_per_year_pct"] = round(
-                float(slope) * 365 * 100, 2,
-            )
-            payload["r_squared"] = round(
-                float(trend.get("r_squared") or 0.0), 3,
-            )
-            payload["pattern"] = "trend"
-        if cp_high:
-            payload["change_point_timestamp"] = str(
-                cp.get("timestamp") or "?",
-            )
-            payload["change_delta_pct"] = round(
-                float(cp["delta"]) * 100, 2,
-            )
-            payload["mean_before_pct"] = round(
-                float(cp.get("mean_before") or 0.0) * 100, 2,
-            )
-            payload["mean_after_pct"] = round(
-                float(cp.get("mean_after") or 0.0) * 100, 2,
-            )
-            # Si on a aussi une rupture, le pattern domine
-            payload["pattern"] = (
-                "trend_and_change_point" if slope_high else "change_point"
-            )
-        facts.append(Fact(
-            type=FactType.REGRESSION_IN_HISTORY,
-            importance=importance,
-            payload=payload,
-            engines_involved=(engine,),
-        ))
-    return facts
+import picarones.measurements.narrative.detectors.history as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/narrative/detectors/pareto.py

@@ -1,136 +1,13 @@
-"""Détecteurs narratifs orientés *coût/performance Pareto* (chantier 5).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.narrative.detectors.pareto`.
 
-2 détecteurs déplacés depuis ``narrative/detectors.py`` :
-
-- :func:`detect_pareto_alternative` (Sprint 19) — alternative coût/qualité
-- :func:`detect_cost_outlier`       (Sprint 19) — moteur dont le coût est aberrant
+Phase E du chantier de refonte en 3 cercles. Le moteur narratif
+(Cercle 2 — measurements/) a quitté ``picarones.core.narrative``.
+Cet alias maintient la rétrocompat des imports historiques.
 """
 
-from __future__ import annotations
-
-import statistics as _stats
-from typing import Optional
-
-from picarones.core.narrative.facts import Fact, FactImportance, FactType
-from picarones.core.narrative.registry import register_detector
-
-from picarones.core.narrative.detectors._helpers import (
-    _engine_by_name,
-    _engines_summary,
-    _n_docs,
-)
-
-
-@register_detector(
-    FactType.PARETO_ALTERNATIVE,
-    priority=90,
-    importance=FactImportance.HIGH,
-)
-def detect_pareto_alternative(benchmark_data: dict) -> list[Fact]:
-    """Moteur Pareto-dominant différent du leader CER.
-
-    Lit ``benchmark_data["pareto"]["cost"]`` (Sprint 19) et émet un Fact si
-    la frontière contient un moteur autre que le leader CER, pour souligner
-    l'existence d'un compromis coût/qualité intéressant.
-    """
-    pareto = (benchmark_data.get("pareto") or {}).get("cost") or {}
-    front = pareto.get("front") or []
-    points = pareto.get("points") or []
-    if len(front) < 2:
-        return []
-
-    ranking = benchmark_data.get("ranking") or []
-    if not ranking:
-        return []
-    leader = ranking[0].get("engine")
-
-    # Le moteur le moins cher sur le front (hors leader)
-    alt: Optional[dict] = None
-    for p in points:
-        if p.get("engine") == leader:
-            continue
-        if p.get("engine") not in front:
-            continue
-        if alt is None or float(p.get("cost") or 0.0) < float(alt.get("cost") or 0.0):
-            alt = p
-    if alt is None:
-        return []
-
-    leader_point = next((p for p in points if p.get("engine") == leader), None)
-    if leader_point is None:
-        return []
-
-    alt_cer = float(alt.get("cer") or 0.0)
-    alt_cost = float(alt.get("cost") or 0.0)
-    leader_cer = float(leader_point.get("cer") or 0.0)
-    leader_cost = float(leader_point.get("cost") or 0.0)
-    if alt_cost >= leader_cost or alt_cost <= 0:
-        return []  # pas réellement moins cher — pas intéressant à remonter
-
-    return [Fact(
-        type=FactType.PARETO_ALTERNATIVE,
-        importance=FactImportance.HIGH,
-        payload={
-            "engine": alt["engine"],
-            "leader": leader,
-            "cer": round(alt_cer, 4),
-            "cer_pct": round(alt_cer * 100, 2),
-            "cost": round(alt_cost, 2),
-            "leader_cer": round(leader_cer, 4),
-            "leader_cer_pct": round(leader_cer * 100, 2),
-            "leader_cost": round(leader_cost, 2),
-            "cost_saving_ratio": round(leader_cost / alt_cost, 1) if alt_cost > 0 else None,
-            "delta_cer_pct": round((alt_cer - leader_cer) * 100, 2),
-            # Unité du coût — propagée pour traçabilité (le template ne
-            # hardcode plus "1000 pages").
-            "cost_unit_pages": 1000,
-        },
-        engines_involved=(alt["engine"],),
-    )]
-
-
-@register_detector(
-    FactType.COST_OUTLIER,
-    priority=110,
-    importance=FactImportance.MEDIUM,
-)
-def detect_cost_outlier(benchmark_data: dict) -> list[Fact]:
-    """Moteur dont le coût est très disproportionné par rapport à son apport.
-
-    Flag un moteur dont le coût ≥ 5× la médiane ET qui n'est pas sur le
-    front Pareto (donc dominé par moins cher OU meilleur CER).
-    """
-    pareto = (benchmark_data.get("pareto") or {}).get("cost") or {}
-    points = pareto.get("points") or []
-    front = set(pareto.get("front") or [])
-    if len(points) < 3:
-        return []
-
-    costs = [float(p["cost"]) for p in points if p.get("cost") is not None]
-    if not costs:
-        return []
-    median_cost = _stats.median(costs)
-    if median_cost <= 0:
-        return []
+from picarones.measurements.narrative.detectors.pareto import *  # noqa: F401, F403
 
-    facts: list[Fact] = []
-    for p in points:
-        c = float(p.get("cost") or 0.0)
-        if c < 5.0 * median_cost:
-            continue
-        if p["engine"] in front:
-            continue  # sur le front → coût justifié par une qualité unique
-        facts.append(Fact(
-            type=FactType.COST_OUTLIER,
-            importance=FactImportance.MEDIUM,
-            payload={
-                "engine": p["engine"],
-                "cost": round(c, 2),
-                "median_cost": round(median_cost, 2),
-                "ratio_to_median": round(c / median_cost, 1),
-                "cer_pct": round(float(p.get("cer") or 0.0) * 100, 2),
-                "cost_unit_pages": 1000,
-            },
-            engines_involved=(p["engine"],),
-        ))
-    return facts
+import picarones.measurements.narrative.detectors.pareto as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/narrative/detectors/quality.py

@@ -1,251 +1,13 @@
-"""Détecteurs narratifs liés à la *qualité texte / fiabilité* (chantier 5).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.narrative.detectors.quality`.
 
-4 détecteurs déplacés depuis ``narrative/detectors.py`` :
-
-- :func:`detect_error_profile_outlier`  (Sprint 4)
-- :func:`detect_llm_hallucination_flag` (Sprint 4)
-- :func:`detect_robustness_fragile`     (Sprint 4)
-- :func:`detect_confidence_warning`     (Sprint 4)
+Phase E du chantier de refonte en 3 cercles. Le moteur narratif
+(Cercle 2 — measurements/) a quitté ``picarones.core.narrative``.
+Cet alias maintient la rétrocompat des imports historiques.
 """
 
-from __future__ import annotations
-
-import statistics as _stats
-from typing import Optional
-
-from picarones.core.narrative.facts import Fact, FactImportance, FactType
-from picarones.core.narrative.registry import register_detector
-
-from picarones.core.narrative.detectors._helpers import (
-    _engine_by_name,
-    _engines_summary,
-    _n_docs,
-)
-
-
-@register_detector(
-    FactType.ERROR_PROFILE_OUTLIER,
-    priority=60,
-    importance=FactImportance.MEDIUM,
-)
-def detect_error_profile_outlier(benchmark_data: dict) -> list[Fact]:
-    """Moteur au profil taxonomique atypique.
-
-    Émet un Fact si, pour un moteur et une classe d'erreur, la part relative
-    est au moins 2× plus élevée que la médiane des autres moteurs (et > 15 %
-    du total pour éviter les strates marginales).
-    """
-    engines = _engines_summary(benchmark_data)
-    # {engine: {class_name: proportion}}
-    profiles: dict[str, dict[str, float]] = {}
-    for e in engines:
-        tax = e.get("aggregated_taxonomy") or {}
-        distribution = tax.get("distribution") or tax.get("proportions") or {}
-        if not distribution:
-            continue
-        profiles[e["name"]] = {k: float(v) for k, v in distribution.items()}
-    if len(profiles) < 2:
-        return []
-
-    # Collecter toutes les classes rencontrées
-    all_classes: set[str] = set()
-    for p in profiles.values():
-        all_classes.update(p.keys())
-
-    facts: list[Fact] = []
-    for cls in all_classes:
-        values = [(name, p.get(cls, 0.0)) for name, p in profiles.items()]
-        props = [v for _, v in values]
-        if not props:
-            continue
-        median_prop = _stats.median(props)
-        for name, v in values:
-            if v < 0.15:  # trop marginal pour être notable
-                continue
-            if median_prop <= 0:
-                continue
-            if v >= 2.0 * median_prop:
-                facts.append(Fact(
-                    type=FactType.ERROR_PROFILE_OUTLIER,
-                    importance=FactImportance.HIGH,
-                    payload={
-                        "engine": name,
-                        "error_class": cls,
-                        "proportion": round(v, 4),
-                        "proportion_pct": round(v * 100, 1),
-                        "median_proportion": round(median_prop, 4),
-                        "median_proportion_pct": round(median_prop * 100, 1),
-                        "ratio_to_median": round(v / median_prop, 2) if median_prop else None,
-                    },
-                    engines_involved=(name,),
-                ))
-    return facts
-
-
-@register_detector(
-    FactType.LLM_HALLUCINATION_FLAG,
-    priority=70,
-    importance=FactImportance.HIGH,
-)
-def detect_llm_hallucination_flag(benchmark_data: dict) -> list[Fact]:
-    """LLM/VLM au taux d'hallucination notablement élevé.
-
-    Déclenché si ``hallucinating_doc_rate`` > 30 % OU ``anchor_score_mean`` < 0,6
-    pour un moteur dont le champ ``is_pipeline`` ou ``is_vlm`` est ``True``.
-    """
-    facts: list[Fact] = []
-    for e in _engines_summary(benchmark_data):
-        agg = e.get("aggregated_hallucination") or {}
-        if not agg:
-            continue
-        rate = agg.get("hallucinating_doc_rate")
-        anchor = agg.get("anchor_score_mean")
-        length_ratio = agg.get("length_ratio_mean")
-        # Signal seulement si c'est un pipeline LLM ou un VLM
-        is_llm = bool(e.get("is_pipeline")) or bool(e.get("is_vlm"))
-        if not is_llm:
-            continue
-
-        flagged = False
-        reasons = []
-        if rate is not None and float(rate) > 0.30:
-            flagged = True
-            reasons.append("taux de documents hallucinés")
-        if anchor is not None and float(anchor) < 0.60:
-            flagged = True
-            reasons.append("ancrage faible")
-        if length_ratio is not None and float(length_ratio) > 1.30:
-            flagged = True
-            reasons.append("sortie anormalement longue")
-        if not flagged:
-            continue
-
-        facts.append(Fact(
-            type=FactType.LLM_HALLUCINATION_FLAG,
-            importance=FactImportance.HIGH,
-            payload={
-                "engine": e["name"],
-                "hallucinating_rate": round(float(rate or 0.0), 4),
-                "hallucinating_rate_pct": round(float(rate or 0.0) * 100, 1),
-                "anchor_score": round(float(anchor), 3) if anchor is not None else None,
-                "length_ratio": round(float(length_ratio), 3) if length_ratio is not None else None,
-                "reasons": reasons,
-                "reasons_list": ", ".join(reasons),
-            },
-            engines_involved=(e["name"],),
-        ))
-    return facts
-
-
-@register_detector(
-    FactType.ROBUSTNESS_FRAGILE,
-    priority=80,
-    importance=FactImportance.MEDIUM,
-)
-def detect_robustness_fragile(benchmark_data: dict) -> list[Fact]:
-    """Moteur qui dégrade fortement au-dessus d'un seuil de bruit/flou.
-
-    Activé si les données de robustesse sont embarquées dans
-    ``benchmark_data["robustness"]`` (hors scope du benchmark classique,
-    produit par ``picarones robustness`` et injecté optionnellement).
-    """
-    robustness = benchmark_data.get("robustness")
-    if not robustness:
-        return []
-
-    facts: list[Fact] = []
-    curves = robustness.get("curves") or robustness.get("engines") or []
-    # Structure attendue : [{engine, degradation_type, points: [{level, cer}]}]
-    # Flag : CER à niveau max > 3× CER au niveau min.
-    for entry in curves:
-        engine = entry.get("engine")
-        dtype = entry.get("degradation_type")
-        points = entry.get("points") or []
-        if not engine or not points or len(points) < 2:
-            continue
-        try:
-            sorted_pts = sorted(points, key=lambda p: float(p["level"]))
-        except (KeyError, TypeError, ValueError):
-            continue
-        first, last = sorted_pts[0], sorted_pts[-1]
-        c0 = float(first.get("cer") or 0.0)
-        c1 = float(last.get("cer") or 0.0)
-        if c0 <= 0.01:  # éviter division par quasi-zéro
-            continue
-        if c1 >= 3.0 * c0 and c1 > 0.15:
-            facts.append(Fact(
-                type=FactType.ROBUSTNESS_FRAGILE,
-                importance=FactImportance.HIGH,
-                payload={
-                    "engine": engine,
-                    "degradation": dtype,
-                    "cer_baseline": round(c0, 4),
-                    "cer_baseline_pct": round(c0 * 100, 1),
-                    "cer_degraded": round(c1, 4),
-                    "cer_degraded_pct": round(c1 * 100, 1),
-                    "ratio": round(c1 / c0, 1),
-                    "level_max": float(last.get("level") or 0),
-                },
-                engines_involved=(engine,),
-            ))
-    return facts
-
-
-@register_detector(
-    FactType.CONFIDENCE_WARNING,
-    priority=120,
-    importance=FactImportance.MEDIUM,
-)
-def detect_confidence_warning(benchmark_data: dict) -> list[Fact]:
-    """Intervalle de confiance large → classement peu fiable.
-
-    Déclenché si, pour le leader ou le runner-up, la largeur de l'IC 95 %
-    est plus du triple de l'écart |leader − runner-up| OU > 5 points de CER.
-    """
-    stats = benchmark_data.get("statistics", {}) or {}
-    cis = stats.get("bootstrap_cis") or []
-    if len(cis) < 2:
-        return []
-
-    ranking = benchmark_data.get("ranking") or []
-    valid = [r for r in ranking if r.get("mean_cer") is not None]
-    if len(valid) < 2:
-        return []
-
-    by_name = {c["engine"]: c for c in cis if "engine" in c}
-    leader = valid[0]["engine"]
-    runner_up = valid[1]["engine"]
-    leader_ci = by_name.get(leader)
-    runner_ci = by_name.get(runner_up)
-    if not leader_ci or not runner_ci:
-        return []
+from picarones.measurements.narrative.detectors.quality import *  # noqa: F401, F403
 
-    gap = abs(float(valid[0]["mean_cer"]) - float(valid[1]["mean_cer"]))
-    facts: list[Fact] = []
-    for engine_name, ci in ((leader, leader_ci), (runner_up, runner_ci)):
-        lo = float(ci.get("ci_lower") or 0.0)
-        hi = float(ci.get("ci_upper") or 0.0)
-        width = hi - lo
-        wide_vs_gap = gap > 0 and width > 3.0 * gap
-        wide_absolute = width > 0.05
-        if wide_vs_gap or wide_absolute:
-            facts.append(Fact(
-                type=FactType.CONFIDENCE_WARNING,
-                importance=FactImportance.MEDIUM,
-                payload={
-                    "engine": engine_name,
-                    "ci_lower": round(lo, 4),
-                    "ci_upper": round(hi, 4),
-                    "ci_width": round(width, 4),
-                    "ci_width_pct": round(width * 100, 2),
-                    "mean_cer": round(float(ci.get("mean") or 0.0), 4),
-                    "mean_cer_pct": round(float(ci.get("mean") or 0.0) * 100, 2),
-                    "gap_to_runner_up_pct": round(gap * 100, 2),
-                    # Niveau de confiance des bornes — propagé pour traçabilité
-                    # anti-hallucination (le template ne hardcode plus "95 %").
-                    "confidence_level": 95,
-                },
-                engines_involved=(engine_name,),
-            ))
-            break  # un seul avertissement suffit
-    return facts
+import picarones.measurements.narrative.detectors.quality as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/narrative/detectors/ranking.py

@@ -1,279 +1,13 @@
-"""Détecteurs narratifs orientés *classement* (chantier 5).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.narrative.detectors.ranking`.
 
-5 détecteurs déplacés depuis ``narrative/detectors.py`` :
-
-- :func:`detect_global_leader_cer`     (Sprint 4)
-- :func:`detect_statistical_tie`       (Sprint 18)
-- :func:`detect_significant_gap`       (Sprint 4)
-- :func:`detect_speed_winner`          (Sprint 4)
-- :func:`detect_median_mean_gap_warning` (Sprint 44)
-
-Comportement et signature inchangés. Tous restent enregistrés
-automatiquement via ``@register_detector`` à l'import.
+Phase E du chantier de refonte en 3 cercles. Le moteur narratif
+(Cercle 2 — measurements/) a quitté ``picarones.core.narrative``.
+Cet alias maintient la rétrocompat des imports historiques.
 """
 
-from __future__ import annotations
-
-import statistics as _stats
-from typing import Optional
-
-from picarones.core.narrative.facts import Fact, FactImportance, FactType
-from picarones.core.narrative.registry import register_detector
-
-from picarones.core.narrative.detectors._helpers import (
-    _engine_by_name,
-    _engines_summary,
-    _n_docs,
-)
-
-
-@register_detector(
-    FactType.GLOBAL_LEADER_CER,
-    priority=10,
-    importance=FactImportance.CRITICAL,
-)
-def detect_global_leader_cer(benchmark_data: dict) -> list[Fact]:
-    """Moteur avec le CER moyen le plus bas sur l'ensemble du corpus.
-
-    Émet un Fact CRITICAL si au moins 2 moteurs sont comparés, en attachant
-    aussi le 2ᵉ pour permettre à l'arbitre de fusionner avec ``significant_gap``.
-    """
-    ranking = benchmark_data.get("ranking") or []
-    # Éliminer les entrées sans CER calculé
-    valid = [r for r in ranking if r.get("mean_cer") is not None]
-    if len(valid) < 1:
-        return []
-
-    leader = valid[0]
-    runner_up = valid[1] if len(valid) >= 2 else None
-
-    payload = {
-        "engine": leader["engine"],
-        "cer": float(leader["mean_cer"]),
-        "cer_pct": round(float(leader["mean_cer"]) * 100, 2),
-        "n_engines": len(valid),
-        "n_docs": _n_docs(benchmark_data),
-    }
-    if runner_up is not None:
-        payload["runner_up"] = runner_up["engine"]
-        payload["runner_up_cer"] = float(runner_up["mean_cer"])
-        payload["runner_up_cer_pct"] = round(float(runner_up["mean_cer"]) * 100, 2)
-
-    return [Fact(
-        type=FactType.GLOBAL_LEADER_CER,
-        importance=FactImportance.CRITICAL,
-        payload=payload,
-        engines_involved=(leader["engine"],),
-    )]
-
-
-@register_detector(
-    FactType.STATISTICAL_TIE,
-    priority=20,
-    importance=FactImportance.CRITICAL,
-)
-def detect_statistical_tie(benchmark_data: dict) -> list[Fact]:
-    """Groupes de moteurs statistiquement indiscernables (Nemenyi)."""
-    nemenyi = benchmark_data.get("statistics", {}).get("nemenyi", {})
-    if not nemenyi or nemenyi.get("error"):
-        return []
-
-    tied_groups = nemenyi.get("tied_groups", [])
-    mean_ranks = nemenyi.get("mean_ranks", {})
-    cd = nemenyi.get("critical_distance", 0.0)
-    alpha = nemenyi.get("alpha", 0.05)
-    n_blocks = nemenyi.get("n_blocks", 0)
-
-    facts: list[Fact] = []
-    for group in tied_groups:
-        if len(group) < 2:
-            continue
-        is_leader_tie = min(mean_ranks.get(n, 999) for n in group) == min(
-            mean_ranks.values(), default=0
-        )
-        importance = FactImportance.CRITICAL if is_leader_tie else FactImportance.HIGH
-
-        facts.append(Fact(
-            type=FactType.STATISTICAL_TIE,
-            importance=importance,
-            payload={
-                "engines": list(group),
-                "engines_list": ", ".join(group),
-                "mean_ranks": {n: mean_ranks.get(n) for n in group},
-                "critical_distance": round(cd, 3),
-                "alpha": alpha,
-                "n_blocks": n_blocks,
-                "includes_leader": is_leader_tie,
-                "n_tied": len(group),
-            },
-            engines_involved=tuple(group),
-        ))
-    return facts
-
-
-@register_detector(
-    FactType.SIGNIFICANT_GAP,
-    priority=30,
-    importance=FactImportance.HIGH,
-)
-def detect_significant_gap(benchmark_data: dict) -> list[Fact]:
-    """Écart statistiquement significatif entre le 1ᵉʳ et le 2ᵉ du classement.
-
-    Lit la matrice de Wilcoxon pairwise et vérifie si la paire (leader,
-    runner-up) y apparaît avec ``significant = True``.
-    """
-    ranking = benchmark_data.get("ranking") or []
-    valid = [r for r in ranking if r.get("mean_cer") is not None]
-    if len(valid) < 2:
-        return []
-
-    leader = valid[0]["engine"]
-    runner_up = valid[1]["engine"]
-
-    pairwise = benchmark_data.get("statistics", {}).get("pairwise_wilcoxon") or []
-    match = None
-    for p in pairwise:
-        names = {p.get("engine_a"), p.get("engine_b")}
-        if names == {leader, runner_up}:
-            match = p
-            break
-    if match is None:
-        return []
-
-    if not match.get("significant"):
-        return []  # pas d'écart significatif — rien à signaler ici
-
-    delta_cer = abs(float(valid[0]["mean_cer"]) - float(valid[1]["mean_cer"]))
-    return [Fact(
-        type=FactType.SIGNIFICANT_GAP,
-        importance=FactImportance.CRITICAL,
-        payload={
-            "leader": leader,
-            "runner_up": runner_up,
-            "p_value": float(match.get("p_value", 0.0)),
-            "delta_cer": round(delta_cer, 4),
-            "delta_cer_pct": round(delta_cer * 100, 2),
-            "n_pairs": int(match.get("n_pairs", 0)),
-        },
-        engines_involved=(leader, runner_up),
-    )]
-
-
-@register_detector(
-    FactType.SPEED_WINNER,
-    priority=100,
-    importance=FactImportance.MEDIUM,
-)
-def detect_speed_winner(benchmark_data: dict) -> list[Fact]:
-    """Moteur significativement plus rapide pour une qualité comparable.
-
-    Déclenché si un moteur est au moins 3× plus rapide que la médiane ET que
-    son CER n'est pas significativement pire (dans le même groupe Nemenyi que
-    le leader OU CER ≤ 1,1 × CER du leader).
-    """
-    durations = _mean_duration_per_engine(benchmark_data)
-    if len(durations) < 2:
-        return []
-
-    values = list(durations.values())
-    median_dur = _stats.median(values)
-    if median_dur <= 0:
-        return []
-
-    ranking = benchmark_data.get("ranking") or []
-    valid = [r for r in ranking if r.get("mean_cer") is not None]
-    if not valid:
-        return []
-    leader_cer = float(valid[0]["mean_cer"])
-    quality_ceiling = max(0.01, leader_cer * 1.10)
-
-    tied_groups = benchmark_data.get("statistics", {}).get("nemenyi", {}).get("tied_groups") or []
-    leader_group: set[str] = set()
-    for g in tied_groups:
-        if valid[0]["engine"] in g:
-            leader_group = set(g)
-            break
-
-    facts: list[Fact] = []
-    candidates = sorted(durations.items(), key=lambda kv: kv[1])
-    for engine, dur in candidates:
-        if dur * 3.0 > median_dur:
-            break  # les suivants sont encore plus lents
-        summary = _engine_by_name(benchmark_data, engine) or {}
-        engine_cer = summary.get("cer")
-        if engine_cer is None:
-            continue
-        acceptable_quality = (
-            engine in leader_group or float(engine_cer) <= quality_ceiling
-        )
-        if not acceptable_quality:
-            continue
-        facts.append(Fact(
-            type=FactType.SPEED_WINNER,
-            importance=FactImportance.MEDIUM,
-            payload={
-                "engine": engine,
-                "mean_duration": round(dur, 3),
-                "median_duration": round(median_dur, 3),
-                "speedup": round(median_dur / dur, 1) if dur > 0 else None,
-                "cer": round(float(engine_cer), 4),
-                "cer_pct": round(float(engine_cer) * 100, 2),
-            },
-            engines_involved=(engine,),
-        ))
-    return facts[:1]  # seulement le plus rapide — éviter le bruit
-
-
-@register_detector(
-    FactType.MEDIAN_MEAN_GAP_WARNING,
-    priority=140,
-    importance=FactImportance.MEDIUM,
-)
-def detect_median_mean_gap_warning(benchmark_data: dict) -> list[Fact]:
-    """Avertit quand le ratio ``|moyenne - médiane| / médiane`` du leader
-    dépasse 30 %, ce qui indique une distribution fortement asymétrique
-    où la moyenne masque les performances réelles.
-
-    Sprint 44 — A.I.2 du plan d'évolution. Cohérent avec le passage du
-    tri par défaut sur la médiane : si la moyenne du leader diverge
-    fortement de la médiane, l'utilisateur doit le savoir pour
-    interpréter correctement les chiffres.
-    """
-    ranking = benchmark_data.get("ranking") or []
-    valid = [
-        r for r in ranking
-        if r.get("median_cer") is not None
-        and r.get("mean_cer") is not None
-    ]
-    if not valid:
-        return []
-
-    leader = valid[0]
-    median_cer = float(leader["median_cer"])
-    mean_cer = float(leader["mean_cer"])
-
-    if median_cer <= 0:
-        # Médiane nulle (corpus très facile pour ce moteur) — l'écart
-        # relatif n'est pas calculable de manière utile, on s'abstient.
-        return []
-
-    relative_gap = abs(mean_cer - median_cer) / median_cer
-    if relative_gap < 0.30:
-        return []
-
-    importance = (
-        FactImportance.HIGH if relative_gap >= 1.0 else FactImportance.MEDIUM
-    )
+from picarones.measurements.narrative.detectors.ranking import *  # noqa: F401, F403
 
-    return [Fact(
-        type=FactType.MEDIAN_MEAN_GAP_WARNING,
-        importance=importance,
-        payload={
-            "engine": leader["engine"],
-            "median_cer_pct": round(median_cer * 100, 2),
-            "mean_cer_pct": round(mean_cer * 100, 2),
-            "relative_gap_pct": round(relative_gap * 100, 1),
-            "n_docs": int(leader.get("documents") or 0),
-        },
-        engines_involved=(leader["engine"],),
-    )]
+import picarones.measurements.narrative.detectors.ranking as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/narrative/detectors/stratum.py

@@ -1,203 +1,13 @@
-"""Détecteurs narratifs liés à la *stratification corpus* (chantier 5).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.narrative.detectors.stratum`.
 
-3 détecteurs + 1 helper (``_stratum_cer_by_engine``) déplacés depuis
-``narrative/detectors.py`` :
-
-- :func:`detect_stratum_winner`             (Sprint 4)
-- :func:`detect_stratum_collapse`           (Sprint 4)
-- :func:`detect_stratification_recommended` (Sprint 45)
+Phase E du chantier de refonte en 3 cercles. Le moteur narratif
+(Cercle 2 — measurements/) a quitté ``picarones.core.narrative``.
+Cet alias maintient la rétrocompat des imports historiques.
 """
 
-from __future__ import annotations
-
-import statistics as _stats
-from typing import Optional
-
-from picarones.core.narrative.facts import Fact, FactImportance, FactType
-from picarones.core.narrative.registry import register_detector
-
-from picarones.core.narrative.detectors._helpers import (
-    _engine_by_name,
-    _engines_summary,
-    _n_docs,
-)
-
-
-def _stratum_cer_by_engine(benchmark_data: dict) -> dict[str, dict[str, list[float]]]:
-    """Agrège les CER par (moteur, strate).
-
-    Strate = ``document["script_type"]`` si présent. Retourne ``{}`` si aucun
-    document n'expose de strate (pas d'émission possible).
-    """
-    out: dict[str, dict[str, list[float]]] = {}
-    for doc in benchmark_data.get("documents") or []:
-        stratum = doc.get("script_type")
-        if not stratum:
-            continue
-        for er in doc.get("engine_results") or []:
-            if er.get("error"):
-                continue
-            cer = er.get("cer")
-            if cer is None:
-                continue
-            name = er.get("engine")
-            out.setdefault(name, {}).setdefault(stratum, []).append(float(cer))
-    return out
-
-
-@register_detector(
-    FactType.STRATUM_WINNER,
-    priority=40,
-    importance=FactImportance.MEDIUM,
-)
-def detect_stratum_winner(benchmark_data: dict) -> list[Fact]:
-    """Moteur qui domine nettement sur une strate (≥ 3 documents, CER
-    au moins 25 % plus bas que le second sur cette strate).
-    """
-    agg = _stratum_cer_by_engine(benchmark_data)
-    if not agg:
-        return []
-
-    # Inverser : {stratum: {engine: mean_cer}}
-    by_stratum: dict[str, dict[str, float]] = {}
-    for engine, strata in agg.items():
-        for stratum, vals in strata.items():
-            if len(vals) < 3:
-                continue
-            by_stratum.setdefault(stratum, {})[engine] = sum(vals) / len(vals)
-
-    facts: list[Fact] = []
-    for stratum, engine_cer in by_stratum.items():
-        if len(engine_cer) < 2:
-            continue
-        ordered = sorted(engine_cer.items(), key=lambda kv: kv[1])
-        best_name, best_cer = ordered[0]
-        second_cer = ordered[1][1]
-        if second_cer == 0:
-            continue
-        if best_cer < second_cer * 0.75:  # dominance ≥ 25 %
-            facts.append(Fact(
-                type=FactType.STRATUM_WINNER,
-                importance=FactImportance.HIGH,
-                payload={
-                    "engine": best_name,
-                    "stratum": stratum,
-                    "cer": round(best_cer, 4),
-                    "cer_pct": round(best_cer * 100, 2),
-                    "second_engine": ordered[1][0],
-                    "second_cer": round(second_cer, 4),
-                    "second_cer_pct": round(second_cer * 100, 2),
-                    "n_docs_stratum": len(agg[best_name][stratum]),
-                },
-                engines_involved=(best_name,),
-                stratum=stratum,
-            ))
-    return facts
-
-
-@register_detector(
-    FactType.STRATUM_COLLAPSE,
-    priority=50,
-    importance=FactImportance.HIGH,
-)
-def detect_stratum_collapse(benchmark_data: dict) -> list[Fact]:
-    """Moteur globalement compétitif qui s'effondre sur une strate.
-
-    Déclenché si, pour un moteur, le CER moyen sur une strate ≥ 3 documents
-    est plus du double du CER global du même moteur.
-    """
-    agg = _stratum_cer_by_engine(benchmark_data)
-    if not agg:
-        return []
-
-    facts: list[Fact] = []
-    for engine_name, strata in agg.items():
-        summary = _engine_by_name(benchmark_data, engine_name) or {}
-        global_cer = summary.get("cer")
-        if global_cer is None:
-            continue
-        global_cer = float(global_cer)
-        if global_cer <= 0:
-            continue
-        for stratum, vals in strata.items():
-            if len(vals) < 3:
-                continue
-            local_cer = sum(vals) / len(vals)
-            if local_cer > 2.0 * global_cer and (local_cer - global_cer) > 0.05:
-                facts.append(Fact(
-                    type=FactType.STRATUM_COLLAPSE,
-                    importance=FactImportance.HIGH,
-                    payload={
-                        "engine": engine_name,
-                        "stratum": stratum,
-                        "local_cer": round(local_cer, 4),
-                        "local_cer_pct": round(local_cer * 100, 2),
-                        "global_cer": round(global_cer, 4),
-                        "global_cer_pct": round(global_cer * 100, 2),
-                        "delta_cer_pct": round((local_cer - global_cer) * 100, 2),
-                        "n_docs_stratum": len(vals),
-                    },
-                    engines_involved=(engine_name,),
-                    stratum=stratum,
-                ))
-    return facts
-
-
-@register_detector(
-    FactType.STRATIFICATION_RECOMMENDED,
-    priority=45,  # juste après STRATUM_WINNER (40), avant STRATUM_COLLAPSE (50)
-    importance=FactImportance.HIGH,
-)
-def detect_stratification_recommended(benchmark_data: dict) -> list[Fact]:
-    """Avertit quand le corpus est hétérogène et que la vue stratifiée
-    apporte un éclairage qualitativement différent du classement global.
-
-    Critère : ``corpus_homogeneity.max_inter_strata_gap > 5 points`` de
-    CER médian sur le moteur leader.  Au-delà de 10 points, importance
-    ``HIGH`` (situation très hétérogène où le seul classement global
-    serait trompeur).
-
-    Lit ``benchmark_data["corpus_homogeneity"]`` exposé par
-    ``BenchmarkResult.as_dict()`` (Sprint 45).
-    """
-    homog = benchmark_data.get("corpus_homogeneity")
-    if not homog:
-        return []
-
-    gap = homog.get("max_inter_strata_gap")
-    if gap is None:
-        return []
-
-    gap = float(gap)
-    if gap < 0.05:
-        return []  # 5 points de CER : seuil de pertinence éditoriale
-
-    leader = str(homog.get("leader") or "")
-    n_strata = int(homog.get("n_strata") or 0)
-    pair = homog.get("leader_max_gap_strata") or ["", ""]
-    if len(pair) < 2:
-        return []
-    min_strat, max_strat = str(pair[0]), str(pair[1])
-
-    leader_per_stratum = homog.get("leader_per_stratum_median") or {}
-    min_med = float(leader_per_stratum.get(min_strat, 0.0))
-    max_med = float(leader_per_stratum.get(max_strat, 0.0))
-
-    importance = (
-        FactImportance.HIGH if gap >= 0.10 else FactImportance.MEDIUM
-    )
+from picarones.measurements.narrative.detectors.stratum import *  # noqa: F401, F403
 
-    return [Fact(
-        type=FactType.STRATIFICATION_RECOMMENDED,
-        importance=importance,
-        payload={
-            "leader": leader,
-            "n_strata": n_strata,
-            "gap_pct": round(gap * 100, 1),
-            "min_stratum": min_strat,
-            "max_stratum": max_strat,
-            "min_stratum_cer_pct": round(min_med * 100, 2),
-            "max_stratum_cer_pct": round(max_med * 100, 2),
-        },
-        engines_involved=(leader,) if leader else (),
-    )]
+import picarones.measurements.narrative.detectors.stratum as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/narrative/facts.py

@@ -1,212 +1,13 @@
-"""Modèle de données du moteur narratif.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.narrative.facts`.
 
-Un ``Fact`` est une observation structurée extraite d'un ``BenchmarkResult``.
-Chaque détecteur retourne zéro, un ou plusieurs ``Fact`` typés. L'arbitre
-(Sprint 4) trie par ``importance`` et sélectionne les faits à afficher.
-
-Règle d'or (à vérifier par tests) : chaque valeur numérique ou nom d'entité
-présent dans ``payload`` doit provenir directement du JSON d'entrée, jamais
-d'une génération. C'est ce qui rend la synthèse reproductible bit-à-bit et
-immune à l'hallucination par construction.
+Phase E du chantier de refonte en 3 cercles. Le moteur narratif
+(Cercle 2 — measurements/) a quitté ``picarones.core.narrative``.
+Cet alias maintient la rétrocompat des imports historiques.
 """
 
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from enum import Enum
-from typing import Callable, Optional
-
-
-class FactType(str, Enum):
-    """Types de faits détectables.
-
-    L'ajout d'un nouveau type se fait ici + un détecteur dans ``detectors.py``
-    + un template dans ``narrative/templates_{lang}.yaml`` (Sprint 4).
-    """
-
-    GLOBAL_LEADER_CER = "global_leader_cer"
-    """Moteur avec le CER médian le plus bas sur l'ensemble du corpus."""
-
-    STATISTICAL_TIE = "statistical_tie"
-    """Top-N moteurs statistiquement indiscernables (Nemenyi, Sprint 3)."""
-
-    SIGNIFICANT_GAP = "significant_gap"
-    """Écart statistiquement significatif entre le 1ᵉʳ et le 2ᵉ du classement."""
-
-    PARETO_ALTERNATIVE = "pareto_alternative"
-    """Moteur sur la frontière Pareto différent du leader CER pur (Sprint 5)."""
-
-    STRATUM_WINNER = "stratum_winner"
-    """Moteur qui domine sur une strate spécifique (siècle, langue, type)."""
-
-    STRATUM_COLLAPSE = "stratum_collapse"
-    """Moteur globalement bon qui s'effondre sur une strate spécifique."""
-
-    ERROR_PROFILE_OUTLIER = "error_profile_outlier"
-    """Moteur avec un profil taxonomique atypique (ex : 3× plus d'erreurs d'abréviation)."""
-
-    LLM_HALLUCINATION_FLAG = "llm_hallucination_flag"
-    """LLM avec un taux d'hallucination notablement supérieur aux autres."""
-
-    ROBUSTNESS_FRAGILE = "robustness_fragile"
-    """Moteur qui dégrade fortement au-dessus d'un seuil de bruit/flou."""
-
-    COST_OUTLIER = "cost_outlier"
-    """Moteur au ratio coût/qualité très défavorable (Sprint 5)."""
-
-    SPEED_WINNER = "speed_winner"
-    """Moteur significativement plus rapide pour une qualité comparable."""
-
-    CONFIDENCE_WARNING = "confidence_warning"
-    """Intervalle de confiance très large : classement peu fiable."""
-
-    ENSEMBLE_OPPORTUNITY = "ensemble_opportunity"
-    """Deux moteurs sont fortement complémentaires : un voting majoritaire
-    pourrait améliorer significativement le CER (Sprint 36)."""
-
-    MEDIAN_MEAN_GAP_WARNING = "median_mean_gap_warning"
-    """Distribution des CER fortement asymétrique sur le corpus —
-    la moyenne du leader est tirée par quelques documents catastrophiques
-    et masque les performances réelles. La médiane (utilisée pour le tri
-    par défaut depuis Sprint 44) est plus représentative."""
-
-    STRATIFICATION_RECOMMENDED = "stratification_recommended"
-    """Le corpus est hétérogène du point de vue script_type : le moteur
-    leader varie fortement selon la strate. Le lecteur doit consulter
-    la vue stratifiée plutôt que de se fier au seul classement global
-    (Sprint 46)."""
-
-    ENGINE_OFF_BASELINE = "engine_off_baseline"
-    """Le CER courant d'un moteur s'écarte significativement de sa
-    moyenne historique sur le même corpus (lue depuis l'historique
-    SQLite, Sprint 8). Lit ``BenchmarkHistory`` via le module
-    ``baseline_comparison`` (Sprint 73). Garde-fous : ≥ 5 runs
-    historiques même corpus + |delta_relatif| > 20 %."""
-
-    ENGINE_UNSTABLE = "engine_unstable"
-    """Un moteur LLM/VLM exécuté plusieurs fois sur les mêmes
-    documents produit des sorties différentes au-delà d'un seuil
-    de variance (Sprint 90).  Lit ``compute_multirun_stability``
-    (Sprint 83).  Garde-fous : ≥ 2 runs et seuil sur le coefficient
-    de variation du CER (>10 % par défaut) ou sur le rappel de
-    runs identiques (<50 %)."""
-
-    REGRESSION_IN_HISTORY = "regression_in_history"
-    """Un moteur montre une tendance ou une rupture défavorable
-    sur l'historique SQLite : son CER moyen s'est dégradé sur
-    les N derniers runs (Sprint 92).  Lit
-    ``compute_corpus_longitudinal`` du module ``longitudinal``.
-    Garde-fous : ≥ 3 runs historiques et soit pente > seuil
-    (régression progressive), soit change-point avec delta >
-    seuil (rupture brutale)."""
-
-
-class FactImportance(int, Enum):
-    """Score d'importance d'un fait — décide l'ordre et la sélection."""
-
-    CRITICAL = 100
-    """À remonter systématiquement en synthèse (ex : leader + écart significatif)."""
-
-    HIGH = 70
-    """À remonter sauf si déjà redondant avec un fait critique."""
-
-    MEDIUM = 40
-    """À remonter si la synthèse a encore de la place."""
-
-    LOW = 10
-    """Informatif, remonté uniquement en vue détaillée."""
-
-
-@dataclass
-class Fact:
-    """Observation structurée extraite d'un benchmark.
-
-    Attributes
-    ----------
-    type:
-        Type de fait (voir ``FactType``).
-    importance:
-        Priorité de sélection (voir ``FactImportance``).
-    payload:
-        Dict de données brutes sérialisables. **Toutes les valeurs doivent
-        provenir du JSON d'entrée** — c'est le garde-fou anti-hallucination.
-    engines_involved:
-        Noms des moteurs concernés. Utilisé par l'arbitre pour détecter
-        les redondances (deux faits sur le même moteur = fusion ou sélection).
-    stratum:
-        Strate concernée (ex : "XVIIe siècle", "latin médiéval") ou None.
-    """
-
-    type: FactType
-    importance: FactImportance
-    payload: dict
-    engines_involved: tuple[str, ...] = ()
-    stratum: Optional[str] = None
-
-    def as_dict(self) -> dict:
-        return {
-            "type": self.type.value,
-            "importance": int(self.importance),
-            "payload": self.payload,
-            "engines_involved": list(self.engines_involved),
-            "stratum": self.stratum,
-        }
-
-
-# ---------------------------------------------------------------------------
-# Registre de détecteurs
-# ---------------------------------------------------------------------------
-
-# Signature d'un détecteur : prend le dict JSON du benchmark, retourne une liste
-# de Fact (potentiellement vide). Doit être pure et déterministe.
-DetectorFn = Callable[[dict], list[Fact]]
-
-
-@dataclass
-class DetectorRegistry:
-    """Registre central des détecteurs de faits.
-
-    Un détecteur est enregistré via ``register(fact_type, fn)``. ``detect_all``
-    appelle tous les détecteurs enregistrés et renvoie la liste consolidée.
-    """
-
-    _detectors: dict[FactType, DetectorFn] = field(default_factory=dict)
-
-    def register(self, fact_type: FactType, fn: DetectorFn) -> None:
-        self._detectors[fact_type] = fn
-
-    def unregister(self, fact_type: FactType) -> None:
-        self._detectors.pop(fact_type, None)
-
-    def registered_types(self) -> tuple[FactType, ...]:
-        return tuple(self._detectors.keys())
-
-    def run(self, benchmark_data: dict) -> list[Fact]:
-        facts: list[Fact] = []
-        for fact_type, fn in self._detectors.items():
-            try:
-                result = fn(benchmark_data)
-            except Exception as e:
-                import logging
-                logging.getLogger(__name__).warning(
-                    "[narrative.detector.%s] fonctionnalité dégradée : %s",
-                    fact_type.value, e,
-                )
-                continue
-            if result:
-                facts.extend(result)
-        return facts
-
-
-def detect_all(benchmark_data: dict, registry: Optional[DetectorRegistry] = None) -> list[Fact]:
-    """Applique tous les détecteurs enregistrés au benchmark donné.
-
-    Point d'entrée du Sprint 4. Pour Sprint 1, le registre par défaut est vide :
-    les détecteurs concrets sont ajoutés sprint par sprint.
-    """
-    if registry is None:
-        registry = _DEFAULT_REGISTRY
-    return registry.run(benchmark_data)
-
+from picarones.measurements.narrative.facts import *  # noqa: F401, F403
 
-_DEFAULT_REGISTRY = DetectorRegistry()
+import picarones.measurements.narrative.facts as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/narrative/registry.py

@@ -1,217 +1,13 @@
-"""Registre déclaratif des détecteurs narratifs (Sprint 29).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.narrative.registry`.
 
-Avant le Sprint 29, ajouter un nouveau type de fait imposait de toucher
-**quatre** fichiers :
-
-  1. ``facts.py``    — ajouter une valeur à ``FactType`` ;
-  2. ``detectors.py`` — écrire ``def detect_xxx(data) -> list[Fact]`` ;
-  3. ``detectors.py`` — l'inscrire dans le dict ``DETECTORS_BY_TYPE`` ;
-  4. ``arbiter.py``  — ajouter le type à la séquence ``DEFAULT_TYPE_ORDER``
-                       au bon endroit pour la priorité éditoriale.
-
-Sprint 29 ramène le nombre de modifications à **deux** :
-
-  1. ``facts.py``    — toujours nécessaire pour le type énuméré ;
-  2. ``detectors.py`` — décorer la fonction avec ``@register_detector(...)``.
-
-Le décorateur :
-  - enregistre la fonction dans un registre global trié par ``priority`` ;
-  - vérifie qu'aucun détecteur ne se réenregistre sur le même ``FactType`` ;
-  - laisse la fonction utilisable telle quelle (rétrocompatibilité) ;
-  - alimente automatiquement ``arbiter.DEFAULT_TYPE_ORDER``.
-
-Conventions de priorité (« politique éditoriale » du rapport)
--------------------------------------------------------------
-Plus la valeur est petite, plus le fait remonte tôt en synthèse à
-importance égale. Pour conserver l'ordre historique du Sprint 23, on
-utilise un pas de 10 pour laisser de la place à des insertions futures :
-
-  10  GLOBAL_LEADER_CER       qui gagne globalement
-  20  STATISTICAL_TIE         y a-t-il un ex-aequo
-  30  SIGNIFICANT_GAP         à quel point l'écart est solide
-  40  STRATUM_WINNER          qui domine sur quel sous-corpus
-  50  STRATUM_COLLAPSE        qui s'effondre sur quoi
-  60  ERROR_PROFILE_OUTLIER   qui se trompe différemment
-  70  LLM_HALLUCINATION_FLAG  hallucinations VLM
-  80  ROBUSTNESS_FRAGILE      sensibilité aux dégradations
-  90  PARETO_ALTERNATIVE      compromis coût/qualité
- 100  SPEED_WINNER            vitesse
- 110  COST_OUTLIER            coût aberrant
- 120  CONFIDENCE_WARNING      mise en garde sur la fiabilité
-
-Le décorateur n'impose **pas** de pas — un détecteur tiers peut très
-bien utiliser ``priority=42`` pour s'insérer entre STRATUM_WINNER et
-STRATUM_COLLAPSE par exemple.
+Phase E du chantier de refonte en 3 cercles. Le moteur narratif
+(Cercle 2 — measurements/) a quitté ``picarones.core.narrative``.
+Cet alias maintient la rétrocompat des imports historiques.
 """
 
-from __future__ import annotations
-
-import logging
-import threading
-from dataclasses import dataclass
-from typing import Callable, Optional
-
-from picarones.core.narrative.facts import (
-    DetectorFn,
-    DetectorRegistry,
-    FactImportance,
-    FactType,
-)
-
-logger = logging.getLogger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# Métadonnées d'un détecteur
-# ---------------------------------------------------------------------------
-
-@dataclass(frozen=True)
-class DetectorEntry:
-    """Métadonnées d'un détecteur enregistré."""
-    fact_type: FactType
-    fn: DetectorFn
-    priority: int
-    importance: FactImportance
-
-
-# ---------------------------------------------------------------------------
-# Registre global
-# ---------------------------------------------------------------------------
-
-_REGISTRY: dict[FactType, DetectorEntry] = {}
-_REGISTRY_LOCK = threading.Lock()
-
-
-def register_detector(
-    fact_type: FactType,
-    *,
-    priority: int,
-    importance: FactImportance = FactImportance.MEDIUM,
-) -> Callable[[DetectorFn], DetectorFn]:
-    """Décorateur d'enregistrement.
-
-    Usage::
-
-        @register_detector(FactType.GLOBAL_LEADER_CER, priority=10,
-                           importance=FactImportance.CRITICAL)
-        def detect_global_leader_cer(data: dict) -> list[Fact]:
-            ...
-
-    Le décorateur :
-      - vérifie qu'aucun autre détecteur n'est déjà enregistré sur
-        ``fact_type`` (sinon ``ValueError``) ;
-      - vérifie que ``priority`` est un entier ;
-      - retourne la fonction inchangée pour ne pas casser les imports
-        existants.
-
-    L'``importance`` mémorisée ici sert de **métadonnée** au registre :
-    chaque détecteur reste libre d'émettre des ``Fact`` avec une
-    importance différente selon le contexte (ex. CRITICAL si l'écart
-    est gigantesque, HIGH sinon).
-    """
-    def _decorator(fn: DetectorFn) -> DetectorFn:
-        with _REGISTRY_LOCK:
-            if fact_type in _REGISTRY:
-                raise ValueError(
-                    f"Détecteur déjà enregistré pour {fact_type.value!r} : "
-                    f"{_REGISTRY[fact_type].fn.__name__}. Désenregistrer "
-                    "explicitement avant de réassigner."
-                )
-            entry = DetectorEntry(
-                fact_type=fact_type,
-                fn=fn,
-                priority=int(priority),
-                importance=importance,
-            )
-            _REGISTRY[fact_type] = entry
-        logger.debug(
-            "[narrative.registry] enregistré %s priority=%s importance=%s",
-            fact_type.value, priority, importance.name,
-        )
-        return fn
-
-    return _decorator
-
-
-def unregister(fact_type: FactType) -> None:
-    """Retire un détecteur du registre — utilisé par les tests."""
-    with _REGISTRY_LOCK:
-        _REGISTRY.pop(fact_type, None)
-
-
-def iter_detectors() -> list[DetectorEntry]:
-    """Retourne tous les détecteurs enregistrés, triés par ``priority``.
-
-    Le tri est stable : à ``priority`` égale, l'ordre d'enregistrement
-    est préservé (utile en présence d'extensions tierces).
-    """
-    with _REGISTRY_LOCK:
-        entries = list(_REGISTRY.values())
-    entries.sort(key=lambda e: e.priority)
-    return entries
-
-
-def detector_for(fact_type: FactType) -> Optional[DetectorEntry]:
-    with _REGISTRY_LOCK:
-        return _REGISTRY.get(fact_type)
-
-
-def clear_registry() -> None:
-    """Vide le registre — réservé aux tests d'isolation."""
-    with _REGISTRY_LOCK:
-        _REGISTRY.clear()
-
-
-def default_type_order() -> tuple[FactType, ...]:
-    """Calcule l'ordre canonique des types depuis le registre courant.
-
-    Source de vérité de ``arbiter.DEFAULT_TYPE_ORDER`` depuis le Sprint 29.
-    """
-    return tuple(e.fact_type for e in iter_detectors())
-
-
-# ---------------------------------------------------------------------------
-# Pont avec ``DetectorRegistry`` historique
-# ---------------------------------------------------------------------------
-
-def populate_legacy_registry(registry: DetectorRegistry) -> None:
-    """Synchronise le ``DetectorRegistry`` historique depuis le décorateur.
-
-    L'objet ``DetectorRegistry`` reste l'API publique pour les
-    consommateurs externes (cf. ``DetectorRegistry.run``) ; cette
-    fonction l'alimente depuis le registre déclaratif courant.
-    """
-    for entry in iter_detectors():
-        registry.register(entry.fact_type, entry.fn)
-
-
-__all__ = [
-    "DetectorEntry",
-    "register_detector",
-    "unregister",
-    "iter_detectors",
-    "detector_for",
-    "clear_registry",
-    "default_type_order",
-    "populate_legacy_registry",
-]
-
-
-# ---------------------------------------------------------------------------
-# Sentinel — sans usage direct ; vérifie au build qu'on n'introduit pas
-# de valeur ``priority`` dupliquée par accident parmi les builtins.
-# ---------------------------------------------------------------------------
+from picarones.measurements.narrative.registry import *  # noqa: F401, F403
 
-def _verify_unique_priorities() -> None:
-    seen: dict[int, FactType] = {}
-    for entry in iter_detectors():
-        if entry.priority in seen:
-            logger.warning(
-                "[narrative.registry] priority %s dupliquée : "
-                "%s et %s — ordre indéterministe à priorité égale.",
-                entry.priority,
-                seen[entry.priority].value,
-                entry.fact_type.value,
-            )
-        else:
-            seen[entry.priority] = entry.fact_type
+import picarones.measurements.narrative.registry as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/narrative/renderer.py

@@ -1,105 +1,13 @@
-"""Rendu des faits narratifs en texte lisible.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.narrative.renderer`.
 
-Les templates sont chargés depuis ``templates/{lang}.yaml`` au premier accès.
-Le rendu utilise ``str.format_map`` sur le ``payload`` du ``Fact``. Aucun LLM,
-aucune génération : la sortie est la concaténation de templates remplis avec
-des valeurs venant strictement du JSON d'entrée.
+Phase E du chantier de refonte en 3 cercles. Le moteur narratif
+(Cercle 2 — measurements/) a quitté ``picarones.core.narrative``.
+Cet alias maintient la rétrocompat des imports historiques.
 """
 
-from __future__ import annotations
+from picarones.measurements.narrative.renderer import *  # noqa: F401, F403
 
-import logging
-import re
-from pathlib import Path
-from typing import Iterable
-
-import yaml
-
-from picarones.core.narrative.facts import Fact
-
-logger = logging.getLogger(__name__)
-
-_TEMPLATES_DIR = Path(__file__).parent / "templates"
-_TEMPLATES_CACHE: dict[str, dict[str, str]] = {}
-
-
-def _load_templates(lang: str) -> dict[str, str]:
-    """Charge et met en cache les templates de la langue demandée.
-
-    Fallback : si la langue n'existe pas, retourne les templates FR. Si FR
-    est également absent (incident d'installation), retourne un dict vide.
-    """
-    if lang in _TEMPLATES_CACHE:
-        return _TEMPLATES_CACHE[lang]
-
-    path = _TEMPLATES_DIR / f"{lang}.yaml"
-    if not path.exists():
-        if lang != "fr":
-            return _load_templates("fr")
-        _TEMPLATES_CACHE[lang] = {}
-        return _TEMPLATES_CACHE[lang]
-
-    try:
-        with path.open(encoding="utf-8") as fh:
-            data = yaml.safe_load(fh) or {}
-        if not isinstance(data, dict):
-            logger.warning("[narrative] %s n'est pas un dict YAML — ignoré", path)
-            _TEMPLATES_CACHE[lang] = {}
-        else:
-            _TEMPLATES_CACHE[lang] = {str(k): str(v).strip() for k, v in data.items()}
-    except yaml.YAMLError as e:
-        logger.warning("[narrative] échec parsing %s : %s", path, e)
-        _TEMPLATES_CACHE[lang] = {}
-
-    return _TEMPLATES_CACHE[lang]
-
-
-class _SafeFormatMap(dict):
-    """Dict qui retourne ``'?'`` pour les clés manquantes dans un template.
-
-    Évite qu'un détecteur mal documenté fasse crasher le rendu. En pratique
-    les tests couvrent les clés attendues, mais la robustesse prévaut.
-    """
-
-    def __missing__(self, key: str) -> str:
-        logger.warning("[narrative] clé manquante dans payload : %r", key)
-        return "?"
-
-
-def render_fact(fact: Fact, lang: str = "fr") -> str:
-    """Rend un Fact en une phrase selon la langue.
-
-    Retourne ``""`` si le template est absent pour ce type.
-    """
-    templates = _load_templates(lang)
-    tpl = templates.get(fact.type.value)
-    if not tpl:
-        return ""
-
-    try:
-        return tpl.format_map(_SafeFormatMap(fact.payload))
-    except (ValueError, KeyError) as e:
-        logger.warning(
-            "[narrative] rendu impossible pour %s : %s", fact.type.value, e,
-        )
-        return ""
-
-
-def render_synthesis(facts: Iterable[Fact], lang: str = "fr") -> list[str]:
-    """Rend une liste de Fact en liste de phrases (ordre préservé)."""
-    out: list[str] = []
-    for fact in facts:
-        phrase = render_fact(fact, lang)
-        phrase = re.sub(r"\s+", " ", phrase).strip()
-        if phrase:
-            out.append(phrase)
-    return out
-
-
-def extract_numbers(text: str) -> list[str]:
-    """Extrait les nombres (décimaux ou entiers) présents dans une phrase.
-
-    Utilisé par le test de traçabilité : chaque nombre remonté en synthèse
-    doit être présent dans le JSON d'entrée.
-    """
-    return re.findall(r"\d+(?:[.,]\d+)?", text)
+import picarones.measurements.narrative.renderer as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/ner.py

@@ -1,309 +1,19 @@
-"""Calcul des métriques de précision sur entités nommées (NER).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.ner`.
 
-Sprint 38 — A.II.1.a du plan d'évolution 2026 : couche de calcul pure.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.ner import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-Pour un médiéviste, un archiviste ou un économiste-historien,
-l'utilité aval d'un OCR ne se mesure pas seulement au CER ; ce qui
-compte c'est de savoir si les **entités nommées** (personnes, lieux,
-dates, organisations) ont survécu à la transcription.  Un CER de 5 %
-qui rate 80 % des noms propres est inutilisable pour l'indexation
-prosopographique.
-
-Stratégie de découpage en sprints
----------------------------------
-Comme pour la divergence taxonomique (Sprints 35-37), on découpe :
-
-- **Sprint 38** (ici) — couche de calcul pure : alignement IoU entre
-  deux listes d'entités, calcul de Precision/Recall/F1 par catégorie
-  et global, détection des hallucinations d'entité.  Aucune dépendance
-  externe (pas de spaCy, pas de Stanza) ; les listes d'entités sont
-  fournies en entrée.  Un test de l'enregistrement dans le registre
-  typé Sprint 34 garantit l'intégration.
-- **Sprint à venir** — backend extracteur (spaCy / Stanza / HIPE) et
-  câblage runner+narratif+HTML.
-
-Format des entités
-------------------
-Compatible avec ``EntitiesGT`` du Sprint 32 — chaque entité est un
-dictionnaire ``{"label": str, "start": int, "end": int, "text": str}``
-où ``start``/``end`` sont des offsets caractère.
-
-Convention d'alignement
------------------------
-Une entité hypothèse "matche" une entité de référence si :
-
-1. les **labels sont identiques** (case-insensitive),
-2. le ratio d'**Intersection-over-Union** (IoU) sur leurs spans
-   caractère est ``≥ iou_threshold`` (défaut : 0,5).
-
-Une entité de référence non matchée → faux négatif (recall pénalisé).
-Une entité hypothèse non matchée → faux positif (précision pénalisée).
-Un faux positif est aussi compté comme **hallucination d'entité**, ce
-qui est utile pour les VLM/LLM qui inventent.
-
-Limites
--------
-- L'alignement bag-of-spans : une entité peut être matchée par au plus
-  une entité de l'autre côté (sinon double-comptage).
-- Les modèles NER (spaCy, etc.) hallucinent eux-mêmes.  La métrique
-  mesure conjointement OCR + NER.  Documenter explicitement.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-from dataclasses import dataclass
-from typing import Iterable
-
-from picarones.core.metric_registry import register_metric
-from picarones.core.modules import ArtifactType
-
-logger = logging.getLogger(__name__)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Modèle de données
-# ──────────────────────────────────────────────────────────────────────────
-
-
-@dataclass(frozen=True)
-class Entity:
-    """Entité nommée alignée sur un texte.
-
-    Attributs
-    ---------
-    label:
-        Catégorie de l'entité (ex. ``"PER"``, ``"LOC"``, ``"DATE"``).
-        La comparaison se fait en *case-insensitive*.
-    start, end:
-        Offsets caractère (inclus, exclu) sur le texte de référence.
-    text:
-        Forme de surface — informative, **non utilisée pour
-        l'alignement** (deux entités peuvent matcher même si leur
-        forme de surface diffère, du moment que leurs spans
-        chevauchent suffisamment).
-    """
-
-    label: str
-    start: int
-    end: int
-    text: str = ""
-
-    def __post_init__(self) -> None:
-        if self.start > self.end:
-            raise ValueError(
-                f"Entity span invalide : start={self.start} > end={self.end}"
-            )
-
-    @property
-    def length(self) -> int:
-        return max(0, self.end - self.start)
-
-
-def _to_entity(obj: Entity | dict) -> Entity:
-    """Coerce un dict (format EntitiesGT) en ``Entity``."""
-    if isinstance(obj, Entity):
-        return obj
-    return Entity(
-        label=str(obj["label"]),
-        start=int(obj["start"]),
-        end=int(obj["end"]),
-        text=str(obj.get("text", "")),
-    )
-
-
-# ────────────────────────────────────────────────────────────��─────────────
-# Alignement par IoU
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def _iou(a: Entity, b: Entity) -> float:
-    """Intersection-over-Union sur les spans caractère."""
-    inter_start = max(a.start, b.start)
-    inter_end = min(a.end, b.end)
-    inter = max(0, inter_end - inter_start)
-    union = a.length + b.length - inter
-    if union <= 0:
-        return 0.0
-    return inter / union
-
-
-def _align(
-    references: list[Entity],
-    hypotheses: list[Entity],
-    iou_threshold: float,
-) -> tuple[list[tuple[int, int, float]], set[int], set[int]]:
-    """Aligne deux listes d'entités par IoU décroissant (greedy).
-
-    Returns
-    -------
-    matches:
-        Liste de triplets ``(idx_ref, idx_hyp, iou)`` triés par IoU
-        décroissant — chaque entité n'apparaît qu'une fois.
-    unmatched_refs:
-        Indices des entités GT non matchées (faux négatifs).
-    unmatched_hyps:
-        Indices des entités hypothèse non matchées (faux positifs).
-    """
-    candidates: list[tuple[float, int, int]] = []
-    for i, r in enumerate(references):
-        for j, h in enumerate(hypotheses):
-            if r.label.casefold() != h.label.casefold():
-                continue
-            score = _iou(r, h)
-            if score >= iou_threshold:
-                candidates.append((score, i, j))
-
-    # Tri par IoU décroissant ; à IoU égale, on prend l'ordre des paires
-    # pour garantir un tri stable et déterministe.
-    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 score, 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, score))
-
-    unmatched_refs = set(range(len(references))) - matched_refs
-    unmatched_hyps = set(range(len(hypotheses))) - matched_hyps
-    return matches, unmatched_refs, unmatched_hyps
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Calcul des métriques
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def _prf(tp: int, fp: int, fn: int) -> dict[str, float]:
-    """Précision / rappel / F1 à partir des comptes."""
-    precision = tp / (tp + fp) if (tp + fp) > 0 else 0.0
-    recall = tp / (tp + fn) if (tp + fn) > 0 else 0.0
-    f1 = (
-        2 * precision * recall / (precision + recall)
-        if (precision + recall) > 0
-        else 0.0
-    )
-    return {
-        "precision": precision,
-        "recall": recall,
-        "f1": f1,
-        "support": tp + fn,
-    }
-
-
-def compute_ner_metrics(
-    reference_entities: Iterable[Entity | dict],
-    hypothesis_entities: Iterable[Entity | dict],
-    iou_threshold: float = 0.5,
-) -> dict:
-    """Calcule la précision/rappel/F1 sur entités nommées.
-
-    Parameters
-    ----------
-    reference_entities:
-        Liste d'entités GT (format ``Entity`` ou dict de
-        ``EntitiesGT``).
-    hypothesis_entities:
-        Liste d'entités produites par le NER sur la sortie OCR.
-    iou_threshold:
-        Seuil de chevauchement caractère pour qu'un appariement
-        soit valide (défaut : 0,5 — convention CoNLL/HIPE).
-
-    Returns
-    -------
-    dict
-        ``{
-            "global": {"precision", "recall", "f1", "support"},
-            "per_category": {label: {"precision", ...}},
-            "true_positives": int,
-            "false_positives": int,
-            "false_negatives": int,
-            "hallucinated_entities": list[dict],   # entités OCR sans GT
-            "missed_entities":       list[dict],   # entités GT non détectées
-            "iou_threshold": float,
-        }``
-    """
-    refs = [_to_entity(e) for e in reference_entities]
-    hyps = [_to_entity(e) for e in hypothesis_entities]
-
-    matches, unmatched_refs, unmatched_hyps = _align(refs, hyps, iou_threshold)
-
-    tp = len(matches)
-    fn = len(unmatched_refs)
-    fp = len(unmatched_hyps)
-
-    # Comptes par catégorie
-    cat_tp: dict[str, int] = {}
-    cat_fn: dict[str, int] = {}
-    cat_fp: dict[str, int] = {}
-    for i, _j, _score in matches:
-        cat = refs[i].label
-        cat_tp[cat] = cat_tp.get(cat, 0) + 1
-    for i in unmatched_refs:
-        cat = refs[i].label
-        cat_fn[cat] = cat_fn.get(cat, 0) + 1
-    for j in unmatched_hyps:
-        cat = hyps[j].label
-        cat_fp[cat] = cat_fp.get(cat, 0) + 1
-
-    all_categories = sorted(set(cat_tp) | set(cat_fn) | set(cat_fp))
-    per_category = {
-        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_category": per_category,
-        "true_positives": tp,
-        "false_positives": fp,
-        "false_negatives": fn,
-        "hallucinated_entities": [
-            {"label": hyps[j].label, "start": hyps[j].start,
-             "end": hyps[j].end, "text": hyps[j].text}
-            for j in sorted(unmatched_hyps)
-        ],
-        "missed_entities": [
-            {"label": refs[i].label, "start": refs[i].start,
-             "end": refs[i].end, "text": refs[i].text}
-            for i in sorted(unmatched_refs)
-        ],
-        "iou_threshold": iou_threshold,
-    }
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Enregistrement dans le registre typé (Sprint 34)
-# ──────────────────────────────────────────────────────────────────────────
-
-
-@register_metric(
-    name="ner_f1",
-    input_types=(ArtifactType.ENTITIES, ArtifactType.ENTITIES),
-    description=(
-        "F1 global sur les entités nommées (alignement IoU ≥ 0,5, "
-        "labels case-insensitive). Pour le détail par catégorie, "
-        "utiliser compute_ner_metrics directement."
-    ),
-    higher_is_better=True,
-    tags={"downstream", "ner", "structure"},
-)
-def ner_f1(
-    reference_entities: Iterable[Entity | dict],
-    hypothesis_entities: Iterable[Entity | dict],
-) -> float:
-    """F1 global ; raccourci enregistré pour les jonctions ``(ENTITIES, ENTITIES)``."""
-    return compute_ner_metrics(reference_entities, hypothesis_entities)["global"]["f1"]
-
+from picarones.measurements.ner import *  # noqa: F401, F403
 
-__all__ = [
-    "Entity",
-    "compute_ner_metrics",
-    "ner_f1",
-]
+import picarones.measurements.ner as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/ner_backends.py

@@ -1,227 +1,19 @@
-"""Backends d'extraction d'entités nommées (Sprint 40).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.ner_backends`.
 
-Suite directe du Sprint 38 : la couche de calcul (`compute_ner_metrics`)
-prend deux listes d'entités, ce module fournit le moyen d'**obtenir** la
-liste d'entités d'un côté à partir d'un texte (généralement la sortie
-OCR du moteur).
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.ner_backends import ...``) de continuer
+à fonctionner sans modification.
 
-Architecture
-------------
-- ``EntityExtractor`` : Protocol Python qui décrit l'interface ; tout
-  callable ``(text: str) -> list[dict]`` est un extracteur valide.  Le
-  format de sortie est compatible ``EntitiesGT`` (Sprint 32) et
-  ``compute_ner_metrics`` (Sprint 38).
-- ``SpacyEntityExtractor`` : implémentation par défaut, lazy-import de
-  spaCy.  Si spaCy n'est pas installé OU si le modèle n'est pas
-  téléchargé, retourne ``[]`` avec un ``logger.warning`` explicite
-  (cf. règle CLAUDE.md : pas de ``except: pass``).
-- ``SPACY_PROFILES`` : dict de profils nommés vers noms de modèles
-  spaCy (FR, EN, multilingue, HIPE pour les corpus historiques).
-- ``get_extractor(profile)`` : factory qui retourne l'extracteur
-  correspondant au profil demandé.
-
-Découplage runner ↔ backend
----------------------------
-Le runner reçoit un ``EntityExtractor`` en paramètre — il n'importe
-**jamais** spaCy directement.  Cela permet :
-
-1. de **tester** sans dépendance externe (le test injecte un callable
-   qui simule l'extraction) ;
-2. de **brancher** des backends alternatifs (Stanza, HIPE custom,
-   modèle fine-tuné maison) sans modifier le runner ;
-3. de **désactiver** la métrique en passant ``None`` — comportement
-   par défaut, rétrocompat stricte.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-from typing import Any, Protocol
-
-logger = logging.getLogger(__name__)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Interface
-# ──────────────────────────────────────────────────────────────────────────
-
-
-class EntityExtractor(Protocol):
-    """Tout callable ``(text) -> list[dict]`` est un extracteur valide.
-
-    Format de sortie attendu : liste de dicts
-    ``{"label": str, "start": int, "end": int, "text": str}``
-    compatibles avec ``compute_ner_metrics`` (Sprint 38) et
-    ``EntitiesGT`` (Sprint 32).
-    """
-
-    def __call__(self, text: str) -> list[dict[str, Any]]: ...
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Profils spaCy nommés
-# ──────────────────────────────────────────────────────────────────────────
-
-
-SPACY_PROFILES: dict[str, str] = {
-    "fr": "fr_core_news_sm",
-    "fr_lg": "fr_core_news_lg",
-    "en": "en_core_web_sm",
-    "en_lg": "en_core_web_lg",
-    "multilingual": "xx_ent_wiki_sm",
-    # HIPE 2022 — modèle historique multilingue (Hugging Face).  Pas
-    # toujours disponible via ``spacy.load`` direct ; documenté pour
-    # mémoire, l'utilisateur peut le wrapper dans un EntityExtractor
-    # custom si besoin.
-    "hipe": "fr_core_news_lg",
-}
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Backend spaCy
-# ──────────────────────────────────────────────────────────────────────────
-
-
-class SpacyEntityExtractor:
-    """Extracteur d'entités basé sur spaCy.
-
-    Lazy-import : ``spacy`` n'est importé qu'au premier appel.  Le
-    modèle est chargé une seule fois et mis en cache sur l'instance.
-
-    Si spaCy n'est pas installé OU si le modèle demandé n'est pas
-    téléchargé, l'extracteur tombe en mode dégradé (retourne ``[]``
-    pour chaque appel) et émet un ``logger.warning`` au premier
-    appel.
-
-    Parameters
-    ----------
-    model_name:
-        Nom du modèle spaCy à charger (ex. ``"fr_core_news_sm"``).
-    label_mapping:
-        Dict optionnel ``{spacy_label: target_label}`` pour
-        normaliser les labels (ex. spaCy utilise ``"PERSON"``,
-        on veut ``"PER"``).  Si ``None``, garde les labels tels
-        quels.
-
-    Examples
-    --------
-    >>> extractor = SpacyEntityExtractor("fr_core_news_sm")
-    >>> entities = extractor("Marie de Bourgogne, en 1477.")
-    >>> # liste de dicts {label, start, end, text}, ou [] si spaCy absent
-    """
-
-    # Mapping par défaut spaCy → conventions HIPE/CoNLL courtes
-    DEFAULT_LABEL_MAPPING: dict[str, str] = {
-        "PERSON": "PER",
-        "PER": "PER",
-        "LOC": "LOC",
-        "GPE": "LOC",       # Geo-Political Entity → LOC
-        "ORG": "ORG",
-        "DATE": "DATE",
-        "TIME": "DATE",
-        "MISC": "MISC",
-    }
-
-    def __init__(
-        self,
-        model_name: str = "fr_core_news_sm",
-        label_mapping: dict[str, str] | None = None,
-    ) -> None:
-        self.model_name = model_name
-        self.label_mapping = (
-            dict(label_mapping)
-            if label_mapping is not None
-            else dict(self.DEFAULT_LABEL_MAPPING)
-        )
-        self._nlp: Any | None = None
-        self._loaded: bool = False
-        self._available: bool = False
-
-    def _load(self) -> None:
-        """Charge spaCy + modèle au premier appel.  Idempotent."""
-        if self._loaded:
-            return
-        self._loaded = True
-        try:
-            import spacy  # type: ignore[import-untyped]
-        except ImportError as exc:
-            logger.warning(
-                "[ner_backends] spaCy non installé (%s) — extraction NER "
-                "désactivée. Installer avec `pip install picarones[ner]`.",
-                exc,
-            )
-            return
-        try:
-            self._nlp = spacy.load(self.model_name)
-            self._available = True
-        except OSError as exc:
-            logger.warning(
-                "[ner_backends] Modèle spaCy %r introuvable (%s) — extraction "
-                "NER désactivée. Télécharger avec `python -m spacy download %s`.",
-                self.model_name, exc, self.model_name,
-            )
-
-    @property
-    def available(self) -> bool:
-        """``True`` si spaCy + le modèle sont chargés et utilisables."""
-        if not self._loaded:
-            self._load()
-        return self._available
-
-    def __call__(self, text: str) -> list[dict[str, Any]]:
-        if not text:
-            return []
-        if not self.available or self._nlp is None:
-            return []
-        doc = self._nlp(text)
-        results: list[dict[str, Any]] = []
-        for ent in doc.ents:
-            label = self.label_mapping.get(ent.label_, ent.label_)
-            results.append({
-                "label": label,
-                "start": int(ent.start_char),
-                "end": int(ent.end_char),
-                "text": ent.text,
-            })
-        return results
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Factory
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def get_extractor(profile: str = "fr") -> SpacyEntityExtractor:
-    """Retourne un extracteur spaCy pour le profil demandé.
-
-    Le profil peut être :
-
-    - une clé de ``SPACY_PROFILES`` (ex. ``"fr"``, ``"en"``,
-      ``"multilingual"``)
-    - un nom de modèle spaCy direct (ex. ``"fr_core_news_lg"``)
-
-    L'extracteur est instancié paresseusement (le modèle n'est chargé
-    qu'au premier appel).  Si le modèle n'est pas disponible,
-    l'extracteur tombe en mode dégradé silencieux (retourne ``[]``).
-    """
-    model_name = SPACY_PROFILES.get(profile, profile)
-    return SpacyEntityExtractor(model_name=model_name)
-
-
-def is_spacy_available() -> bool:
-    """``True`` si la librairie ``spacy`` est importable, sans charger
-    de modèle."""
-    try:
-        import spacy  # noqa: F401
-    except ImportError:
-        return False
-    return True
-
+from picarones.measurements.ner_backends import *  # noqa: F401, F403
 
-__all__ = [
-    "EntityExtractor",
-    "SpacyEntityExtractor",
-    "SPACY_PROFILES",
-    "get_extractor",
-    "is_spacy_available",
-]
+import picarones.measurements.ner_backends as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/normalization.py

@@ -1,420 +1,19 @@
-"""Profils de normalisation unicode pour le calcul du CER diplomatique.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.normalization`.
 
-La normalisation diplomatique permet de calculer un CER tenant compte des
-équivalences graphiques propres aux documents historiques : ſ=s, u=v, i=j, etc.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.normalization import ...``) de continuer
+à fonctionner sans modification.
 
-En appliquant la même table aux deux textes (GT et OCR), on mesure les erreurs
-"substantielles" (transcription erronée) en ignorant les variations graphiques
-codifiées connues.
-
-Trois niveaux de normalisation sont disponibles :
-
-1. NFC       : normalisation Unicode canonique (décomposition+recomposition)
-2. caseless  : NFC + pliage de casse (casefold)
-3. diplomatic: NFC + table de correspondances historiques configurables
-
-Les profils préconfigurés couvrent les cas d'usage patrimoniaux courants.
-Ils sont également chargeables depuis un fichier YAML.
-
-Exemple YAML
-------------
-name: medieval_custom
-caseless: false
-diplomatic:
-  ſ: s
-  u: v
-  i: j
-  y: i
-  æ: ae
-  œ: oe
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import unicodedata
-from dataclasses import dataclass, field
-from pathlib import Path
-
-
-# ---------------------------------------------------------------------------
-# Tables de correspondances diplomatiques préconfigurées
-# ---------------------------------------------------------------------------
-
-#: Français médiéval (XIIe–XVe siècle)
-DIPLOMATIC_FR_MEDIEVAL: dict[str, str] = {
-    "ſ": "s",    # s long → s
-    "u": "v",    # u/v interchangeables en position initiale
-    "i": "j",    # i/j interchangeables
-    "y": "i",    # y vocalique → i
-    "æ": "ae",   # ligature æ
-    "œ": "oe",   # ligature œ
-    "ꝑ": "per",  # abréviation per/par
-    "ꝓ": "pro",  # abréviation pro
-    "\u0026": "et",  # & → et
-}
-
-#: Français moderne / imprimés anciens (XVIe–XVIIIe siècle)
-DIPLOMATIC_FR_EARLY_MODERN: dict[str, str] = {
-    "ſ": "s",    # s long
-    "æ": "ae",
-    "œ": "oe",
-    "\u0026": "et",
-    "ỹ": "yn",   # y tilde
-}
-
-#: Latin médiéval
-DIPLOMATIC_LATIN_MEDIEVAL: dict[str, str] = {
-    "ſ": "s",
-    "u": "v",
-    "i": "j",
-    "y": "i",
-    "æ": "ae",
-    "œ": "oe",
-    "ꝑ": "per",
-    "ꝓ": "pro",
-    "ꝗ": "que",   # q barré → que
-    "\u0026": "et",
-}
-
-#: Profil minimal — uniquement NFC + s long
-DIPLOMATIC_MINIMAL: dict[str, str] = {
-    "ſ": "s",
-}
-
-#: Anglais moderne / imprimés anciens (XVIe–XVIIIe siècle)
-#: Orthographe «early modern»  : ſ=s, u/v, i/j, vv=w, þ=th, ð=th, ȝ=y
-DIPLOMATIC_EN_EARLY_MODERN: dict[str, str] = {
-    "ſ": "s",     # s long → s
-    "u": "v",     # u/v interchangeables (vpon → upon)
-    "i": "j",     # i/j interchangeables (ioy → joy)
-    "vv": "w",    # vv → w (vvhich → which)
-    "þ": "th",    # thorn → th
-    "ð": "th",    # eth → th
-    "ȝ": "y",     # yogh → y
-    "æ": "ae",    # ligature æ
-    "œ": "oe",    # ligature œ
-    "\u0026": "and",  # & → and
-}
-
-#: Anglais médiéval (XIIe–XVe siècle) — abréviations manuscrites incluses
-DIPLOMATIC_EN_MEDIEVAL: dict[str, str] = {
-    "ſ": "s",
-    "u": "v",
-    "i": "j",
-    "vv": "w",
-    "þ": "th",
-    "ð": "th",
-    "ȝ": "y",
-    "æ": "ae",
-    "œ": "oe",
-    "\u0026": "and",
-    # Abréviations courantes dans les manuscrits anglais médiévaux
-    "ꝑ": "per",   # p barré → per/par
-    "ꝓ": "pro",   # p crocheté → pro
-    "ꝗ": "que",   # q barré → que
-    "\ua75b": "r", # lettre r rotunda → r
-}
-
-#: Écriture secrétaire (XVIe–XVIIe siècle) — secretary hand
-#: Confusions visuelles propres à l'écriture cursive anglaise
-DIPLOMATIC_EN_SECRETARY: dict[str, str] = {
-    "ſ": "s",
-    "u": "v",
-    "i": "j",
-    "vv": "w",
-    "þ": "th",
-    "ð": "th",
-    "ȝ": "y",
-    "\u0026": "and",
-    # Confusions visuelles typiques : e/c, n/u, m/w en secrétaire
-    # Note : ne pas normaliser e/c automatiquement (trop agressif) ;
-    # on se limite aux substituts graphiques historiquement documentés
-}
-
-
-# ---------------------------------------------------------------------------
-# Profil de normalisation
-# ---------------------------------------------------------------------------
-
-@dataclass
-class NormalizationProfile:
-    """Décrit une stratégie de normalisation pour le calcul du CER diplomatique.
-
-    Parameters
-    ----------
-    name:
-        Identifiant lisible du profil (ex : ``"medieval_french"``).
-    nfc:
-        Applique la normalisation Unicode NFC (recommandé, activé par défaut).
-    caseless:
-        Pliage de casse (casefold) après NFC.
-    diplomatic_table:
-        Table de correspondances graphiques historiques appliquée caractère
-        par caractère sur les deux textes avant calcul du CER.
-    exclude_chars:
-        Ensemble de caractères supprimés des deux textes (GT et OCR) avant
-        tout calcul de métriques (CER, WER, MER, WIL et CER diplomatique).
-        Utile pour ignorer la ponctuation ou les apostrophes.
-    description:
-        Description courte du profil (affichée dans le rapport HTML).
-    """
-
-    name: str
-    nfc: bool = True
-    caseless: bool = False
-    diplomatic_table: dict[str, str] = field(default_factory=dict)
-    exclude_chars: frozenset = field(default_factory=frozenset)
-    description: str = ""
-
-    def normalize(self, text: str) -> str:
-        """Applique le profil de normalisation à un texte."""
-        if self.exclude_chars:
-            text = "".join(c for c in text if c not in self.exclude_chars)
-        if self.nfc:
-            text = unicodedata.normalize("NFC", text)
-        if self.caseless:
-            text = text.casefold()
-        if self.diplomatic_table:
-            text = _apply_diplomatic_table(text, self.diplomatic_table)
-        return text
-
-    def as_dict(self) -> dict:
-        return {
-            "name": self.name,
-            "nfc": self.nfc,
-            "caseless": self.caseless,
-            "diplomatic_table": self.diplomatic_table,
-            "exclude_chars": sorted(self.exclude_chars),
-            "description": self.description,
-        }
-
-    @classmethod
-    def from_yaml(cls, path: str | Path) -> "NormalizationProfile":
-        """Charge un profil depuis un fichier YAML.
-
-        Le fichier YAML doit contenir les clés ``name``, optionnellement
-        ``caseless``, ``description``, ``diplomatic`` (dict str→str) et
-        ``exclude_chars`` (liste ou chaîne de caractères à ignorer).
-
-        Example
-        -------
-        .. code-block:: yaml
-
-            name: medieval_custom
-            caseless: false
-            description: Français médiéval personnalisé
-            exclude_chars: ".,;:!?"
-            diplomatic:
-              ſ: s
-              u: v
-        """
-        try:
-            import yaml
-        except ImportError as exc:
-            raise RuntimeError(
-                "Le package 'pyyaml' est requis pour charger les profils YAML. "
-                "Installez-le avec : pip install pyyaml"
-            ) from exc
-
-        data = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
-        return cls(
-            name=data.get("name", Path(path).stem),
-            nfc=bool(data.get("nfc", True)),
-            caseless=bool(data.get("caseless", False)),
-            diplomatic_table=data.get("diplomatic", {}),
-            exclude_chars=_parse_exclude_chars(data.get("exclude_chars", "")),
-            description=data.get("description", ""),
-        )
-
-    @classmethod
-    def from_dict(cls, data: dict) -> "NormalizationProfile":
-        """Charge un profil depuis un dictionnaire (ex : section YAML inline)."""
-        return cls(
-            name=data.get("name", "custom"),
-            nfc=bool(data.get("nfc", True)),
-            caseless=bool(data.get("caseless", False)),
-            diplomatic_table=data.get("diplomatic", {}),
-            exclude_chars=_parse_exclude_chars(data.get("exclude_chars", "")),
-            description=data.get("description", ""),
-        )
-
-
-# ---------------------------------------------------------------------------
-# Profils préconfigurés
-# ---------------------------------------------------------------------------
-
-NORMALIZATION_PROFILES: dict[str, NormalizationProfile] = {
-    "nfc": NormalizationProfile(
-        name="nfc",
-        nfc=True,
-        caseless=False,
-        diplomatic_table={},
-        description="Normalisation NFC uniquement",
-    ),
-    "caseless": NormalizationProfile(
-        name="caseless",
-        nfc=True,
-        caseless=True,
-        diplomatic_table={},
-        description="NFC + insensible à la casse",
-    ),
-    "minimal": NormalizationProfile(
-        name="minimal",
-        nfc=True,
-        caseless=False,
-        diplomatic_table=DIPLOMATIC_MINIMAL,
-        description="Minimal : NFC + s long seulement",
-    ),
-    "medieval_french": NormalizationProfile(
-        name="medieval_french",
-        nfc=True,
-        caseless=False,
-        diplomatic_table=DIPLOMATIC_FR_MEDIEVAL,
-        description="Français médiéval (XIIe–XVe) : ſ=s, u=v, i=j, æ=ae, œ=oe",
-    ),
-    "early_modern_french": NormalizationProfile(
-        name="early_modern_french",
-        nfc=True,
-        caseless=False,
-        diplomatic_table=DIPLOMATIC_FR_EARLY_MODERN,
-        description="Imprimés anciens (XVIe–XVIIIe) : ſ=s, æ=ae, œ=oe",
-    ),
-    "medieval_latin": NormalizationProfile(
-        name="medieval_latin",
-        nfc=True,
-        caseless=False,
-        diplomatic_table=DIPLOMATIC_LATIN_MEDIEVAL,
-        description="Latin médiéval : ſ=s, u=v, i=j, ꝑ=per, ꝓ=pro",
-    ),
-    "early_modern_english": NormalizationProfile(
-        name="early_modern_english",
-        nfc=True,
-        caseless=False,
-        diplomatic_table=DIPLOMATIC_EN_EARLY_MODERN,
-        description="Early Modern English (XVIth–XVIIIth c.): ſ=s, u=v, i=j, vv=w, þ=th, ð=th, ȝ=y",
-    ),
-    "medieval_english": NormalizationProfile(
-        name="medieval_english",
-        nfc=True,
-        caseless=False,
-        diplomatic_table=DIPLOMATIC_EN_MEDIEVAL,
-        description="Medieval English (XIIth–XVth c.): ſ=s, u=v, i=j, þ=th, ȝ=y, ꝑ=per, ꝓ=pro",
-    ),
-    "secretary_hand": NormalizationProfile(
-        name="secretary_hand",
-        nfc=True,
-        caseless=False,
-        diplomatic_table=DIPLOMATIC_EN_SECRETARY,
-        description="Secretary hand (XVIth–XVIIth c.): ſ=s, u=v, i=j, vv=w, þ=th, ð=th, ȝ=y",
-    ),
-    # ── Profils d'exclusion de caractères ────────────────────────────────
-    "sans_ponctuation": NormalizationProfile(
-        name="sans_ponctuation",
-        nfc=True,
-        caseless=False,
-        diplomatic_table={},
-        exclude_chars=frozenset(". , ; : ! ? ' \u2019 \" - \u2013 \u2014 ( ) [ ]".split()),
-        description="NFC + suppression de la ponctuation courante : . , ; : ! ? ' \" - – — ( ) [ ]",
-    ),
-    "sans_apostrophes": NormalizationProfile(
-        name="sans_apostrophes",
-        nfc=True,
-        caseless=False,
-        diplomatic_table={},
-        exclude_chars=frozenset(["'", "\u2019"]),  # apostrophe droite + apostrophe typographique
-        description="NFC + suppression des apostrophes droite (') et typographique (\u2019)",
-    ),
-}
-
-
-def get_builtin_profile(name: str) -> NormalizationProfile:
-    """Retourne un profil préconfigurée par son identifiant.
-
-    Identifiants disponibles
-    ------------------------
-    - ``"medieval_french"``      : français médiéval XIIe–XVe (ſ=s, u=v, i=j, æ=ae, œ=oe…)
-    - ``"early_modern_french"``  : imprimés anciens XVIe–XVIIIe (ſ=s, œ=oe, æ=ae…)
-    - ``"medieval_latin"``       : latin médiéval (ſ=s, u=v, i=j, ꝑ=per, ꝓ=pro…)
-    - ``"early_modern_english"`` : anglais imprimé XVIe–XVIIIe (ſ=s, u=v, i=j, vv=w, þ=th, ð=th, ȝ=y)
-    - ``"medieval_english"``     : anglais manuscrit XIIe–XVe (+ abréviations ꝑ, ꝓ…)
-    - ``"secretary_hand"``       : écriture secrétaire anglaise XVIe–XVIIe (cursive administrative)
-    - ``"minimal"``              : uniquement NFC + s long
-    - ``"nfc"``                  : NFC seul (sans table diplomatique)
-    - ``"caseless"``             : NFC + pliage de casse
-
-    Raises
-    ------
-    KeyError
-        Si le nom n'est pas reconnu.
-    """
-    if name not in NORMALIZATION_PROFILES:
-        raise KeyError(
-            f"Profil de normalisation inconnu : '{name}'. "
-            f"Disponibles : {', '.join(NORMALIZATION_PROFILES)}"
-        )
-    return NORMALIZATION_PROFILES[name]
-
-
-# ---------------------------------------------------------------------------
-# Fonctions utilitaires
-# ---------------------------------------------------------------------------
-
-def _parse_exclude_chars(value: "str | list | None") -> frozenset:
-    """Convertit une liste de caractères (str ou list) en frozenset.
-
-    Accepte :
-    - Une chaîne de caractères séparés par une virgule+espace (ex. ``"', -, –"``)
-      ou simplement concaténés sans séparateur (ex. ``".,;:!?"``)
-    - Une liste Python/YAML de chaînes (chacune un caractère)
-    - None ou chaîne vide → frozenset vide
-
-    Règle de désambiguïsation : si la chaîne contient la séquence ``", "``
-    (virgule suivie d'un espace), on découpe par ``", "``. Sinon, chaque
-    caractère Unicode est un item distinct.
-    """
-    if not value:
-        return frozenset()
-    if isinstance(value, (list, tuple)):
-        return frozenset(str(c) for c in value if c)
-    raw = str(value)
-    # Désambiguïsation : séparer par ", " si présent (format lisible)
-    if ", " in raw:
-        return frozenset(c.strip() for c in raw.split(",") if c.strip())
-    # Sinon, chaque caractère Unicode est un item distinct
-    return frozenset(raw)
-
-
-def _apply_diplomatic_table(text: str, table: dict[str, str]) -> str:
-    """Applique une table de correspondances diplomatiques en un seul pass.
-
-    Les clés multi-caractères (ex : ``"ae"`` → ``"æ"``) sont gérées en priorité
-    sur les correspondances simples. Le remplacement est fait en un seul pass
-    via regex pour éviter les remplacements en cascade (ex : ``"ſ"→"s"`` puis
-    ``"s"→"z"`` donnerait ``"z"`` au lieu de ``"s"``).
-    """
-    if not table:
-        return text
-
-    import re
-
-    # Séparer les clés simples (1 char) des clés multi-chars
-    multi_keys = sorted(
-        (k for k in table if len(k) > 1), key=len, reverse=True
-    )
-    simple_table = {k: v for k, v in table.items() if len(k) == 1}
-
-    if multi_keys:
-        # Single-pass : construire un pattern regex avec toutes les clés multi-chars
-        # triées par longueur décroissante pour matcher les plus longues d'abord
-        pattern = re.compile("|".join(re.escape(k) for k in multi_keys))
-        text = pattern.sub(lambda m: table[m.group(0)], text)
-
-    # Remplacements char par char (single-pass via itération)
-    if simple_table:
-        text = "".join(simple_table.get(c, c) for c in text)
-
-    return text
-
+from picarones.measurements.normalization import *  # noqa: F401, F403
 
-# Profil par défaut utilisé pour le CER diplomatique intégré
-DEFAULT_DIPLOMATIC_PROFILE: NormalizationProfile = get_builtin_profile("medieval_french")
+import picarones.measurements.normalization as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/numerical_sequences.py

@@ -1,422 +1,19 @@
-"""Précision sur séquences numériques — Sprint 85 (A.II.5b).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.numerical_sequences`.
 
-Sprint 85 — A.II.5b du plan d'évolution 2026.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.numerical_sequences import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-Pour un économiste-historien, un éditeur de chartes ou un
-archiviste, la **fidélité aux séquences numériques** est un
-proxy direct de la qualité éditoriale.  Un OCR qui rate
-*« 1789 »* dans une charte révolutionnaire ou *« f. 12v »*
-dans une cote d'archives produit un corpus inutilisable pour la
-recherche fine, même si le CER global est respectable.
-
-Catégories couvertes
---------------------
-1. **Dates arabes** : ``1789``, ``1450``, ``1ᵉʳ janvier 1789``
-   (le module détecte les **années** sur 4 chiffres dans la
-   plage [1000-2099]).
-2. **Numéraux romains** : ``MDCLXVIII``, ``XIV``, ``Tome IV``.
-   Réutilise ``picarones.core.roman_numerals`` (Sprint 60).
-3. **Foliotation** : ``f. 12``, ``f. 12r``, ``fol. 24v``,
-   ``p. 5``, ``pp. 12-15``, ``n° 42``.
-4. **Montants** : ``12 livres``, ``5 sols``, ``8 deniers``,
-   ``100 £``, ``50 ₣``, ``20 €``, formes Ancien Régime
-   (``l.``, ``s.``, ``d.``).
-5. **Années régnales** : ``an III``, ``l'an V``, ``an de
-   grâce 1450``, ``an de la République``.
-
-Méthode
--------
-Pour chaque catégorie, on extrait les occurrences (regex
-spécialisée) en GT et en hypothèse.  On classe ensuite chaque
-GT en **3 statuts** :
-
-- ``strict_preserved`` : forme exacte présente dans
-  l'hypothèse (sensible à la casse seulement pour la
-  foliotation, sinon la convention est documentée par
-  catégorie) ;
-- ``value_preserved`` : la **valeur** apparaît même si la
-  forme diffère (ex. ``XIV`` GT et ``14`` hypothèse —
-  considéré comme valeur préservée mais forme non) ;
-- ``lost`` : aucune trace exploitable.
-
-Sortie
-------
-``compute_numerical_sequence_metrics(reference, hypothesis)``
-retourne :
-
-```
-{
-    "global_strict_score": float,        # ∈ [0, 1]
-    "global_value_score": float,         # ∈ [0, 1]
-    "n_total": int,
-    "per_category": {
-        "year": {"n_total": int, "strict": int, "value": int,
-                 "strict_score": float, "value_score": float,
-                 "lost_items": list[str]},
-        "roman": {...},
-        "foliation": {...},
-        "currency": {...},
-        "regnal": {...},
-    },
-}
-```
-
-Limites
--------
-- Les regex sont **conservatrices** : on rate quelques
-  formes rares plutôt que de produire des faux positifs (par
-  exemple, ``mil cinq cens`` en français médiéval n'est pas
-  détecté comme année — la couche calcul s'en tient aux
-  formes les plus reconnaissables).  Pour un corpus
-  spécifique, l'utilisateur peut composer ses propres
-  détecteurs et les passer via ``custom_detectors``.
-- ``value_preserved`` exige une équivalence de **valeur
-  numérique** : ``XIV`` ↔ ``14`` est OK pour les romains ;
-  ``f. 12v`` ↔ ``f. 12r`` n'est **pas** OK pour la
-  foliotation (recto/verso est une information distincte).
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-import re
-from typing import Optional
-
-from picarones.core.metric_registry import register_metric
-from picarones.core.modules import ArtifactType
-from picarones.core.roman_numerals import (
-    detect_roman_numerals,
-    roman_to_int,
-)
-
-logger = logging.getLogger(__name__)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Constantes / catégories
-# ──────────────────────────────────────────────────────────────────────────
-
-
-CATEGORIES = ("year", "roman", "foliation", "currency", "regnal")
-
-
-# Dates arabes — 4 chiffres dans la plage [1000-2099].
-# On exige une frontière de mot pour ne pas attraper
-# « 12345 » (volume) ou « 0001 » (numéro de page).
-_RE_YEAR = re.compile(r"\b(1[0-9]{3}|20[0-9]{2})\b")
-
-
-# Foliotation : f. 12, f. 12r, fol. 24v, p. 5, pp. 12-15, n° 42
-# La capture conserve la forme intégrale (avec ponctuation et
-# r/v) parce que recto/verso est une information distincte.
-_RE_FOLIATION = re.compile(
-    r"\b(?:fol\.?|f\.|pp\.|p\.|n\.°|n°)\s*"  # préfixe : fol., f., pp., p., n°
-    r"(\d+(?:\s*-\s*\d+)?)"                  # nombre ou plage (12 / 12-15)
-    r"\s*([rvRV])?",                         # suffixe optionnel r/v
-    re.UNICODE,
-)
-
-
-# Montants : nombre suivi d'une unité monétaire.
-# On accepte espaces multiples mais pas de saut de ligne.
-_RE_CURRENCY = re.compile(
-    r"\b(\d+(?:[.,]\d+)?)\s*"                # montant (entier ou décimal)
-    r"(livres?|sols?|deniers?|écus?|florins?|francs?|"
-    r"l\.|s\.|d\.|£|€|₣)"                    # unité
-    r"(?=\b|[\s,;.!?:]|$)",                  # frontière souple post-symbole
-    re.UNICODE | re.IGNORECASE,
-)
-
-
-# Années régnales : « an III », « an de grâce 1450 »,
-# « l'an V de la République ».
-# Capture le numéral (romain ou arabe).
-_RE_REGNAL = re.compile(
-    r"\b(?:l['’]\s*)?an\s+(?:de\s+(?:grâce|la\s+R[eé]publique)\s+)?"
-    r"([IVXLCDMivxlcdm]+|\d{1,4})\b",
-    re.UNICODE,
-)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Détection par catégorie
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def _detect_years(text: str) -> list[tuple[str, int]]:
-    """Retourne [(forme, valeur)] pour chaque année 4 chiffres."""
-    if not text:
-        return []
-    return [(m.group(0), int(m.group(0))) for m in _RE_YEAR.finditer(text)]
-
-
-def _detect_romans_with_values(text: str) -> list[tuple[str, int]]:
-    """Numéraux romains accompagnés de leur valeur entière.
-    Délègue à ``roman_numerals.detect_roman_numerals`` (Sprint 60),
-    qui retourne ``(start, form, value)``.
-    """
-    if not text:
-        return []
-    out: list[tuple[str, int]] = []
-    for _start, form, value in detect_roman_numerals(text, min_length=2):
-        if value is not None:
-            out.append((form, value))
-    return out
-
-
-def _detect_foliations(text: str) -> list[tuple[str, str]]:
-    """Foliotation. Retourne [(forme_complète, clé_normalisée)] où la
-    clé inclut le suffixe r/v normalisé (recto/verso).
-    """
-    if not text:
-        return []
-    out: list[tuple[str, str]] = []
-    for m in _RE_FOLIATION.finditer(text):
-        full = m.group(0).strip()
-        nums = re.sub(r"\s+", "", m.group(1))  # ex : "12-15"
-        suffix = (m.group(2) or "").lower()
-        key = f"{nums}{suffix}"
-        out.append((full, key))
-    return out
-
-
-def _detect_currencies(text: str) -> list[tuple[str, tuple[str, str]]]:
-    """Montants. Clé = (montant_normalisé, unité_canonique).
-
-    L'unité canonique compresse les variantes (« livres » et
-    « livre » → « livre » ; « £ » reste « £ »).
-    """
-    if not text:
-        return []
-    canon = {
-        "livre": "livre", "livres": "livre", "l.": "livre",
-        "sol": "sol", "sols": "sol", "s.": "sol",
-        "denier": "denier", "deniers": "denier", "d.": "denier",
-        "écu": "écu", "écus": "écu",
-        "florin": "florin", "florins": "florin",
-        "franc": "franc", "francs": "franc",
-        "£": "£", "€": "€", "₣": "₣",
-    }
-    out: list[tuple[str, tuple[str, str]]] = []
-    for m in _RE_CURRENCY.finditer(text):
-        amount = m.group(1).replace(",", ".")
-        unit_raw = m.group(2).lower()
-        unit = canon.get(unit_raw, unit_raw)
-        out.append((m.group(0), (amount, unit)))
-    return out
-
-
-def _detect_regnal(text: str) -> list[tuple[str, int]]:
-    """Années régnales. Retourne [(forme, valeur_int)] avec la
-    valeur extraite (romain → int ou arabe → int).
-    """
-    if not text:
-        return []
-    out: list[tuple[str, int]] = []
-    for m in _RE_REGNAL.finditer(text):
-        numeral = m.group(1)
-        value: Optional[int]
-        if numeral.isdigit():
-            value = int(numeral)
-        else:
-            value = roman_to_int(numeral)
-        if value is not None:
-            out.append((m.group(0), value))
-    return out
-
-
-_DETECTORS = {
-    "year": _detect_years,
-    "roman": _detect_romans_with_values,
-    "foliation": _detect_foliations,
-    "currency": _detect_currencies,
-    "regnal": _detect_regnal,
-}
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Calcul principal
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def _classify_per_category(
-    gt_items: list,
-    hyp_items: list,
-    *,
-    form_extractor,
-    value_extractor,
-) -> dict:
-    """Pour chaque item GT, le classe en strict_preserved /
-    value_preserved / lost.
-
-    Multiplicité respectée : un item hypothèse ne peut servir
-    qu'à un seul match (forme prioritaire sur valeur).
-    """
-    hyp_used = [False] * len(hyp_items)
-    n_strict = 0
-    n_value = 0
-    lost: list[str] = []
-    # Première passe : matchs stricts (forme exacte)
-    matched: list[bool] = [False] * len(gt_items)
-    for gi, gt_item in enumerate(gt_items):
-        gt_form = form_extractor(gt_item)
-        for hi, hyp_item in enumerate(hyp_items):
-            if hyp_used[hi]:
-                continue
-            if form_extractor(hyp_item) == gt_form:
-                hyp_used[hi] = True
-                matched[gi] = True
-                n_strict += 1
-                break
-    # Deuxième passe : matchs sur valeur (forme différente)
-    for gi, gt_item in enumerate(gt_items):
-        if matched[gi]:
-            n_value += 1  # strict implique value
-            continue
-        gt_val = value_extractor(gt_item)
-        for hi, hyp_item in enumerate(hyp_items):
-            if hyp_used[hi]:
-                continue
-            if value_extractor(hyp_item) == gt_val:
-                hyp_used[hi] = True
-                matched[gi] = True
-                n_value += 1
-                break
-        if not matched[gi]:
-            lost.append(form_extractor(gt_item))
-    n_total = len(gt_items)
-    return {
-        "n_total": n_total,
-        "strict": n_strict,
-        "value": n_value,
-        "strict_score": n_strict / n_total if n_total else 0.0,
-        "value_score": n_value / n_total if n_total else 0.0,
-        "lost_items": lost,
-    }
-
-
-def compute_numerical_sequence_metrics(
-    reference: Optional[str],
-    hypothesis: Optional[str],
-) -> dict:
-    """Calcule la précision sur séquences numériques.
-
-    Returns
-    -------
-    dict
-        Voir docstring du module.  Si ``reference`` est vide
-        ou ne contient aucune séquence détectée, retourne
-        ``{n_total: 0, ...}`` avec scores à 0 (pas None).
-    """
-    ref = reference or ""
-    hyp = hypothesis or ""
-
-    # Spécifications par catégorie : (gt_items, hyp_items,
-    # extractor de forme, extractor de valeur).
-    specs: dict[str, dict] = {}
-    # year : (form="1789", value=1789)
-    specs["year"] = {
-        "gt": _detect_years(ref),
-        "hyp": _detect_years(hyp),
-        "form": lambda it: it[0],
-        "value": lambda it: it[1],
-    }
-    # roman : (form="MDCLXVIII", value=1668)
-    specs["roman"] = {
-        "gt": _detect_romans_with_values(ref),
-        "hyp": _detect_romans_with_values(hyp),
-        "form": lambda it: it[0],
-        "value": lambda it: it[1],
-    }
-    # foliation : (form="f. 12r", value="12r")
-    specs["foliation"] = {
-        "gt": _detect_foliations(ref),
-        "hyp": _detect_foliations(hyp),
-        "form": lambda it: it[0],
-        "value": lambda it: it[1],
-    }
-    # currency : (form="12 livres", value=("12", "livre"))
-    specs["currency"] = {
-        "gt": _detect_currencies(ref),
-        "hyp": _detect_currencies(hyp),
-        "form": lambda it: it[0],
-        "value": lambda it: it[1],
-    }
-    # regnal : (form="an III", value=3)
-    specs["regnal"] = {
-        "gt": _detect_regnal(ref),
-        "hyp": _detect_regnal(hyp),
-        "form": lambda it: it[0],
-        "value": lambda it: it[1],
-    }
-
-    per_category: dict[str, dict] = {}
-    total = 0
-    total_strict = 0
-    total_value = 0
-    for cat, spec in specs.items():
-        breakdown = _classify_per_category(
-            spec["gt"], spec["hyp"],
-            form_extractor=spec["form"],
-            value_extractor=spec["value"],
-        )
-        per_category[cat] = breakdown
-        total += breakdown["n_total"]
-        total_strict += breakdown["strict"]
-        total_value += breakdown["value"]
-
-    return {
-        "n_total": total,
-        "global_strict_score": (
-            total_strict / total if total else 0.0
-        ),
-        "global_value_score": (
-            total_value / total if total else 0.0
-        ),
-        "per_category": per_category,
-    }
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Enregistrement registre typé
-# ──────────────────────────────────────────────────────────────────────────
-
-
-@register_metric(
-    name="numerical_sequence_strict_score",
-    input_types=(ArtifactType.TEXT, ArtifactType.TEXT),
-    description=(
-        "Précision sur séquences numériques en mode strict (forme "
-        "préservée). Couvre années arabes, numéraux romains, "
-        "foliotation, montants Ancien Régime, années régnales."
-    ),
-)
-def numerical_sequence_strict_score(reference: str, hypothesis: str) -> float:
-    return compute_numerical_sequence_metrics(
-        reference, hypothesis,
-    )["global_strict_score"]
-
-
-@register_metric(
-    name="numerical_sequence_value_score",
-    input_types=(ArtifactType.TEXT, ArtifactType.TEXT),
-    description=(
-        "Précision sur séquences numériques en mode valeur "
-        "(la valeur est préservée même si la forme diffère, "
-        "ex. XIV → 14)."
-    ),
-)
-def numerical_sequence_value_score(reference: str, hypothesis: str) -> float:
-    return compute_numerical_sequence_metrics(
-        reference, hypothesis,
-    )["global_value_score"]
-
+from picarones.measurements.numerical_sequences import *  # noqa: F401, F403
 
-__all__ = [
-    "CATEGORIES",
-    "compute_numerical_sequence_metrics",
-    "numerical_sequence_strict_score",
-    "numerical_sequence_value_score",
-]
+import picarones.measurements.numerical_sequences as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/numerical_sequences_runner.py

@@ -1,102 +1,19 @@
-"""Câblage runner des séquences numériques (Sprint 86).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.numerical_sequences_runner`.
 
-Sprint 86 — A.II.5b (vue HTML + câblage runner).
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.numerical_sequences_runner import ...``) de continuer
+à fonctionner sans modification.
 
-Le module ``picarones/core/numerical_sequences.py`` (Sprint 85)
-a livré la couche de calcul.  Ce helper prépare la donnée
-adaptative pour le runner et agrège les compteurs par moteur.
-
-Adaptive masking
-----------------
-On ne stocke le résultat que si la GT contient au moins une
-séquence numérique détectée — sinon le module n'apparaît pas
-dans le rapport.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-from typing import Iterable, Optional
-
-from picarones.core.numerical_sequences import (
-    CATEGORIES,
-    compute_numerical_sequence_metrics,
-)
-
-logger = logging.getLogger(__name__)
-
-
-def compute_numerical_sequence_metrics_adaptive(
-    reference: Optional[str],
-    hypothesis: Optional[str],
-) -> Optional[dict]:
-    """Calcule les métriques séquences numériques avec masquage
-    adaptatif : retourne ``None`` si la GT n'en contient
-    aucune."""
-    if not reference:
-        return None
-    result = compute_numerical_sequence_metrics(reference, hypothesis or "")
-    if (result.get("n_total") or 0) == 0:
-        return None
-    return result
-
-
-def aggregate_numerical_sequence_metrics(
-    per_doc: Iterable[Optional[dict]],
-) -> Optional[dict]:
-    """Agrège par moteur : somme les compteurs par catégorie et
-    recalcule les scores globaux et per-category.
-
-    Format de sortie identique à ``compute_numerical_sequence_metrics``
-    pour faciliter le rendu HTML symétrique.
-    """
-    docs = [d for d in per_doc if d]
-    if not docs:
-        return None
-    total_n = 0
-    total_strict = 0
-    total_value = 0
-    per_cat: dict[str, dict] = {}
-    for cat in CATEGORIES:
-        per_cat[cat] = {
-            "n_total": 0,
-            "strict": 0,
-            "value": 0,
-            "lost_items": [],
-        }
-    for d in docs:
-        for cat in CATEGORIES:
-            cat_data = (d.get("per_category") or {}).get(cat) or {}
-            per_cat[cat]["n_total"] += int(cat_data.get("n_total") or 0)
-            per_cat[cat]["strict"] += int(cat_data.get("strict") or 0)
-            per_cat[cat]["value"] += int(cat_data.get("value") or 0)
-            per_cat[cat]["lost_items"].extend(
-                cat_data.get("lost_items") or [],
-            )
-        total_n += int(d.get("n_total") or 0)
-    # Recalcul des scores
-    for cat, slot in per_cat.items():
-        n = slot["n_total"]
-        slot["strict_score"] = slot["strict"] / n if n else 0.0
-        slot["value_score"] = slot["value"] / n if n else 0.0
-        # Cap des lost_items à 50 par catégorie
-        slot["lost_items"] = slot["lost_items"][:50]
-        total_strict += slot["strict"]
-        total_value += slot["value"]
-    return {
-        "n_docs": len(docs),
-        "n_total": total_n,
-        "global_strict_score": (
-            total_strict / total_n if total_n else 0.0
-        ),
-        "global_value_score": (
-            total_value / total_n if total_n else 0.0
-        ),
-        "per_category": per_cat,
-    }
-
+from picarones.measurements.numerical_sequences_runner import *  # noqa: F401, F403
 
-__all__ = [
-    "compute_numerical_sequence_metrics_adaptive",
-    "aggregate_numerical_sequence_metrics",
-]
+import picarones.measurements.numerical_sequences_runner as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/pricing.py

@@ -1,309 +1,19 @@
-"""Modélisation des coûts — APIs cloud et temps d'inférence local.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.pricing`.
 
-Sert uniquement à la vue Pareto coût/qualité du rapport (Sprint 5).
-Les prix sont indicatifs et vieillissent vite : voir ``picarones/data/pricing.yaml``
-pour les hypothèses, dates et URLs de référence.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.pricing import ...``) de continuer
+à fonctionner sans modification.
 
-Conventions
------------
-- Unité monétaire : EUR (conversion indicative depuis USD quand applicable).
-- Coût exprimé par **1 000 pages** traitées.
-- Coût local = temps moyen d'inférence × taux horaire (paramétrable).
-- Empreinte carbone optionnelle : kWh × intensité g CO₂/kWh du réseau
-  d'exécution (mix France bas carbone par défaut pour le local,
-  moyenne cloud hyperscaler pour les APIs).
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
+from picarones.measurements.pricing import *  # noqa: F401, F403
 
-import logging
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Optional
-
-import yaml
-
-logger = logging.getLogger(__name__)
-
-_DEFAULT_PRICING_PATH = Path(__file__).parent.parent / "data" / "pricing.yaml"
-
-
-@dataclass(frozen=True)
-class PricingDefaults:
-    """Valeurs par défaut du fichier de prix (section ``meta``)."""
-
-    last_updated: Optional[str] = None
-    currency: str = "EUR"
-    hourly_rate_local_cpu_eur: float = 0.08
-    hourly_rate_local_gpu_eur: float = 1.20
-    grid_intensity_local: float = 58.0
-    grid_intensity_cloud: float = 380.0
-
-
-@dataclass
-class EngineCost:
-    """Coût estimé d'un moteur sur 1 000 pages, avec traçabilité des hypothèses.
-
-    La représentation est immuable après construction : une fois que l'utilisateur
-    a choisi un taux horaire local, toutes les instances partagent cette
-    hypothèse par injection explicite dans ``build_costs_for_benchmark``.
-    """
-
-    engine_key: str
-    """Nom ou modèle servant de clé dans la table (ex. ``"gpt-4o"``, ``"tesseract"``)."""
-
-    type: str  # "local" | "cloud_api" | "unknown"
-
-    cost_per_1k_pages_eur: Optional[float] = None
-    """Coût par 1 000 pages en euros. ``None`` si les données sont insuffisantes."""
-
-    currency: str = "EUR"
-
-    # Source / date
-    pricing_source_url: Optional[str] = None
-    pricing_date: Optional[str] = None
-
-    # Pour les APIs cloud : prix brut
-    api_price_per_1k_pages: Optional[float] = None
-
-    # Pour le local : temps d'inférence et taux horaire utilisés
-    local_mean_seconds_per_page: Optional[float] = None
-    hourly_rate_eur: Optional[float] = None
-
-    # Empreinte carbone (estimation — étiquetée "expérimentale" dans le rapport)
-    kwh_per_1k_pages: Optional[float] = None
-    grid_intensity_g_co2_per_kwh: Optional[float] = None
-    co2_per_1k_pages_g: Optional[float] = None
-
-    notes: Optional[str] = None
-
-    assumptions: list[str] = field(default_factory=list)
-    """Liste d'hypothèses textuelles à afficher sous le graphique."""
-
-    def as_dict(self) -> dict:
-        return {
-            "engine_key": self.engine_key,
-            "type": self.type,
-            "cost_per_1k_pages_eur": self.cost_per_1k_pages_eur,
-            "currency": self.currency,
-            "pricing_source_url": self.pricing_source_url,
-            "pricing_date": self.pricing_date,
-            "api_price_per_1k_pages": self.api_price_per_1k_pages,
-            "local_mean_seconds_per_page": self.local_mean_seconds_per_page,
-            "hourly_rate_eur": self.hourly_rate_eur,
-            "kwh_per_1k_pages": self.kwh_per_1k_pages,
-            "grid_intensity_g_co2_per_kwh": self.grid_intensity_g_co2_per_kwh,
-            "co2_per_1k_pages_g": self.co2_per_1k_pages_g,
-            "notes": self.notes,
-            "assumptions": list(self.assumptions),
-        }
-
-
-def load_pricing_database(path: Optional[Path] = None) -> tuple[PricingDefaults, dict]:
-    """Charge la table de prix YAML.
-
-    Retourne ``(defaults, engines_table)`` où ``engines_table`` est un dict
-    ``{engine_key: raw_entry}``.
-    """
-    path = Path(path) if path else _DEFAULT_PRICING_PATH
-    if not path.exists():
-        logger.warning("[pricing] fichier %s introuvable", path)
-        return PricingDefaults(), {}
-    try:
-        with path.open(encoding="utf-8") as fh:
-            data = yaml.safe_load(fh) or {}
-    except yaml.YAMLError as e:
-        logger.warning("[pricing] échec parsing %s : %s", path, e)
-        return PricingDefaults(), {}
-
-    meta = data.get("meta", {}) or {}
-    defaults = PricingDefaults(
-        last_updated=meta.get("last_updated"),
-        currency=meta.get("currency", "EUR"),
-        hourly_rate_local_cpu_eur=float(meta.get("default_hourly_rate_local_cpu_eur", 0.08)),
-        hourly_rate_local_gpu_eur=float(meta.get("default_hourly_rate_local_gpu_eur", 1.20)),
-        grid_intensity_local=float(meta.get("default_grid_intensity_g_co2_per_kwh", 58.0)),
-        grid_intensity_cloud=float(meta.get("cloud_grid_intensity_g_co2_per_kwh", 380.0)),
-    )
-    engines_table = data.get("engines", {}) or {}
-    return defaults, engines_table
-
-
-def _match_key(engine_name: str, llm_model: Optional[str], table: dict) -> Optional[str]:
-    """Cherche la meilleure clé pour ce moteur dans la table.
-
-    Stratégie : d'abord le nom du modèle LLM (pour les pipelines), puis le
-    nom OCR, puis un match partiel (substring) comme filet de sécurité.
-    """
-    candidates = [llm_model, engine_name]
-    for c in candidates:
-        if c and c in table:
-            return c
-    # Matching partiel — utile pour "tesseract → gpt-4o" ou "gpt-4o-vision"
-    for c in candidates:
-        if not c:
-            continue
-        for key in table:
-            if key in c:
-                return key
-    return None
-
-
-def estimate_cost(
-    engine_name: str,
-    *,
-    llm_model: Optional[str] = None,
-    is_pipeline: bool = False,
-    measured_seconds_per_page: Optional[float] = None,
-    table: Optional[dict] = None,
-    defaults: Optional[PricingDefaults] = None,
-    hourly_rate_override_eur: Optional[float] = None,
-) -> EngineCost:
-    """Calcule le ``EngineCost`` pour un moteur donné.
-
-    Parameters
-    ----------
-    engine_name:
-        Nom public du moteur (ex. ``"tesseract"``, ``"tesseract → gpt-4o"``).
-    llm_model:
-        Si pipeline OCR+LLM, le modèle LLM utilisé — prioritaire pour la
-        lookup car c'est lui qui domine le coût.
-    is_pipeline:
-        Indique un pipeline OCR+LLM (change la sémantique de lookup).
-    measured_seconds_per_page:
-        Temps moyen observé sur le benchmark courant. Remplace la valeur
-        indicative de la table si fournie (plus fiable).
-    table, defaults:
-        Overrides pour tests ou usage institutionnel.
-    hourly_rate_override_eur:
-        Taux horaire à utiliser pour le calcul local (sinon valeur table
-        ou défaut).
-    """
-    if table is None or defaults is None:
-        _defaults, _table = load_pricing_database()
-        defaults = defaults or _defaults
-        table = table or _table
-
-    key = _match_key(engine_name, llm_model if is_pipeline else None, table)
-    if key is None:
-        return EngineCost(
-            engine_key=engine_name,
-            type="unknown",
-            assumptions=["Aucune entrée dans la table de prix pour ce moteur."],
-        )
-
-    entry = table[key]
-    etype = str(entry.get("type", "unknown"))
-    notes = entry.get("notes")
-    assumptions: list[str] = []
-    currency = defaults.currency
-
-    cost_eur: Optional[float] = None
-    api_price: Optional[float] = None
-    local_seconds = measured_seconds_per_page
-    hourly_rate = None
-
-    if etype == "cloud_api":
-        api_price = entry.get("api_price_per_1k_pages")
-        if api_price is not None:
-            cost_eur = float(api_price)
-            assumptions.append(
-                f"Prix API indicatif : {cost_eur:.2f} €/1000 pages "
-                f"(source : {entry.get('pricing_source_url', '—')}, {entry.get('pricing_date', 'date inconnue')})."
-            )
-    elif etype == "local":
-        indicative_seconds = entry.get("local_mean_seconds_per_page")
-        if local_seconds is None and indicative_seconds is not None:
-            local_seconds = float(indicative_seconds)
-            assumptions.append(
-                f"Temps d'inférence indicatif : {local_seconds:.1f} s/page (non mesuré sur ce benchmark)."
-            )
-        elif local_seconds is not None:
-            assumptions.append(
-                f"Temps d'inférence mesuré : {local_seconds:.1f} s/page (moyenne sur le corpus)."
-            )
-
-        hourly_rate = (
-            hourly_rate_override_eur
-            if hourly_rate_override_eur is not None
-            else entry.get("hourly_rate_override_eur")
-        )
-        if hourly_rate is None:
-            # Heuristique : si l'entrée précise un override GPU, sinon CPU
-            hourly_rate = (
-                defaults.hourly_rate_local_gpu_eur
-                if "gpu" in str(notes or "").lower()
-                else defaults.hourly_rate_local_cpu_eur
-            )
-        hourly_rate = float(hourly_rate)
-
-        if local_seconds is not None and hourly_rate is not None:
-            cost_eur = (local_seconds / 3600.0) * hourly_rate * 1000.0
-            assumptions.append(
-                f"Taux horaire appliqué : {hourly_rate:.2f} €/h "
-                f"(défaut {'GPU' if hourly_rate >= 0.5 else 'CPU'})."
-            )
-
-    # Empreinte carbone optionnelle
-    kwh_1k = entry.get("kwh_per_1k_pages")
-    grid = (
-        entry.get("grid_intensity_g_co2_per_kwh")
-        or (defaults.grid_intensity_cloud if etype == "cloud_api" else defaults.grid_intensity_local)
-    )
-    co2_g = None
-    if kwh_1k is not None and grid is not None:
-        co2_g = float(kwh_1k) * float(grid)
-
-    return EngineCost(
-        engine_key=key,
-        type=etype,
-        cost_per_1k_pages_eur=cost_eur,
-        currency=currency,
-        pricing_source_url=entry.get("pricing_source_url"),
-        pricing_date=entry.get("pricing_date"),
-        api_price_per_1k_pages=api_price,
-        local_mean_seconds_per_page=local_seconds,
-        hourly_rate_eur=hourly_rate,
-        kwh_per_1k_pages=float(kwh_1k) if kwh_1k is not None else None,
-        grid_intensity_g_co2_per_kwh=float(grid) if grid is not None else None,
-        co2_per_1k_pages_g=co2_g,
-        notes=notes,
-        assumptions=assumptions,
-    )
-
-
-def build_costs_for_benchmark(
-    engines_summary: list[dict],
-    durations_by_engine: dict[str, float],
-    *,
-    hourly_rate_local_eur: Optional[float] = None,
-    pricing_path: Optional[Path] = None,
-) -> dict[str, dict]:
-    """Calcule le coût de chaque moteur d'un benchmark.
-
-    Returns
-    -------
-    dict ``{engine_name: EngineCost.as_dict()}``.
-    """
-    defaults, table = load_pricing_database(pricing_path)
-    out: dict[str, dict] = {}
-    for e in engines_summary:
-        name = e.get("name")
-        if not name:
-            continue
-        measured = durations_by_engine.get(name)
-        llm_model = None
-        pipeline_info = e.get("pipeline_info") or {}
-        if pipeline_info:
-            llm_model = pipeline_info.get("llm_model")
-        cost = estimate_cost(
-            engine_name=name,
-            llm_model=llm_model,
-            is_pipeline=bool(e.get("is_pipeline")),
-            measured_seconds_per_page=measured,
-            table=table,
-            defaults=defaults,
-            hourly_rate_override_eur=hourly_rate_local_eur,
-        )
-        out[name] = cost.as_dict()
-    return out
+import picarones.measurements.pricing as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/rare_tokens.py

@@ -1,254 +1,19 @@
-"""Rare-token recall — Sprint 71 (A.I.1 chantier 2 du plan 2026).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.rare_tokens`.
 
-Pourquoi ce module
-------------------
-Le CER global d'un moteur peut sembler bon (ex. 5 %) tout en
-masquant des **erreurs systématiques sur les tokens rares** : noms
-propres, toponymes peu fréquents, mots techniques, formules latines
-récurrentes mais pas dominantes.  Pour un usage prosopographique
-(indexation de noms, recherche généalogique), ce sont précisément
-ces tokens-là qui comptent.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.rare_tokens import ...``) de continuer
+à fonctionner sans modification.
 
-Ce module mesure le **rappel sur les tokens rares** d'un corpus —
-défaut : tokens dont la fréquence corpus-wide est ≤ 2 (hapax +
-dis legomena, terminologie de lexicométrie classique).
-
-Hypothèse à valider expérimentalement
--------------------------------------
-La conjecture du plan A.I.1 : *« cette métrique discrimine plus
-les moteurs que le CER global »*.  Si confirmée sur un corpus
-patrimonial réel, elle gagne sa place dans le tableau de
-classement principal — décision laissée au chercheur après
-observation.
-
-Stratégie de découpage
-----------------------
-Cohérente avec NER (38), Flesch (52), philologie (55-60) : couche
-de calcul pure d'abord, sans intégration runner.  La vue HTML
-« worst lines / rare tokens manqués » suit dans un sprint dédié.
-
-Pas d'enregistrement dans le registre typé Sprint 34
-----------------------------------------------------
-La métrique exige **trois entrées** (reference, hypothesis, set
-des tokens rares) et le set des rares est calculé corpus-wide
-(donc connu seulement après itération sur tout le corpus).  La
-signature ne rentre pas dans ``(TEXT, TEXT)``.  L'utilisateur
-appelle explicitement ``compute_rare_token_recall`` avec le set
-qu'il a calculé.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-import re
-from collections import Counter
-from typing import Iterable, Optional
-
-logger = logging.getLogger(__name__)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Tokenisation Unicode-aware
-# ──────────────────────────────────────────────────────────────────────────
-
-# Token = séquence maximale de caractères de mot Unicode (\w en
-# Python 3 utilise déjà la table Unicode), incluant l'apostrophe
-# typographique '’' à l'intérieur (« l'an », « d’une ») et les
-# tirets internes (« peut-être »).  La ponctuation isolée et les
-# espaces sont des séparateurs.
-
-_TOKEN_RE = re.compile(
-    r"\w+(?:[’'\-]\w+)*",
-    flags=re.UNICODE,
-)
-
-
-def tokenize(text: Optional[str]) -> list[str]:
-    """Tokenisation Unicode-aware.
-
-    Conserve les contractions (``l'an``, ``d’une``) et les mots
-    composés (``peut-être``, ``c'est-à-dire``) comme un seul token.
-    Casse préservée — l'utilisateur normalise lui-même via
-    ``case_sensitive=False`` dans les fonctions aval s'il le veut.
-    """
-    if not text:
-        return []
-    return _TOKEN_RE.findall(text)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Distribution de fréquence corpus-wide
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def frequency_distribution(
-    documents: Iterable[str],
-    *,
-    case_sensitive: bool = False,
-) -> Counter[str]:
-    """Calcule ``{token: count}`` sur l'ensemble du corpus.
-
-    Parameters
-    ----------
-    documents:
-        Itérable de textes (typiquement les ``ground_truth`` des
-        documents du corpus).
-    case_sensitive:
-        Si ``False`` (défaut), tous les tokens sont mis en
-        minuscule avant comptage.
-    """
-    counter: Counter[str] = Counter()
-    for doc in documents:
-        tokens = tokenize(doc)
-        if not case_sensitive:
-            tokens = [t.lower() for t in tokens]
-        counter.update(tokens)
-    return counter
-
-
-def extract_rare_tokens(
-    documents: Iterable[str],
-    *,
-    max_freq: int = 2,
-    case_sensitive: bool = False,
-) -> frozenset[str]:
-    """Retourne l'ensemble des tokens dont la fréquence
-    corpus-wide est ``≤ max_freq``.
-
-    Convention de lexicométrie : ``max_freq=1`` retourne uniquement
-    les hapax legomena (1 occurrence) ; ``max_freq=2`` retourne
-    hapax + dis legomena (≤ 2 occurrences) — défaut.
-
-    Les tokens qui n'apparaissent **jamais** dans le corpus ne sont
-    évidemment pas inclus (le ``Counter`` ne les liste pas).
-    """
-    if max_freq < 1:
-        raise ValueError("max_freq doit être ≥ 1")
-    counter = frequency_distribution(
-        documents, case_sensitive=case_sensitive,
-    )
-    return frozenset(t for t, c in counter.items() if c <= max_freq)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Calcul du rappel par document
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def compute_rare_token_recall(
-    reference: Optional[str],
-    hypothesis: Optional[str],
-    rare_tokens: Iterable[str],
-    *,
-    case_sensitive: bool = False,
-) -> dict:
-    """Calcule le rappel sur les tokens rares présents dans la GT.
-
-    Parameters
-    ----------
-    reference:
-        Texte GT du document.
-    hypothesis:
-        Texte produit par l'OCR.
-    rare_tokens:
-        Itérable des tokens rares — typiquement le résultat de
-        ``extract_rare_tokens`` sur le corpus complet.
-    case_sensitive:
-        Si ``False`` (défaut), la comparaison se fait sur les
-        formes minuscules.
-
-    Returns
-    -------
-    dict
-        ``{
-            "n_rare_tokens_in_reference": int,
-                # nombre d'**occurrences** de tokens rares dans la GT
-                # (multiplicité préservée — un token rare présent 2
-                # fois compte 2)
-            "n_rare_tokens_recalled": int,
-                # nombre d'occurrences correctement présentes dans hyp
-                # (alignement bag-of-tokens : min(count_ref, count_hyp))
-            "recall": float,
-                # ratio dans [0, 1], ou 0.0 si aucun rare en GT
-            "missed_tokens": list[str],
-                # liste des tokens rares **manqués** (avec multiplicité,
-                # ex. "Dupont" présent 2 fois en GT et 1 fois en hyp →
-                # missed_tokens contient ["Dupont"] une fois)
-        }``
-
-    Cas dégénérés
-    -------------
-    - GT vide ou aucun token rare présent → recall = 0.0, listes
-      vides (convention : on ne récompense pas l'absence de
-      tokens rares).
-    - Hyp vide avec rares en GT → tous manqués, recall = 0.0.
-    """
-    ref = reference or ""
-    hyp = hypothesis or ""
-
-    if case_sensitive:
-        rare_set = frozenset(rare_tokens)
-        ref_tokens = tokenize(ref)
-        hyp_tokens = tokenize(hyp)
-    else:
-        rare_set = frozenset(t.lower() for t in rare_tokens)
-        ref_tokens = [t.lower() for t in tokenize(ref)]
-        hyp_tokens = [t.lower() for t in tokenize(hyp)]
-
-    # Multiplicité : on compte uniquement les rares présents dans la GT
-    ref_rare_counts: Counter[str] = Counter(
-        t for t in ref_tokens if t in rare_set
-    )
-    n_rare_in_ref = sum(ref_rare_counts.values())
-    if n_rare_in_ref == 0:
-        return {
-            "n_rare_tokens_in_reference": 0,
-            "n_rare_tokens_recalled": 0,
-            "recall": 0.0,
-            "missed_tokens": [],
-        }
-
-    # Bag-of-tokens dans hyp pour les tokens rares uniquement
-    hyp_rare_counts: Counter[str] = Counter(
-        t for t in hyp_tokens if t in rare_set
-    )
-    # Recall multiplicitaire : pour chaque token, min(ref_count, hyp_count)
-    n_recalled = 0
-    missed: list[str] = []
-    for token, ref_count in ref_rare_counts.items():
-        hyp_count = hyp_rare_counts.get(token, 0)
-        recalled = min(ref_count, hyp_count)
-        n_recalled += recalled
-        missed_count = ref_count - recalled
-        if missed_count > 0:
-            missed.extend([token] * missed_count)
-
-    return {
-        "n_rare_tokens_in_reference": n_rare_in_ref,
-        "n_rare_tokens_recalled": n_recalled,
-        "recall": n_recalled / n_rare_in_ref,
-        "missed_tokens": missed,
-    }
-
-
-def rare_token_recall(
-    reference: Optional[str],
-    hypothesis: Optional[str],
-    rare_tokens: Iterable[str],
-    *,
-    case_sensitive: bool = False,
-) -> float:
-    """Raccourci : retourne uniquement le rappel ∈ [0, 1]."""
-    return compute_rare_token_recall(
-        reference, hypothesis, rare_tokens,
-        case_sensitive=case_sensitive,
-    )["recall"]
-
+from picarones.measurements.rare_tokens import *  # noqa: F401, F403
 
-__all__ = [
-    "tokenize",
-    "frequency_distribution",
-    "extract_rare_tokens",
-    "compute_rare_token_recall",
-    "rare_token_recall",
-]
+import picarones.measurements.rare_tokens as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/readability.py

@@ -1,252 +1,19 @@
-"""Métriques de lisibilité (Flesch) — Sprint 52.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.readability`.
 
-Sprint 52 — A.II.2.3 du plan d'évolution 2026 : couche de calcul pure
-de la métrique Flesch, indépendante de tout alignement OCR/GT.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.readability import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-Les LLM produisent du texte plus « lisse » que les manuscrits
-historiques.  Cette tendance à la modernisation est mesurable par la
-différence de score de lisibilité entre la GT et la sortie OCR/LLM —
-**indépendamment des classes taxonomiques** et **sans alignement
-caractère/mot**.  C'est l'avantage clé du score Flesch : il fonctionne
-même quand l'OCR est très dégradé (cas d'un LLM qui invente du texte
-moderne plausible mais déconnecté de la GT).
-
-Stratégie de découpage
-----------------------
-Comme pour le NER (Sprint 38) et la calibration (Sprint 39), on
-découpe :
-
-- **Sprint 52** (ici) — couche de calcul pure : ``flesch_score`` et
-  ``flesch_delta``.  Aucune dépendance externe ; les heuristiques de
-  comptage de syllabes sont en pur Python, déterministes, testées.
-- **Sprints suivants** — câblage runner pour calculer
-  ``flesch_delta`` par document et l'agréger au moteur, puis vue HTML.
-
-Formules
---------
-- **Anglais** (Flesch original 1948) :
-  ``206.835 - 1.015 × (mots/phrases) - 84.6 × (syllabes/mots)``
-- **Français** (Kandel-Moles 1958) :
-  ``207 - 1.015 × (mots/phrases) - 73.6 × (syllabes/mots)``
-
-Le score est borné dans ``[0, 100]`` — 100 ↔ « très facile à lire »,
-0 ↔ « très difficile ».  Une **augmentation** du score quand on passe
-de la GT à l'OCR signale une simplification (typique des LLM
-modernisants).  Une **chute** signale une dégradation OCR.
-
-Limites documentées
--------------------
-- Le comptage de syllabes est heuristique.  En français, des règles
-  comme « -ier non final = 2 syllabes » ne sont pas appliquées
-  finement.  Acceptable pour une métrique de **comparaison relative**
-  (delta GT vs OCR), pas pour publier une absolue.
-- Sur des textes très courts (< 20 mots), la formule perd en
-  fiabilité.  Le seuil minimal est documenté.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-import re
-from typing import Literal
-
-from picarones.core.metric_registry import register_metric
-from picarones.core.modules import ArtifactType
-
-logger = logging.getLogger(__name__)
-
-
-Language = Literal["fr", "en"]
-
-# Coefficients de la formule Flesch selon la langue.
-_FLESCH_COEFFS: dict[str, tuple[float, float, float]] = {
-    "en": (206.835, 1.015, 84.6),     # Flesch 1948
-    "fr": (207.0,   1.015, 73.6),     # Kandel-Moles 1958
-}
-
-# Voyelles utilisées pour l'heuristique de comptage de syllabes.
-# On utilise un set qui inclut les diacritiques courantes en FR/EN.
-_VOWELS = set("aeiouyàâäéèêëîïôöùûüÿæœAEIOUYÀÂÄÉÈÊËÎÏÔÖÙÛÜŸÆŒ")
-
-# Regex de découpage en phrases : ponctuation finale + espace ou fin.
-# Tolère les multiples points (« ... ») et garde un découpage robuste.
-_SENTENCE_SPLIT_RE = re.compile(r"[.!?…]+(?:\s+|$)")
-
-# Regex de tokenisation simple (mots) : séquences de caractères "lettres".
-_WORD_RE = re.compile(r"[\w'-]+", re.UNICODE)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Compteurs de base
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def count_words(text: str) -> int:
-    """Nombre de mots (tokens alphanumériques) dans ``text``."""
-    if not text:
-        return 0
-    return len(_WORD_RE.findall(text))
-
-
-def count_sentences(text: str) -> int:
-    """Nombre de phrases dans ``text``.
-
-    Découpage par ponctuation finale (``.``, ``!``, ``?``, ``…``).
-    Renvoie au minimum 1 si ``text`` contient au moins un mot, pour
-    éviter une division par zéro dans la formule de Flesch sur les
-    textes sans ponctuation finale.
-    """
-    if not text:
-        return 0
-    parts = [p for p in _SENTENCE_SPLIT_RE.split(text) if p.strip()]
-    n = len(parts)
-    if n == 0 and count_words(text) > 0:
-        return 1
-    return n
-
-
-def count_syllables_word(word: str) -> int:
-    """Heuristique de comptage de syllabes pour un mot isolé.
-
-    Règle : on compte les **groupes de voyelles consécutives** (en
-    incluant ``y`` et les diacritiques courantes).  C'est une
-    approximation grossière mais déterministe et testable.
-
-    Cas limites :
-    - mot vide → 0
-    - mot sans voyelle → 1 (par convention, ex. acronymes ``BNF``)
-    - mot d'une seule voyelle isolée → 1
-    """
-    if not word:
-        return 0
-    word = word.lower()
-    in_vowel_group = False
-    count = 0
-    for ch in word:
-        if ch in _VOWELS:
-            if not in_vowel_group:
-                count += 1
-                in_vowel_group = True
-        else:
-            in_vowel_group = False
-    return count or 1
-
-
-def count_syllables(text: str) -> int:
-    """Somme des syllabes de tous les mots de ``text``."""
-    if not text:
-        return 0
-    return sum(count_syllables_word(w) for w in _WORD_RE.findall(text))
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Score Flesch
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def flesch_score(text: str, lang: Language = "fr") -> float:
-    """Calcule le score de lisibilité Flesch pour ``text``.
-
-    Parameters
-    ----------
-    text:
-        Texte à évaluer.  Peut contenir ponctuation, accents, etc.
-    lang:
-        ``"fr"`` (Kandel-Moles 1958, défaut) ou ``"en"`` (Flesch 1948).
-
-    Returns
-    -------
-    float
-        Score borné dans ``[0, 100]``.  Renvoie ``0.0`` sur un texte
-        vide ou sans mot exploitable.
-
-    Notes
-    -----
-    Le score chute fortement avec :
-    - longues phrases (mots/phrases élevé)
-    - mots polysyllabiques (syllabes/mots élevé)
-    Une montée du score lors du passage GT → OCR signale qu'un LLM a
-    « lissé » la langue (phrases plus courtes, mots plus communs).
-    """
-    if lang not in _FLESCH_COEFFS:
-        raise ValueError(f"Langue non supportée : {lang!r}. Choisir 'fr' ou 'en'.")
-
-    n_words = count_words(text)
-    if n_words == 0:
-        return 0.0
-    n_sentences = max(1, count_sentences(text))
-    n_syllables = count_syllables(text)
-    if n_syllables == 0:
-        return 0.0
-
-    base, k_words, k_syll = _FLESCH_COEFFS[lang]
-    raw = base - k_words * (n_words / n_sentences) - k_syll * (n_syllables / n_words)
-    return max(0.0, min(100.0, raw))
-
-
-def flesch_delta(
-    reference: str,
-    hypothesis: str,
-    lang: Language = "fr",
-) -> float:
-    """Différence ``flesch_score(hypothesis) - flesch_score(reference)``.
-
-    Interprétation
-    --------------
-    - **Positif** : l'hypothèse OCR est plus lisible que la GT —
-      signal d'**over-normalisation** (typique des LLM qui modernisent
-      des textes anciens).
-    - **Négatif** : l'OCR est moins lisible — signal de dégradation
-      (caractères mal reconnus brisent la fluidité).
-    - **≈ 0** : OCR fidèle à la GT en termes de complexité linguistique.
-
-    Borné dans ``[-100, +100]``.
-    """
-    return flesch_score(hypothesis, lang=lang) - flesch_score(reference, lang=lang)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Enregistrement dans le registre typé (Sprint 34)
-# ──────────────────────────────────────────────────────────────────────────
-
-
-@register_metric(
-    name="flesch_delta_fr",
-    input_types=(ArtifactType.TEXT, ArtifactType.TEXT),
-    description=(
-        "Différence de score Flesch (Kandel-Moles, FR) entre la sortie "
-        "OCR et la GT. Positif = OCR plus lisible (signal "
-        "d'over-normalisation LLM). Aucun alignement requis."
-    ),
-    higher_is_better=False,  # un delta proche de 0 = fidélité ; positif = LLM lissant
-    tags={"text", "readability", "over_normalization"},
-)
-def _registered_flesch_delta_fr(reference: str, hypothesis: str) -> float:
-    return flesch_delta(reference, hypothesis, lang="fr")
-
-
-@register_metric(
-    name="flesch_delta_en",
-    input_types=(ArtifactType.TEXT, ArtifactType.TEXT),
-    description=(
-        "Flesch reading ease delta (Flesch 1948, EN) between OCR and GT. "
-        "Positive = OCR easier to read than GT (LLM smoothing signal). "
-        "No alignment required."
-    ),
-    higher_is_better=False,
-    tags={"text", "readability", "over_normalization"},
-)
-def _registered_flesch_delta_en(reference: str, hypothesis: str) -> float:
-    return flesch_delta(reference, hypothesis, lang="en")
-
+from picarones.measurements.readability import *  # noqa: F401, F403
 
-__all__ = [
-    "flesch_score",
-    "flesch_delta",
-    "count_words",
-    "count_sentences",
-    "count_syllables",
-    "count_syllables_word",
-]
+import picarones.measurements.readability as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/readability_runner.py

@@ -1,114 +1,19 @@
-"""Câblage runner du delta Flesch (Sprint 87 — A.II.2).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.readability_runner`.
 
-Sprint 87 — A.II.2 (vue HTML + câblage runner du delta Flesch
-livré par le Sprint 52).
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.readability_runner import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-Le ``flesch_delta`` mesure la différence de lisibilité entre la
-GT et la sortie OCR.  Un score positif signale une *over-
-normalisation* typique des LLM/VLM qui modernisent un texte
-ancien (le Flesch monte parce que les mots sont plus simples) ;
-un score négatif signale une dégradation OCR brutale.
-
-Cette métrique est calculée **automatiquement** par le runner
-sur chaque document, agrégée par moteur, et présentée dans le
-rapport.
-
-Adaptive masking
-----------------
-On ne calcule que si la GT contient ≥ 5 mots — en dessous, le
-Flesch est trop instable pour être informatif.
-
-Langue
-------
-Lecture depuis ``corpus.metadata.get("language", "fr")``.  Pour
-les corpus mixtes, l'utilisateur peut passer une langue
-explicite à l'orchestrateur.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-import statistics
-from typing import Iterable, Optional
-
-from picarones.core.readability import (
-    Language,
-    count_words,
-    flesch_delta,
-    flesch_score,
-)
-
-logger = logging.getLogger(__name__)
-
-
-_MIN_WORDS_FOR_FLESCH = 5
-
-
-def compute_readability_metrics(
-    reference: Optional[str],
-    hypothesis: Optional[str],
-    *,
-    lang: Language = "fr",
-) -> Optional[dict]:
-    """Calcule le delta Flesch d'un document avec adaptive masking.
-
-    Retourne ``None`` si la GT contient moins de
-    ``_MIN_WORDS_FOR_FLESCH`` mots.
-    """
-    ref = reference or ""
-    n_ref_words = count_words(ref)
-    if n_ref_words < _MIN_WORDS_FOR_FLESCH:
-        return None
-    hyp = hypothesis or ""
-    flesch_ref = flesch_score(ref, lang=lang)
-    flesch_hyp = flesch_score(hyp, lang=lang) if hyp else None
-    delta = (
-        flesch_delta(ref, hyp, lang=lang) if hyp else None
-    )
-    return {
-        "lang": lang,
-        "flesch_reference": flesch_ref,
-        "flesch_hypothesis": flesch_hyp,
-        "flesch_delta": delta,
-        "n_words_reference": n_ref_words,
-    }
-
-
-def aggregate_readability_metrics(
-    per_doc: Iterable[Optional[dict]],
-) -> Optional[dict]:
-    """Agrège : moyenne/médiane des deltas + part de docs
-    « over-normalisés » (delta > +5 points).
-    """
-    docs = [d for d in per_doc if d]
-    if not docs:
-        return None
-    deltas = [
-        float(d["flesch_delta"]) for d in docs
-        if isinstance(d.get("flesch_delta"), (int, float))
-    ]
-    if not deltas:
-        return None
-    over_norm = sum(1 for d in deltas if d > 5.0)
-    under_norm = sum(1 for d in deltas if d < -5.0)
-    lang = docs[0].get("lang") or "fr"
-    return {
-        "lang": lang,
-        "n_docs": len(docs),
-        "n_docs_with_delta": len(deltas),
-        "delta_mean": statistics.fmean(deltas),
-        "delta_median": statistics.median(deltas),
-        "delta_min": min(deltas),
-        "delta_max": max(deltas),
-        "n_over_normalized": over_norm,
-        "n_under_normalized": under_norm,
-        "over_normalized_rate": over_norm / len(deltas),
-    }
-
+from picarones.measurements.readability_runner import *  # noqa: F401, F403
 
-__all__ = [
-    "compute_readability_metrics",
-    "aggregate_readability_metrics",
-]
+import picarones.measurements.readability_runner as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/reading_order.py

@@ -1,196 +1,19 @@
-"""Reading order F1 (ICDAR 2015, Antonacopoulos) — Sprint 53.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.reading_order`.
 
-Sprint 53 — A.II.2.1 du plan d'évolution 2026.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.reading_order import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-Sur un manuscrit glosé, un journal multi-colonnes ou un registre
-paroissial complexe, le **classement des moteurs en CER** peut être
-trompeur : un moteur peut avoir un excellent CER caractère et un
-**ordre de lecture catastrophique**.  Le résultat est inutilisable
-pour la recherche plein texte (Elastic, Solr) ou pour reconstituer
-une narration linéaire.
-
-La métrique standard est définie par Antonacopoulos et al. dans
-ICDAR 2015 — F1 sur les **paires d'ordre relatif** entre régions
-ALTO/PAGE.  Pour chaque paire ``(a, b)`` telle que ``a`` précède
-``b`` dans la GT :
-
-- **TP** si ``a`` précède aussi ``b`` dans l'hypothèse,
-- **FN** si la paire est manquante (régions absentes ou ordre
-  inversé) côté hypothèse,
-- **FP** si une paire ``(a, b)`` apparaît dans l'hypothèse alors que
-  la GT n'a pas cet ordre (régions hallucinées ou inversion).
-
-Le F1 est la moyenne harmonique des deux.
-
-Stratégie de découpage
-----------------------
-Cohérent avec NER (Sprint 38), calibration (Sprint 39), Flesch
-(Sprint 52) : couche de calcul pure d'abord.  L'utilisateur fournit
-deux listes ordonnées d'IDs de régions (typiquement extraites de
-ALTO/PAGE par un parser amont).  Le câblage runner et la vue HTML
-suivent dans des sprints dédiés.
-
-Compatible directement avec ``ReadingOrderGT`` du Sprint 32 :
-``ReadingOrderGT.region_order`` est exactement le format attendu.
-
-Convention sur les régions
---------------------------
-- Les IDs sont des chaînes (``"r_1"``, ``"region_main"``, etc.).
-- Les **doublons** sont ignorés au calcul des paires ordonnées
-  (chaque ID compte une fois par séquence).
-- Une région présente dans la GT mais absente de l'hypothèse
-  contribue aux paires FN.
-- Une région présente dans l'hypothèse mais absente de la GT
-  contribue aux paires FP.
-- Si une séquence a < 2 régions distinctes, aucune paire n'est
-  émise — le F1 retourne ``0.0`` ou ``1.0`` selon que les deux
-  séquences soient identiques.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-from itertools import combinations
-from typing import Iterable
-
-from picarones.core.metric_registry import register_metric
-from picarones.core.modules import ArtifactType
-
-logger = logging.getLogger(__name__)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Helpers
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def _ordered_pairs(sequence: list[str]) -> set[tuple[str, str]]:
-    """Retourne l'ensemble des paires ``(a, b)`` telles que ``a``
-    précède strictement ``b`` dans ``sequence``.
-
-    Doublons : chaque ID est traité une seule fois (première occurrence
-    dans la séquence).  Cohérent avec ICDAR 2015 où les régions ont
-    des IDs uniques.
-    """
-    seen: list[str] = []
-    seen_set: set[str] = set()
-    for r in sequence:
-        if r not in seen_set:
-            seen.append(r)
-            seen_set.add(r)
-    return set(combinations(seen, 2))
-
-
-def _normalize_input(value: Iterable[str] | None) -> list[str]:
-    """Coerce une entrée en list[str], en filtrant les valeurs vides."""
-    if value is None:
-        return []
-    return [str(v) for v in value if v is not None and str(v).strip()]
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Métrique principale
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def compute_reading_order_metrics(
-    reference_order: Iterable[str] | None,
-    hypothesis_order: Iterable[str] | None,
-) -> dict:
-    """Calcule precision / recall / F1 sur l'ordre relatif des régions.
-
-    Parameters
-    ----------
-    reference_order:
-        Séquence ordonn��e d'IDs de régions issue de la GT (typiquement
-        ``ReadingOrderGT.region_order`` du Sprint 32).
-    hypothesis_order:
-        Séquence ordonnée d'IDs de régions produite par un moteur
-        OCR/HTR ou un reconstructeur ALTO.
-
-    Returns
-    -------
-    dict
-        ``{"precision", "recall", "f1", "true_positives",
-        "false_positives", "false_negatives", "n_ref_pairs",
-        "n_hyp_pairs", "common_regions", "ref_only_regions",
-        "hyp_only_regions"}``.
-
-    Comportements aux bornes
-    ------------------------
-    - Deux séquences identiques (mêmes régions, même ordre) → F1 = 1.0.
-    - Ordre strictement inversé → F1 = 0.0 (toutes les paires
-      relatives sont fausses).
-    - Une séquence vide vs une séquence non vide → F1 = 0.0.
-    - Deux séquences vides → F1 = 0.0 et tous les compteurs à 0
-      (convention : on ne récompense pas l'absence).
-    """
-    ref = _normalize_input(reference_order)
-    hyp = _normalize_input(hypothesis_order)
-
-    ref_pairs = _ordered_pairs(ref)
-    hyp_pairs = _ordered_pairs(hyp)
-
-    tp = len(ref_pairs & hyp_pairs)
-    fn = len(ref_pairs - hyp_pairs)
-    fp = len(hyp_pairs - ref_pairs)
-
-    precision = tp / (tp + fp) if (tp + fp) > 0 else 0.0
-    recall = tp / (tp + fn) if (tp + fn) > 0 else 0.0
-    f1 = (
-        2 * precision * recall / (precision + recall)
-        if (precision + recall) > 0
-        else 0.0
-    )
-
-    ref_set = set(ref)
-    hyp_set = set(hyp)
-    return {
-        "precision": precision,
-        "recall": recall,
-        "f1": f1,
-        "true_positives": tp,
-        "false_positives": fp,
-        "false_negatives": fn,
-        "n_ref_pairs": len(ref_pairs),
-        "n_hyp_pairs": len(hyp_pairs),
-        "common_regions": sorted(ref_set & hyp_set),
-        "ref_only_regions": sorted(ref_set - hyp_set),
-        "hyp_only_regions": sorted(hyp_set - ref_set),
-    }
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Enregistrement dans le registre typé (Sprint 34)
-# ──────────────────────────────────────────────────────────────────────────
-
-
-@register_metric(
-    name="reading_order_f1",
-    input_types=(ArtifactType.READING_ORDER, ArtifactType.READING_ORDER),
-    description=(
-        "F1 sur l'ordre relatif des régions ALTO/PAGE (ICDAR 2015, "
-        "Antonacopoulos). Pour chaque paire (a,b) où a précède b dans "
-        "la GT, vérifie que a précède aussi b dans l'hypothèse."
-    ),
-    higher_is_better=True,
-    tags={"structure", "icdar", "alto", "page"},
-)
-def reading_order_f1(
-    reference: Iterable[str] | None,
-    hypothesis: Iterable[str] | None,
-) -> float:
-    """Raccourci : retourne uniquement le F1 global.
-
-    Pour les détails par paire (TP/FP/FN, régions communes, etc.),
-    appeler ``compute_reading_order_metrics`` directement.
-    """
-    return compute_reading_order_metrics(reference, hypothesis)["f1"]
-
+from picarones.measurements.reading_order import *  # noqa: F401, F403
 
-__all__ = [
-    "compute_reading_order_metrics",
-    "reading_order_f1",
-]
+import picarones.measurements.reading_order as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/reliability.py

@@ -1,360 +1,19 @@
-"""Métriques de fiabilité — Sprint 83 (A.II.4).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.reliability`.
 
-Sprint 83 — A.II.4 du plan d'évolution 2026 (Étape 4).
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.reliability import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-Une publication scientifique qui rapporte un CER LLM sans
-stabilité est méthodologiquement faible.  Et un benchmark qui
-ignore le plafond humain (« deux paléographes ne sont pas même
-d'accord ») crée des classements faussement optimistes.  Ce
-module livre deux familles complémentaires :
-
-1. **Inter-annotator agreement (IAA)** — quand un document a
-   plusieurs GT (deux paléographes, par ex.), Cohen κ et
-   Krippendorff α mesurent l'accord au niveau caractère.
-   Lecture : *« le CER de Pero (4,2 %) approche le plafond
-   humain (κ = 0,89). »*
-
-2. **Stabilité multi-runs** — quand on relance la même
-   pipeline LLM N fois sur les mêmes documents, on mesure :
-   variance du CER, taux de tokens divergents entre runs,
-   CER pairwise moyen.
-
-Périmètre Sprint 83
--------------------
-**Couche de calcul uniquement** — fonctions pures, pas
-d'intégration runner ni de vue HTML.  L'extension du loader
-pour accepter ``doc_001.gt.A.txt`` / ``doc_001.gt.B.txt`` est
-documentée comme dépendance future ; en attendant le sprint
-dédié, on prend deux strings GT en entrée.
-
-Méthode
--------
-*IAA caractère par caractère.*  On aligne les deux GT par
-``difflib.SequenceMatcher`` au niveau caractère et on construit
-une table de contingence ``(annotator_a_char, annotator_b_char)``
-sur les positions ``equal`` ou ``replace``.  Cohen κ utilise
-cette table directement.  Krippendorff α utilise la version
-matricielle (différence binaire pour le mode nominal).
-
-*Stabilité multi-runs.*  ``compute_multirun_stability(runs)``
-prend une liste de N transcriptions du **même** document et
-renvoie variance/écart-type/coefficient de variation du CER si
-référence fournie ; sinon, taux pairwise de divergence
-(intersection-vs-union des tokens).
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-import statistics
-from typing import Optional, Sequence
-
-logger = logging.getLogger(__name__)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Helpers d'alignement caractère par caractère
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def _aligned_char_pairs(
-    text_a: str, text_b: str,
-) -> list[tuple[str, str]]:
-    """Aligne ``text_a`` et ``text_b`` caractère par caractère.
-
-    Retourne la liste des paires alignées sur les segments
-    ``equal`` et ``replace`` de ``SequenceMatcher`` (les ``insert``
-    et ``delete`` sont ignorés — pas d'alignement valide).
-    """
-    if not text_a and not text_b:
-        return []
-    import difflib
-    matcher = difflib.SequenceMatcher(None, text_a, text_b, autojunk=False)
-    pairs: list[tuple[str, str]] = []
-    for tag, i1, i2, j1, j2 in matcher.get_opcodes():
-        if tag == "equal":
-            for k in range(i2 - i1):
-                pairs.append((text_a[i1 + k], text_b[j1 + k]))
-        elif tag == "replace":
-            paired = min(i2 - i1, j2 - j1)
-            for k in range(paired):
-                pairs.append((text_a[i1 + k], text_b[j1 + k]))
-        # insert/delete : pas d'alignement bilatéral exploitable
-    return pairs
-
-
-__all__: list[str] = []
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# 1. Cohen's kappa (deux annotateurs, accord nominal)
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def cohen_kappa(
-    annotations_a: Sequence,
-    annotations_b: Sequence,
-) -> Optional[float]:
-    """Cohen's κ entre deux annotateurs sur des observations
-    appariées.
-
-    Définition :
-
-        κ = (po - pe) / (1 - pe)
-
-    où ``po`` est l'accord observé (proportion de paires égales)
-    et ``pe`` l'accord attendu par hasard (somme sur les classes
-    de p_a(c) × p_b(c)).
-
-    Conventions :
-    - retourne ``None`` si les deux séquences sont vides ou de
-      tailles incompatibles ;
-    - κ = 1.0 quand l'accord est parfait, 0.0 quand il égale le
-      hasard, négatif si pire que le hasard ;
-    - quand ``pe == 1`` (un seul label dans les deux séquences),
-      retourne 1.0 si les séquences sont identiques, 0.0 sinon
-      (κ est mathématiquement indéfini, on choisit une
-      convention transparente documentée).
-    """
-    if len(annotations_a) != len(annotations_b):
-        return None
-    n = len(annotations_a)
-    if n == 0:
-        return None
-    # Accord observé
-    agree = sum(1 for a, b in zip(annotations_a, annotations_b) if a == b)
-    p_o = agree / n
-    # Accord attendu par hasard
-    from collections import Counter
-    count_a = Counter(annotations_a)
-    count_b = Counter(annotations_b)
-    classes = set(count_a) | set(count_b)
-    p_e = sum(
-        (count_a.get(c, 0) / n) * (count_b.get(c, 0) / n)
-        for c in classes
-    )
-    if p_e >= 1.0 - 1e-12:
-        # Indéfini ; convention : 1 si identité totale, 0 sinon
-        return 1.0 if p_o >= 1.0 - 1e-12 else 0.0
-    return (p_o - p_e) / (1.0 - p_e)
-
-
-__all__.append("cohen_kappa")
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# 2. Krippendorff's alpha (généralisation à N annotateurs)
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def krippendorff_alpha(
-    annotations_per_unit: Sequence[Sequence],
-) -> Optional[float]:
-    """Krippendorff's α en mode nominal pour N annotateurs.
-
-    Parameters
-    ----------
-    annotations_per_unit:
-        Liste d'unités, chaque unité étant la liste des
-        annotations produites par les différents annotateurs sur
-        cette unité.  ``None`` dans une cellule = annotation
-        manquante (autorisée).
-
-    Définition (Krippendorff 1980, équation pour métrique
-    nominale) :
-
-        α = 1 - D_o / D_e
-
-    où ``D_o`` est le désaccord observé (paires en désaccord
-    intra-unité, normalisées) et ``D_e`` le désaccord attendu
-    par hasard.  ``α = 1`` accord parfait, ``α = 0`` hasard,
-    négatif si pire.
-
-    Conventions :
-    - unités avec moins de 2 annotations valides : ignorées
-      (Krippendorff convention) ;
-    - retourne ``None`` si moins d'une unité utilisable ou
-      ``D_e == 0`` (un seul label dans tout le corpus).
-    """
-    from collections import Counter
-    # Valeurs observées au niveau corpus
-    value_counts: Counter = Counter()
-    pair_disagree = 0.0
-    pair_total = 0.0
-    for unit in annotations_per_unit:
-        valid = [v for v in unit if v is not None]
-        m = len(valid)
-        if m < 2:
-            continue
-        # paires intra-unité (sans repetition, ordonné)
-        for i in range(m):
-            for j in range(m):
-                if i == j:
-                    continue
-                pair_total += 1.0 / (m - 1)
-                if valid[i] != valid[j]:
-                    pair_disagree += 1.0 / (m - 1)
-        for v in valid:
-            value_counts[v] += 1
-    if pair_total == 0:
-        return None
-    n_total = sum(value_counts.values())
-    if n_total < 2:
-        return None
-    # Désaccord attendu (sur paires aléatoires sans remise)
-    expected_disagree = 0.0
-    for v_a, c_a in value_counts.items():
-        for v_b, c_b in value_counts.items():
-            if v_a != v_b:
-                expected_disagree += c_a * c_b
-    expected_disagree /= n_total * (n_total - 1)
-    if expected_disagree <= 1e-12:
-        return None
-    d_o = pair_disagree / pair_total
-    return 1.0 - (d_o / expected_disagree)
-
-
-__all__.append("krippendorff_alpha")
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# 3. Helpers IAA caractère
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def compute_iaa(
-    transcription_a: str,
-    transcription_b: str,
-) -> Optional[dict]:
-    """Calcule κ et α au niveau caractère entre deux
-    transcriptions du même document.
-
-    Aligne via ``_aligned_char_pairs`` puis :
-    - κ : sur la liste des paires alignées ;
-    - α : sur les unités à 2 annotations (équivalent à κ sur ce
-      cas, mais le cadre généralise à N annotateurs).
-
-    Retourne ``None`` si pas d'alignement possible (transcriptions
-    vides ou totalement disjointes).
-    """
-    pairs = _aligned_char_pairs(transcription_a, transcription_b)
-    if not pairs:
-        return None
-    kappa = cohen_kappa([a for a, _ in pairs], [b for _, b in pairs])
-    alpha = krippendorff_alpha([[a, b] for a, b in pairs])
-    return {
-        "n_aligned_chars": len(pairs),
-        "cohen_kappa": kappa,
-        "krippendorff_alpha": alpha,
-        "agreement_rate": (
-            sum(1 for a, b in pairs if a == b) / len(pairs)
-        ),
-    }
-
-
-__all__.append("compute_iaa")
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# 4. Stabilité multi-runs (variance CER, divergence pairwise)
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def _split_words(text: str) -> list[str]:
-    return text.split() if text else []
-
-
-def compute_multirun_stability(
-    runs: Sequence[str],
-    *,
-    reference: Optional[str] = None,
-) -> Optional[dict]:
-    """Mesure la stabilité de N runs successifs d'une même
-    pipeline (typiquement LLM/VLM non déterministe) sur un
-    document.
-
-    Parameters
-    ----------
-    runs:
-        Liste des transcriptions produites à chaque run (≥ 2).
-    reference:
-        Transcription de référence (GT). Si fournie, on calcule
-        ``cer_per_run``, leur variance et leur coefficient de
-        variation.
-
-    Returns
-    -------
-    dict | None
-        ``{
-            "n_runs": int,
-            "pairwise_disagreement_mean": float,  # divergence moyenne
-            "pairwise_disagreement_max": float,
-            "identical_run_rate": float,          # paires identiques / total
-            "cer_per_run": Optional[list[float]],
-            "cer_mean": Optional[float],
-            "cer_stdev": Optional[float],
-            "cer_cv": Optional[float],            # cv = stdev / mean
-            "n_distinct_outputs": int,
-        }``
-        ou ``None`` si moins de 2 runs.
-    """
-    if len(runs) < 2:
-        return None
-    runs_list = list(runs)
-    # Divergence pairwise (token-level Jaccard distance)
-    n = len(runs_list)
-    n_pairs = 0
-    sum_disagree = 0.0
-    max_disagree = 0.0
-    n_identical = 0
-    for i in range(n):
-        for j in range(i + 1, n):
-            n_pairs += 1
-            tokens_i = set(_split_words(runs_list[i]))
-            tokens_j = set(_split_words(runs_list[j]))
-            union = tokens_i | tokens_j
-            if not union:
-                disagree = 0.0
-            else:
-                disagree = 1.0 - len(tokens_i & tokens_j) / len(union)
-            sum_disagree += disagree
-            if disagree > max_disagree:
-                max_disagree = disagree
-            if runs_list[i] == runs_list[j]:
-                n_identical += 1
-    pairwise_mean = sum_disagree / n_pairs if n_pairs else 0.0
-    identical_rate = n_identical / n_pairs if n_pairs else 0.0
-    distinct = len(set(runs_list))
-
-    cer_per_run: Optional[list[float]] = None
-    cer_mean: Optional[float] = None
-    cer_stdev: Optional[float] = None
-    cer_cv: Optional[float] = None
-    if reference is not None:
-        from picarones.core.metrics import _cer_from_strings
-        cer_per_run = [_cer_from_strings(reference, r) for r in runs_list]
-        cer_per_run = [v for v in cer_per_run if v is not None]
-        if cer_per_run:
-            cer_mean = statistics.fmean(cer_per_run)
-            if len(cer_per_run) >= 2:
-                cer_stdev = statistics.stdev(cer_per_run)
-                cer_cv = (
-                    cer_stdev / cer_mean if cer_mean and cer_mean > 0
-                    else None
-                )
-    return {
-        "n_runs": n,
-        "pairwise_disagreement_mean": pairwise_mean,
-        "pairwise_disagreement_max": max_disagree,
-        "identical_run_rate": identical_rate,
-        "n_distinct_outputs": distinct,
-        "cer_per_run": cer_per_run,
-        "cer_mean": cer_mean,
-        "cer_stdev": cer_stdev,
-        "cer_cv": cer_cv,
-    }
-
+from picarones.measurements.reliability import *  # noqa: F401, F403
 
-__all__.append("compute_multirun_stability")
+import picarones.measurements.reliability as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/robustness.py

@@ -1,731 +1,19 @@
-"""Analyse de robustesse des moteurs OCR face aux dégradations d'image.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.robustness`.
 
-Fonctionnement
---------------
-1. Génération de versions dégradées des images du corpus à différents niveaux :
-   - Bruit gaussien (sigma croissant)
-   - Flou gaussien (kernel size croissant)
-   - Rotation (angle croissant)
-   - Réduction de résolution (facteur de downscaling)
-   - Binarisation (seuillage Otsu ou fixe)
-2. Exécution du moteur OCR sur chaque version dégradée
-3. Calcul du CER pour chaque niveau de dégradation
-4. Génération de courbes de robustesse (CER en fonction du niveau)
-5. Identification du seuil critique (niveau à partir duquel CER > seuil)
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.robustness import ...``) de continuer
+à fonctionner sans modification.
 
-Usage
------
->>> from picarones.core.robustness import RobustnessAnalyzer
->>> analyzer = RobustnessAnalyzer(engine, degradation_types=["noise", "blur"])
->>> report = analyzer.analyze(corpus)
->>> print(report.critical_thresholds)
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
+from picarones.measurements.robustness import *  # noqa: F401, F403
 
-import logging
-import math
-import os
-import tempfile
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import TYPE_CHECKING, Optional
-
-if TYPE_CHECKING:
-    from picarones.core.corpus import Corpus, Document
-    from picarones.engines.base import BaseOCREngine
-
-logger = logging.getLogger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# Paramètres de dégradation
-# ---------------------------------------------------------------------------
-
-# Niveaux de dégradation pour chaque type
-DEGRADATION_LEVELS: dict[str, list] = {
-    "noise": [0, 5, 15, 30, 50, 80],          # sigma du bruit gaussien
-    "blur": [0, 1, 2, 3, 5, 8],               # rayon du flou gaussien (pixels)
-    "rotation": [0, 1, 2, 5, 10, 20],         # angle de rotation (degrés)
-    "resolution": [1.0, 0.75, 0.5, 0.33, 0.25, 0.1],  # facteur de résolution
-    "binarization": [0, 64, 96, 128, 160, 192],  # seuil de binarisation (0 = Otsu)
-}
-
-DEGRADATION_LABELS: dict[str, list[str]] = {
-    "noise": ["original", "σ=5", "σ=15", "σ=30", "σ=50", "σ=80"],
-    "blur": ["original", "r=1", "r=2", "r=3", "r=5", "r=8"],
-    "rotation": ["0°", "1°", "2°", "5°", "10°", "20°"],
-    "resolution": ["100%", "75%", "50%", "33%", "25%", "10%"],
-    "binarization": ["original", "seuil=64", "seuil=96", "seuil=128", "seuil=160", "seuil=192"],
-}
-
-ALL_DEGRADATION_TYPES = list(DEGRADATION_LEVELS.keys())
-
-
-# ---------------------------------------------------------------------------
-# Dégradation d'image (pure Python + stdlib, optionnellement Pillow/NumPy)
-# ---------------------------------------------------------------------------
-
-def _apply_gaussian_noise(pixels: list[list[list[int]]], sigma: float, rng_seed: int = 0) -> list[list[list[int]]]:
-    """Applique du bruit gaussien (pure Python)."""
-    import random
-    rng = random.Random(rng_seed)
-    h = len(pixels)
-    w = len(pixels[0]) if h > 0 else 0
-    result = []
-    for y in range(h):
-        row = []
-        for x in range(w):
-            pixel = []
-            for c in pixels[y][x]:
-                noise = rng.gauss(0, sigma)
-                val = int(c + noise)
-                pixel.append(max(0, min(255, val)))
-            row.append(pixel)
-        result.append(row)
-    return result
-
-
-def _apply_box_blur(pixels: list[list[list[int]]], radius: int) -> list[list[list[int]]]:
-    """Applique un flou de boîte (approximation du flou gaussien, pure Python)."""
-    if radius <= 0:
-        return pixels
-    h = len(pixels)
-    w = len(pixels[0]) if h > 0 else 0
-    channels = len(pixels[0][0]) if h > 0 and w > 0 else 3
-
-    def blur_pass(data: list[list[list[int]]]) -> list[list[list[int]]]:
-        out = []
-        for y in range(h):
-            row = []
-            for x in range(w):
-                totals = [0] * channels
-                count = 0
-                for dy in range(-radius, radius + 1):
-                    for dx in range(-radius, radius + 1):
-                        ny, nx = y + dy, x + dx
-                        if 0 <= ny < h and 0 <= nx < w:
-                            for c in range(channels):
-                                totals[c] += data[ny][nx][c]
-                            count += 1
-                row.append([t // count for t in totals])
-            out.append(row)
-        return out
-
-    return blur_pass(pixels)
-
-
-def _apply_rotation_simple(pixels: list[list[list[int]]], angle_deg: float) -> list[list[list[int]]]:
-    """Rotation avec interpolation au plus proche voisin (pure Python).
-
-    Pour des angles faibles, l'effet est réaliste.
-    """
-    if angle_deg == 0:
-        return pixels
-    h = len(pixels)
-    w = len(pixels[0]) if h > 0 else 0
-    channels = len(pixels[0][0]) if h > 0 and w > 0 else 3
-
-    angle_rad = math.radians(angle_deg)
-    cos_a = math.cos(angle_rad)
-    sin_a = math.sin(angle_rad)
-    cx, cy = w / 2, h / 2
-
-    result = [[[245, 240, 232][:channels] for _ in range(w)] for _ in range(h)]
-    for y in range(h):
-        for x in range(w):
-            # Coordonnées source
-            sx = cos_a * (x - cx) + sin_a * (y - cy) + cx
-            sy = -sin_a * (x - cx) + cos_a * (y - cy) + cy
-            ix, iy = int(round(sx)), int(round(sy))
-            if 0 <= ix < w and 0 <= iy < h:
-                result[y][x] = list(pixels[iy][ix])
-    return result
-
-
-def _apply_resolution_reduction(
-    pixels: list[list[list[int]]], factor: float
-) -> list[list[list[int]]]:
-    """Réduit la résolution puis remonte à la taille originale (pixelisation)."""
-    if factor >= 1.0:
-        return pixels
-    h = len(pixels)
-    w = len(pixels[0]) if h > 0 else 0
-    new_h = max(1, int(h * factor))
-    new_w = max(1, int(w * factor))
-
-    # Downscale
-    small = []
-    for y in range(new_h):
-        row = []
-        src_y = int(y / factor)
-        for x in range(new_w):
-            src_x = int(x / factor)
-            row.append(list(pixels[min(src_y, h - 1)][min(src_x, w - 1)]))
-        small.append(row)
-
-    # Upscale (nearest-neighbor)
-    result = []
-    for y in range(h):
-        row = []
-        src_y = min(int(y * factor), new_h - 1)
-        for x in range(w):
-            src_x = min(int(x * factor), new_w - 1)
-            row.append(list(small[src_y][src_x]))
-        result.append(row)
-    return result
-
-
-def _apply_binarization(
-    pixels: list[list[list[int]]], threshold: int
-) -> list[list[list[int]]]:
-    """Binarise l'image (seuillage fixe sur luminosité)."""
-    h = len(pixels)
-    w = len(pixels[0]) if h > 0 else 0
-    result = []
-
-    # Calculer le seuil Otsu si threshold == 0
-    if threshold == 0:
-        histogram = [0] * 256
-        total = h * w
-        for y in range(h):
-            for x in range(w):
-                p = pixels[y][x]
-                lum = int(0.299 * p[0] + 0.587 * p[1] + 0.114 * p[2]) if len(p) >= 3 else p[0]
-                histogram[lum] += 1
-        # Otsu simplifié
-        best_thresh = 128
-        best_var = -1.0
-        total_sum = sum(i * histogram[i] for i in range(256))
-        w0, w1, sum0 = 0, total, 0.0
-        for t in range(256):
-            w0 += histogram[t]
-            if w0 == 0:
-                continue
-            w1 = total - w0
-            if w1 == 0:
-                break
-            sum0 += t * histogram[t]
-            mean0 = sum0 / w0
-            mean1 = (total_sum - sum0) / w1
-            var = w0 * w1 * (mean0 - mean1) ** 2
-            if var > best_var:
-                best_var = var
-                best_thresh = t
-        threshold = best_thresh
-
-    for y in range(h):
-        row = []
-        for x in range(w):
-            p = pixels[y][x]
-            lum = int(0.299 * p[0] + 0.587 * p[1] + 0.114 * p[2]) if len(p) >= 3 else p[0]
-            val = 255 if lum >= threshold else 0
-            row.append([val] * len(p))
-        result.append(row)
-    return result
-
-
-def degrade_image_bytes(
-    png_bytes: bytes,
-    degradation_type: str,
-    level: float,
-) -> bytes:
-    """Dégrade une image PNG et retourne les bytes PNG modifiés.
-
-    Utilise Pillow si disponible, sinon utilise l'implémentation pure Python.
-
-    Parameters
-    ----------
-    png_bytes:
-        Bytes de l'image PNG source.
-    degradation_type:
-        Type de dégradation (``"noise"``, ``"blur"``, ``"rotation"``,
-        ``"resolution"``, ``"binarization"``).
-    level:
-        Niveau de dégradation (valeur numérique selon le type).
-
-    Returns
-    -------
-    bytes
-        Bytes de l'image PNG dégradée.
-    """
-    try:
-        return _degrade_pillow(png_bytes, degradation_type, level)
-    except ImportError:
-        return _degrade_pure_python(png_bytes, degradation_type, level)
-
-
-def _degrade_pillow(png_bytes: bytes, degradation_type: str, level: float) -> bytes:
-    """Dégradation avec Pillow (meilleure qualité)."""
-    import io
-    from PIL import Image, ImageFilter
-
-    img = Image.open(io.BytesIO(png_bytes)).convert("RGB")
-
-    if degradation_type == "noise":
-        if level > 0:
-            import random
-            # RGB : 3 octets par pixel, tobytes() reste stable Pillow 10 → 14+
-            raw = img.tobytes()
-            rng = random.Random(0)
-            noisy = []
-            for i in range(0, len(raw), 3):
-                r, g, b = raw[i], raw[i + 1], raw[i + 2]
-                noisy.append((
-                    max(0, min(255, int(r + rng.gauss(0, level)))),
-                    max(0, min(255, int(g + rng.gauss(0, level)))),
-                    max(0, min(255, int(b + rng.gauss(0, level)))),
-                ))
-            img.putdata(noisy)
-
-    elif degradation_type == "blur":
-        if level > 0:
-            img = img.filter(ImageFilter.GaussianBlur(radius=level))
-
-    elif degradation_type == "rotation":
-        if level != 0:
-            img = img.rotate(-level, expand=False, fillcolor=(245, 240, 232))
-
-    elif degradation_type == "resolution":
-        if level < 1.0:
-            w, h = img.size
-            new_w, new_h = max(1, int(w * level)), max(1, int(h * level))
-            img = img.resize((new_w, new_h), Image.NEAREST)
-            img = img.resize((w, h), Image.NEAREST)
-
-    elif degradation_type == "binarization":
-        img = img.convert("L")  # niveaux de gris
-        if level == 0:
-            # Seuillage Otsu : calcul du seuil optimal
-            histogram = img.histogram()
-            total = img.size[0] * img.size[1]
-            best_thresh, best_var = 128, -1.0
-            total_sum = sum(i * histogram[i] for i in range(256))
-            w0, sum0 = 0, 0.0
-            for t in range(256):
-                w0 += histogram[t]
-                if w0 == 0:
-                    continue
-                w1 = total - w0
-                if w1 == 0:
-                    break
-                sum0 += t * histogram[t]
-                var = w0 * w1 * (sum0 / w0 - (total_sum - sum0) / w1) ** 2
-                if var > best_var:
-                    best_var = var
-                    best_thresh = t
-            threshold = best_thresh
-        else:
-            threshold = int(level)
-        img = img.point(lambda p: 255 if p >= threshold else 0, "1").convert("RGB")
-
-    buf = io.BytesIO()
-    img.save(buf, format="PNG")
-    return buf.getvalue()
-
-
-def _degrade_pure_python(png_bytes: bytes, degradation_type: str, level: float) -> bytes:
-    """Dégradation en pur Python (sans Pillow).
-
-    Décode le PNG, applique la transformation, ré-encode en PNG.
-    Note : n'implémente pas le décodage PNG complet — utilise des stubs.
-    """
-    # Pour l'implémentation pure Python, on applique des transformations
-    # minimales sur les bytes bruts en créant une image de test synthétique.
-    # En pratique, Pillow est presque toujours disponible dans l'environnement Picarones.
-    logger.warning(
-        "Pillow non disponible : dégradation '%s' appliquée en mode dégradé (stub)",
-        degradation_type,
-    )
-    # Retourner l'image originale légèrement modifiée (simulation)
-    return png_bytes
-
-
-# ---------------------------------------------------------------------------
-# Structures de résultats
-# ---------------------------------------------------------------------------
-
-@dataclass
-class DegradationCurve:
-    """Courbe CER vs niveau de dégradation pour un moteur et un type de dégradation."""
-    engine_name: str
-    degradation_type: str
-    levels: list[float]
-    labels: list[str]
-    cer_values: list[Optional[float]]
-    """CER moyen (0-1) à chaque niveau. None si calcul impossible."""
-    critical_threshold_level: Optional[float] = None
-    """Niveau à partir duquel CER > cer_threshold."""
-    cer_threshold: float = 0.20
-    """Seuil de CER utilisé pour déterminer le niveau critique."""
-
-    def as_dict(self) -> dict:
-        return {
-            "engine_name": self.engine_name,
-            "degradation_type": self.degradation_type,
-            "levels": self.levels,
-            "labels": self.labels,
-            "cer_values": self.cer_values,
-            "critical_threshold_level": self.critical_threshold_level,
-            "cer_threshold": self.cer_threshold,
-        }
-
-
-@dataclass
-class RobustnessReport:
-    """Rapport complet d'analyse de robustesse pour un ou plusieurs moteurs."""
-    engine_names: list[str]
-    corpus_name: str
-    degradation_types: list[str]
-    curves: list[DegradationCurve]
-    summary: dict = field(default_factory=dict)
-    """Résumé : moteur le plus robuste par type de dégradation, seuils critiques…"""
-
-    def get_curves_for_engine(self, engine_name: str) -> list[DegradationCurve]:
-        return [c for c in self.curves if c.engine_name == engine_name]
-
-    def get_curves_for_type(self, degradation_type: str) -> list[DegradationCurve]:
-        return [c for c in self.curves if c.degradation_type == degradation_type]
-
-    def as_dict(self) -> dict:
-        return {
-            "engine_names": self.engine_names,
-            "corpus_name": self.corpus_name,
-            "degradation_types": self.degradation_types,
-            "curves": [c.as_dict() for c in self.curves],
-            "summary": self.summary,
-        }
-
-
-# ---------------------------------------------------------------------------
-# Analyseur de robustesse
-# ---------------------------------------------------------------------------
-
-class RobustnessAnalyzer:
-    """Lance une analyse de robustesse sur un corpus.
-
-    Parameters
-    ----------
-    engines:
-        Un ou plusieurs moteurs OCR (``BaseOCREngine``).
-    degradation_types:
-        Liste des types de dégradation à tester.
-        Par défaut : tous (``"noise"``, ``"blur"``, ``"rotation"``,
-        ``"resolution"``, ``"binarization"``).
-    cer_threshold:
-        Seuil de CER pour définir le niveau critique (défaut : 0.20 = 20%).
-    custom_levels:
-        Niveaux personnalisés par type (remplace les valeurs par défaut).
-
-    Examples
-    --------
-    >>> from picarones.engines.tesseract import TesseractEngine
-    >>> from picarones.core.robustness import RobustnessAnalyzer
-    >>> engine = TesseractEngine(config={"lang": "fra"})
-    >>> analyzer = RobustnessAnalyzer([engine], degradation_types=["noise", "blur"])
-    >>> report = analyzer.analyze(corpus)
-    """
-
-    def __init__(
-        self,
-        engines: "list[BaseOCREngine]",
-        degradation_types: Optional[list[str]] = None,
-        cer_threshold: float = 0.20,
-        custom_levels: Optional[dict[str, list]] = None,
-    ) -> None:
-        if not isinstance(engines, list):
-            engines = [engines]
-        self.engines = engines
-        self.degradation_types = degradation_types or ALL_DEGRADATION_TYPES
-        self.cer_threshold = cer_threshold
-        self.levels = dict(DEGRADATION_LEVELS)
-        if custom_levels:
-            self.levels.update(custom_levels)
-
-    def analyze(
-        self,
-        corpus: "Corpus",
-        show_progress: bool = True,
-        max_docs: int = 10,
-    ) -> RobustnessReport:
-        """Lance l'analyse de robustesse sur le corpus.
-
-        Parameters
-        ----------
-        corpus:
-            Corpus Picarones avec images et GT.
-        show_progress:
-            Affiche la progression.
-        max_docs:
-            Nombre maximum de documents à traiter (pour la rapidité).
-
-        Returns
-        -------
-        RobustnessReport
-        """
-        from picarones.core.metrics import compute_metrics
-
-        docs = corpus.documents[:max_docs]
-        curves: list[DegradationCurve] = []
-
-        for engine in self.engines:
-            for deg_type in self.degradation_types:
-                levels = self.levels[deg_type]
-                labels = DEGRADATION_LABELS.get(deg_type, [str(lv) for lv in levels])
-
-                cer_per_level: list[Optional[float]] = []
-
-                if show_progress:
-                    try:
-                        from tqdm import tqdm
-                        level_iter = tqdm(
-                            list(enumerate(levels)),
-                            desc=f"{engine.name} / {deg_type}",
-                        )
-                    except ImportError:
-                        level_iter = enumerate(levels)
-                else:
-                    level_iter = enumerate(levels)
-
-                for lvl_idx, level in level_iter:
-                    doc_cers: list[float] = []
-
-                    for doc in docs:
-                        gt = doc.ground_truth.strip()
-                        if not gt:
-                            continue
-
-                        # Obtenir l'image (fichier ou data URI)
-                        degraded_bytes = self._get_degraded_image(
-                            doc, deg_type, level
-                        )
-                        if degraded_bytes is None:
-                            continue
-
-                        # Sauvegarder temporairement et OCR
-                        with tempfile.NamedTemporaryFile(
-                            suffix=".png", delete=False
-                        ) as tmp:
-                            tmp.write(degraded_bytes)
-                            tmp_path = tmp.name
-
-                        try:
-                            ocr_result = engine.run(tmp_path)
-                            hypothesis = ocr_result.text
-                            metrics = compute_metrics(gt, hypothesis)
-                            doc_cers.append(metrics.cer)
-                        except Exception as exc:
-                            logger.debug(
-                                "Erreur OCR %s niveau %s=%s: %s",
-                                engine.name, deg_type, level, exc
-                            )
-                        finally:
-                            try:
-                                os.unlink(tmp_path)
-                            except OSError:
-                                pass
-
-                    if doc_cers:
-                        cer_per_level.append(sum(doc_cers) / len(doc_cers))
-                    else:
-                        cer_per_level.append(None)
-
-                # Calculer le niveau critique
-                critical = self._find_critical_level(
-                    levels, cer_per_level, self.cer_threshold
-                )
-
-                curves.append(DegradationCurve(
-                    engine_name=engine.name,
-                    degradation_type=deg_type,
-                    levels=levels,
-                    labels=labels[:len(levels)],
-                    cer_values=cer_per_level,
-                    critical_threshold_level=critical,
-                    cer_threshold=self.cer_threshold,
-                ))
-
-        summary = self._build_summary(curves)
-
-        return RobustnessReport(
-            engine_names=[e.name for e in self.engines],
-            corpus_name=corpus.name,
-            degradation_types=self.degradation_types,
-            curves=curves,
-            summary=summary,
-        )
-
-    def _get_degraded_image(
-        self,
-        doc: "Document",
-        degradation_type: str,
-        level: float,
-    ) -> Optional[bytes]:
-        """Retourne les bytes PNG de l'image dégradée."""
-        # Charger l'image originale
-        original_bytes = self._load_image(doc)
-        if original_bytes is None:
-            return None
-
-        # Niveau 0 = image originale (sauf binarisation à 0 = Otsu)
-        if (degradation_type == "noise" and level == 0) or \
-           (degradation_type == "blur" and level == 0) or \
-           (degradation_type == "rotation" and level == 0) or \
-           (degradation_type == "resolution" and level >= 1.0):
-            return original_bytes
-
-        return degrade_image_bytes(original_bytes, degradation_type, level)
-
-    def _load_image(self, doc: "Document") -> Optional[bytes]:
-        """Charge les bytes PNG de l'image d'un document."""
-        img_path = doc.image_path
-
-        # Data URI (base64)
-        if img_path.startswith("data:image/"):
-            import base64
-            try:
-                _, b64 = img_path.split(",", 1)
-                return base64.b64decode(b64)
-            except Exception as exc:
-                logger.debug("Impossible de décoder data URI: %s", exc)
-                return None
-
-        # Fichier local
-        path = Path(img_path)
-        if path.exists():
-            return path.read_bytes()
-
-        logger.debug("Image introuvable : %s", img_path)
-        return None
-
-    @staticmethod
-    def _find_critical_level(
-        levels: list[float],
-        cer_values: list[Optional[float]],
-        threshold: float,
-    ) -> Optional[float]:
-        """Trouve le niveau à partir duquel CER dépasse le seuil."""
-        for level, cer in zip(levels, cer_values):
-            if cer is not None and cer > threshold:
-                return level
-        return None
-
-    @staticmethod
-    def _build_summary(curves: list[DegradationCurve]) -> dict:
-        """Construit le résumé de l'analyse."""
-        summary: dict = {}
-
-        # Par type de dégradation : moteur le plus robuste
-        by_type: dict[str, dict[str, list]] = {}
-        for curve in curves:
-            dt = curve.degradation_type
-            if dt not in by_type:
-                by_type[dt] = {}
-            valid_cers = [c for c in curve.cer_values if c is not None]
-            if valid_cers:
-                by_type[dt][curve.engine_name] = valid_cers
-
-        for dt, engine_cers in by_type.items():
-            if not engine_cers:
-                continue
-            # Robustesse = CER moyen sur tous les niveaux (plus bas = plus robuste)
-            best_engine = min(engine_cers, key=lambda e: sum(engine_cers[e]) / len(engine_cers[e]))
-            summary[f"most_robust_{dt}"] = best_engine
-
-        # Seuils critiques par moteur
-        for curve in curves:
-            key = f"critical_{curve.engine_name}_{curve.degradation_type}"
-            summary[key] = curve.critical_threshold_level
-
-        return summary
-
-
-# ---------------------------------------------------------------------------
-# Données de démonstration de robustesse
-# ---------------------------------------------------------------------------
-
-def generate_demo_robustness_report(
-    engine_names: Optional[list[str]] = None,
-    seed: int = 42,
-) -> RobustnessReport:
-    """Génère un rapport de robustesse fictif mais réaliste pour la démo.
-
-    Parameters
-    ----------
-    engine_names:
-        Noms des moteurs à simuler (défaut : tesseract, pero_ocr).
-    seed:
-        Graine aléatoire.
-
-    Returns
-    -------
-    RobustnessReport
-    """
-    import random
-    rng = random.Random(seed)
-
-    if engine_names is None:
-        engine_names = ["tesseract", "pero_ocr"]
-
-    # CER de base par moteur
-    base_cer = {
-        "tesseract": 0.12,
-        "pero_ocr": 0.07,
-        "ancien_moteur": 0.25,
-    }
-
-    # Sensibilité par type de dégradation (facteur multiplicatif par niveau)
-    sensitivity = {
-        "tesseract": {
-            "noise": 0.04, "blur": 0.05, "rotation": 0.06,
-            "resolution": 0.12, "binarization": 0.03,
-        },
-        "pero_ocr": {
-            "noise": 0.02, "blur": 0.03, "rotation": 0.04,
-            "resolution": 0.08, "binarization": 0.02,
-        },
-        "ancien_moteur": {
-            "noise": 0.06, "blur": 0.08, "rotation": 0.10,
-            "resolution": 0.15, "binarization": 0.05,
-        },
-    }
-
-    deg_types = ALL_DEGRADATION_TYPES
-    curves: list[DegradationCurve] = []
-
-    for engine_name in engine_names:
-        cer_base = base_cer.get(engine_name, 0.15)
-        sens = sensitivity.get(engine_name, {dt: 0.05 for dt in deg_types})
-
-        for deg_type in deg_types:
-            levels = DEGRADATION_LEVELS[deg_type]
-            labels = DEGRADATION_LABELS[deg_type]
-            s = sens.get(deg_type, 0.05)
-
-            cer_values = []
-            for i, level in enumerate(levels):
-                noise = rng.gauss(0, 0.005)
-                cer = min(1.0, cer_base + s * i + noise)
-                cer_values.append(round(max(0.0, cer), 4))
-
-            critical = RobustnessAnalyzer._find_critical_level(levels, cer_values, 0.20)
-
-            curves.append(DegradationCurve(
-                engine_name=engine_name,
-                degradation_type=deg_type,
-                levels=list(levels),
-                labels=labels[:len(levels)],
-                cer_values=cer_values,
-                critical_threshold_level=critical,
-                cer_threshold=0.20,
-            ))
-
-    summary = RobustnessAnalyzer._build_summary(curves)
-
-    return RobustnessReport(
-        engine_names=engine_names,
-        corpus_name="Corpus de démonstration — Chroniques médiévales",
-        degradation_types=deg_types,
-        curves=curves,
-        summary=summary,
-    )
+import picarones.measurements.robustness as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/robustness_projection.py

@@ -1,287 +1,19 @@
-"""Projection de robustesse synthétique sur le corpus réel —
-Sprint 81 (A.I.8).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.robustness_projection`.
 
-Sprint 81 — A.I.8 du plan d'évolution 2026.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.robustness_projection import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-Le module ``picarones/core/robustness.py`` (Sprint 8) génère des
-courbes CER vs niveau de dégradation **synthétique** (bruit, flou,
-rotation, résolution).  ``picarones/core/image_quality.py`` mesure
-le bruit/flou/contraste **réels** des images du corpus.  Ce
-sprint **projette** les caractéristiques réelles sur les courbes
-synthétiques pour estimer le **déficit attendu de CER** sur le
-corpus dans son état actuel.
-
-Lecture concrète
-----------------
-*« 30 % de vos documents ont un bruit équivalent à σ=15 où
-Tesseract perd 8 points de CER — soit un déficit attendu global
-de 2,4 points (30 % × 8 points). »*
-
-Méthode
--------
-1. Pour chaque document, on extrait la valeur de qualité réelle
-   (``noise_level``, ``blur_score``, ``contrast_score``…) depuis
-   ``ImageQualityResult``.
-2. Pour chaque type de dégradation, on interpole linéairement la
-   ``DegradationCurve`` synthétique : CER attendu à ce niveau.
-3. On agrège : CER moyen attendu, % docs au-dessus du seuil
-   critique de la courbe, déficit projeté = CER_attendu -
-   CER_baseline (niveau nul).
-
-Sortie
-------
-``project_robustness_on_corpus(curves, image_qualities)`` retourne
-``{engine_name: {degradation_type: {expected_cer_mean,
-deficit_vs_baseline, n_docs_above_critical, n_docs}}}``.
-
-Limites
--------
-- Mapping ``image_quality → degradation level`` : on suppose que
-  ``noise_level`` (ImageQualityResult) correspond à σ
-  (DegradationCurve), et idem pour ``blur_score`` ↔ rayon de
-  flou.  Si un corpus expose ces valeurs avec une échelle
-  différente, le mapping est documenté et l'utilisateur peut
-  passer ``quality_to_level`` custom.
-- Interpolation **linéaire** entre les points de la courbe.  Au-
-  delà des bornes, on **clip** au point extrême (pas
-  d'extrapolation hasardeuse).
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-import statistics
-from typing import Callable, Iterable, Optional
-
-logger = logging.getLogger(__name__)
-
-
-# Mapping par défaut entre attributs ImageQualityResult et types
-# de dégradation synthétique.  L'utilisateur peut passer un dict
-# custom pour modifier ce mapping.
-_DEFAULT_QUALITY_FIELD: dict[str, str] = {
-    "noise":      "noise_level",       # σ
-    "blur":       "blur_score",        # Variance laplacienne (inverse)
-    "contrast":   "contrast_score",
-    "rotation":   "rotation_angle",
-    "resolution": "resolution_score",  # peut être absent
-}
-
-
-def _interpolate_cer(
-    levels: list[float],
-    cer_values: list[Optional[float]],
-    target_level: float,
-) -> Optional[float]:
-    """Interpolation linéaire : retourne CER attendu à
-    ``target_level``.
-
-    - Si ``target_level`` est en-dessous du minimum de levels,
-      retourne le CER au minimum (clip).
-    - Si au-dessus du maximum, retourne le CER au maximum.
-    - Sinon, interpolation linéaire entre les deux points
-      encadrants.
-    - Retourne ``None`` si aucun ``cer_value`` valide.
-    """
-    if not levels:
-        return None
-    # Filtrer les paires (level, cer) où cer est None
-    pairs = [
-        (lvl, cer) for lvl, cer in zip(levels, cer_values)
-        if cer is not None
-    ]
-    if not pairs:
-        return None
-    pairs.sort(key=lambda p: p[0])
-    # Clip
-    if target_level <= pairs[0][0]:
-        return pairs[0][1]
-    if target_level >= pairs[-1][0]:
-        return pairs[-1][1]
-    # Interpolation
-    for i in range(len(pairs) - 1):
-        lo_lvl, lo_cer = pairs[i]
-        hi_lvl, hi_cer = pairs[i + 1]
-        if lo_lvl <= target_level <= hi_lvl:
-            if hi_lvl == lo_lvl:
-                return lo_cer
-            ratio = (target_level - lo_lvl) / (hi_lvl - lo_lvl)
-            return lo_cer + (hi_cer - lo_cer) * ratio
-    return None  # ne devrait pas arriver
-
-
-def _extract_quality_value(
-    quality: dict, degradation_type: str,
-    custom_mapping: Optional[dict[str, str]] = None,
-) -> Optional[float]:
-    """Extrait la valeur de qualité pertinente pour un type de
-    dégradation depuis un ``ImageQualityResult.as_dict()``."""
-    mapping = custom_mapping or _DEFAULT_QUALITY_FIELD
-    field = mapping.get(degradation_type)
-    if field is None:
-        return None
-    value = quality.get(field)
-    if value is None:
-        return None
-    try:
-        return float(value)
-    except (TypeError, ValueError):
-        return None
-
-
-def project_robustness_on_corpus(
-    curves: Iterable,
-    image_qualities: list[dict],
-    *,
-    quality_to_level: Optional[Callable[[dict, str], Optional[float]]] = None,
-    critical_threshold: Optional[float] = None,
-) -> dict:
-    """Projette les courbes de robustesse sur les qualités réelles.
-
-    Parameters
-    ----------
-    curves:
-        Itérable de ``DegradationCurve`` (ou dicts compatibles
-        avec ``engine_name``, ``degradation_type``, ``levels``,
-        ``cer_values``, ``critical_threshold_level``).
-    image_qualities:
-        Liste de dicts ``ImageQualityResult.as_dict()`` (un par
-        document).  Si vide, retourne une projection vide.
-    quality_to_level:
-        Fonction custom ``(quality_dict, degradation_type) →
-        Optional[float]`` pour adapter le mapping qualité→niveau.
-        Par défaut, utilise ``_DEFAULT_QUALITY_FIELD``.
-    critical_threshold:
-        Override pour le seuil critique de CER (défaut : utilise
-        ``DegradationCurve.cer_threshold``).
-
-    Returns
-    -------
-    dict
-        ``{
-            engine_name: {
-                degradation_type: {
-                    "n_docs": int,
-                    "n_docs_with_data": int,    # qualité disponible
-                    "expected_cer_mean": float, # moyenne CER attendu
-                    "expected_cer_median": float,
-                    "baseline_cer": float,      # CER à niveau min
-                    "deficit_vs_baseline": float,
-                    "n_docs_above_critical": int,
-                    "critical_threshold_level": float | None,
-                    "critical_threshold_cer": float,
-                },
-            },
-        }``
-    """
-    extractor = quality_to_level or (
-        lambda q, dt: _extract_quality_value(q, dt)
-    )
-    out: dict[str, dict] = {}
-
-    for curve in curves:
-        # Accepter dict ou DegradationCurve
-        if hasattr(curve, "as_dict"):
-            data = curve.as_dict()
-        else:
-            data = curve
-        engine = data.get("engine_name")
-        deg_type = data.get("degradation_type")
-        levels = data.get("levels") or []
-        cer_values = data.get("cer_values") or []
-        crit_lvl = data.get("critical_threshold_level")
-        crit_cer = (
-            critical_threshold
-            if critical_threshold is not None
-            else data.get("cer_threshold", 0.20)
-        )
-        if not engine or not deg_type:
-            continue
-
-        per_doc_cer: list[float] = []
-        n_docs_with_data = 0
-        n_above_critical = 0
-        for quality in image_qualities:
-            level = extractor(quality, deg_type)
-            if level is None:
-                continue
-            n_docs_with_data += 1
-            cer = _interpolate_cer(levels, cer_values, level)
-            if cer is None:
-                continue
-            per_doc_cer.append(cer)
-            if cer > crit_cer:
-                n_above_critical += 1
-
-        if not per_doc_cer:
-            continue
-
-        # Baseline = CER au niveau minimum (sans dégradation)
-        baseline = _interpolate_cer(
-            levels, cer_values,
-            min(levels) if levels else 0.0,
-        )
-        expected_mean = statistics.fmean(per_doc_cer)
-        expected_median = statistics.median(per_doc_cer)
-        deficit = (
-            expected_mean - baseline
-            if baseline is not None else None
-        )
-
-        out.setdefault(engine, {})[deg_type] = {
-            "n_docs": len(image_qualities),
-            "n_docs_with_data": n_docs_with_data,
-            "expected_cer_mean": expected_mean,
-            "expected_cer_median": expected_median,
-            "baseline_cer": baseline,
-            "deficit_vs_baseline": deficit,
-            "n_docs_above_critical": n_above_critical,
-            "critical_threshold_level": crit_lvl,
-            "critical_threshold_cer": crit_cer,
-        }
-    return out
-
-
-def aggregate_projection_per_engine(projection: dict) -> dict:
-    """Pour chaque moteur, agrège le déficit projeté en sommant
-    sur tous les types de dégradation.
-
-    Lecture : *« déficit total attendu pour Tesseract = 5,2 points
-    de CER si on considère les 4 dégradations indépendamment »*.
-
-    Note : la sommation **suppose l'indépendance** des
-    dégradations, ce qui n'est pas strictement vrai mais reste
-    une approximation utile pour le diagnostic.
-    """
-    out: dict[str, dict] = {}
-    for engine, per_type in projection.items():
-        total_deficit = 0.0
-        n_types_with_data = 0
-        max_deficit_type: Optional[tuple[str, float]] = None
-        for deg_type, stats in per_type.items():
-            deficit = stats.get("deficit_vs_baseline")
-            if deficit is None:
-                continue
-            total_deficit += deficit
-            n_types_with_data += 1
-            if max_deficit_type is None or deficit > max_deficit_type[1]:
-                max_deficit_type = (deg_type, deficit)
-        out[engine] = {
-            "total_expected_deficit": total_deficit,
-            "n_degradation_types": n_types_with_data,
-            "worst_degradation_type": (
-                max_deficit_type[0] if max_deficit_type else None
-            ),
-            "worst_degradation_deficit": (
-                max_deficit_type[1] if max_deficit_type else None
-            ),
-        }
-    return out
-
+from picarones.measurements.robustness_projection import *  # noqa: F401, F403
 
-__all__ = [
-    "project_robustness_on_corpus",
-    "aggregate_projection_per_engine",
-]
+import picarones.measurements.robustness_projection as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/searchability.py

@@ -1,225 +1,19 @@
-"""Recherchabilité fuzzy — Sprint 84 (A.II.5).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.searchability`.
 
-Sprint 84 — A.II.5 du plan d'évolution 2026.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.searchability import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-Le CER mesure les erreurs caractère par caractère.  Mais pour
-un usage *recherche plein-texte* (ce que font Elastic, Solr en
-mode fuzzy, ou la recherche full-text de Gallica), la question
-réelle est :
-
-    *« Combien de mots de ma GT sont retrouvables dans la
-    sortie OCR, à orthographe approchée près ? »*
-
-Un CER de 8 % peut donner 95 % de findability si les erreurs
-sont concentrées sur des caractères non-significatifs ou sur
-quelques mots aberrants ; à l'inverse, 4 % de CER mais
-distribué sur tous les noms propres rend le corpus inutilisable
-pour l'indexation prosopographique.
-
-Méthode
--------
-Pour chaque token GT, on regarde s'il existe au moins un token
-hypothèse à distance de Levenshtein ≤ ``max_distance`` (défaut
-2, valeur Elastic ``fuzziness: AUTO`` standard pour mots ≥ 5
-caractères).  Le **rappel** est la proportion de tokens GT
-ainsi retrouvés.
-
-Multiplicité
-------------
-Si la GT contient *« le »* deux fois et l'hypothèse une fois,
-seul un token GT est compté comme retrouvé (alignement
-multi-set, comme ``rare_token_recall`` Sprint 71).
-
-Sortie
-------
-``compute_searchability(reference, hypothesis)`` retourne
-``{n_gt_tokens, n_searchable, recall, missed_tokens}``.
-
-Limites documentées
--------------------
-- Tokenisation par split sur whitespace (cohérent avec le reste
-  du codebase).  Pas de stemming ni de lemmatisation.
-- Levenshtein non pondéré — substitution = insertion = suppression
-  = 1.  Pour un poids différent (par ex. faute classique
-  diacritique = 0,5), passer une fonction custom.
-- Pas de sémantique : *« roi »* ≠ *« souverain »*.  Pour la
-  similarité sémantique, voir des modules futurs (BERTScore).
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-from typing import Optional
-
-from picarones.core.metric_registry import register_metric
-from picarones.core.modules import ArtifactType
-
-logger = logging.getLogger(__name__)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Tokenisation et distance d'édition
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def _split_words(text: Optional[str]) -> list[str]:
-    """Tokenisation par whitespace — cohérent avec
-    ``lexical_modernization.py``, ``rare_tokens.py``, etc."""
-    if not text:
-        return []
-    return text.split()
-
-
-def levenshtein_distance(a: str, b: str) -> int:
-    """Distance de Levenshtein (substitution=insertion=suppression=1).
-
-    Implémentation DP O(|a|·|b|) en mémoire O(min(|a|,|b|)).
-    """
-    if a == b:
-        return 0
-    if len(a) < len(b):
-        a, b = b, a
-    # |a| ≥ |b|
-    if not b:
-        return len(a)
-    previous = list(range(len(b) + 1))
-    for i, ca in enumerate(a, start=1):
-        current = [i] + [0] * len(b)
-        for j, cb in enumerate(b, start=1):
-            cost = 0 if ca == cb else 1
-            current[j] = min(
-                current[j - 1] + 1,        # insertion
-                previous[j] + 1,           # suppression
-                previous[j - 1] + cost,    # substitution
-            )
-        previous = current
-    return previous[-1]
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Calcul principal
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def compute_searchability(
-    reference: Optional[str],
-    hypothesis: Optional[str],
-    *,
-    max_distance: int = 2,
-    case_sensitive: bool = False,
-) -> dict:
-    """Recherchabilité fuzzy de ``reference`` dans ``hypothesis``.
-
-    Parameters
-    ----------
-    reference, hypothesis:
-        Transcriptions GT et OCR.
-    max_distance:
-        Seuil de distance de Levenshtein (≤ pour considérer un
-        token comme retrouvé).  Défaut 2 — convention
-        ``fuzziness: AUTO`` d'Elastic pour mots ≥ 5 caractères.
-    case_sensitive:
-        Si False (défaut), casse insensible côté match — la
-        sortie ``missed_tokens`` reste avec la casse GT
-        originale.
-
-    Returns
-    -------
-    dict
-        ``{
-            "n_gt_tokens": int,
-            "n_searchable": int,
-            "recall": float | None,    # None si n_gt_tokens == 0
-            "missed_tokens": list[str],
-            "max_distance": int,
-        }``
-    """
-    if max_distance < 0:
-        raise ValueError(f"max_distance doit être ≥ 0, reçu {max_distance}")
-    gt_tokens = _split_words(reference)
-    hyp_tokens = _split_words(hypothesis)
-    n_gt = len(gt_tokens)
-    if n_gt == 0:
-        return {
-            "n_gt_tokens": 0,
-            "n_searchable": 0,
-            "recall": None,
-            "missed_tokens": [],
-            "max_distance": max_distance,
-        }
-    # Multi-set : un token hypothèse ne peut servir qu'une fois.
-    # Tri par longueur croissante pour matcher d'abord les
-    # tokens GT les plus courts (où ε-fautes sont plus rares).
-    if case_sensitive:
-        gt_for_match = list(gt_tokens)
-        hyp_for_match = list(hyp_tokens)
-    else:
-        gt_for_match = [t.lower() for t in gt_tokens]
-        hyp_for_match = [t.lower() for t in hyp_tokens]
-
-    hyp_used = [False] * len(hyp_for_match)
-    n_searchable = 0
-    missed: list[str] = []
-    for gi, gt_match in enumerate(gt_for_match):
-        # Court-circuit si match exact disponible
-        best_idx = -1
-        best_dist = max_distance + 1
-        for hi, used in enumerate(hyp_used):
-            if used:
-                continue
-            hyp_match = hyp_for_match[hi]
-            # Court-circuit longueur (Levenshtein ≥ |Δlen|)
-            if abs(len(hyp_match) - len(gt_match)) > max_distance:
-                continue
-            d = levenshtein_distance(gt_match, hyp_match)
-            if d < best_dist:
-                best_dist = d
-                best_idx = hi
-                if d == 0:
-                    break  # match exact, inutile de chercher mieux
-        if best_idx >= 0 and best_dist <= max_distance:
-            hyp_used[best_idx] = True
-            n_searchable += 1
-        else:
-            missed.append(gt_tokens[gi])
-    recall = n_searchable / n_gt
-    return {
-        "n_gt_tokens": n_gt,
-        "n_searchable": n_searchable,
-        "recall": recall,
-        "missed_tokens": missed,
-        "max_distance": max_distance,
-    }
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# Enregistrement registre typé (Sprint 34)
-# ──────────────────────────────────────────────────────────────────────────
-
-
-@register_metric(
-    name="searchability_recall",
-    input_types=(ArtifactType.TEXT, ArtifactType.TEXT),
-    description=(
-        "Recherchabilité fuzzy : proportion de tokens GT retrouvés "
-        "dans l'OCR à distance de Levenshtein ≤ 2. Proxy direct de "
-        "la qualité pour la recherche plein-texte (Elastic, Solr)."
-    ),
-)
-def searchability_recall_metric(reference: str, hypothesis: str) -> float:
-    """Variante scalaire pour le registre typé : retourne le
-    rappel en [0, 1], ou ``0.0`` si la GT est vide (convention
-    cohérente avec rare_token_recall Sprint 71).
-    """
-    result = compute_searchability(reference, hypothesis)
-    recall = result.get("recall")
-    return 0.0 if recall is None else recall
-
+from picarones.measurements.searchability import *  # noqa: F401, F403
 
-__all__ = [
-    "levenshtein_distance",
-    "compute_searchability",
-    "searchability_recall_metric",
-]
+import picarones.measurements.searchability as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/searchability_runner.py

@@ -1,81 +1,19 @@
-"""Câblage runner de la recherchabilité (Sprint 86).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.searchability_runner`.
 
-Sprint 86 — A.II.5a (vue HTML + câblage runner).
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.searchability_runner import ...``) de continuer
+à fonctionner sans modification.
 
-Le module ``picarones/core/searchability.py`` (Sprint 84) a livré
-la couche de calcul.  Ce helper prépare la donnée pour le runner
-historique et l'agrégation par moteur.
-
-Adaptive masking
-----------------
-Comme pour les modules philologiques (Sprint 61), on ne calcule
-le rappel que si la GT contient au moins un token —  pas de
-calcul vide qui produirait du bruit dans le rapport.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-from typing import Iterable, Optional
-
-from picarones.core.searchability import (
-    _split_words,
-    compute_searchability,
-)
-
-logger = logging.getLogger(__name__)
-
-
-def compute_searchability_metrics(
-    reference: Optional[str],
-    hypothesis: Optional[str],
-    *,
-    max_distance: int = 2,
-) -> Optional[dict]:
-    """Recherchabilité d'un document (adaptive).
-
-    Retourne ``None`` si la GT est vide ou ne contient aucun
-    token — ce qui déclenche l'adaptive masking côté HTML.
-    """
-    if not reference or not _split_words(reference):
-        return None
-    return compute_searchability(
-        reference, hypothesis or "", max_distance=max_distance,
-    )
-
-
-def aggregate_searchability_metrics(
-    per_doc: Iterable[Optional[dict]],
-) -> Optional[dict]:
-    """Agrège les métriques par-doc en un score corpus-wide.
-
-    Convention : on somme les ``n_gt_tokens`` et ``n_searchable``
-    et on recalcule un rappel **micro** (cohérent avec ECE/MCE
-    Sprint 39 et NER Sprint 38).
-    """
-    docs = [d for d in per_doc if d]
-    if not docs:
-        return None
-    n_gt = sum(int(d.get("n_gt_tokens") or 0) for d in docs)
-    n_search = sum(int(d.get("n_searchable") or 0) for d in docs)
-    if n_gt == 0:
-        return None
-    # On garde l'union des missed_tokens (capped pour ne pas
-    # exploser le JSON sur de gros corpus)
-    missed: list[str] = []
-    for d in docs:
-        missed.extend(d.get("missed_tokens") or [])
-    return {
-        "n_docs": len(docs),
-        "n_gt_tokens": n_gt,
-        "n_searchable": n_search,
-        "recall": n_search / n_gt,
-        "missed_tokens_sample": missed[:50],
-        "max_distance": docs[0].get("max_distance", 2),
-    }
-
+from picarones.measurements.searchability_runner import *  # noqa: F401, F403
 
-__all__ = [
-    "compute_searchability_metrics",
-    "aggregate_searchability_metrics",
-]
+import picarones.measurements.searchability_runner as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/specialization.py

@@ -1,187 +1,19 @@
-"""Score de spécialisation inter-moteurs — Sprint 89 (A.II.8b).
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.specialization`.
 
-Sprint 89 — A.II.8b du plan d'évolution 2026.
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.specialization import ...``) de continuer
+à fonctionner sans modification.
 
-Pourquoi ce module
-------------------
-La matrice de divergence taxonomique (Sprint 35
-``inter_engine.taxonomy_divergence_matrix``) répond à *« à quel
-point ces moteurs se trompent-ils différemment ? »*.  Ce
-sprint la transforme en un **score de spécialisation** lisible
-et complète la lecture par :
-
-- une **classification** discrète (similar / distinct /
-  highly_specialized) que le chercheur peut consommer sans
-  avoir à interpréter une distance ;
-- un **top-N des paires** les plus spécialisées, qui répond
-  directement à la question *« quels moteurs sont les meilleurs
-  candidats pour un voting ensemble ? »*.
-
-Ce module **ne recommande pas** de pipeline d'ensemble — il
-fournit l'observation factuelle et laisse le chercheur arbitrer.
-
-Convention de score
--------------------
-On utilise la **Jensen-Shannon divergence** déjà calculée par
-``inter_engine.jensen_shannon_divergence`` : elle est
-symétrique, bornée dans [0, 1], et son interprétation est
-intuitive :
-
-- ≈ 0 → profils taxonomiques identiques
-- 1 → distributions totalement disjointes
-
-Dépendances
------------
-S'appuie strictement sur ``picarones.core.inter_engine`` (Sprint
-35) — pas de double calcul, pas de logique nouvelle de
-divergence.
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
 """
 
-from __future__ import annotations
-
-import logging
-from typing import Optional
-
-from picarones.core.inter_engine import jensen_shannon_divergence
-
-logger = logging.getLogger(__name__)
-
-
-# Seuils par convention éditoriale.  La roadmap ne fixe rien :
-# ces seuils sont des **guides de lecture**, pas des verdicts.
-# Le chercheur peut les surcharger via ``classify_specialization``.
-DEFAULT_THRESHOLDS = (
-    ("similar", 0.10),
-    ("distinct", 0.30),
-    ("highly_specialized", 1.01),  # tout score ≥ 0.30
-)
-
-
-def compute_specialization_score(
-    taxonomy_a: dict[str, float],
-    taxonomy_b: dict[str, float],
-) -> float:
-    """Score de spécialisation entre deux moteurs ∈ [0, 1].
-
-    0 = mêmes erreurs, 1 = erreurs totalement disjointes.
-    Délègue à ``jensen_shannon_divergence`` (Sprint 35).
-    """
-    return jensen_shannon_divergence(taxonomy_a, taxonomy_b)
-
-
-def classify_specialization(
-    score: float,
-    thresholds: Optional[tuple[tuple[str, float], ...]] = None,
-) -> str:
-    """Classe le score en catégorie discrète.
-
-    Convention :
-    - score < 0.10 → ``similar``
-    - 0.10 ≤ score < 0.30 → ``distinct``
-    - score ≥ 0.30 → ``highly_specialized``
-
-    L'utilisateur peut passer ses propres ``thresholds`` (liste
-    triée par valeur croissante de tuples ``(label, max_score)``).
-    """
-    rules = thresholds or DEFAULT_THRESHOLDS
-    for label, max_score in rules:
-        if score < max_score:
-            return label
-    # Garde-fou : si aucun seuil ne match, dernière catégorie
-    return rules[-1][0]
-
-
-def compute_specialization_matrix(
-    taxonomies: dict[str, dict[str, float]],
-) -> Optional[dict]:
-    """Matrice de spécialisation symétrique entre tous les moteurs.
-
-    Parameters
-    ----------
-    taxonomies:
-        Map ``{engine_name: {error_class: count_or_proportion}}``.
-
-    Returns
-    -------
-    dict | None
-        ``{
-            "engines": list[str],
-            "matrix": list[list[float]],       # carrée, symétrique
-            "n_pairs": int,                     # paires distinctes
-            "max_score": float,
-            "max_pair": (str, str) | None,
-        }`` ; ``None`` si moins de 2 moteurs.
-    """
-    if not taxonomies or len(taxonomies) < 2:
-        return None
-    engines = sorted(taxonomies.keys())
-    n = len(engines)
-    matrix = [[0.0] * n for _ in range(n)]
-    n_pairs = 0
-    max_score = 0.0
-    max_pair: Optional[tuple[str, str]] = None
-    for i in range(n):
-        for j in range(i + 1, n):
-            score = compute_specialization_score(
-                taxonomies[engines[i]], taxonomies[engines[j]],
-            )
-            matrix[i][j] = score
-            matrix[j][i] = score
-            n_pairs += 1
-            if score > max_score:
-                max_score = score
-                max_pair = (engines[i], engines[j])
-    return {
-        "engines": engines,
-        "matrix": matrix,
-        "n_pairs": n_pairs,
-        "max_score": max_score,
-        "max_pair": max_pair,
-    }
-
-
-def top_specialized_pairs(
-    matrix_data: Optional[dict],
-    n: int = 5,
-    *,
-    min_score: float = 0.0,
-) -> list[dict]:
-    """Top-N paires de moteurs triées par score décroissant.
-
-    Returns
-    -------
-    list[dict]
-        Une liste de ``{
-            "engine_a": str, "engine_b": str,
-            "score": float, "category": str,
-        }`` triée par score décroissant.  Liste vide si
-        ``matrix_data`` est ``None`` ou que toutes les paires
-        sont sous ``min_score``.
-    """
-    if not matrix_data:
-        return []
-    engines = matrix_data["engines"]
-    matrix = matrix_data["matrix"]
-    pairs: list[dict] = []
-    for i, engine_a in enumerate(engines):
-        for j in range(i + 1, len(engines)):
-            score = matrix[i][j]
-            if score < min_score:
-                continue
-            pairs.append({
-                "engine_a": engine_a,
-                "engine_b": engines[j],
-                "score": score,
-                "category": classify_specialization(score),
-            })
-    pairs.sort(key=lambda p: -p["score"])
-    return pairs[:n]
-
+from picarones.measurements.specialization import *  # noqa: F401, F403
 
-__all__ = [
-    "DEFAULT_THRESHOLDS",
-    "compute_specialization_score",
-    "classify_specialization",
-    "compute_specialization_matrix",
-    "top_specialized_pairs",
-]
+import picarones.measurements.specialization as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])

picarones/core/statistics.py

@@ -1,1127 +1,19 @@
-"""Tests statistiques et clustering d'erreurs pour Picarones.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.measurements.statistics`.
 
-Fonctions fournies
-------------------
-- wilcoxon_test(a, b)                  : Wilcoxon signé-rangé (2 moteurs appariés)
-- bootstrap_ci(values, ...)            : intervalle de confiance à 95 % par bootstrap
-- compute_pairwise_stats(...)          : matrice de Wilcoxon entre toutes les paires
-- friedman_test(engine_cer_map)        : Friedman (k moteurs, n documents)       [Sprint 17]
-- nemenyi_posthoc(engine_cer_map)      : post-hoc Nemenyi avec critical distance [Sprint 17]
-- build_critical_difference_svg(...)   : rendu SVG du CDD (Demšar 2006)          [Sprint 17]
-- compute_pareto_front(points, ...)    : frontière de Pareto multi-objectifs     [Sprint 19]
-- cluster_errors(...)                  : regroupement des patterns d'erreurs
-- compute_correlation_matrix(...)      : matrice de corrélation des métriques
-- compute_reliability_curve(...)       : courbe CER vs. % docs les plus faciles
-- compute_venn_data(...)               : diagramme de Venn 2/3 moteurs
-"""
-
-from __future__ import annotations
-
-import math
-import random
-import re
-from collections import defaultdict
-from dataclasses import dataclass
-from typing import Optional
-
-# Import optionnel de scipy — utilisé pour le test de Wilcoxon si disponible
-# (méthode exacte pour n ≤ 25, approximation normale pour n > 25).
-# En son absence, l'implémentation native (approximation normale pour n ≥ 10)
-# est utilisée automatiquement.
-try:
-    from scipy.stats import wilcoxon as _scipy_wilcoxon  # type: ignore[import-untyped]
-    _SCIPY_AVAILABLE = True
-except ImportError:
-    _SCIPY_AVAILABLE = False
-
-
-# ---------------------------------------------------------------------------
-# Bootstrap CI
-# ---------------------------------------------------------------------------
-
-def bootstrap_ci(
-    values: list[float],
-    n_iter: int = 1000,
-    ci: float = 0.95,
-    seed: int = 42,
-) -> tuple[float, float]:
-    """Intervalle de confiance par bootstrap.
-
-    Parameters
-    ----------
-    values : liste des valeurs (ex. CER par document)
-    n_iter : nombre d'itérations bootstrap (défaut 1000)
-    ci     : niveau de confiance (défaut 0.95 → 95 %)
-    seed   : graine RNG pour reproductibilité
-
-    Returns
-    -------
-    (lower, upper) — les bornes de l'IC à ``ci`` %
-    """
-    if not values:
-        return (0.0, 0.0)
-    rng = random.Random(seed)
-    n = len(values)
-    means = []
-    for _ in range(n_iter):
-        sample = [values[rng.randint(0, n - 1)] for _ in range(n)]
-        means.append(sum(sample) / n)
-    means.sort()
-    alpha = (1.0 - ci) / 2.0
-    lo_idx = max(0, int(alpha * n_iter))
-    hi_idx = min(n_iter - 1, int((1.0 - alpha) * n_iter))
-    return (means[lo_idx], means[hi_idx])
-
-
-# ---------------------------------------------------------------------------
-# Test de Wilcoxon signé-rangé (implémentation pure Python)
-# ---------------------------------------------------------------------------
-
-def wilcoxon_test(
-    a: list[float],
-    b: list[float],
-    zero_method: str = "wilcox",
-) -> dict:
-    """Test de Wilcoxon signé-rangé entre deux séries de CER appariées.
-
-    Retourne un dict avec :
-      - statistic     : W = min(W⁺, W⁻)
-      - p_value       : p-value bilatérale
-      - significant   : bool (p < 0.05)
-      - interpretation : phrase lisible
-      - n_pairs       : nombre de paires utilisées (après retrait des zéros)
-      - W_plus        : somme des rangs des différences positives
-      - W_minus       : somme des rangs des différences négatives
-
-    Hypothèses et limites
-    ---------------------
-    * Les observations sont appariées (même corpus, deux moteurs différents).
-    * Le test est non-paramétrique : aucune hypothèse de normalité des CER.
-    * ``zero_method="wilcox"`` (défaut) : les paires sans différence (aᵢ = bᵢ)
-      sont simplement exclues.  Les autres méthodes (``"pratt"``, ``"zsplit"``)
-      nécessitent scipy.
-    * **Approximation normale** (implémentation native, n ≥ 10) :
-      L'approximation est raisonnable pour n ≥ 10 et converge vers la
-      distribution exacte.  Pour n < 10, une table critique simplifiée est
-      utilisée (p ∈ {0.04, 0.20}) — résultat **conservateur**.
-    * **scipy** (si installé) : ``scipy.stats.wilcoxon`` est utilisé à la place
-      de l'approximation native.  scipy utilise la méthode exacte pour n ≤ 25
-      et l'approximation normale pour n > 25, ce qui est plus précis.
-    * **Validité** : le test suppose la symétrie de la distribution des
-      différences.  Avec de très petits n (< 5), les résultats sont peu fiables
-      quelle que soit la méthode.
-
-    Parameters
-    ----------
-    a, b : séries de CER (même longueur, même ordre de documents)
-    zero_method : gestion des paires nulles (défaut : ``"wilcox"``)
-    """
-    if len(a) != len(b):
-        raise ValueError("Les deux listes doivent avoir la même longueur")
-
-    diffs = [x - y for x, y in zip(a, b)]
-
-    # Retirer les zéros (méthode "wilcox")
-    if zero_method == "wilcox":
-        diffs = [d for d in diffs if d != 0.0]
-
-    n = len(diffs)
-    if n == 0:
-        return {
-            "statistic": 0.0,
-            "p_value": 1.0,
-            "significant": False,
-            "interpretation": "Aucune différence entre les deux concurrents.",
-            "n_pairs": 0,
-        }
-
-    # Rangs des valeurs absolues
-    abs_diffs = [abs(d) for d in diffs]
-    indexed = sorted(enumerate(abs_diffs), key=lambda x: x[1])
-
-    # Gestion des ex-aequo : rang moyen
-    ranks = [0.0] * n
-    i = 0
-    while i < n:
-        j = i
-        while j < n and abs_diffs[indexed[j][0]] == abs_diffs[indexed[i][0]]:
-            j += 1
-        avg_rank = (i + j + 1) / 2.0  # rang moyen (1-based)
-        for k in range(i, j):
-            ranks[indexed[k][0]] = avg_rank
-        i = j
-
-    W_plus  = sum(ranks[k] for k in range(n) if diffs[k] > 0)
-    W_minus = sum(ranks[k] for k in range(n) if diffs[k] < 0)
-    W = min(W_plus, W_minus)
-
-    # Calcul de la p-value : scipy si disponible, sinon approximation native
-    if _SCIPY_AVAILABLE:
-        try:
-            scipy_res = _scipy_wilcoxon(diffs, zero_method=zero_method)
-            p_value = float(scipy_res.pvalue)
-        except Exception:
-            # Repli sur l'implémentation native en cas d'erreur scipy
-            p_value = _native_p_value(n, W)
-    else:
-        p_value = _native_p_value(n, W)
-
-    significant = p_value < 0.05
-
-    if significant:
-        better = "premier" if W_plus < W_minus else "second"
-        interpretation = (
-            f"Différence statistiquement significative (p = {p_value:.4f} < 0.05). "
-            f"Le {better} concurrent obtient de meilleurs scores."
-        )
-    else:
-        interpretation = (
-            f"Différence non significative (p = {p_value:.4f} ≥ 0.05). "
-            "On ne peut pas conclure que l'un surpasse l'autre."
-        )
-
-    return {
-        "statistic": round(W, 4),
-        "p_value": round(p_value, 6),
-        "significant": significant,
-        "interpretation": interpretation,
-        "n_pairs": n,
-        "W_plus": round(W_plus, 4),
-        "W_minus": round(W_minus, 4),
-    }
-
-
-def _normal_sf(z: float) -> float:
-    """Survival function de la loi normale standard (1 - CDF)."""
-    # Approximation Abramowitz & Stegun 26.2.17
-    t = 1.0 / (1.0 + 0.2316419 * abs(z))
-    poly = t * (0.319381530 + t * (-0.356563782 + t * (1.781477937
-           + t * (-1.821255978 + t * 1.330274429))))
-    phi_z = math.exp(-0.5 * z * z) / math.sqrt(2.0 * math.pi)
-    p = phi_z * poly
-    return p if z >= 0 else 1.0 - p
-
-
-# Table des valeurs critiques de W pour α=0.05 bilatéral (test exact, source : tables de Wilcoxon)
-_W_CRITICAL = {1: 0, 2: 0, 3: 0, 4: 0, 5: 0, 6: 0, 7: 2, 8: 3, 9: 5}
-
-
-def _wilcoxon_exact_p(n: int, w: float) -> float:
-    """P-value approximée pour petits n (< 10) via table critique simplifiée.
-
-    Note : résultat **conservateur** — seules deux valeurs sont retournées :
-    0.04 (significatif à 5 %) ou 0.20 (non significatif).
-    Préférer scipy pour des p-values exactes.
-    """
-    critical = _W_CRITICAL.get(n, 0)
-    if w <= critical:
-        return 0.04  # significatif à 5 %
-    return 0.20      # non significatif (approximation conservative)
-
-
-def _native_p_value(n: int, W: float) -> float:
-    """Calcule la p-value via l'approximation normale (n ≥ 10) ou la table exacte (n < 10)."""
-    if n >= 10:
-        mu = n * (n + 1) / 4.0
-        sigma2 = n * (n + 1) * (2 * n + 1) / 24.0
-        if sigma2 <= 0:
-            return 1.0
-        z = abs((W + 0.5) - mu) / math.sqrt(sigma2)  # correction de continuité
-        return 2.0 * _normal_sf(z)  # test bilatéral
-    return _wilcoxon_exact_p(n, W)
-
-
-# ---------------------------------------------------------------------------
-# Matrice des tests pairwise
-# ---------------------------------------------------------------------------
-
-def compute_pairwise_stats(
-    engine_cer_map: dict[str, list[float]],
-) -> list[dict]:
-    """Calcule les tests de Wilcoxon entre toutes les paires de concurrents.
-
-    Parameters
-    ----------
-    engine_cer_map : dict {engine_name → [cer_doc1, cer_doc2, ...]}
-
-    Returns
-    -------
-    Liste de dicts, un par paire :
-      - engine_a, engine_b, statistic, p_value, significant, interpretation
-    """
-    names = list(engine_cer_map.keys())
-    results = []
-    for i in range(len(names)):
-        for j in range(i + 1, len(names)):
-            a_name, b_name = names[i], names[j]
-            a_vals = engine_cer_map[a_name]
-            b_vals = engine_cer_map[b_name]
-            # Aligner les longueurs
-            min_len = min(len(a_vals), len(b_vals))
-            if min_len < 2:
-                continue
-            res = wilcoxon_test(a_vals[:min_len], b_vals[:min_len])
-            results.append({
-                "engine_a": a_name,
-                "engine_b": b_name,
-                **res,
-            })
-    return results
-
-
-# ---------------------------------------------------------------------------
-# Test de Friedman + post-hoc Nemenyi (Sprint 17)
-# ---------------------------------------------------------------------------
-#
-# Référence : Demšar, J. (2006), "Statistical Comparisons of Classifiers over
-# Multiple Data Sets", Journal of Machine Learning Research 7:1-30. Standard
-# de facto pour comparer plusieurs systèmes sur plusieurs datasets — ici :
-# plusieurs moteurs OCR sur plusieurs documents. Le CDD (critical difference
-# diagram) issu de Nemenyi est le rendu canonique.
-
-# Valeurs critiques de la distribution du Studentized Range divisées par √2,
-# pour df = ∞ (approximation usuelle pour Nemenyi). Source : tables de Tukey.
-# Clé : nombre de traitements k ; valeur : q_α pour α ∈ {0.05, 0.01}.
-_NEMENYI_Q_TABLE = {
-    # k   q_0.05   q_0.01
-    2:  (1.960, 2.576),
-    3:  (2.343, 2.913),
-    4:  (2.569, 3.113),
-    5:  (2.728, 3.255),
-    6:  (2.850, 3.364),
-    7:  (2.949, 3.452),
-    8:  (3.031, 3.526),
-    9:  (3.102, 3.590),
-    10: (3.164, 3.646),
-    11: (3.219, 3.696),
-    12: (3.268, 3.741),
-    13: (3.313, 3.781),
-    14: (3.354, 3.818),
-    15: (3.391, 3.853),
-    16: (3.426, 3.886),
-    17: (3.458, 3.916),
-    18: (3.489, 3.944),
-    19: (3.517, 3.970),
-    20: (3.544, 3.995),
-    25: (3.658, 4.095),
-    30: (3.739, 4.167),
-    40: (3.858, 4.272),
-    50: (3.945, 4.349),
-}
-
-
-def _chi_square_sf(x: float, df: int) -> float:
-    """Survival function de la loi chi², 1 - CDF(x).
-
-    Utilise scipy si disponible (méthode exacte), sinon Wilson-Hilferty
-    (approximation normale précise dès df ≥ 3).
-    """
-    if x <= 0 or df <= 0:
-        return 1.0
-    try:
-        from scipy.stats import chi2 as _chi2  # type: ignore[import-untyped]
-        return float(_chi2.sf(x, df))
-    except ImportError:
-        pass
-    # Wilson-Hilferty : transforme chi² en approximation normale
-    z = (((x / df) ** (1.0 / 3.0)) - (1.0 - 2.0 / (9.0 * df))) / math.sqrt(2.0 / (9.0 * df))
-    return _normal_sf(z)
-
-
-def _rank_row(values: list[float]) -> list[float]:
-    """Rangs d'une ligne — petit = rang 1. Ex-aequo : rangs moyens."""
-    n = len(values)
-    indexed = sorted(range(n), key=lambda i: values[i])
-    ranks = [0.0] * n
-    i = 0
-    while i < n:
-        j = i
-        while j < n and values[indexed[j]] == values[indexed[i]]:
-            j += 1
-        avg_rank = (i + j + 1) / 2.0  # 1-based
-        for k in range(i, j):
-            ranks[indexed[k]] = avg_rank
-        i = j
-    return ranks
-
-
-def _aligned_cer_matrix(
-    engine_cer_map: dict[str, list[float]],
-) -> tuple[list[str], list[list[float]]]:
-    """Construit la matrice (k moteurs × n documents) alignée sur la longueur
-    minimale. Retourne ``(noms, matrice_colonne_par_moteur)``.
-
-    Friedman exige des blocs (documents) complets : si les moteurs n'ont pas
-    tous été exécutés sur les mêmes documents, on tronque à la longueur
-    minimale, documentée dans le résultat via ``n_blocks``.
-    """
-    names = list(engine_cer_map.keys())
-    if not names:
-        return [], []
-    min_len = min(len(v) for v in engine_cer_map.values())
-    if min_len == 0:
-        return names, []
-    matrix = [engine_cer_map[n][:min_len] for n in names]
-    return names, matrix
-
-
-def friedman_test(engine_cer_map: dict[str, list[float]]) -> dict:
-    """Test de Friedman — k moteurs sur n documents appariés.
-
-    Test non-paramétrique équivalent à l'ANOVA à mesures répétées pour des
-    données ordinales. Hypothèse nulle : tous les moteurs ont la même
-    performance moyenne. Rejet → au moins un moteur diffère des autres.
-
-    Parameters
-    ----------
-    engine_cer_map:
-        Dict ``{engine_name → [cer_doc1, cer_doc2, ...]}``. Tous les moteurs
-        doivent avoir été évalués sur les mêmes documents (dans le même ordre).
-
-    Returns
-    -------
-    dict avec :
-      - ``statistic``     : Q corrigé pour les ex-aequo
-      - ``p_value``       : p-value (scipy si dispo, sinon Wilson-Hilferty)
-      - ``significant``   : bool, p < 0.05
-      - ``df``            : degrés de liberté = k - 1
-      - ``n_blocks``      : nombre de documents (blocs) utilisés
-      - ``n_engines``     : nombre de moteurs (k)
-      - ``mean_ranks``    : dict ``{engine: rang_moyen}``
-      - ``interpretation``: phrase lisible
-      - ``error``         : message si le test n'est pas applicable
-    """
-    names, matrix = _aligned_cer_matrix(engine_cer_map)
-    k = len(names)
-    n = len(matrix[0]) if matrix else 0
-
-    if k < 2:
-        return {
-            "statistic": 0.0, "p_value": 1.0, "significant": False,
-            "df": 0, "n_blocks": n, "n_engines": k,
-            "mean_ranks": {names[0]: 1.0} if k == 1 else {},
-            "interpretation": "Test de Friedman non applicable : il faut au moins 2 moteurs.",
-            "error": "not_enough_engines",
-        }
-    if n < 2:
-        return {
-            "statistic": 0.0, "p_value": 1.0, "significant": False,
-            "df": k - 1, "n_blocks": n, "n_engines": k,
-            "mean_ranks": {name: 1.0 for name in names},
-            "interpretation": "Test de Friedman non applicable : il faut au moins 2 documents communs.",
-            "error": "not_enough_blocks",
-        }
-
-    # Rangs par bloc (document) : pour chaque doc, ranger les k moteurs
-    ranks_by_engine: list[list[float]] = [[] for _ in range(k)]
-    for j in range(n):
-        row = [matrix[i][j] for i in range(k)]
-        row_ranks = _rank_row(row)
-        for i in range(k):
-            ranks_by_engine[i].append(row_ranks[i])
-
-    rank_sums = [sum(r) for r in ranks_by_engine]
-    mean_ranks = {names[i]: rank_sums[i] / n for i in range(k)}
-
-    # Statistique Q non-corrigée (sans ex-aequo)
-    #   Q = 12 / (n·k·(k+1)) · Σ R_j² − 3·n·(k+1)
-    Q = (12.0 / (n * k * (k + 1))) * sum(rs ** 2 for rs in rank_sums) - 3.0 * n * (k + 1)
-
-    # Correction pour les ex-aequo (ties factor) — ajuste si des rangs sont
-    # partagés dans certains blocs. Formule : Q_corr = Q / (1 - T/(n·(k³−k)))
-    # où T = Σ (tⱼ³ − tⱼ) sur tous les groupes d'ex-aequo.
-    tie_correction = 0.0
-    for j in range(n):
-        row = [matrix[i][j] for i in range(k)]
-        sorted_row = sorted(row)
-        i = 0
-        while i < len(sorted_row):
-            count = 1
-            while i + count < len(sorted_row) and sorted_row[i + count] == sorted_row[i]:
-                count += 1
-            if count > 1:
-                tie_correction += count ** 3 - count
-            i += count
-    denom = 1.0 - tie_correction / (n * (k ** 3 - k)) if k >= 2 else 1.0
-    if denom > 0:
-        Q = Q / denom
-
-    df = k - 1
-    p_value = _chi_square_sf(Q, df)
-    significant = p_value < 0.05
-
-    if significant:
-        interpretation = (
-            f"Test de Friedman significatif (Q = {Q:.3f}, df = {df}, p = {p_value:.4f}). "
-            f"Au moins un moteur diffère des autres — utiliser le post-hoc Nemenyi "
-            f"pour identifier les paires distinguables."
-        )
-    else:
-        interpretation = (
-            f"Test de Friedman non significatif (Q = {Q:.3f}, df = {df}, p = {p_value:.4f}). "
-            f"Aucune différence globale détectée entre les moteurs sur ce corpus."
-        )
-
-    return {
-        "statistic": round(Q, 4),
-        "p_value": round(p_value, 6),
-        "significant": significant,
-        "df": df,
-        "n_blocks": n,
-        "n_engines": k,
-        "mean_ranks": {k_: round(v, 4) for k_, v in mean_ranks.items()},
-        "interpretation": interpretation,
-    }
-
-
-def _nemenyi_critical_value(k: int, alpha: float = 0.05) -> Optional[float]:
-    """Valeur critique q_α pour k traitements, df = ∞.
-
-    Retourne ``None`` si k est hors table (< 2 ou > 50).
-    """
-    if k < 2:
-        return None
-    if k in _NEMENYI_Q_TABLE:
-        q05, q01 = _NEMENYI_Q_TABLE[k]
-        return q05 if alpha == 0.05 else q01 if alpha == 0.01 else q05
-    # Au-delà de la table : borne supérieure (conservateur)
-    max_k = max(_NEMENYI_Q_TABLE.keys())
-    if k > max_k:
-        q05, q01 = _NEMENYI_Q_TABLE[max_k]
-        return q05 if alpha == 0.05 else q01
-    # Entre deux clés : interpolation linéaire
-    keys = sorted(_NEMENYI_Q_TABLE.keys())
-    for i in range(len(keys) - 1):
-        if keys[i] < k < keys[i + 1]:
-            lo, hi = keys[i], keys[i + 1]
-            q_lo = _NEMENYI_Q_TABLE[lo][0 if alpha == 0.05 else 1]
-            q_hi = _NEMENYI_Q_TABLE[hi][0 if alpha == 0.05 else 1]
-            frac = (k - lo) / (hi - lo)
-            return q_lo + frac * (q_hi - q_lo)
-    return None
-
-
-def nemenyi_posthoc(
-    engine_cer_map: dict[str, list[float]],
-    alpha: float = 0.05,
-) -> dict:
-    """Post-hoc de Nemenyi — identifie les paires de moteurs statistiquement
-    indiscernables après un test de Friedman.
-
-    Calcule la *critical distance* CD = q_α · √(k·(k+1) / (6·n)). Deux moteurs
-    dont les rangs moyens diffèrent de moins que CD ne sont **pas**
-    statistiquement distinguables au seuil α.
-
-    Returns
-    -------
-    dict avec :
-      - ``alpha``               : seuil utilisé
-      - ``critical_distance``   : CD calculée
-      - ``q_alpha``             : valeur critique q_α issue de la table
-      - ``n_blocks``, ``n_engines``
-      - ``mean_ranks``          : rangs moyens par moteur (dict)
-      - ``engines_sorted``      : liste des moteurs triés par rang croissant
-      - ``significant_matrix``  : matrice bool (list[list[bool]]),
-                                  ``True`` = paire significativement différente
-      - ``tied_groups``         : liste de listes de moteurs indiscernables
-                                  (groupes maximaux d'ex-aequo pratiques)
-      - ``error``               : présent si le test n'est pas applicable
-    """
-    names, matrix = _aligned_cer_matrix(engine_cer_map)
-    k = len(names)
-    n = len(matrix[0]) if matrix else 0
-
-    if k < 2 or n < 2:
-        return {
-            "alpha": alpha,
-            "critical_distance": 0.0,
-            "q_alpha": 0.0,
-            "n_blocks": n,
-            "n_engines": k,
-            "mean_ranks": {name: 1.0 for name in names},
-            "engines_sorted": list(names),
-            "significant_matrix": [[False] * k for _ in range(k)],
-            "tied_groups": [list(names)] if names else [],
-            "error": "not_enough_data",
-        }
-
-    # Friedman fournit les rangs moyens — on les recalcule ici pour rester
-    # autonome (sans forcer l'utilisateur à chaîner les deux appels).
-    ranks_by_engine: list[list[float]] = [[] for _ in range(k)]
-    for j in range(n):
-        row = [matrix[i][j] for i in range(k)]
-        row_ranks = _rank_row(row)
-        for i in range(k):
-            ranks_by_engine[i].append(row_ranks[i])
+Phase E du chantier de refonte en 3 cercles. Cette mesure (Cercle 2)
+n'est plus dans ``picarones.core/`` ; elle vit dans
+``picarones.measurements/``. L'alias ici permet aux imports
+historiques (``from picarones.core.statistics import ...``) de continuer
+à fonctionner sans modification.
 
-    mean_ranks_list = [sum(r) / n for r in ranks_by_engine]
-    mean_ranks = {names[i]: round(mean_ranks_list[i], 4) for i in range(k)}
-
-    q_alpha = _nemenyi_critical_value(k, alpha) or 0.0
-    critical_distance = q_alpha * math.sqrt(k * (k + 1) / (6.0 * n))
-
-    # Matrice de significativité : paire (i,j) significative si |R_i - R_j| > CD
-    significant_matrix = [
-        [
-            (i != j) and (abs(mean_ranks_list[i] - mean_ranks_list[j]) > critical_distance)
-            for j in range(k)
-        ]
-        for i in range(k)
-    ]
-
-    # Groupes d'ex-aequo pratiques : fenêtre glissante sur les rangs triés.
-    # Deux moteurs sont dans le même groupe si leur écart ≤ CD.
-    order = sorted(range(k), key=lambda i: mean_ranks_list[i])
-    sorted_names = [names[i] for i in order]
-    sorted_ranks = [mean_ranks_list[i] for i in order]
-
-    tied_groups: list[list[str]] = []
-    i = 0
-    while i < len(sorted_names):
-        # étendre le groupe tant que le moteur suivant est à ≤ CD du premier du groupe
-        j = i
-        while j + 1 < len(sorted_names) and (sorted_ranks[j + 1] - sorted_ranks[i]) <= critical_distance:
-            j += 1
-        tied_groups.append(sorted_names[i:j + 1])
-        i = j + 1 if j > i else i + 1
-
-    return {
-        "alpha": alpha,
-        "critical_distance": round(critical_distance, 4),
-        "q_alpha": round(q_alpha, 4),
-        "n_blocks": n,
-        "n_engines": k,
-        "mean_ranks": mean_ranks,
-        "engines_sorted": sorted_names,
-        "significant_matrix": significant_matrix,
-        "tied_groups": tied_groups,
-    }
-
-
-# ---------------------------------------------------------------------------
-# Critical Difference Diagram — rendu SVG (Sprint 17)
-# ---------------------------------------------------------------------------
-
-def build_critical_difference_svg(
-    nemenyi_result: dict,
-    width: int = 780,
-    row_height: int = 22,
-) -> str:
-    """Génère le SVG du Critical Difference Diagram (Demšar 2006).
-
-    Le diagramme montre :
-      * un axe horizontal des rangs moyens (1 à k),
-      * chaque moteur positionné sur l'axe à son rang moyen,
-      * des barres horizontales épaisses reliant les moteurs statistiquement
-        indiscernables (distance ≤ CD),
-      * la longueur de CD affichée au-dessus de l'axe en référence.
-
-    Parameters
-    ----------
-    nemenyi_result:
-        Résultat de ``nemenyi_posthoc``.
-    width:
-        Largeur totale du SVG en pixels.
-    row_height:
-        Hauteur de chaque ligne d'étiquette moteur (auto-adaptatif).
-
-    Returns
-    -------
-    Chaîne contenant le SVG (balise racine ``<svg>…</svg>``).
-    """
-    k = nemenyi_result.get("n_engines", 0)
-    if k < 2 or nemenyi_result.get("error"):
-        return (
-            '<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="40" '
-            'role="img" aria-label="Critical Difference Diagram indisponible">'
-            '<text x="10" y="24" font-family="sans-serif" font-size="12" fill="#666">'
-            'Critical Difference Diagram non calculable — données insuffisantes.'
-            '</text></svg>'
-        )
-
-    engines_sorted: list[str] = list(nemenyi_result.get("engines_sorted", []))
-    mean_ranks: dict[str, float] = dict(nemenyi_result.get("mean_ranks", {}))
-    tied_groups: list[list[str]] = list(nemenyi_result.get("tied_groups", []))
-    cd: float = float(nemenyi_result.get("critical_distance", 0.0))
-
-    # Dimensions
-    left_pad, right_pad = 40, 40
-    top_pad = 50   # espace pour l'affichage CD
-    axis_y = top_pad + 10
-    bars_start_y = axis_y + 20  # première barre d'ex-aequo sous l'axe
-    # Empiler une ligne par groupe + une ligne par étiquette
-    label_rows = k  # chaque moteur a sa propre ligne de label
-    bars_count = len(tied_groups)
-    total_h = bars_start_y + bars_count * 10 + label_rows * row_height + 20
-
-    axis_x0, axis_x1 = left_pad, width - right_pad
-    axis_width = axis_x1 - axis_x0
-
-    def x_for_rank(r: float) -> float:
-        # Rang 1 à gauche, rang k à droite
-        if k <= 1:
-            return axis_x0
-        return axis_x0 + (r - 1.0) / (k - 1.0) * axis_width
-
-    parts: list[str] = []
-    parts.append(
-        f'<svg xmlns="http://www.w3.org/2000/svg" width="100%" viewBox="0 0 {width} {total_h}" '
-        f'role="img" aria-label="Critical Difference Diagram (Friedman-Nemenyi)" '
-        f'font-family="system-ui, -apple-system, sans-serif">'
-    )
-    parts.append('<style>.cd-axis{stroke:#334155;stroke-width:1.5}.cd-tick{stroke:#334155;stroke-width:1}'
-                 '.cd-label{fill:#0f172a;font-size:11px}'
-                 '.cd-tie{stroke:#0f172a;stroke-width:4;stroke-linecap:round}'
-                 '.cd-cd-bar{stroke:#dc2626;stroke-width:2}'
-                 '.cd-cd-txt{fill:#dc2626;font-size:11px;font-weight:600}'
-                 '.cd-name{fill:#0f172a;font-size:12px}'
-                 '.cd-rank{fill:#64748b;font-size:10px}'
-                 '</style>')
-
-    # Barre CD de référence (en haut, à gauche de l'axe)
-    if cd > 0 and k >= 2:
-        cd_bar_x0 = axis_x0
-        cd_bar_x1 = axis_x0 + (cd / max(1, k - 1)) * axis_width
-        cd_y = top_pad - 20
-        parts.append(f'<line class="cd-cd-bar" x1="{cd_bar_x0:.1f}" y1="{cd_y}" '
-                     f'x2="{cd_bar_x1:.1f}" y2="{cd_y}"/>')
-        parts.append(f'<line class="cd-cd-bar" x1="{cd_bar_x0:.1f}" y1="{cd_y - 4}" '
-                     f'x2="{cd_bar_x0:.1f}" y2="{cd_y + 4}"/>')
-        parts.append(f'<line class="cd-cd-bar" x1="{cd_bar_x1:.1f}" y1="{cd_y - 4}" '
-                     f'x2="{cd_bar_x1:.1f}" y2="{cd_y + 4}"/>')
-        parts.append(f'<text class="cd-cd-txt" x="{(cd_bar_x0 + cd_bar_x1)/2:.1f}" y="{cd_y - 8}" '
-                     f'text-anchor="middle">CD = {cd:.3f}</text>')
-
-    # Axe principal
-    parts.append(f'<line class="cd-axis" x1="{axis_x0}" y1="{axis_y}" '
-                 f'x2="{axis_x1}" y2="{axis_y}"/>')
-    # Ticks entiers
-    for r in range(1, k + 1):
-        xt = x_for_rank(r)
-        parts.append(f'<line class="cd-tick" x1="{xt:.1f}" y1="{axis_y - 5}" '
-                     f'x2="{xt:.1f}" y2="{axis_y + 5}"/>')
-        parts.append(f'<text class="cd-label" x="{xt:.1f}" y="{axis_y - 9}" '
-                     f'text-anchor="middle">{r}</text>')
-
-    # Barres reliant les groupes indiscernables
-    for i, group in enumerate(tied_groups):
-        if len(group) < 2:
-            continue
-        rs = [mean_ranks[n] for n in group]
-        x0 = x_for_rank(min(rs))
-        x1 = x_for_rank(max(rs))
-        y_bar = bars_start_y + i * 10
-        parts.append(f'<line class="cd-tie" x1="{x0 - 3:.1f}" y1="{y_bar}" '
-                     f'x2="{x1 + 3:.1f}" y2="{y_bar}"/>')
-
-    # Étiquettes des moteurs : la moitié la plus basse à gauche, l'autre à droite
-    labels_y_base = bars_start_y + bars_count * 10 + 15
-    half = (len(engines_sorted) + 1) // 2
-    left_engines = engines_sorted[:half]
-    right_engines = engines_sorted[half:]
-
-    for idx, name in enumerate(left_engines):
-        r = mean_ranks[name]
-        x = x_for_rank(r)
-        y_label = labels_y_base + idx * row_height
-        # Ligne du moteur vers axe
-        parts.append(f'<line class="cd-tick" x1="{x:.1f}" y1="{axis_y + 6}" '
-                     f'x2="{x:.1f}" y2="{y_label - 4}"/>')
-        parts.append(f'<line class="cd-tick" x1="{x:.1f}" y1="{y_label - 4}" '
-                     f'x2="{axis_x0 - 4:.1f}" y2="{y_label - 4}"/>')
-        parts.append(f'<text class="cd-name" x="{axis_x0 - 6:.1f}" y="{y_label}" '
-                     f'text-anchor="end">{_svg_escape(name)} '
-                     f'<tspan class="cd-rank">({r:.2f})</tspan></text>')
-
-    for idx, name in enumerate(right_engines):
-        r = mean_ranks[name]
-        x = x_for_rank(r)
-        y_label = labels_y_base + idx * row_height
-        parts.append(f'<line class="cd-tick" x1="{x:.1f}" y1="{axis_y + 6}" '
-                     f'x2="{x:.1f}" y2="{y_label - 4}"/>')
-        parts.append(f'<line class="cd-tick" x1="{x:.1f}" y1="{y_label - 4}" '
-                     f'x2="{axis_x1 + 4:.1f}" y2="{y_label - 4}"/>')
-        parts.append(f'<text class="cd-name" x="{axis_x1 + 6:.1f}" y="{y_label}" '
-                     f'text-anchor="start">{_svg_escape(name)} '
-                     f'<tspan class="cd-rank">({r:.2f})</tspan></text>')
-
-    parts.append('</svg>')
-    return "".join(parts)
-
-
-def _svg_escape(text: str) -> str:
-    """Échappe un texte pour inclusion sûre dans un nœud SVG/XML."""
-    return (text.replace("&", "&amp;")
-                .replace("<", "&lt;")
-                .replace(">", "&gt;")
-                .replace('"', "&quot;")
-                .replace("'", "&#39;"))
-
-
-# ---------------------------------------------------------------------------
-# Frontière de Pareto (Sprint 19)
-# ---------------------------------------------------------------------------
-
-def compute_pareto_front(
-    points: list[dict],
-    objectives: tuple[str, ...] = ("cer", "cost"),
-    name_key: str = "engine",
-    minimize: Optional[tuple[bool, ...]] = None,
-) -> list[str]:
-    """Calcule la frontière de Pareto sur ``len(objectives)`` dimensions.
-
-    Un point ``p`` est Pareto-dominant si aucun autre point n'a, pour TOUS
-    les objectifs, une valeur au moins aussi bonne ET au moins une valeur
-    strictement meilleure.
-
-    Parameters
-    ----------
-    points:
-        Liste de dicts. Chaque dict doit contenir ``name_key`` et toutes les
-        clés de ``objectives``. Les points dont une valeur d'objectif est
-        ``None`` sont ignorés (pas de comparaison possible).
-    objectives:
-        Clés des objectifs à minimiser/maximiser.
-    name_key:
-        Clé identifiant le point (par défaut ``"engine"``).
-    minimize:
-        Pour chaque objectif, ``True`` = minimiser (ex. CER, coût),
-        ``False`` = maximiser (ex. ancrage). Doit avoir la même longueur
-        que ``objectives``.
-
-    Returns
-    -------
-    Liste des ``name`` des points sur le front Pareto, ordre stable depuis
-    ``points``.
-    """
-    if minimize is None:
-        minimize = tuple(True for _ in objectives)
-    if len(minimize) != len(objectives):
-        raise ValueError("`minimize` doit avoir la même longueur que `objectives`")
-
-    valid = []
-    for p in points:
-        try:
-            vals = tuple(float(p[k]) for k in objectives)
-        except (KeyError, TypeError, ValueError):
-            continue
-        valid.append((p[name_key], vals))
-
-    front: list[str] = []
-    for name_a, vals_a in valid:
-        dominated = False
-        for name_b, vals_b in valid:
-            if name_a == name_b:
-                continue
-            # B domine A si B est ≥ aussi bon partout ET strictement meilleur quelque part
-            better_or_equal_everywhere = True
-            strictly_better_somewhere = False
-            for va, vb, mini in zip(vals_a, vals_b, minimize):
-                if mini:
-                    if vb > va:
-                        better_or_equal_everywhere = False
-                        break
-                    if vb < va:
-                        strictly_better_somewhere = True
-                else:  # maximiser
-                    if vb < va:
-                        better_or_equal_everywhere = False
-                        break
-                    if vb > va:
-                        strictly_better_somewhere = True
-            if better_or_equal_everywhere and strictly_better_somewhere:
-                dominated = True
-                break
-        if not dominated:
-            front.append(name_a)
-    return front
-
-
-# ---------------------------------------------------------------------------
-# Clustering des patterns d'erreurs
-# ---------------------------------------------------------------------------
-
-# Patterns d'erreurs fréquentes (OCR + HTR documents patrimoniaux)
-_ERROR_PATTERNS = [
-    # (pattern_re, label)
-    (r"\brn\b.*\bm\b|\bm\b.*\brn\b|rn→m|m→rn",       "confusion rn/m"),
-    (r"[lI]→1|1→[lI]|l→1|1→l|I→1|1→I",               "confusion l/1/I"),
-    (r"u→n|n→u|v→u|u→v",                              "confusion u/n/v"),
-    (r"[oO]→0|0→[oO]",                                "confusion O/0"),
-    (r"ſ→[fs]|[fs]→ſ",                                "confusion ſ/f/s"),
-    (r"é→e|è→e|ê→e|e→[éèê]",                          "erreur diacritique é/e"),
-    (r"œ→oe|oe→œ|æ→ae|ae→æ",                          "ligature œ/æ"),
-    (r"[fF]i→fi|fi→[fF]i",                            "ligature fi"),
-    (r"[fF]l→fl|fl→[fF]l",                            "ligature fl"),
-    (r"\s+→''|''→\s+",                                "segmentation espace"),
-]
-
-def _extract_error_pairs(gt: str, hyp: str) -> list[tuple[str, str]]:
-    """Extrait les paires (gt_char_seq, hyp_char_seq) d'erreurs de substitution."""
-    from picarones.report.diff_utils import compute_word_diff
-    ops = compute_word_diff(gt, hyp)
-    pairs = []
-    for op in ops:
-        if op["op"] == "replace":
-            pairs.append((op["old"], op["new"]))
-        elif op["op"] == "delete":
-            pairs.append((op["text"], ""))
-        elif op["op"] == "insert":
-            pairs.append(("", op["text"]))
-    return pairs
-
-
-@dataclass
-class ErrorCluster:
-    """Un cluster d'erreurs similaires."""
-    cluster_id: int
-    label: str
-    """Description humaine du pattern (ex. 'confusion rn/m')."""
-    count: int
-    examples: list[dict]
-    """Liste de {engine, gt_fragment, ocr_fragment}."""
-
-    def as_dict(self) -> dict:
-        return {
-            "cluster_id": self.cluster_id,
-            "label": self.label,
-            "count": self.count,
-            "examples": self.examples[:5],  # 5 exemples max
-        }
-
-
-def cluster_errors(
-    error_data: list[dict],
-    max_clusters: int = 8,
-) -> list[ErrorCluster]:
-    """Regroupe les erreurs en clusters avec labels lisibles.
-
-    Parameters
-    ----------
-    error_data : liste de dicts {engine, gt, hypothesis}
-    max_clusters : nombre max de clusters à retourner
-
-    Returns
-    -------
-    Liste de ErrorCluster triée par count décroissant.
-    """
-    # Collecter tous les patterns d'erreur avec contexte
-    # Clé : catégorie d'erreur → liste d'exemples
-    bucket: dict[str, list[dict]] = defaultdict(list)
-    other_pairs: list[dict] = []
-
-    for item in error_data:
-        engine = item.get("engine", "")
-        gt = item.get("gt", "")
-        hyp = item.get("hypothesis", "")
-        pairs = _extract_error_pairs(gt, hyp)
-
-        for old, new in pairs:
-            if not old and not new:
-                continue
-            matched = False
-            # Essayer de matcher un pattern connu
-            probe = f"{old}→{new}"
-            for _pat, label in _ERROR_PATTERNS:
-                try:
-                    if re.search(_pat, probe, re.IGNORECASE):
-                        bucket[label].append({
-                            "engine": engine,
-                            "gt_fragment": old,
-                            "ocr_fragment": new,
-                        })
-                        matched = True
-                        break
-                except re.error:
-                    pass
-
-            if not matched:
-                # Regrouper les substitutions restantes par paire de caractères
-                if len(old) <= 3 and len(new) <= 3:
-                    key = f"{old}→{new}" if (old and new) else (f"—→{new}" if new else f"{old}→—")
-                    bucket[key].append({
-                        "engine": engine,
-                        "gt_fragment": old,
-                        "ocr_fragment": new,
-                    })
-                else:
-                    other_pairs.append({
-                        "engine": engine,
-                        "gt_fragment": old,
-                        "ocr_fragment": new,
-                    })
-
-    # Construire les clusters triés par fréquence
-    clusters: list[ErrorCluster] = []
-    cluster_id = 1
-    sorted_buckets = sorted(bucket.items(), key=lambda x: -len(x[1]))
-
-    for label, examples in sorted_buckets[:max_clusters - 1]:
-        clusters.append(ErrorCluster(
-            cluster_id=cluster_id,
-            label=label,
-            count=len(examples),
-            examples=examples,
-        ))
-        cluster_id += 1
-
-    # Cluster "autres"
-    if other_pairs:
-        clusters.append(ErrorCluster(
-            cluster_id=cluster_id,
-            label="autres substitutions",
-            count=len(other_pairs),
-            examples=other_pairs,
-        ))
-
-    # Trier par count décroissant et limiter
-    clusters.sort(key=lambda c: -c.count)
-    return clusters[:max_clusters]
-
-
-# ---------------------------------------------------------------------------
-# Matrice de corrélation entre métriques
-# ---------------------------------------------------------------------------
-
-def _pearson(x: list[float], y: list[float]) -> float:
-    """Coefficient de corrélation de Pearson."""
-    n = len(x)
-    if n < 2:
-        return 0.0
-    mx = sum(x) / n
-    my = sum(y) / n
-    num = sum((xi - mx) * (yi - my) for xi, yi in zip(x, y))
-    den = math.sqrt(
-        sum((xi - mx) ** 2 for xi in x) * sum((yi - my) ** 2 for yi in y)
-    )
-    return num / den if den > 0 else 0.0
-
-
-def compute_correlation_matrix(
-    metrics_per_doc: list[dict],
-    metric_keys: Optional[list[str]] = None,
-) -> dict:
-    """Calcule la matrice de corrélation entre toutes les métriques numériques.
-
-    Parameters
-    ----------
-    metrics_per_doc : liste de dicts, un par document, contenant les métriques
-    metric_keys     : clés à inclure (None → toutes les clés numériques)
-
-    Returns
-    -------
-    {
-      "labels": [...],
-      "matrix": [[r_ij, ...], ...]   // coefficients de Pearson
-    }
-    """
-    if not metrics_per_doc:
-        return {"labels": [], "matrix": []}
-
-    if metric_keys is None:
-        # Déduire les clés numériques
-        sample = metrics_per_doc[0]
-        metric_keys = [k for k, v in sample.items() if isinstance(v, (int, float))]
-
-    # Construire les vecteurs
-    vectors: dict[str, list[float]] = {k: [] for k in metric_keys}
-    for doc in metrics_per_doc:
-        for k in metric_keys:
-            v = doc.get(k)
-            vectors[k].append(float(v) if v is not None else 0.0)
-
-    # Calculer la matrice
-    labels = metric_keys
-    n = len(labels)
-    matrix = []
-    for i in range(n):
-        row = []
-        for j in range(n):
-            r = _pearson(vectors[labels[i]], vectors[labels[j]])
-            row.append(round(r, 4))
-        matrix.append(row)
-
-    return {"labels": labels, "matrix": matrix}
-
-
-# ---------------------------------------------------------------------------
-# Courbe de fiabilité (reliability curve)
-# ---------------------------------------------------------------------------
-
-def compute_reliability_curve(
-    cer_values: list[float],
-    steps: int = 20,
-) -> list[dict]:
-    """Pour les X% documents les plus faciles, quel est le CER moyen ?
-
-    Returns
-    -------
-    Liste de {pct_docs: float, mean_cer: float}
-    """
-    if not cer_values:
-        return []
-    sorted_cer = sorted(cer_values)
-    n = len(sorted_cer)
-    points = []
-    for step in range(1, steps + 1):
-        pct = step / steps
-        cutoff = max(1, int(pct * n))
-        subset = sorted_cer[:cutoff]
-        mean_cer = sum(subset) / len(subset)
-        points.append({"pct_docs": round(pct * 100, 1), "mean_cer": round(mean_cer, 6)})
-    return points
-
-
-# ---------------------------------------------------------------------------
-# Données pour le diagramme de Venn (erreurs communes / exclusives)
-# ---------------------------------------------------------------------------
-
-def compute_venn_data(
-    engine_error_sets: dict[str, set[str]],
-) -> dict:
-    """Calcule les cardinalités pour un diagramme de Venn entre 2 ou 3 concurrents.
-
-    Parameters
-    ----------
-    engine_error_sets : {engine_name → set of doc_id:error_token_pair strings}
-
-    Returns
-    -------
-    Pour 2 concurrents :
-      {only_a, only_b, both, label_a, label_b}
-    Pour 3 concurrents :
-      {only_a, only_b, only_c, ab, ac, bc, abc, label_a, label_b, label_c}
-    """
-    names = list(engine_error_sets.keys())[:3]  # max 3 pour Venn lisible
-    if len(names) < 2:
-        return {}
+Voir :doc:`docs/architecture-cercles.md` pour la cartographie des
+3 cercles. Le ``core/`` strict ne contient plus que les abstractions
+du domaine et l'orchestration (Cercle 1).
+"""
 
-    sets = {n: engine_error_sets[n] for n in names}
+from picarones.measurements.statistics import *  # noqa: F401, F403
 
-    if len(names) == 2:
-        a, b = names
-        sa, sb = sets[a], sets[b]
-        return {
-            "type": "venn2",
-            "label_a": a,
-            "label_b": b,
-            "only_a": len(sa - sb),
-            "only_b": len(sb - sa),
-            "both": len(sa & sb),
-        }
-    else:
-        a, b, c = names
-        sa, sb, sc = sets[a], sets[b], sets[c]
-        return {
-            "type": "venn3",
-            "label_a": a,
-            "label_b": b,
-            "label_c": c,
-            "only_a": len(sa - sb - sc),
-            "only_b": len(sb - sa - sc),
-            "only_c": len(sc - sa - sb),
-            "ab": len((sa & sb) - sc),
-            "ac": len((sa & sc) - sb),
-            "bc": len((sb & sc) - sa),
-            "abc": len(sa & sb & sc),
-        }
+import picarones.measurements.statistics as _module
+__all__ = getattr(_module, "__all__", [
+    nm for nm in dir(_module) if not nm.startswith("_")
+])