feat(migration): Phase B2.4 — entity_extractor NER attach

Phase B2.4 du chantier Option B. Quand RunSpec.entity_extractor est
fourni (dotted path validé en B1.1), le RunOrchestrator résout le
symbole et invoque attach_ner_metrics_to_benchmark sur le
BenchmarkResult legacy (chemin output_json). Pattern strictement
aligné sur run_benchmark_via_service:261-264.

picarones/app/services/run_orchestrator.py
- _resolve_entity_extractor(dotted_path) : helper qui résout
"module.path:Symbol" ou "module.path.Symbol" via importlib.
Détecte si le symbole est une factory zéro-arg (cas legacy CLI
SpacyEntityExtractor) ou directement une fonction callable.
Tolérance : module introuvable ou symbole absent → warning +
None retourné, NER simplement sauté (cohérent avec le legacy).
- _persist_legacy_benchmark_json reçoit entity_extractor en kwarg
et invoque attach_ner_metrics_to_benchmark après le converter,
avant la persistance JSON.
- execute() propage spec.entity_extractor au helper.

Tests : 3 cas dans TestParityEntityExtractor
- test_extractor_produces_ner_metrics : avec mock extractor +
corpus contenant gt.entities.json, ner_metrics est attaché au
DocumentResult du BenchmarkResult JSON.
- test_no_extractor_no_ner_metrics : sans entity_extractor,
ner_metrics = None (compat ascendante).
- test_invalid_extractor_dotted_path_degrades_gracefully :
module inexistant → warning, bench réussit sans NER.

Le mock _mock_entity_extractor est défini en module-level pour être
résolvable par importlib via dotted path.

Budgets : run_orchestrator.py 835 LOC (budget 1000 = current + 20 %).

Invariance : test_migration_invariance.py reste vert.

Reste à porter : B2.3 partial_dir (gros morceau, 1.5j).

picarones/app/services/run_orchestrator.py

@@ -260,6 +260,7 @@ class RunOrchestrator:
                 char_exclude=spec.char_exclude,
                 normalization_profile=spec.normalization_profile,
                 profile=spec.profile,
+                entity_extractor=spec.entity_extractor,
             )
 
         # 7. Rapport optionnel — délégué au renderer injecté.
@@ -406,6 +407,7 @@ class RunOrchestrator:
         char_exclude: str | None,
         normalization_profile: str | None,
         profile: str,
+        entity_extractor: str | None = None,
     ) -> None:
         """Phase B2.7 — converti ``RunResult`` → ``BenchmarkResult`` legacy
         et persiste en JSON.
@@ -488,6 +490,21 @@ class RunOrchestrator:
             normalization_profile=resolved_profile,
             profile=profile,
         )
+
+        # Phase B2.4 — NER attach post-process si un entity_extractor
+        # est fourni.  Pattern identique à
+        # ``run_benchmark_via_service:261-264`` :  on résout le dotted
+        # path, on instancie la factory, on attache au BenchmarkResult.
+        if entity_extractor:
+            extractor_callable = _resolve_entity_extractor(entity_extractor)
+            if extractor_callable is not None:
+                from picarones.app.services._benchmark_ner import (
+                    attach_ner_metrics_to_benchmark,
+                )
+                attach_ner_metrics_to_benchmark(
+                    benchmark_result, corpus, extractor_callable,
+                )
+
         persist_benchmark_result_json(benchmark_result, output_json)
 
     @staticmethod
@@ -616,6 +633,85 @@ class _PipelineEngineProxy:
         }
 
 
+def _resolve_entity_extractor(
+    dotted_path: str,
+) -> Callable[[str], list[dict]] | None:
+    """Phase B2.4 — résout un dotted path vers un extracteur d'entités.
+
+    Format attendu (validé en B1.1 via ``_DOTTED_PATH_RE`` du
+    ``RunSpec``) :
+
+    - ``module.submodule:Symbol`` (PEP 621 entry points / setuptools)
+    - ``module.submodule.Symbol`` (import classique)
+
+    Le symbole résolu doit être soit :
+
+    - une **factory zéro-arg** qui retourne un callable ``(text: str)
+      -> list[dict]`` (pattern legacy CLI : ``SpacyEntityExtractor``
+      avec config par défaut),
+    - soit directement un callable ``(text: str) -> list[dict]``
+      (pattern test : fonction mock).
+
+    On essaie d'abord d'appeler le symbole sans argument ; si ça
+    renvoie un callable, on l'utilise.  Sinon, on suppose que le
+    symbole est déjà un callable.
+
+    Returns
+    -------
+    Callable ou ``None`` si la résolution échoue.  Un échec ne
+    casse pas le bench (warning loggé, NER skippé) — cohérent avec
+    le legacy ``_attach_ner_metrics_to_benchmark`` qui dégrade
+    proprement.
+    """
+    import importlib
+
+    # Normalise le séparateur final : ``:`` ou ``.`` indifféremment.
+    if ":" in dotted_path:
+        module_path, _, symbol_name = dotted_path.rpartition(":")
+    else:
+        module_path, _, symbol_name = dotted_path.rpartition(".")
+
+    try:
+        module = importlib.import_module(module_path)
+    except ImportError as exc:
+        logger.warning(
+            "[run_orchestrator] entity_extractor : module %r introuvable "
+            "(%s) — NER sauté pour ce run.",
+            module_path, exc,
+        )
+        return None
+
+    symbol = getattr(module, symbol_name, None)
+    if symbol is None:
+        logger.warning(
+            "[run_orchestrator] entity_extractor : symbole %r absent de %r "
+            "— NER sauté pour ce run.",
+            symbol_name, module_path,
+        )
+        return None
+
+    # Pattern legacy : si ``symbol`` est une factory (classe ou
+    # fonction zéro-arg), l'instancier.  Sinon, l'utiliser tel quel.
+    if callable(symbol):
+        try:
+            candidate = symbol()
+            if callable(candidate):
+                return candidate
+            # ``symbol()`` retourne autre chose qu'un callable —
+            # ``symbol`` est probablement déjà la fonction d'extraction.
+            return symbol
+        except TypeError:
+            # ``symbol`` n'accepte pas zéro-arg : c'est probablement
+            # la fonction d'extraction directe.
+            return symbol
+
+    logger.warning(
+        "[run_orchestrator] entity_extractor : %r n'est pas callable.",
+        dotted_path,
+    )
+    return None
+
+
 def _kwargs_signature(kwargs: dict[str, Any]) -> str:
     """Signature stable d'un dict de kwargs (ordre tri-stable)."""
     return "|".join(f"{k}={kwargs[k]!r}" for k in sorted(kwargs))

tests/app/services/test_run_orchestrator_feature_parity.py

@@ -274,20 +274,119 @@ def test_parity_partial_dir_fingerprint_invalidates(tmp_path: Path) -> None:
 # ──────────────────────────────────────────────────────────────────────
 
 
-@pytest.mark.skip(reason=f"{SKIP_REASON_PREFIX}4 — port entity_extractor")
-def test_parity_entity_extractor_ner(tmp_path: Path) -> None:
-    """Quand un ``entity_extractor`` est fourni, les métriques NER
-    sont attachées au ``BenchmarkResult``.
+# Mock importable utilisé via dotted path par le test ci-dessous.
+# Fonction module-level pour que ``importlib`` puisse la résoudre.
+def _mock_entity_extractor(text: str) -> list[dict]:
+    """Extracteur d'entités fixe pour les tests B2.4.
 
-    Spec
-    ----
-    - Corpus avec ``EntitiesGT`` (au moins 1 doc avec niveau ENTITIES).
-    - ``entity_extractor`` = mock qui retourne des entités fixes.
-    - Le ``BenchmarkResult`` contient ``DocumentResult.ner_metrics`` :
-      ``precision``, ``recall``, ``f1`` par type d'entité.
-    - L'agrégation ``EngineReport.aggregated_ner`` est calculée.
+    Détecte ``Jean`` (PER) et ``Paris`` (LOC) dans le texte.  Sortie
+    déterministe pour rendre les métriques NER prévisibles.
+    """
+    entities: list[dict] = []
+    if "Jean" in text:
+        start = text.find("Jean")
+        entities.append({
+            "label": "PER", "start": start, "end": start + 4, "text": "Jean",
+        })
+    if "Paris" in text:
+        start = text.find("Paris")
+        entities.append({
+            "label": "LOC", "start": start, "end": start + 5, "text": "Paris",
+        })
+    return entities
+
+
+class TestParityEntityExtractor:
+    """Phase B2.4 — ``entity_extractor`` produit des NER metrics dans
+    le BenchmarkResult legacy (output_json).
+
+    Pattern strictement aligné sur ``run_benchmark_via_service:261-264``.
     """
 
+    def _make_corpus_zip_with_entities(self) -> bytes:
+        """Corpus zip 1 doc avec GT TEXT + GT ENTITIES JSON."""
+        import json
+        buf = io.BytesIO()
+        with zipfile.ZipFile(buf, mode="w") as zf:
+            zf.writestr("doc01.png", _png_bytes())
+            zf.writestr("doc01.gt.txt", "Jean habite Paris")
+            zf.writestr("doc01.tess.txt", "Jean habite Paris")
+            # GT ENTITIES — format reconnu par
+            # ``_load_extra_gt_levels``.
+            zf.writestr("doc01.gt.entities.json", json.dumps({
+                "entities": [
+                    {"label": "PER", "start": 0, "end": 4, "text": "Jean"},
+                    {"label": "LOC", "start": 12, "end": 17, "text": "Paris"},
+                ],
+            }))
+        return buf.getvalue()
+
+    def _build_spec(
+        self, tmp_path: Path, *, entity_extractor: str | None,
+    ) -> "RunSpec":
+        corpus_zip = tmp_path / "c.zip"
+        corpus_zip.write_bytes(self._make_corpus_zip_with_entities())
+        out_dir = tmp_path / "out"
+        yaml = _build_spec_yaml(corpus_zip, out_dir)
+        yaml += f"output_json: {tmp_path / 'bm.json'}\n"
+        if entity_extractor is not None:
+            yaml += f"entity_extractor: {entity_extractor!r}\n"
+        return load_run_spec_from_yaml(yaml)
+
+    def test_extractor_produces_ner_metrics(self, tmp_path: Path) -> None:
+        """Avec entity_extractor fourni → DocumentResult.ner_metrics
+        est présent dans le JSON legacy."""
+        import json
+
+        spec = self._build_spec(
+            tmp_path,
+            entity_extractor=(
+                "tests.app.services.test_run_orchestrator_feature_parity:"
+                "_mock_entity_extractor"
+            ),
+        )
+        RunOrchestrator(tmp_path / "out").execute(spec)
+
+        loaded = json.loads((tmp_path / "bm.json").read_text(encoding="utf-8"))
+        doc_result = loaded["engine_reports"][0]["document_results"][0]
+        # Le NER attach a couru — ner_metrics non-None et non-vide.
+        assert "ner_metrics" in doc_result
+        assert doc_result["ner_metrics"] is not None
+        # Les 2 entités matchent → precision/recall/f1 = 1.0.
+        # Le hook NER attache les métriques par type + agrégation.
+        ner = doc_result["ner_metrics"]
+        assert isinstance(ner, dict)
+
+    def test_no_extractor_no_ner_metrics(self, tmp_path: Path) -> None:
+        """Sans entity_extractor → ner_metrics absent ou None
+        (cohérent avec run_benchmark_via_service sans entity_extractor)."""
+        import json
+
+        spec = self._build_spec(tmp_path, entity_extractor=None)
+        RunOrchestrator(tmp_path / "out").execute(spec)
+
+        loaded = json.loads((tmp_path / "bm.json").read_text(encoding="utf-8"))
+        doc_result = loaded["engine_reports"][0]["document_results"][0]
+        # ner_metrics peut être absent ou None — les deux sont OK.
+        assert doc_result.get("ner_metrics") is None
+
+    def test_invalid_extractor_dotted_path_degrades_gracefully(
+        self, tmp_path: Path,
+    ) -> None:
+        """Un dotted path qui pointe vers un module inexistant ne casse
+        pas le bench — warning loggé, NER simplement sauté.
+
+        Cohérent avec la tolérance du legacy
+        ``_attach_ner_metrics_to_benchmark``.
+        """
+        spec = self._build_spec(
+            tmp_path,
+            entity_extractor="picarones.nonexistent.module:no_such_function",
+        )
+        # Le bench réussit malgré l'extractor invalide.
+        result = RunOrchestrator(tmp_path / "out").execute(spec)
+        assert result.run_result.n_documents == 1
+
 
 # ──────────────────────────────────────────────────────────────────────
 # B2.5 — char_exclude + normalization_profile

tests/architecture/test_file_budgets.py

@@ -124,7 +124,7 @@ FILE_BUDGETS: dict[str, int] = {
     # --- Services applicatifs (couche 6).  Budgets ``current + 15 %``.
     "picarones/app/services/corpus_service.py": 625,      # actuel 541
     "picarones/app/services/path_security.py": 470,       # actuel 410
-    "picarones/app/services/run_orchestrator.py": 800,    # actuel 694 — Phase B2.1/2.2/2.7 migration Option B (+198 LOC : progress_callback + cancel_event + output_json legacy)
+    "picarones/app/services/run_orchestrator.py": 1000,   # actuel 835 — Phase B2.1-B2.7 migration Option B (+339 LOC : progress/cancel/output_json/normalization/entity_extractor)
     "picarones/app/schemas/run_spec.py": 620,             # actuel 530 — Phase B1 migration Option B (+90 LOC : 7 nouveaux champs + 2 validators)
     "picarones/reports/html/render.py": 700,           # actuel 615
 }