refactor(measurements): split runner.py (1019 → 6 sub-modules) by concern

Sprint « découpage de runner.py » — dernier god-module du repo. Le
fichier monolithique de 1019 lignes mélangeait orchestration, calcul
document, workers picklables, persistance NDJSON, agrégations et
câblage NER. Éclaté par concern en un sous-package
``picarones/measurements/runner/``.

Structure du nouveau sous-package :

- ``__init__.py`` (103 lignes) — ré-exports rétrocompat 100%.
- ``orchestration.py`` (494) — ``run_benchmark`` (boucle
principale, pools, agrégation
par moteur) + ``_build_pipeline_info``.
- ``document.py`` (190) — ``_compute_document_result``
(toutes métriques + hooks
via ``run_document_hooks``)
+ ``_calibration_from_engine_result``
+ helpers timeout/erreur.
- ``partial.py`` (140) — Persistance NDJSON des
résultats partiels (lock,
sanitize, write/read/delete).
- ``ner_attach.py`` (133) — Câblage NER post-process
(Sprint 40) + agrégation NER.
- ``workers.py`` (107) — Fonctions niveau module pour
``ProcessPoolExecutor``
(``_cpu_doc_worker``) et
``ThreadPoolExecutor``
(``_io_doc_worker``).
- ``aggregation.py`` (82) — 8 délégations rétrocompat vers
``builtin_hooks._aggregate_*``
(chantier 2 post-Sprint 97).

Le plus gros sous-module (``orchestration.py``) reste à 494 lignes,
sous le budget 575 calibré (current + ~15 %).

Rétrocompat
-----------
Les ~25 fichiers qui font ``from picarones.measurements.runner
import X`` continuent à fonctionner sans modification grâce aux
ré-exports dans ``__init__.py``. Symboles privés ré-exportés pour
les tests qui les consomment directement : ``_compute_document_result``
(test_sprint13), ``_calibration_from_engine_result`` (test_sprint42),
``_aggregate_*`` (test_sprint13/42), ``_attach_ner_metrics`` +
``_aggregate_ner`` (test_sprint40), ``_cpu_doc_worker`` /
``_io_doc_worker`` (test_sprint13), ``_save_partial_line`` +
``_load_partial`` (test_sprint13).

Préservation de l'historique git via ``git mv runner.py
runner/__init__.py`` puis Write des contenus.

Discipline d'audit récursif (2 tours)
-------------------------------------
**Tour 1** (agent Explore ciblé sur 8 angles : API publique, imports
circulaires, refs croisées, lock partagé, side-effects, docstrings,
dead code, monkey-patching) :
- 0 critique, 0 majeur. 2 mineurs faux positifs (``_aggregate_ner``
réellement dans ``ner_attach.py`` par cohérence sémantique ;
``Optional`` réellement utilisé dans les 8 signatures).

**Tour 2** (audit manuel hors-spec sur 7 angles : cohérence frontière,
``__module__`` introspection, nommage logger, imports relatifs/absolus,
symboles privés exposés vs consommés, taille comparée, parité
``statistics/``) :
- ``test_sprint40`` utilise ``caplog.at_level(logger="picarones.
measurements.runner")`` — vérifié : la propagation Python loggers
fait remonter les records de ``runner.ner_attach`` au parent. Test
passe.
- ``test_sprint13`` utilise ``__import__(...)._compute_document_result``
— vérifié : ré-export rend l'introspection transparente. Test passe.
- Tous les imports inter-modules en absolu (cohérent avec
``statistics/`` et le reste du projet).
- 6 symboles privés exposés sans consommateur de test (``_partial_write_lock``,
``_make_*_doc_result``, ``_delete_partial``, ``_sanitize_filename``,
``_build_pipeline_info``) : conservés pour rétrocompat stricte
(étaient attributs publics de ``runner.py``).

Calibration des invariants
--------------------------
- ``BROKEN_PATHS_BASELINE`` : 72 → 73. Un audit historique
(``docs/audits/institutional-readiness-2026-05.md``) référence
``picarones/measurements/runner.py`` qui est devenu un sous-package.
Convention : audit historique intouchable, baseline relevée avec
justification.
- ``FILE_BUDGETS`` : entrée ``runner.py`` retirée (n'existe plus),
ajout ``runner/orchestration.py: 575`` (current 494 + ~15 %).
- ``writing-a-pipeline-module.md`` ligne 353 : ``runner.py`` →
``runner/`` corrigé en place (doc vivante).

Test ``test_partial_file_created_during_run`` corrigé : ``patch.object(
runner_mod, "_save_partial_line")`` ne suffisait plus car
``orchestration.py`` importe directement ``_save_partial_line`` depuis
``partial.py``. Patché sur ``orchestration._save_partial_line`` à la
place.

Suite : 3865 passed, 2 skipped (parité). ruff : All checks passed!

https://claude.ai/code/session_018us43uphCvqwm2TARqyYoH

README.md

@@ -385,7 +385,7 @@ ruff check picarones/ tests/
 python -m mypy picarones/core/
 ```
 
-**Test suite**: ~3865 tests, ~3 min on a modern laptop. Coverage
+**Test suite**: ~3871 tests, ~3 min on a modern laptop. Coverage
 floor at 85% (currently ~87%). The `network` marker excludes tests
 requiring live HTTP.
 

docs/user/writing-a-pipeline-module.md

@@ -350,7 +350,7 @@ brancher dans la pipeline et de mesurer.
 ### 6.b « Et si je veux juste tester une pipeline OCR seule, sans étapes en aval ? »
 
 C'est exactement ce que fait le runner OCR historique
-(`run_benchmark` dans `picarones/measurements/runner.py`) — il est
+(`run_benchmark` dans `picarones/measurements/runner/`) — il est
 toujours là, n'a pas changé, et reste la voie recommandée pour
 les benchmarks d'OCR mono-étage.
 

picarones/measurements/runner/__init__.py

@@ -0,0 +1,103 @@
+"""Orchestrateur du benchmark.
+
+Exécute les moteurs OCR/HTR sur le corpus de manière parallèle :
+
+- ``ProcessPoolExecutor`` pour les moteurs CPU-bound (Tesseract, Pero OCR,
+  Kraken) — les workers picklables vivent dans :mod:`workers`.
+- ``ThreadPoolExecutor`` pour les moteurs IO-bound / API (Mistral, Google,
+  Azure, LLMs).
+
+Avant le sprint « découpage de runner.py » (mai 2026) ce module était
+un fichier unique de 1019 lignes. Le sous-package éclate la
+responsabilité par concern :
+
+- :mod:`document` — calcul d'un :class:`DocumentResult` à partir d'un
+  OCR (métriques principales + hooks via ``run_document_hooks(profile)``).
+- :mod:`workers` — fonctions de niveau module pour ``ProcessPoolExecutor``
+  (:func:`_cpu_doc_worker`) et ``ThreadPoolExecutor`` (:func:`_io_doc_worker`).
+- :mod:`partial` — persistance NDJSON des résultats partiels pour
+  reprise sur interruption.
+- :mod:`orchestration` — :func:`run_benchmark` (boucle principale,
+  pools, agrégation par moteur) + :func:`_build_pipeline_info`.
+- :mod:`aggregation` — délégations rétrocompat vers les agrégateurs de
+  ``builtin_hooks`` (chantier 2 post-Sprint 97).
+- :mod:`ner_attach` — câblage NER au post-process (Sprint 40).
+
+Ce ``__init__.py`` ré-exporte toute l'API publique historique pour que
+les ~25 fichiers qui importent depuis ``picarones.measurements.runner``
+continuent à fonctionner sans modification. Les symboles privés
+``_compute_document_result``, ``_load_partial``, ``_partial_path``,
+``_aggregate_*``, ``_calibration_from_engine_result`` sont ré-exportés
+car les tests Sprint 13/40/42 les consomment directement.
+"""
+
+from picarones.measurements.runner.aggregation import (
+    _aggregate_calibration,
+    _aggregate_char_scores,
+    _aggregate_confusion,
+    _aggregate_hallucination,
+    _aggregate_image_quality,
+    _aggregate_line_metrics,
+    _aggregate_structure,
+    _aggregate_taxonomy,
+)
+from picarones.measurements.runner.document import (
+    _calibration_from_engine_result,
+    _compute_document_result,
+    _make_error_doc_result,
+    _make_timeout_doc_result,
+)
+from picarones.measurements.runner.ner_attach import (
+    _aggregate_ner,
+    _attach_ner_metrics,
+)
+from picarones.measurements.runner.orchestration import (
+    _build_pipeline_info,
+    run_benchmark,
+)
+from picarones.measurements.runner.partial import (
+    _delete_partial,
+    _load_partial,
+    _partial_path,
+    _partial_write_lock,
+    _sanitize_filename,
+    _save_partial_line,
+)
+from picarones.measurements.runner.workers import (
+    _cpu_doc_worker,
+    _io_doc_worker,
+)
+
+__all__ = [
+    # API publique principale
+    "run_benchmark",
+    # Helpers calcul document
+    "_compute_document_result",
+    "_calibration_from_engine_result",
+    "_make_error_doc_result",
+    "_make_timeout_doc_result",
+    # Workers picklables
+    "_cpu_doc_worker",
+    "_io_doc_worker",
+    # Persistance partial
+    "_partial_path",
+    "_load_partial",
+    "_save_partial_line",
+    "_delete_partial",
+    "_sanitize_filename",
+    "_partial_write_lock",
+    # Orchestration helper
+    "_build_pipeline_info",
+    # Délégations agrégation (rétrocompat tests Sprint 13/42)
+    "_aggregate_calibration",
+    "_aggregate_char_scores",
+    "_aggregate_confusion",
+    "_aggregate_hallucination",
+    "_aggregate_image_quality",
+    "_aggregate_line_metrics",
+    "_aggregate_structure",
+    "_aggregate_taxonomy",
+    # NER (Sprint 40)
+    "_aggregate_ner",
+    "_attach_ner_metrics",
+]

picarones/measurements/runner/aggregation.py

@@ -0,0 +1,82 @@
+"""Délégations rétrocompat vers ``builtin_hooks._aggregate_*``.
+
+Chantier 2 (post-Sprint 97) : la logique d'agrégation par-engine de
+toutes les métriques (confusion, taxonomy, structure, image_quality,
+line_metrics, hallucination, calibration, char_scores) vit désormais
+dans :mod:`picarones.measurements.builtin_hooks` (single source of truth,
+exposé via le registre :mod:`picarones.core.metric_hooks`).
+
+Les noms ci-dessous restent disponibles depuis
+``picarones.measurements.runner`` pour la rétrocompat des tests
+Sprint 13 / 42 qui les importent directement.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+def _aggregate_confusion(doc_results: list) -> Optional[dict]:
+    """Délégation vers :func:`builtin_hooks._aggregate_confusion`."""
+    from picarones.measurements.builtin_hooks import _aggregate_confusion as _impl
+    return _impl(doc_results)
+
+
+def _aggregate_char_scores(doc_results: list) -> Optional[dict]:
+    """Délégation vers :func:`builtin_hooks._aggregate_char_scores`."""
+    from picarones.measurements.builtin_hooks import _aggregate_char_scores as _impl
+    return _impl(doc_results)
+
+
+def _aggregate_taxonomy(doc_results: list) -> Optional[dict]:
+    """Délégation vers :func:`builtin_hooks._aggregate_taxonomy`."""
+    from picarones.measurements.builtin_hooks import _aggregate_taxonomy as _impl
+    return _impl(doc_results)
+
+
+def _aggregate_structure(doc_results: list) -> Optional[dict]:
+    """Délégation vers :func:`builtin_hooks._aggregate_structure`."""
+    from picarones.measurements.builtin_hooks import _aggregate_structure as _impl
+    return _impl(doc_results)
+
+
+def _aggregate_image_quality(doc_results: list) -> Optional[dict]:
+    """Délégation vers :func:`builtin_hooks._aggregate_image_quality`."""
+    from picarones.measurements.builtin_hooks import _aggregate_image_quality as _impl
+    return _impl(doc_results)
+
+
+def _aggregate_line_metrics(doc_results: list) -> Optional[dict]:
+    """Délégation vers :func:`builtin_hooks._aggregate_line_metrics`."""
+    from picarones.measurements.builtin_hooks import _aggregate_line_metrics as _impl
+    return _impl(doc_results)
+
+
+def _aggregate_hallucination(doc_results: list) -> Optional[dict]:
+    """Délégation vers :func:`builtin_hooks._aggregate_hallucination`."""
+    from picarones.measurements.builtin_hooks import _aggregate_hallucination as _impl
+    return _impl(doc_results)
+
+
+def _aggregate_calibration(doc_results: list) -> Optional[dict]:
+    """Délégation vers :func:`builtin_hooks._aggregate_calibration`.
+
+    Conservé pour la rétrocompat du test ``test_sprint42_calibration_runner``
+    qui importe directement depuis ``picarones.measurements.runner``. La
+    logique réelle vit dans :mod:`picarones.measurements.builtin_hooks`
+    (chantier 2 post-Sprint 97).
+    """
+    from picarones.measurements.builtin_hooks import _aggregate_calibration as _impl
+    return _impl(doc_results)
+
+
+__all__ = [
+    "_aggregate_calibration",
+    "_aggregate_char_scores",
+    "_aggregate_confusion",
+    "_aggregate_hallucination",
+    "_aggregate_image_quality",
+    "_aggregate_line_metrics",
+    "_aggregate_structure",
+    "_aggregate_taxonomy",
+]

picarones/measurements/runner/document.py

@@ -0,0 +1,190 @@
+"""Construction d'un :class:`DocumentResult` à partir d'un OCR.
+
+Centralise le calcul de toutes les métriques attachées à un document
+unique : métriques principales (CER/WER/MER/WIL via jiwer), hooks
+optionnels (calibration, taxonomy, philological, etc. — exécutés via
+``run_document_hooks(profile)``), et meta pipeline OCR+LLM.
+
+Aussi : helpers pour construire les ``DocumentResult`` synthétiques
+en cas de timeout ou d'erreur d'engine (``_make_timeout_doc_result``,
+``_make_error_doc_result``).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from picarones.core.results import DocumentResult
+from picarones.engines.base import EngineResult
+from picarones.measurements.metrics import MetricsResult, compute_metrics
+
+
+def _calibration_from_engine_result(
+    ground_truth: str,
+    token_confidences: list,
+) -> Optional[dict]:
+    """Délégation vers
+    :func:`picarones.measurements.builtin_hooks.calibration_from_engine_result`.
+
+    Conservé pour la rétrocompat des tests Sprint 42 qui font
+    ``from picarones.measurements.runner import _calibration_from_engine_result``.
+    Toute évolution du calcul doit se faire dans ``builtin_hooks``.
+    """
+    from picarones.measurements.builtin_hooks import calibration_from_engine_result
+    return calibration_from_engine_result(ground_truth, token_confidences)
+
+
+def _compute_document_result(
+    doc_id: str,
+    image_path: str,
+    ground_truth: str,
+    ocr_result: EngineResult,
+    char_exclude: Optional[frozenset],
+    corpus_lang: str = "fr",
+    profile: str = "standard",
+) -> DocumentResult:
+    """Calcule toutes les métriques pour un document et retourne un DocumentResult.
+
+    Utilisable à la fois dans le processus principal (IO-bound) et dans les
+    sous-processus créés par ProcessPoolExecutor (CPU-bound).
+    Les imports lourds sont différés pour accélérer le démarrage des sous-processus.
+
+    Chantier 2 (post-Sprint 97) — refonte
+    ------------------------------------
+    Les 11 ``try/except`` codés en dur (Sprints 5+10+39+42+61+86+87) sont
+    désormais centralisés dans ``picarones.measurements.builtin_hooks`` et
+    sélectionnés via ``run_document_hooks(profile)``.  Le profil
+    ``"standard"`` (défaut) reproduit strictement le comportement
+    pré-chantier-2.  Les profils ``"minimal"``, ``"philological"``,
+    ``"diagnostics"``, ``"economics"``, ``"pipeline"``, ``"full"``
+    permettent à l'utilisateur de moduler le coût de calcul.
+    """
+    import logging as _logging
+    _logger = _logging.getLogger(__name__)
+
+    # Eager-load des hooks natifs pour peupler le registre dans les
+    # sous-processus du pool (le top-level ``import`` du runner ne le fait
+    # pas pour ne pas pénaliser le démarrage des moteurs minimaux).
+    import picarones.measurements.builtin_hooks  # noqa: F401
+    from picarones.core.metric_hooks import run_document_hooks
+
+    if ocr_result.success:
+        metrics = compute_metrics(ground_truth, ocr_result.text, char_exclude=char_exclude)
+    else:
+        metrics = MetricsResult(
+            cer=1.0, cer_nfc=1.0, cer_caseless=1.0,
+            wer=1.0, wer_normalized=1.0, mer=1.0, wil=1.0,
+            reference_length=len(ground_truth),
+            hypothesis_length=0,
+            error=ocr_result.error,
+        )
+
+    ocr_intermediate = ocr_result.metadata.get("ocr_intermediate")
+    pipeline_meta: dict = {}
+
+    if ocr_result.metadata.get("is_pipeline"):
+        pipeline_meta = {
+            "pipeline_mode": ocr_result.metadata.get("pipeline_mode"),
+            "prompt_file": ocr_result.metadata.get("prompt_file"),
+            "llm_model": ocr_result.metadata.get("llm_model"),
+            "llm_provider": ocr_result.metadata.get("llm_provider"),
+        }
+        if ocr_intermediate is not None and ocr_result.success:
+            try:
+                from picarones.pipelines.over_normalization import detect_over_normalization
+                over_norm = detect_over_normalization(
+                    ground_truth=ground_truth,
+                    ocr_text=ocr_intermediate,
+                    llm_text=ocr_result.text,
+                )
+                pipeline_meta["over_normalization"] = over_norm.as_dict()
+            except Exception as e:
+                _logger.warning("[over_normalization] fonctionnalité dégradée : %s", e)
+
+    # Hooks document-level — chaque hook produit un attribut nommé du
+    # ``DocumentResult``.  Les hooks invalides pour ce contexte (échec
+    # OCR pour les hooks ``requires_success``, absence de
+    # ``token_confidences`` pour ``calibration``) sont sautés
+    # silencieusement.  Les exceptions levées par un hook sont
+    # capturées et loggées en warning par ``run_document_hooks``.
+    extras = run_document_hooks(
+        profile,
+        ground_truth=ground_truth,
+        hypothesis=ocr_result.text,
+        image_path=image_path,
+        corpus_lang=corpus_lang,
+        ocr_result=ocr_result,
+    )
+
+    return DocumentResult(
+        doc_id=doc_id,
+        image_path=image_path,
+        ground_truth=ground_truth,
+        hypothesis=ocr_result.text,
+        metrics=metrics,
+        duration_seconds=ocr_result.duration_seconds,
+        engine_error=ocr_result.error,
+        ocr_intermediate=ocr_intermediate,
+        pipeline_metadata=pipeline_meta,
+        confusion_matrix=extras.get("confusion_matrix"),
+        char_scores=extras.get("char_scores"),
+        taxonomy=extras.get("taxonomy"),
+        structure=extras.get("structure"),
+        image_quality=extras.get("image_quality"),
+        line_metrics=extras.get("line_metrics"),
+        hallucination_metrics=extras.get("hallucination_metrics"),
+        calibration_metrics=extras.get("calibration_metrics"),
+        philological_metrics=extras.get("philological_metrics"),
+        searchability_metrics=extras.get("searchability_metrics"),
+        numerical_sequence_metrics=extras.get("numerical_sequence_metrics"),
+        readability_metrics=extras.get("readability_metrics"),
+    )
+
+
+def _make_timeout_doc_result(doc: object, timeout_seconds: float) -> DocumentResult:
+    """DocumentResult synthétique pour un document ayant dépassé le timeout."""
+    err = f"timeout ({timeout_seconds:.0f}s)"
+    metrics = MetricsResult(
+        cer=1.0, cer_nfc=1.0, cer_caseless=1.0,
+        wer=1.0, wer_normalized=1.0, mer=1.0, wil=1.0,
+        reference_length=len(doc.ground_truth),  # type: ignore[attr-defined]
+        hypothesis_length=0,
+        error=err,
+    )
+    return DocumentResult(
+        doc_id=doc.doc_id,  # type: ignore[attr-defined]
+        image_path=str(doc.image_path),  # type: ignore[attr-defined]
+        ground_truth=doc.ground_truth,  # type: ignore[attr-defined]
+        hypothesis="",
+        metrics=metrics,
+        duration_seconds=timeout_seconds,
+        engine_error=err,
+    )
+
+
+def _make_error_doc_result(doc: object, error_msg: str) -> DocumentResult:
+    """DocumentResult synthétique pour une erreur lors d'un appel engine."""
+    metrics = MetricsResult(
+        cer=1.0, cer_nfc=1.0, cer_caseless=1.0,
+        wer=1.0, wer_normalized=1.0, mer=1.0, wil=1.0,
+        reference_length=len(doc.ground_truth),  # type: ignore[attr-defined]
+        hypothesis_length=0,
+        error=error_msg,
+    )
+    return DocumentResult(
+        doc_id=doc.doc_id,  # type: ignore[attr-defined]
+        image_path=str(doc.image_path),  # type: ignore[attr-defined]
+        ground_truth=doc.ground_truth,  # type: ignore[attr-defined]
+        hypothesis="",
+        metrics=metrics,
+        duration_seconds=0.0,
+        engine_error=error_msg,
+    )
+
+
+__all__ = [
+    "_calibration_from_engine_result",
+    "_compute_document_result",
+    "_make_error_doc_result",
+    "_make_timeout_doc_result",
+]

picarones/measurements/runner/ner_attach.py

@@ -0,0 +1,133 @@
+"""Câblage NER au post-process du benchmark (Sprint 40).
+
+Le runner appelle :func:`_attach_ner_metrics` après que tous les
+documents ont été calculés, pour les moteurs où la GT possède un
+niveau ``ENTITIES`` (Sprint 32 — multi-level GT).
+
+L'extracteur NER est typiquement un wrapper :class:`SpacyEntityExtractor`
+construit via :func:`picarones.measurements.ner_backends.get_extractor`.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from picarones.core.corpus import Corpus
+
+logger = logging.getLogger(__name__)
+
+
+def _attach_ner_metrics(
+    corpus: Corpus,
+    doc_results: list,
+    entity_extractor: callable,
+) -> None:
+    """Calcule et attache ``DocumentResult.ner_metrics`` pour chaque doc
+    dont la GT possède un niveau ``ENTITIES`` (Sprint 32).
+
+    L'extracteur est appelé sur l'hypothèse OCR ``dr.hypothesis``.
+    Les erreurs sont dégradées en warnings (pas de propagation) afin
+    de ne pas casser le benchmark si un document spécifique fait
+    crasher le NER.
+    """
+    try:
+        from picarones.core.corpus import GTLevel
+        from picarones.measurements.ner import compute_ner_metrics
+    except ImportError as exc:
+        logger.warning("[ner.attach] imports indisponibles : %s", exc)
+        return
+
+    docs_by_id = {d.doc_id: d for d in corpus.documents}
+    n_done = 0
+    for dr in doc_results:
+        if dr.engine_error is not None or not dr.hypothesis:
+            continue
+        doc = docs_by_id.get(dr.doc_id)
+        if doc is None or not doc.has_gt(GTLevel.ENTITIES):
+            continue
+        try:
+            gt_payload = doc.get_gt(GTLevel.ENTITIES)
+            gt_entities = list(gt_payload.entities) if gt_payload else []
+            hyp_entities = entity_extractor(dr.hypothesis) or []
+            dr.ner_metrics = compute_ner_metrics(gt_entities, hyp_entities)
+            n_done += 1
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(
+                "[ner.attach] %s : extraction/comparaison NER dégradée : %s",
+                dr.doc_id, exc,
+            )
+
+    if n_done > 0:
+        logger.info("[ner] %d documents évalués pour NER.", n_done)
+
+
+def _aggregate_ner(doc_results: list) -> "dict | None":
+    """Agrège les métriques NER au niveau du moteur.
+
+    Recalcule precision/recall/F1 *micro* à partir des sommes globales
+    de TP/FP/FN, plus le détail par catégorie, plus les compteurs
+    totaux d'hallucinations et d'entités manquées.
+    """
+    relevant = [dr for dr in doc_results if dr.ner_metrics is not None]
+    if not relevant:
+        return None
+
+    total_tp = 0
+    total_fp = 0
+    total_fn = 0
+    cat_tp: dict[str, int] = {}
+    cat_fp: dict[str, int] = {}
+    cat_fn: dict[str, int] = {}
+    total_hallucinated = 0
+    total_missed = 0
+    iou_threshold = 0.5
+
+    for dr in relevant:
+        m = dr.ner_metrics
+        total_tp += int(m.get("true_positives", 0))
+        total_fp += int(m.get("false_positives", 0))
+        total_fn += int(m.get("false_negatives", 0))
+        total_hallucinated += len(m.get("hallucinated_entities", []) or [])
+        total_missed += len(m.get("missed_entities", []) or [])
+        iou_threshold = float(m.get("iou_threshold", iou_threshold))
+        for cat, stats in (m.get("per_category") or {}).items():
+            cat_tp[cat] = cat_tp.get(cat, 0)
+            cat_fp[cat] = cat_fp.get(cat, 0)
+            cat_fn[cat] = cat_fn.get(cat, 0)
+            # Reconstitue les sommes par catégorie via support et P/R
+            support = int(stats.get("support", 0))
+            recall = float(stats.get("recall", 0.0))
+            precision = float(stats.get("precision", 0.0))
+            tp_cat = round(support * recall) if support > 0 else 0
+            fn_cat = max(0, support - tp_cat)
+            fp_cat = (
+                round(tp_cat * (1 - precision) / precision)
+                if precision > 0 else 0
+            )
+            cat_tp[cat] += tp_cat
+            cat_fp[cat] += fp_cat
+            cat_fn[cat] += fn_cat
+
+    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}
+
+    return {
+        "global": _prf(total_tp, total_fp, total_fn),
+        "per_category": {
+            cat: _prf(cat_tp[cat], cat_fp[cat], cat_fn[cat])
+            for cat in sorted(set(cat_tp) | set(cat_fp) | set(cat_fn))
+        },
+        "true_positives": total_tp,
+        "false_positives": total_fp,
+        "false_negatives": total_fn,
+        "hallucinated_total": total_hallucinated,
+        "missed_total": total_missed,
+        "doc_count": len(relevant),
+        "iou_threshold": iou_threshold,
+    }
+
+
+__all__ = ["_aggregate_ner", "_attach_ner_metrics"]

picarones/measurements/{runner.py → runner/orchestration.py}

@@ -1,21 +1,25 @@
-"""Orchestrateur du benchmark.
+"""Orchestrateur principal du benchmark.
 
-Exécute les moteurs OCR/HTR sur le corpus de manière parallèle :
-- ``ProcessPoolExecutor`` pour les moteurs CPU-bound (Tesseract, Pero OCR, Kraken)
-- ``ThreadPoolExecutor``  pour les moteurs IO-bound / API (Mistral, Google, Azure, LLMs)
+Contient :func:`run_benchmark` et son helper :func:`_build_pipeline_info`.
 
-Les résultats partiels sont sauvegardés après chaque document dans un fichier
-``{partial_dir}/{corpus}_{engine}.partial.json`` (NDJSON).  Si le benchmark est
-interrompu, la prochaine exécution reprend automatiquement depuis ce fichier.
+Le runner exécute chaque moteur de la liste sur le corpus complet :
+
+- Pour les moteurs CPU-bound (``execution_mode == "cpu"`` :
+  Tesseract, Pero OCR, Kraken), utilise un ``ProcessPoolExecutor``
+  et délègue aux workers picklables de :mod:`workers`.
+- Pour les moteurs IO-bound (Mistral, Google Vision, Azure, LLMs),
+  utilise un ``ThreadPoolExecutor``.
+
+Les résultats partiels (NDJSON par moteur) sont gérés par
+:mod:`partial` ; le calcul d'un :class:`DocumentResult` individuel
+par :mod:`document` ; l'agrégation finale par les hooks délégués à
+:mod:`builtin_hooks` (chantier 2 post-Sprint 97).
 """
 
 from __future__ import annotations
 
 import concurrent.futures
-import json
 import logging
-import re
-import tempfile
 import threading
 import time
 from pathlib import Path
@@ -24,379 +28,28 @@ from typing import Optional
 from tqdm import tqdm
 
 from picarones.core.corpus import Corpus
-from picarones.measurements.metrics import MetricsResult, compute_metrics
 from picarones.core.results import BenchmarkResult, DocumentResult, EngineReport
-from picarones.engines.base import BaseOCREngine, EngineResult
+from picarones.engines.base import BaseOCREngine
+from picarones.measurements.runner.document import (
+    _make_error_doc_result,
+    _make_timeout_doc_result,
+)
+from picarones.measurements.runner.ner_attach import (
+    _aggregate_ner,
+    _attach_ner_metrics,
+)
+from picarones.measurements.runner.partial import (
+    _delete_partial,
+    _load_partial,
+    _save_partial_line,
+)
+from picarones.measurements.runner.workers import (
+    _cpu_doc_worker,
+    _io_doc_worker,
+)
 
 logger = logging.getLogger(__name__)
 
-# Lock pour la sérialisation des écritures de résultats partiels
-_partial_write_lock = threading.Lock()
-
-
-# ---------------------------------------------------------------------------
-# Workers de niveau module (requis pour ProcessPoolExecutor — picklables)
-# ---------------------------------------------------------------------------
-
-def _cpu_doc_worker(args: tuple) -> "DocumentResult":
-    """Worker pour ProcessPoolExecutor (moteurs CPU-bound).
-
-    Instancie le moteur dans le sous-processus, exécute l'OCR et calcule
-    toutes les métriques.  Doit être une fonction de niveau module pour être
-    sérialisable par ``pickle``.
-
-    Le tuple ``args`` peut contenir, par compatibilité ascendante :
-    - 7 éléments : legacy (Sprint 13)
-    - 8 éléments : + ``corpus_lang`` (Sprint 87)
-    - 9 éléments : + ``profile`` (chantier 2 post-Sprint 97)
-    """
-    if len(args) == 9:
-        (engine_module, engine_class_name, engine_config, doc_id,
-         image_path, ground_truth, char_exclude_chars, corpus_lang,
-         profile) = args
-    elif len(args) == 8:
-        (engine_module, engine_class_name, engine_config, doc_id,
-         image_path, ground_truth, char_exclude_chars, corpus_lang) = args
-        profile = "standard"
-    else:
-        (engine_module, engine_class_name, engine_config, doc_id,
-         image_path, ground_truth, char_exclude_chars) = args
-        corpus_lang = "fr"
-        profile = "standard"
-    import importlib
-    mod = importlib.import_module(engine_module)
-    engine_cls = getattr(mod, engine_class_name)
-    engine = engine_cls(config=engine_config)
-    ocr_result = engine.run(image_path)
-    char_exclude = frozenset(char_exclude_chars) if char_exclude_chars else None
-    return _compute_document_result(
-        doc_id=doc_id,
-        image_path=image_path,
-        ground_truth=ground_truth,
-        ocr_result=ocr_result,
-        char_exclude=char_exclude,
-        corpus_lang=corpus_lang,
-        profile=profile,
-    )
-
-
-def _io_doc_worker(
-    engine: BaseOCREngine,
-    doc: object,
-    char_exclude: Optional[frozenset],
-    corpus_lang: str = "fr",
-    profile: str = "standard",
-) -> "DocumentResult":
-    """Worker pour ThreadPoolExecutor (moteurs IO-bound / API).
-
-    Exécute l'OCR et calcule les métriques dans un thread.  L'instance du
-    moteur est partagée entre les threads — les adaptateurs HTTP sont
-    généralement sans état mutable entre les appels.
-
-    Si le document possède un texte OCR pré-calculé (corpus triplet) et que
-    le moteur est un pipeline OCR+LLM, utilise ``run_with_ocr_text()`` pour
-    court-circuiter l'étape OCR et tester directement la post-correction LLM.
-    """
-    doc_ocr_text = getattr(doc, "ocr_text", None)
-    if doc_ocr_text is not None:
-        # Corpus triplet — vérifier si le moteur supporte run_with_ocr_text
-        run_with = getattr(engine, "run_with_ocr_text", None)
-        if run_with is not None:
-            ocr_result = run_with(doc.image_path, doc_ocr_text)  # type: ignore[attr-defined]
-        else:
-            # Moteur OCR classique — ignorer le texte OCR pré-calculé
-            ocr_result = engine.run(doc.image_path)  # type: ignore[attr-defined]
-    else:
-        ocr_result = engine.run(doc.image_path)  # type: ignore[attr-defined]
-
-    return _compute_document_result(
-        doc_id=doc.doc_id,  # type: ignore[attr-defined]
-        image_path=str(doc.image_path),  # type: ignore[attr-defined]
-        ground_truth=doc.ground_truth,  # type: ignore[attr-defined]
-        ocr_result=ocr_result,
-        char_exclude=char_exclude,
-        corpus_lang=corpus_lang,
-        profile=profile,
-    )
-
-
-# ---------------------------------------------------------------------------
-# Calcul documentaire centralisé
-# ---------------------------------------------------------------------------
-
-
-# Chantier 2 (post-Sprint 97) — la logique du helper calibration vit
-# désormais dans :mod:`picarones.measurements.builtin_hooks`. Ce nom reste exposé
-# ici pour la rétrocompat des tests Sprint 42 qui font
-# ``from picarones.measurements.runner import _calibration_from_engine_result``.
-def _calibration_from_engine_result(
-    ground_truth: str,
-    token_confidences: list,
-) -> Optional[dict]:
-    """Délégation vers :func:`picarones.measurements.builtin_hooks.calibration_from_engine_result`.
-
-    Conservé pour la rétrocompat des tests existants ; toute évolution
-    du calcul doit se faire dans ``builtin_hooks``.
-    """
-    from picarones.measurements.builtin_hooks import calibration_from_engine_result
-    return calibration_from_engine_result(ground_truth, token_confidences)
-
-
-
-
-def _compute_document_result(
-    doc_id: str,
-    image_path: str,
-    ground_truth: str,
-    ocr_result: EngineResult,
-    char_exclude: Optional[frozenset],
-    corpus_lang: str = "fr",
-    profile: str = "standard",
-) -> DocumentResult:
-    """Calcule toutes les métriques pour un document et retourne un DocumentResult.
-
-    Utilisable à la fois dans le processus principal (IO-bound) et dans les
-    sous-processus créés par ProcessPoolExecutor (CPU-bound).
-    Les imports lourds sont différés pour accélérer le démarrage des sous-processus.
-
-    Chantier 2 (post-Sprint 97) — refonte
-    ------------------------------------
-    Les 11 ``try/except`` codés en dur (Sprints 5+10+39+42+61+86+87) sont
-    désormais centralisés dans ``picarones.measurements.builtin_hooks`` et
-    sélectionnés via ``run_document_hooks(profile)``.  Le profil
-    ``"standard"`` (défaut) reproduit strictement le comportement
-    pré-chantier-2.  Les profils ``"minimal"``, ``"philological"``,
-    ``"diagnostics"``, ``"economics"``, ``"pipeline"``, ``"full"``
-    permettent à l'utilisateur de moduler le coût de calcul.
-    """
-    import logging as _logging
-    _logger = _logging.getLogger(__name__)
-
-    # Eager-load des hooks natifs pour peupler le registre dans les
-    # sous-processus du pool (le top-level ``import`` du runner ne le fait
-    # pas pour ne pas pénaliser le démarrage des moteurs minimaux).
-    import picarones.measurements.builtin_hooks  # noqa: F401
-    from picarones.core.metric_hooks import run_document_hooks
-
-    if ocr_result.success:
-        metrics = compute_metrics(ground_truth, ocr_result.text, char_exclude=char_exclude)
-    else:
-        metrics = MetricsResult(
-            cer=1.0, cer_nfc=1.0, cer_caseless=1.0,
-            wer=1.0, wer_normalized=1.0, mer=1.0, wil=1.0,
-            reference_length=len(ground_truth),
-            hypothesis_length=0,
-            error=ocr_result.error,
-        )
-
-    ocr_intermediate = ocr_result.metadata.get("ocr_intermediate")
-    pipeline_meta: dict = {}
-
-    if ocr_result.metadata.get("is_pipeline"):
-        pipeline_meta = {
-            "pipeline_mode": ocr_result.metadata.get("pipeline_mode"),
-            "prompt_file": ocr_result.metadata.get("prompt_file"),
-            "llm_model": ocr_result.metadata.get("llm_model"),
-            "llm_provider": ocr_result.metadata.get("llm_provider"),
-        }
-        if ocr_intermediate is not None and ocr_result.success:
-            try:
-                from picarones.pipelines.over_normalization import detect_over_normalization
-                over_norm = detect_over_normalization(
-                    ground_truth=ground_truth,
-                    ocr_text=ocr_intermediate,
-                    llm_text=ocr_result.text,
-                )
-                pipeline_meta["over_normalization"] = over_norm.as_dict()
-            except Exception as e:
-                _logger.warning("[over_normalization] fonctionnalité dégradée : %s", e)
-
-    # Hooks document-level — chaque hook produit un attribut nommé du
-    # ``DocumentResult``.  Les hooks invalides pour ce contexte (échec
-    # OCR pour les hooks ``requires_success``, absence de
-    # ``token_confidences`` pour ``calibration``) sont sautés
-    # silencieusement.  Les exceptions levées par un hook sont
-    # capturées et loggées en warning par ``run_document_hooks``.
-    extras = run_document_hooks(
-        profile,
-        ground_truth=ground_truth,
-        hypothesis=ocr_result.text,
-        image_path=image_path,
-        corpus_lang=corpus_lang,
-        ocr_result=ocr_result,
-    )
-
-    return DocumentResult(
-        doc_id=doc_id,
-        image_path=image_path,
-        ground_truth=ground_truth,
-        hypothesis=ocr_result.text,
-        metrics=metrics,
-        duration_seconds=ocr_result.duration_seconds,
-        engine_error=ocr_result.error,
-        ocr_intermediate=ocr_intermediate,
-        pipeline_metadata=pipeline_meta,
-        confusion_matrix=extras.get("confusion_matrix"),
-        char_scores=extras.get("char_scores"),
-        taxonomy=extras.get("taxonomy"),
-        structure=extras.get("structure"),
-        image_quality=extras.get("image_quality"),
-        line_metrics=extras.get("line_metrics"),
-        hallucination_metrics=extras.get("hallucination_metrics"),
-        calibration_metrics=extras.get("calibration_metrics"),
-        philological_metrics=extras.get("philological_metrics"),
-        searchability_metrics=extras.get("searchability_metrics"),
-        numerical_sequence_metrics=extras.get("numerical_sequence_metrics"),
-        readability_metrics=extras.get("readability_metrics"),
-    )
-
-
-def _make_timeout_doc_result(doc: object, timeout_seconds: float) -> DocumentResult:
-    """DocumentResult synthétique pour un document ayant dépassé le timeout."""
-    err = f"timeout ({timeout_seconds:.0f}s)"
-    metrics = MetricsResult(
-        cer=1.0, cer_nfc=1.0, cer_caseless=1.0,
-        wer=1.0, wer_normalized=1.0, mer=1.0, wil=1.0,
-        reference_length=len(doc.ground_truth),  # type: ignore[attr-defined]
-        hypothesis_length=0,
-        error=err,
-    )
-    return DocumentResult(
-        doc_id=doc.doc_id,  # type: ignore[attr-defined]
-        image_path=str(doc.image_path),  # type: ignore[attr-defined]
-        ground_truth=doc.ground_truth,  # type: ignore[attr-defined]
-        hypothesis="",
-        metrics=metrics,
-        duration_seconds=timeout_seconds,
-        engine_error=err,
-    )
-
-
-def _make_error_doc_result(doc: object, error_msg: str) -> DocumentResult:
-    """DocumentResult synthétique pour un document en erreur inattendue."""
-    metrics = MetricsResult(
-        cer=1.0, cer_nfc=1.0, cer_caseless=1.0,
-        wer=1.0, wer_normalized=1.0, mer=1.0, wil=1.0,
-        reference_length=len(doc.ground_truth),  # type: ignore[attr-defined]
-        hypothesis_length=0,
-        error=error_msg,
-    )
-    return DocumentResult(
-        doc_id=doc.doc_id,  # type: ignore[attr-defined]
-        image_path=str(doc.image_path),  # type: ignore[attr-defined]
-        ground_truth=doc.ground_truth,  # type: ignore[attr-defined]
-        hypothesis="",
-        metrics=metrics,
-        duration_seconds=0.0,
-        engine_error=error_msg,
-    )
-
-
-# ---------------------------------------------------------------------------
-# Résultats partiels (sauvegarde / reprise)
-# ---------------------------------------------------------------------------
-
-def _sanitize_filename(s: str) -> str:
-    return re.sub(r"[^\w\-]", "_", s)[:64]
-
-
-def _partial_path(
-    corpus_name: str,
-    engine_name: str,
-    partial_dir: Optional[str | Path],
-) -> Path:
-    base = Path(partial_dir) if partial_dir else Path(tempfile.gettempdir())
-    name = (
-        f"picarones_{_sanitize_filename(corpus_name)}"
-        f"_{_sanitize_filename(engine_name)}.partial.json"
-    )
-    return base / name
-
-
-def _load_partial(
-    corpus_name: str,
-    engine_name: str,
-    partial_dir: Optional[str | Path],
-) -> tuple[Path, list[DocumentResult]]:
-    """Charge les résultats partiels d'une exécution précédente interrompue.
-
-    Returns
-    -------
-    (path, results) — chemin du fichier partiel et liste des DocumentResult déjà calculés.
-    """
-    path = _partial_path(corpus_name, engine_name, partial_dir)
-    results: list[DocumentResult] = []
-    if not path.exists():
-        return path, results
-
-    try:
-        with path.open("r", encoding="utf-8") as fh:
-            for line in fh:
-                line = line.strip()
-                if not line:
-                    continue
-                d = json.loads(line)
-                m = d.get("metrics", {})
-                metrics = MetricsResult(
-                    cer=m.get("cer", 1.0),
-                    cer_nfc=m.get("cer_nfc", 1.0),
-                    cer_caseless=m.get("cer_caseless", 1.0),
-                    wer=m.get("wer", 1.0),
-                    wer_normalized=m.get("wer_normalized", 1.0),
-                    mer=m.get("mer", 1.0),
-                    wil=m.get("wil", 1.0),
-                    reference_length=m.get("reference_length", 0),
-                    hypothesis_length=m.get("hypothesis_length", 0),
-                    error=m.get("error"),
-                )
-                results.append(DocumentResult(
-                    doc_id=d["doc_id"],
-                    image_path=d.get("image_path", ""),
-                    ground_truth=d.get("ground_truth", ""),
-                    hypothesis=d.get("hypothesis", ""),
-                    metrics=metrics,
-                    duration_seconds=d.get("duration_seconds", 0.0),
-                    engine_error=d.get("engine_error"),
-                    ocr_intermediate=d.get("ocr_intermediate"),
-                    pipeline_metadata=d.get("pipeline_metadata", {}),
-                    confusion_matrix=d.get("confusion_matrix"),
-                    char_scores=d.get("char_scores"),
-                    taxonomy=d.get("taxonomy"),
-                    structure=d.get("structure"),
-                    image_quality=d.get("image_quality"),
-                    line_metrics=d.get("line_metrics"),
-                    hallucination_metrics=d.get("hallucination_metrics"),
-                ))
-    except Exception as e:
-        logger.warning("Impossible de charger les résultats partiels '%s' : %s", path, e)
-        results = []
-
-    return path, results
-
-
-def _save_partial_line(partial_path: Path, doc_result: DocumentResult) -> None:
-    """Ajoute une entrée NDJSON au fichier de résultats partiels (thread-safe)."""
-    try:
-        line = json.dumps(doc_result.as_dict(), ensure_ascii=False) + "\n"
-        with _partial_write_lock:
-            with partial_path.open("a", encoding="utf-8") as fh:
-                fh.write(line)
-    except Exception as e:
-        logger.warning("Impossible d'écrire dans le fichier partiel '%s' : %s", partial_path, e)
-
-
-def _delete_partial(partial_path: Path) -> None:
-    """Supprime le fichier de résultats partiels à la fin d'un moteur."""
-    try:
-        if partial_path.exists():
-            partial_path.unlink()
-    except Exception as e:
-        logger.warning("Impossible de supprimer le fichier partiel '%s' : %s", partial_path, e)
-
-
-# ---------------------------------------------------------------------------
-# Benchmark principal
-# ---------------------------------------------------------------------------
 
 def run_benchmark(
     corpus: Corpus,
@@ -838,182 +491,4 @@ def _build_pipeline_info(engine: BaseOCREngine, doc_results: list[DocumentResult
     return info
 
 
-# ---------------------------------------------------------------------------
-# Helpers d'agrégation — délégations rétrocompat
-# ---------------------------------------------------------------------------
-# Chantier 2 (post-Sprint 97) : les implémentations vivent désormais dans
-# :mod:`picarones.measurements.builtin_hooks` (single source of truth, exposé via
-# le registre :mod:`picarones.core.metric_hooks`).  Les noms ci-dessous
-# restent disponibles depuis ``picarones.measurements.runner`` pour la rétrocompat
-# des tests Sprint 13 / 42 qui les importent directement.
-
-def _aggregate_confusion(doc_results: list) -> Optional[dict]:
-    """Délégation vers :func:`builtin_hooks._aggregate_confusion`."""
-    from picarones.measurements.builtin_hooks import _aggregate_confusion as _impl
-    return _impl(doc_results)
-
-
-def _aggregate_char_scores(doc_results: list) -> Optional[dict]:
-    """Délégation vers :func:`builtin_hooks._aggregate_char_scores`."""
-    from picarones.measurements.builtin_hooks import _aggregate_char_scores as _impl
-    return _impl(doc_results)
-
-
-def _aggregate_taxonomy(doc_results: list) -> Optional[dict]:
-    """Délégation vers :func:`builtin_hooks._aggregate_taxonomy`."""
-    from picarones.measurements.builtin_hooks import _aggregate_taxonomy as _impl
-    return _impl(doc_results)
-
-
-def _aggregate_structure(doc_results: list) -> Optional[dict]:
-    """Délégation vers :func:`builtin_hooks._aggregate_structure`."""
-    from picarones.measurements.builtin_hooks import _aggregate_structure as _impl
-    return _impl(doc_results)
-
-
-def _aggregate_image_quality(doc_results: list) -> Optional[dict]:
-    """Délégation vers :func:`builtin_hooks._aggregate_image_quality`."""
-    from picarones.measurements.builtin_hooks import _aggregate_image_quality as _impl
-    return _impl(doc_results)
-
-
-def _aggregate_line_metrics(doc_results: list) -> Optional[dict]:
-    """Délégation vers :func:`builtin_hooks._aggregate_line_metrics`."""
-    from picarones.measurements.builtin_hooks import _aggregate_line_metrics as _impl
-    return _impl(doc_results)
-
-
-def _aggregate_hallucination(doc_results: list) -> Optional[dict]:
-    """Délégation vers :func:`builtin_hooks._aggregate_hallucination`."""
-    from picarones.measurements.builtin_hooks import _aggregate_hallucination as _impl
-    return _impl(doc_results)
-
-
-# ────────────────────────────────────────��─────────────────────────────────
-# Sprint 40 — extraction NER au post-process et agrégation
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def _attach_ner_metrics(
-    corpus: Corpus,
-    doc_results: list,
-    entity_extractor: callable,
-) -> None:
-    """Calcule et attache ``DocumentResult.ner_metrics`` pour chaque doc
-    dont la GT possède un niveau ``ENTITIES`` (Sprint 32).
-
-    L'extracteur est appelé sur l'hypothèse OCR ``dr.hypothesis``.
-    Les erreurs sont dégradées en warnings (pas de propagation) afin
-    de ne pas casser le benchmark si un document spécifique fait
-    crasher le NER.
-    """
-    try:
-        from picarones.core.corpus import GTLevel
-        from picarones.measurements.ner import compute_ner_metrics
-    except ImportError as exc:
-        logger.warning("[ner.attach] imports indisponibles : %s", exc)
-        return
-
-    docs_by_id = {d.doc_id: d for d in corpus.documents}
-    n_done = 0
-    for dr in doc_results:
-        if dr.engine_error is not None or not dr.hypothesis:
-            continue
-        doc = docs_by_id.get(dr.doc_id)
-        if doc is None or not doc.has_gt(GTLevel.ENTITIES):
-            continue
-        try:
-            gt_payload = doc.get_gt(GTLevel.ENTITIES)
-            gt_entities = list(gt_payload.entities) if gt_payload else []
-            hyp_entities = entity_extractor(dr.hypothesis) or []
-            dr.ner_metrics = compute_ner_metrics(gt_entities, hyp_entities)
-            n_done += 1
-        except Exception as exc:  # noqa: BLE001
-            logger.warning(
-                "[ner.attach] %s : extraction/comparaison NER dégradée : %s",
-                dr.doc_id, exc,
-            )
-
-    if n_done > 0:
-        logger.info("[ner] %d documents évalués pour NER.", n_done)
-
-
-def _aggregate_calibration(doc_results: list) -> Optional[dict]:
-    """Délégation vers :func:`builtin_hooks._aggregate_calibration`.
-
-    Conservé pour la rétrocompat du test ``test_sprint42_calibration_runner``
-    qui importe directement depuis ``picarones.measurements.runner``. La logique
-    réelle vit dans :mod:`picarones.measurements.builtin_hooks` (chantier 2
-    post-Sprint 97).
-    """
-    from picarones.measurements.builtin_hooks import _aggregate_calibration as _impl
-    return _impl(doc_results)
-
-
-def _aggregate_ner(doc_results: list) -> Optional[dict]:
-    """Agrège les métriques NER au niveau du moteur.
-
-    Recalcule precision/recall/F1 *micro* à partir des sommes globales
-    de TP/FP/FN, plus le détail par catégorie, plus les compteurs
-    totaux d'hallucinations et d'entités manquées.
-    """
-    relevant = [dr for dr in doc_results if dr.ner_metrics is not None]
-    if not relevant:
-        return None
-
-    total_tp = 0
-    total_fp = 0
-    total_fn = 0
-    cat_tp: dict[str, int] = {}
-    cat_fp: dict[str, int] = {}
-    cat_fn: dict[str, int] = {}
-    total_hallucinated = 0
-    total_missed = 0
-    iou_threshold = 0.5
-
-    for dr in relevant:
-        m = dr.ner_metrics
-        total_tp += int(m.get("true_positives", 0))
-        total_fp += int(m.get("false_positives", 0))
-        total_fn += int(m.get("false_negatives", 0))
-        total_hallucinated += len(m.get("hallucinated_entities", []) or [])
-        total_missed += len(m.get("missed_entities", []) or [])
-        iou_threshold = float(m.get("iou_threshold", iou_threshold))
-        for cat, stats in (m.get("per_category") or {}).items():
-            cat_tp[cat] = cat_tp.get(cat, 0)
-            cat_fp[cat] = cat_fp.get(cat, 0)
-            cat_fn[cat] = cat_fn.get(cat, 0)
-            # Reconstitue les sommes par catégorie via support et P/R
-            support = int(stats.get("support", 0))
-            recall = float(stats.get("recall", 0.0))
-            precision = float(stats.get("precision", 0.0))
-            tp_cat = round(support * recall) if support > 0 else 0
-            fn_cat = max(0, support - tp_cat)
-            fp_cat = (
-                round(tp_cat * (1 - precision) / precision)
-                if precision > 0 else 0
-            )
-            cat_tp[cat] += tp_cat
-            cat_fp[cat] += fp_cat
-            cat_fn[cat] += fn_cat
-
-    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}
-
-    return {
-        "global": _prf(total_tp, total_fp, total_fn),
-        "per_category": {
-            cat: _prf(cat_tp[cat], cat_fp[cat], cat_fn[cat])
-            for cat in sorted(set(cat_tp) | set(cat_fp) | set(cat_fn))
-        },
-        "true_positives": total_tp,
-        "false_positives": total_fp,
-        "false_negatives": total_fn,
-        "hallucinated_total": total_hallucinated,
-        "missed_total": total_missed,
-        "doc_count": len(relevant),
-        "iou_threshold": iou_threshold,
-    }
+__all__ = ["_build_pipeline_info", "run_benchmark"]

picarones/measurements/runner/partial.py

@@ -0,0 +1,140 @@
+"""Persistance des résultats partiels du benchmark (NDJSON).
+
+Quand le runner traite un corpus, il écrit chaque ``DocumentResult``
+dans un fichier ``{partial_dir}/picarones_{corpus}_{engine}.partial.json``
+au format NDJSON. Si le benchmark est interrompu (Ctrl+C, crash, kill),
+la prochaine exécution reprend depuis ce fichier sans perdre le travail
+déjà fait.
+
+Thread-safe : le module utilise un :class:`threading.Lock` partagé
+entre toutes les écritures pour sérialiser les appends.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import tempfile
+import threading
+from pathlib import Path
+from typing import Optional
+
+from picarones.core.results import DocumentResult
+from picarones.measurements.metrics import MetricsResult
+
+logger = logging.getLogger(__name__)
+
+# Lock pour la sérialisation des écritures de résultats partiels.
+# Partagé entre tous les call sites (workers IO et CPU se relayent
+# sur la même file).
+_partial_write_lock = threading.Lock()
+
+
+def _sanitize_filename(s: str) -> str:
+    return re.sub(r"[^\w\-]", "_", s)[:64]
+
+
+def _partial_path(
+    corpus_name: str,
+    engine_name: str,
+    partial_dir: Optional[str | Path],
+) -> Path:
+    base = Path(partial_dir) if partial_dir else Path(tempfile.gettempdir())
+    name = (
+        f"picarones_{_sanitize_filename(corpus_name)}"
+        f"_{_sanitize_filename(engine_name)}.partial.json"
+    )
+    return base / name
+
+
+def _load_partial(
+    corpus_name: str,
+    engine_name: str,
+    partial_dir: Optional[str | Path],
+) -> tuple[Path, list[DocumentResult]]:
+    """Charge les résultats partiels d'une exécution précédente interrompue.
+
+    Returns
+    -------
+    (path, results) — chemin du fichier partiel et liste des
+    DocumentResult déjà calculés.
+    """
+    path = _partial_path(corpus_name, engine_name, partial_dir)
+    results: list[DocumentResult] = []
+    if not path.exists():
+        return path, results
+
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                d = json.loads(line)
+                m = d.get("metrics", {})
+                metrics = MetricsResult(
+                    cer=m.get("cer", 1.0),
+                    cer_nfc=m.get("cer_nfc", 1.0),
+                    cer_caseless=m.get("cer_caseless", 1.0),
+                    wer=m.get("wer", 1.0),
+                    wer_normalized=m.get("wer_normalized", 1.0),
+                    mer=m.get("mer", 1.0),
+                    wil=m.get("wil", 1.0),
+                    reference_length=m.get("reference_length", 0),
+                    hypothesis_length=m.get("hypothesis_length", 0),
+                    error=m.get("error"),
+                )
+                results.append(DocumentResult(
+                    doc_id=d["doc_id"],
+                    image_path=d.get("image_path", ""),
+                    ground_truth=d.get("ground_truth", ""),
+                    hypothesis=d.get("hypothesis", ""),
+                    metrics=metrics,
+                    duration_seconds=d.get("duration_seconds", 0.0),
+                    engine_error=d.get("engine_error"),
+                    ocr_intermediate=d.get("ocr_intermediate"),
+                    pipeline_metadata=d.get("pipeline_metadata", {}),
+                    confusion_matrix=d.get("confusion_matrix"),
+                    char_scores=d.get("char_scores"),
+                    taxonomy=d.get("taxonomy"),
+                    structure=d.get("structure"),
+                    image_quality=d.get("image_quality"),
+                    line_metrics=d.get("line_metrics"),
+                    hallucination_metrics=d.get("hallucination_metrics"),
+                ))
+    except Exception as e:
+        logger.warning("Impossible de charger les résultats partiels '%s' : %s", path, e)
+        results = []
+
+    return path, results
+
+
+def _save_partial_line(partial_path: Path, doc_result: DocumentResult) -> None:
+    """Ajoute une entrée NDJSON au fichier de résultats partiels (thread-safe)."""
+    try:
+        line = json.dumps(doc_result.as_dict(), ensure_ascii=False) + "\n"
+        with _partial_write_lock:
+            with partial_path.open("a", encoding="utf-8") as fh:
+                fh.write(line)
+    except Exception as e:
+        logger.warning("Impossible d'écrire dans le fichier partiel '%s' : %s", partial_path, e)
+
+
+def _delete_partial(partial_path: Path) -> None:
+    """Supprime le fichier de résultats partiels à la fin d'un moteur."""
+    try:
+        if partial_path.exists():
+            partial_path.unlink()
+    except Exception as e:
+        logger.warning("Impossible de supprimer le fichier partiel '%s' : %s", partial_path, e)
+
+
+__all__ = [
+    "_delete_partial",
+    "_load_partial",
+    "_partial_path",
+    "_partial_write_lock",
+    "_sanitize_filename",
+    "_save_partial_line",
+]

picarones/measurements/runner/workers.py

@@ -0,0 +1,107 @@
+"""Workers de niveau module pour les pools d'exécution.
+
+Deux workers correspondant aux deux modes d'exécution :
+
+- :func:`_cpu_doc_worker` — pour ``ProcessPoolExecutor`` (moteurs
+  CPU-bound, instanciés dans le sous-processus). Doit être picklable :
+  c'est pour ça qu'il est défini au niveau module.
+- :func:`_io_doc_worker` — pour ``ThreadPoolExecutor`` (moteurs
+  IO-bound / API HTTP). L'instance du moteur est partagée entre les
+  threads.
+
+Les deux finissent par appeler :func:`_compute_document_result` du
+sous-module :mod:`document` pour calculer toutes les métriques.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from picarones.core.results import DocumentResult
+from picarones.engines.base import BaseOCREngine
+from picarones.measurements.runner.document import _compute_document_result
+
+
+def _cpu_doc_worker(args: tuple) -> "DocumentResult":
+    """Worker pour ProcessPoolExecutor (moteurs CPU-bound).
+
+    Instancie le moteur dans le sous-processus, exécute l'OCR et calcule
+    toutes les métriques.  Doit être une fonction de niveau module pour être
+    sérialisable par ``pickle``.
+
+    Le tuple ``args`` peut contenir, par compatibilité ascendante :
+    - 7 éléments : legacy (Sprint 13)
+    - 8 éléments : + ``corpus_lang`` (Sprint 87)
+    - 9 éléments : + ``profile`` (chantier 2 post-Sprint 97)
+    """
+    if len(args) == 9:
+        (engine_module, engine_class_name, engine_config, doc_id,
+         image_path, ground_truth, char_exclude_chars, corpus_lang,
+         profile) = args
+    elif len(args) == 8:
+        (engine_module, engine_class_name, engine_config, doc_id,
+         image_path, ground_truth, char_exclude_chars, corpus_lang) = args
+        profile = "standard"
+    else:
+        (engine_module, engine_class_name, engine_config, doc_id,
+         image_path, ground_truth, char_exclude_chars) = args
+        corpus_lang = "fr"
+        profile = "standard"
+    import importlib
+    mod = importlib.import_module(engine_module)
+    engine_cls = getattr(mod, engine_class_name)
+    engine = engine_cls(config=engine_config)
+    ocr_result = engine.run(image_path)
+    char_exclude = frozenset(char_exclude_chars) if char_exclude_chars else None
+    return _compute_document_result(
+        doc_id=doc_id,
+        image_path=image_path,
+        ground_truth=ground_truth,
+        ocr_result=ocr_result,
+        char_exclude=char_exclude,
+        corpus_lang=corpus_lang,
+        profile=profile,
+    )
+
+
+def _io_doc_worker(
+    engine: BaseOCREngine,
+    doc: object,
+    char_exclude: Optional[frozenset],
+    corpus_lang: str = "fr",
+    profile: str = "standard",
+) -> "DocumentResult":
+    """Worker pour ThreadPoolExecutor (moteurs IO-bound / API).
+
+    Exécute l'OCR et calcule les métriques dans un thread.  L'instance du
+    moteur est partagée entre les threads — les adaptateurs HTTP sont
+    généralement sans état mutable entre les appels.
+
+    Si le document possède un texte OCR pré-calculé (corpus triplet) et que
+    le moteur est un pipeline OCR+LLM, utilise ``run_with_ocr_text()`` pour
+    court-circuiter l'étape OCR et tester directement la post-correction LLM.
+    """
+    doc_ocr_text = getattr(doc, "ocr_text", None)
+    if doc_ocr_text is not None:
+        # Corpus triplet — vérifier si le moteur supporte run_with_ocr_text
+        run_with = getattr(engine, "run_with_ocr_text", None)
+        if run_with is not None:
+            ocr_result = run_with(doc.image_path, doc_ocr_text)  # type: ignore[attr-defined]
+        else:
+            # Moteur OCR classique — ignorer le texte OCR pré-calculé
+            ocr_result = engine.run(doc.image_path)  # type: ignore[attr-defined]
+    else:
+        ocr_result = engine.run(doc.image_path)  # type: ignore[attr-defined]
+
+    return _compute_document_result(
+        doc_id=doc.doc_id,  # type: ignore[attr-defined]
+        image_path=str(doc.image_path),  # type: ignore[attr-defined]
+        ground_truth=doc.ground_truth,  # type: ignore[attr-defined]
+        ocr_result=ocr_result,
+        char_exclude=char_exclude,
+        corpus_lang=corpus_lang,
+        profile=profile,
+    )
+
+
+__all__ = ["_cpu_doc_worker", "_io_doc_worker"]

tests/architecture/test_doc_paths.py

@@ -38,15 +38,18 @@ REPO_ROOT = Path(__file__).resolve().parents[2]
 #:   historiques référencent ``picarones/measurements/statistics.py``
 #:   qui est maintenant un sous-package. Baseline relevée.
 #: - 72 (sprint « zéro dette actionnable », 2026-05-02) : 50 chemins
-#:   massivement corrigés — 44 dans CLAUDE.md (``core/X.py`` →
-#:   ``measurements/X.py`` pour les modules réellement déplacés
-#:   historiquement) + 6 dans docs vivants (profiles, cli-workflows,
-#:   evolution-2026, user/writing-a-pipeline-module, SPECS).
+#:   massivement corrigés — 44 dans CLAUDE.md + 6 dans docs vivants.
+#: - 73 (sprint « découpage de runner.py », 2026-05-03) :
+#:   ``picarones/measurements/runner.py`` est désormais un sous-package
+#:   ``runner/``. ``docs/user/writing-a-pipeline-module.md`` a été
+#:   corrigé en place ; un audit historique
+#:   (``docs/audits/institutional-readiness-2026-05.md``) référence
+#:   l'ancien chemin et reste intouché par convention.
 #:
-#: Les 72 restants sont **TOUS** dans :
+#: Les 73 restants sont **TOUS** dans :
 #: - ``CHANGELOG.md`` (67) : journal historique versionné, intouchable.
-#: - ``docs/audits/*.md`` (5) : audits historiques, intouchables.
-BROKEN_PATHS_BASELINE = 72
+#: - ``docs/audits/*.md`` (6) : audits historiques, intouchables.
+BROKEN_PATHS_BASELINE = 73
 
 #: Patrons de fichiers de documentation à scanner.
 DOC_GLOBS: tuple[str, ...] = (

tests/architecture/test_file_budgets.py

@@ -39,7 +39,11 @@ FILE_BUDGETS: dict[str, int] = {
     # ``picarones/measurements/statistics/`` lors du sprint
     # « découpage de statistics.py » (2026-05-02). Plus aucun fichier
     # de la famille ne dépasse 350 lignes, donc aucune entrée requise.
-    "picarones/measurements/runner.py": 1200,             # actuel 1019
+    # runner.py (1019 lignes) a été éclaté en sous-package
+    # ``picarones/measurements/runner/`` lors du sprint
+    # « découpage de runner.py » (2026-05-03). Le plus gros sous-module
+    # est ``orchestration.py`` (494 lignes), surveillé ci-dessous.
+    "picarones/measurements/runner/orchestration.py": 575,  # actuel 494
     # --- Refactor (sprint « découpage de generator.py ») : passé de
     # 1063 à 431 lignes via extraction vers picarones/report/assets.py
     # et le sous-package picarones/report/report_data/. Budget serré

tests/integration/test_sprint13_parallelisation_stats.py

@@ -260,10 +260,16 @@ class TestRunnerPartialResults:
         from picarones.core.corpus import load_corpus_from_directory
         from picarones.measurements.runner import run_benchmark
         from picarones.engines.base import BaseOCREngine
-        import picarones.measurements.runner as runner_mod
+        # Sprint « découpage de runner.py » (mai 2026) : ``_save_partial_line``
+        # vit désormais dans le sous-module ``runner.partial`` ; le ré-export
+        # dans ``runner.__init__`` est une référence figée. Pour patcher
+        # dynamiquement la fonction utilisée par ``run_benchmark``, il faut
+        # cibler le module source.
+        from picarones.measurements.runner import partial as _partial_mod
+        from picarones.measurements.runner import orchestration as _orch_mod
 
         save_calls: list[str] = []
-        original_save = runner_mod._save_partial_line
+        original_save = _partial_mod._save_partial_line
 
         def tracking_save(path, doc_result):
             save_calls.append(doc_result.doc_id)
@@ -276,7 +282,9 @@ class TestRunnerPartialResults:
             def _run_ocr(self, image_path): return "texte"
 
         corpus = load_corpus_from_directory(str(tmp_corpus))
-        with patch.object(runner_mod, "_save_partial_line", side_effect=tracking_save):
+        # Patche la fonction directement dans l'orchestrateur, qui
+        # l'a importée depuis ``partial`` au moment du chargement.
+        with patch.object(_orch_mod, "_save_partial_line", side_effect=tracking_save):
             run_benchmark(
                 corpus, [MockEngine()],
                 show_progress=False,