docs: mettre à jour CLAUDE.md, api-stable.md, supprimer architecture-cercles.md

- ``CLAUDE.md`` : section Architecture réécrite pour refléter la
structure 3 cercles. Ancien tableau "chantiers post-Sprint 97"
remplacé par un manifeste concis qui pointe vers
``docs/architecture.md``. Section "Moteur narratif" mise à jour
pour refléter la nouvelle location (``measurements/narrative/`` +
``core/facts.py``). Compteurs de tests actualisés.
- ``docs/api-stable.md`` : noms des modules mis à jour pour refléter
les nouveaux chemins (``picarones.measurements.metrics``,
``picarones.measurements.runner``, ``picarones.core.pipeline``,
``picarones.measurements.pipeline_benchmark``,
``picarones.measurements.pipeline_comparison``,
``picarones.measurements.pipeline_spec_loader``,
``picarones.measurements.builtin_metrics``,
``picarones.measurements.alto_metrics``,
``picarones.web.jobs``, ``picarones.core.facts``).
- ``docs/architecture-cercles.md`` supprimé : remplacé par
``docs/architecture.md`` (plus à jour, plus précis).
- ``picarones/extras/__init__.py`` et
``picarones/measurements/__init__.py`` : référence à
``architecture.md`` au lieu de l'ancien ``architecture-cercles.md``.
- ``tests/test_phaseC_migration.py`` supprimé (validait la migration
intermédiaire).

https://claude.ai/code/session_01Hsd7kL8yeCbXn1mA7GQK9L

CLAUDE.md

@@ -6,121 +6,89 @@ HuggingFace Space : huggingface.co/spaces/Ma-Ri-Ba-Ku/Picarones (Docker, port 78
 
 ---
 
-## Lecture rapide — chantiers post-Sprint 97
+## Architecture en 3 cercles
 
-5 chantiers ont consolidé l'architecture sans suppression :
+Voir le manifeste complet dans [`docs/architecture.md`](docs/architecture.md).
 
-| # | Livré | Effet | Doc |
-|---|---|---|---|
-| 1 | `TextToAltoMonoRegion` + refonte `BaseOCREngine` | Valide l'axe B bout-en-bout (BaseModule réel TEXT→ALTO + 5 engines factorisés) | [`docs/architecture.md`](docs/architecture.md) |
-| 2 | Profils + registre de hooks | `runner.py` allégé de 303 lignes ; 7 profils pour moduler le calcul ; `--profile` ajouté | [`docs/profiles.md`](docs/profiles.md) |
-| 3 | 5 vues HTML thématiques | 16 renderers orphelins regroupés en `economics`, `advanced_taxonomy`, `diagnostics`, `pipeline`, `robustness` | [`docs/views.md`](docs/views.md) |
-| 4 | Workflows CLI + LLM Sprint 15 + Gallica/IIIF | 3 commandes `diagnose`/`economics`/`edition` ; Sprint 15 propagé aux 4 LLM ; `_http.py` factorisé | [`docs/cli-workflows.md`](docs/cli-workflows.md) |
-| 5 | Découpage monolithes | `cli.py` 1519L → 7 fichiers ; `narrative/detectors.py` 1229L → 8 fichiers (6 familles + helpers) | [`docs/architecture.md`](docs/architecture.md) |
-
-Branche : `claude/code-quality-audit-ACnhK`. Voir [`CHANGELOG.md`](CHANGELOG.md)
-section `[post-Sprint 97]` pour le détail.
+```
+   Cercle 3 (extras, report, cli, web)
+   │
+   ▼
+   Cercle 2 (measurements, engines, llm, pipelines, modules)
+   │
+   ▼
+   Cercle 1 (core)
+```
 
-**18 détecteurs narratifs** (et non « 12 » comme annoncé dans les sprints
-historiques) — voir
-[`picarones/core/narrative/detectors/`](picarones/core/narrative/detectors/).
+Règle de dépendance stricte : les imports vont uniquement de l'extérieur
+vers l'intérieur. **Aucun shim** — un module a un seul emplacement.
 
 ---
 
 ## Setup
 
 ```bash
-pip install -e ".[dev,web]"          # IMPORTANT : toujours inclure [web] pour les tests
+pip install -e ".[dev,web]"          # toujours inclure [web] pour les tests
 pytest tests/ -q --tb=short          # lancer les tests
 picarones demo --output rapport.html # rapport démo sans moteur installé
 picarones serve --port 8080          # interface web locale
 ```
 
-Mise à jour Codespace complète :
-```bash
-git pull && pip install -e ".[dev,web]" && picarones demo --output rapport_demo.html && picarones serve --port 8080
-```
-
 ---
 
-## Architecture
+## Structure
 
 ```
 picarones/
-├── cli/                    # (chantier 5) Package CLI Click — 7 fichiers
-│   ├── __init__.py         # Groupe `cli` + helpers + commandes simples
-│   ├── _workflows.py       # run, diagnose, economics, edition, compare
-│   ├── _pipeline.py        # pipeline run + compare
-│   ├── _imports.py, _serve.py, _history.py, _robustness.py
-├── fixtures.py             # Données de test fictives (documents médiévaux)
-├── modules/                # (chantier 1) Modules BaseModule de référence
-│   └── alto_text_to_mono_region.py    # Reconstructeur ALTO baseline
-├── core/
-│   ├── corpus.py           # Chargement corpus (dossier local, ALTO XML, PAGE XML)
-│   ├── metrics.py          # CER, WER, MER, WIL (via jiwer)
-│   ├── normalization.py    # Profils : nfc, caseless, minimal, medieval_french, early_modern_french,
-│   │                       #           medieval_latin, early_modern_english, medieval_english
-│   ├── statistics.py       # Bootstrap CI 95%, Wilcoxon (scipy optionnel), corrélations
-│   ├── runner.py           # Orchestrateur benchmark (ThreadPool IO-bound, ProcessPool CPU-bound)
-│   ├── results.py          # Modèles de données DocumentResult, BenchmarkResults + export JSON
-│   ├── confusion.py        # Matrice de confusion unicode
-│   ├── char_scores.py      # Scores ligatures (fi, fl, œ, æ, ꝑ…) et diacritiques
-│   ├── taxonomy.py         # Taxonomie erreurs 9 classes (confusion visuelle, abréviation…)
-│   ├── structure.py        # Analyse structurelle (blocs, lignes, mots)
-│   ├── image_quality.py    # Métriques qualité image (contraste, bruit, résolution…)
-│   ├── difficulty.py       # Score difficulté intrinsèque par document
-│   ├── hallucination.py    # Détection hallucinations VLM (score ancrage, ratio longueur)
-│   ├── line_metrics.py     # Distribution erreurs par ligne (Gini, percentiles)
-│   ├── history.py          # Suivi longitudinal SQLite
-│   ├── robustness.py       # Analyse robustesse (bruit, flou, rotation, résolution)
-│   └── narrative/          # Moteur narratif factuel (Sprint 16) — modèle Fact + registre
-│       ├── facts.py        # Fact, FactType (12 types), FactImportance, DetectorRegistry
-│       └── detectors.py    # Stubs des 12 détecteurs, implémentations par sprint
-├── engines/
-│   ├── base.py             # BaseEngine avec execution_mode ("io" ou "cpu")
-│   ├── tesseract.py        # execution_mode = "cpu"
-│   ├── pero_ocr.py         # execution_mode = "cpu"
-│   ├── mistral_ocr.py      # endpoint /v1/ocr dédié (pas chat/completions)
-│   ├── google_vision.py
-│   └── azure_doc_intel.py
-├── llm/
-│   ├── base.py
-│   ├── mistral_adapter.py
-│   ├── openai_adapter.py
-│   ├── anthropic_adapter.py
-│   └── ollama_adapter.py
-├── pipelines/
-│   ├── base.py             # OCRLLMPipeline (interface BaseOCREngine)
-│   └── over_normalization.py
-├── prompts/                # 8 fichiers .txt FR+EN
-│   ├── medieval_french.txt
-│   ├── medieval_french_zero_shot.txt
-│   ├── early_modern_french.txt
-│   ├── early_modern_french_zero_shot.txt
-│   ├── medieval_english.txt
-│   ├── early_modern_english.txt
-│   ├── medieval_latin.txt
-│   └── zero_shot.txt
-├── report/
-│   ├── generator.py        # Orchestration Jinja2 (617 lignes depuis Sprint 17)
-│   ├── diff_utils.py
-│   ├── templates/          # Templates Jinja2 (Sprint 17)
-│   │   ├── base.html.j2    # assemble tout via {% include %}
-│   │   ├── _header.html, _footer.html, _styles.css, _app.js
-│   │   └── view_ranking.html, view_gallery.html, view_document.html,
-│   │       view_analyses.html, view_characters.html
-│   ├── i18n/               # Traductions FR/EN (Sprint 17 — extraites de i18n.py)
-│   │   ├── fr.json
-│   │   └── en.json
-│   └── vendor/             # Chart.js vendorisé
-├── web/
-│   └── app.py              # FastAPI, SSE, upload corpus ZIP, endpoints modèles dynamiques
-└── importers/
-    ├── iiif.py
-    ├── htr_united.py
-    ├── huggingface.py
-    ├── gallica.py
-    └── escriptorium.py
+├── core/                       Cercle 1 — abstractions pures (7 modules)
+│   ├── modules.py              BaseModule, ArtifactType
+│   ├── corpus.py               Document, Corpus, GTLevel, payloads typés
+│   ├── results.py              DocumentResult, EngineReport, BenchmarkResult
+│   ├── metric_registry.py      MetricSpec, register_metric, compute_at_junction
+│   ├── metric_hooks.py         register_document_metric, register_corpus_aggregator
+│   ├── pipeline.py             PipelineRunner, PipelineSpec, PipelineStep
+│   └── facts.py                Fact, FactType, FactImportance, DetectorRegistry
+│
+├── measurements/               Cercle 2 — métriques officielles (~55 modules)
+│   ├── runner.py               run_benchmark (orchestration)
+│   ├── metrics.py / statistics.py / normalization.py / builtin_hooks.py
+│   ├── confusion.py / taxonomy.py / calibration.py / line_metrics.py / ...
+│   ├── readability.py / reliability.py / searchability.py / ner.py / ...
+│   ├── mufi.py / abbreviations.py / unicode_blocks.py / roman_numerals.py
+│   ├── pipeline_benchmark.py / pipeline_comparison.py / pipeline_spec_loader.py
+│   └── narrative/              moteur narratif (arbiter, renderer, registry,
+│                                18 détecteurs en 6 familles : ranking, pareto,
+│                                stratum, quality, history, ensemble)
+│
+├── engines/                    Cercle 2 — adapters OCR (5)
+│   ├── base.py                 BaseOCREngine (hérite de BaseModule)
+│   ├── tesseract.py / pero_ocr.py
+│   ├── mistral_ocr.py / google_vision.py / azure_doc_intel.py
+│
+├── llm/                        Cercle 2 — adapters LLM (4)
+│   ├── base.py / mistral_adapter.py / openai_adapter.py
+│   └── anthropic_adapter.py / ollama_adapter.py
+│
+├── pipelines/                  Cercle 2 — pipelines OCR+LLM intégrés
+│   ├── base.py (OCRLLMPipeline) / over_normalization.py
+│
+├── modules/                    Cercle 2 — modules BaseModule officiels
+│   └── alto_text_to_mono_region.py
+│
+├── extras/                     Cercle 3 — plugins / extensions
+│   └── importers/              IIIF, Gallica, HTR-United, HuggingFace, eScriptorium
+│
+├── report/                     Cercle 3 — rendu HTML
+│   ├── generator.py / colors.py / diff_utils.py
+│   ├── views/                  5 vues thématiques
+│   ├── templates/ / i18n/ / glossary/ / vendor/
+│   └── *_render.py             ~22 renderers (calibration, NER, Pareto, etc.)
+│
+├── cli/                        Cercle 3 — Click (7 fichiers)
+├── web/                        Cercle 3 — FastAPI (app.py, jobs.py)
+├── prompts/                    8 fichiers .txt FR+EN
+├── data/                       Tables indicatives (pricing.yaml)
+└── fixtures.py                 Corpus de test fictifs
 ```
 
 ---
@@ -160,7 +128,7 @@ correspondants (`test_sprint15_llm_pipeline_bugs.py`, `test_sprint8_escriptorium
   CI, Makefile et invocation directe produisent le même résultat. Le job
   `lint` du CI est bloquant — un F401 (import inutilisé) ou un E741
   (variable ambiguë) fait échouer la PR, par design.
-- **Les profils de normalisation** sont dans `picarones/core/normalization.py` — l'endpoint
+- **Les profils de normalisation** sont dans `picarones/measurements/normalization.py` — l'endpoint
   `/api/normalization/profiles` doit les lire dynamiquement depuis ce fichier, pas depuis une
   liste statique.
 
@@ -299,58 +267,52 @@ AZURE_DOC_INTEL_KEY=...
 
 ---
 
-## Moteur narratif (Sprint 16)
+## Moteur narratif
 
-Fondations en place dans `picarones/core/narrative/` :
+Le modèle de données (`Fact`, `FactType`, `FactImportance`,
+`DetectorRegistry`) vit en cercle 1 dans
+[`picarones/core/facts.py`](picarones/core/facts.py). Les détecteurs et
+le rendu vivent en cercle 2 :
 
 ```
-core/narrative/
-├── __init__.py              # API publique + pipeline build_synthesis
-├── facts.py                 # Modèle Fact, FactType (12 types), FactImportance, DetectorRegistry
-├── detectors.py             # 10 détecteurs implémentés (Sprint 19) + 2 stubs (Sprint 5)
-├── arbiter.py               # Tri par importance, non-redondance, anti-contradiction
-├── renderer.py              # Rendu templates YAML par str.format_map (déterministe)
-└── templates/
-    ├── fr.yaml              # 10 templates français
-    └── en.yaml              # 10 templates anglais
+picarones/measurements/narrative/
+├── __init__.py              API publique + pipeline build_synthesis
+├── arbiter.py               Tri par importance, non-redondance, anti-contradiction
+├── renderer.py              Rendu templates YAML par str.format_map (déterministe)
+├── registry.py              Registre par défaut des détecteurs
+├── templates/{fr,en}.yaml   18 templates × 2 langues
+└── detectors/               18 détecteurs en 6 familles
+    ├── ranking.py           5 (global_leader, statistical_tie, significant_gap,
+    │                          speed_winner, median_mean_gap_warning)
+    ├── pareto.py            2 (pareto_alternative, cost_outlier)
+    ├── stratum.py           3 (stratum_winner, stratum_collapse,
+    │                          stratification_recommended)
+    ├── quality.py           4 (error_profile_outlier, llm_hallucination_flag,
+    │                          robustness_fragile, confidence_warning)
+    ├── history.py           3 (engine_off_baseline, engine_unstable,
+    │                          regression_in_history)
+    └── ensemble.py          1 (ensemble_opportunity)
 ```
 
-**Principe anti-hallucination** : chaque valeur numérique ou nom d'entité dans le
-`payload` d'un `Fact` doit provenir du JSON d'entrée. Test `test_sprint19_narrative_engine.py`
-parse la synthèse rendue et vérifie que chaque nombre est traçable au payload
-(via `_numbers_in_payload`) augmenté d'une liste blanche limitative de constantes
-de template (`95`, `100`).
-
-**Détecteurs activés dans le registre par défaut (Sprint 20)** — les 12 sont opérationnels :
-- Sprint 3 : `statistical_tie`
-- Sprint 4 : `global_leader_cer`, `significant_gap`, `stratum_winner`, `stratum_collapse`,
-  `error_profile_outlier`, `llm_hallucination_flag`, `robustness_fragile`,
-  `speed_winner`, `confidence_warning`
-- Sprint 5 : `pareto_alternative`, `cost_outlier`
+**Principe anti-hallucination** : chaque valeur numérique ou nom d'entité
+dans le `payload` d'un `Fact` provient du JSON d'entrée. Le test
+`test_sprint19_narrative_engine.py` parse la synthèse rendue et vérifie
+la traçabilité.
 
-**Règle anti-contradiction** (arbitre) : si `SIGNIFICANT_GAP` (Wilcoxon non corrigé)
-et `STATISTICAL_TIE` (Nemenyi corrigé) concernent les mêmes moteurs, Nemenyi
-l'emporte — on ne veut pas dire en même temps "A bat B significativement" ET
-"A et B sont indiscernables".
+**Règle anti-contradiction** (arbitre) : si `SIGNIFICANT_GAP` (Wilcoxon
+non corrigé) et `STATISTICAL_TIE` (Nemenyi corrigé) concernent les mêmes
+moteurs, Nemenyi l'emporte.
 
-**Pipeline** : `build_synthesis(benchmark_data, lang, max_facts=5)` détecte,
-arbitre, rend. Le `ReportGenerator.generate` l'appelle et passe le résultat
-au template `_narrative_summary.html` (placé entre `_header.html` et `_critical_difference.html`).
+**Pipeline** : `build_synthesis(benchmark_data, lang, max_facts=5)`
+détecte, arbitre, rend.
 
 ---
 
 ## Contexte développement
 
-- **Environnement** : GitHub Codespaces (`/workspaces/Picarones`), Python 3.12
-- **Tests** : 3098+ passed, 2 skipped (cf. CHANGELOG section `[post-Sprint 97]`
-  pour les nouveaux tests des chantiers 1-5 qui ajoutent ~1500 lignes
-  de validation : `test_alto_baseline.py`, `test_metric_hooks.py`,
-  `test_views.py`, `test_chantier4.py`, `test_chantier5.py`).
+- **Environnement** : GitHub Codespaces, Python 3.11+
+- **Tests** : `pytest tests/ -q` → ~3354 passed, 2 skipped, 0 failed.
 - **Plan d'évolution actif** : [`docs/roadmap/evolution-2026.md`](docs/roadmap/evolution-2026.md).
-- **Documentation post-chantiers** : [`docs/architecture.md`](docs/architecture.md),
-  [`docs/profiles.md`](docs/profiles.md), [`docs/cli-workflows.md`](docs/cli-workflows.md),
-  [`docs/views.md`](docs/views.md).
+- **Manifeste architecture** : [`docs/architecture.md`](docs/architecture.md).
+- **API publique stable** : [`docs/api-stable.md`](docs/api-stable.md).
 - **Branche active** : `claude/code-quality-audit-ACnhK`.
-- **Détecteurs narratifs** : 18 (et non 12 comme indiqué historiquement),
-  organisés en 6 familles dans
-  [`picarones/core/narrative/detectors/`](picarones/core/narrative/detectors/).

docs/api-stable.md

@@ -79,7 +79,7 @@ class EngineReport:      # agrégat moteur sur tout le corpus
 class BenchmarkResult:   # résultat global multi-moteurs
 ```
 
-### `picarones.core.metrics`
+### `picarones.measurements.metrics`
 
 ```python
 class MetricsResult:     # CER, WER, MER, WIL + variantes diplomatique/caseless
@@ -87,7 +87,7 @@ def compute_metrics(reference, hypothesis, char_exclude=None) -> MetricsResult
 def aggregate_metrics(results: list) -> dict
 ```
 
-### `picarones.core.runner`
+### `picarones.measurements.runner`
 
 ```python
 def run_benchmark(
@@ -105,7 +105,7 @@ def run_benchmark(
 ) -> BenchmarkResult
 ```
 
-### `picarones.core.pipeline_runner`
+### `picarones.core.pipeline`
 
 ```python
 class PipelineStep:
@@ -115,7 +115,7 @@ class PipelineResult:
 class PipelineRunner:
 ```
 
-### `picarones.core.pipeline_benchmark`
+### `picarones.measurements.pipeline_benchmark`
 
 ```python
 class StepAggregate:
@@ -125,7 +125,7 @@ def default_initial_inputs(doc) -> dict
 def run_pipeline_benchmark(spec, corpus, factory=...) -> PipelineBenchmarkResult
 ```
 
-### `picarones.core.pipeline_comparison`
+### `picarones.measurements.pipeline_comparison`
 
 ```python
 class PipelineComparisonResult:
@@ -133,7 +133,7 @@ class PipelineComparisonResult:
 def compare_pipelines(specs, corpus, factories=None) -> PipelineComparisonResult
 ```
 
-### `picarones.core.pipeline_spec_loader`
+### `picarones.measurements.pipeline_spec_loader`
 
 ```python
 class PipelineSpecLoadError(ValueError):
@@ -183,7 +183,7 @@ def run_document_hooks(profile, *, ground_truth, hypothesis, image_path, corpus_
 def run_corpus_aggregators(profile, document_results) -> dict
 ```
 
-### `picarones.core.builtin_metrics`
+### `picarones.measurements.builtin_metrics`
 
 Métriques scalaires natives, enregistrées dans le registre typé :
 
@@ -197,7 +197,7 @@ def wil(reference, hypothesis) -> float
 def text_preservation_after_reconstruction(reference_text, hypothesis_alto) -> float
 ```
 
-### `picarones.core.alto_metrics`
+### `picarones.measurements.alto_metrics`
 
 Métriques (ALTO, ALTO) + helper :
 
@@ -210,7 +210,7 @@ def alto_text_mer(reference_alto, hypothesis_alto) -> float
 def alto_text_wil(reference_alto, hypothesis_alto) -> float
 ```
 
-### `picarones.core.jobs`
+### `picarones.web.jobs`
 
 Persistance des jobs benchmark (utilisé par l'interface web) :
 
@@ -241,7 +241,7 @@ def reset_default_store(...)
   reflètent ces changements.
 - **Modules `picarones.extras/`** : statut variable selon le
   sous-package (academic / governance / historical / importers).
-  Voir `docs/architecture-cercles.md`.
+  Voir `docs/architecture.md`.
 - **Comportement des renderers HTML** : la structure des fichiers HTML
   peut évoluer entre versions mineures. Nous gardons les noms des
   vues principales.
@@ -268,15 +268,15 @@ version mineure si une RFC le justifie.
 
 ```python
 # Mesures (déplacées vers picarones.measurements/)
-from picarones.core.confusion import build_confusion_matrix
-from picarones.core.taxonomy import classify_errors
-from picarones.core.calibration import compute_calibration_metrics
+from picarones.measurements.confusion import build_confusion_matrix
+from picarones.measurements.taxonomy import classify_errors
+from picarones.measurements.calibration import compute_calibration_metrics
 # ... ~40 modules métriques ...
 
 # Moteur narratif (déplacé vers picarones.measurements.narrative/)
-from picarones.core.narrative import build_synthesis
-from picarones.core.narrative.facts import Fact
-from picarones.core.narrative.detectors import detect_global_leader_cer
+from picarones.measurements.narrative import build_synthesis
+from picarones.core.facts import Fact, FactType, FactImportance
+from picarones.measurements.narrative.detectors import detect_global_leader_cer
 
 # Plugins (déplacés vers picarones.extras/)
 from picarones.core.taxonomy_intra_doc import compute_taxonomy_position_heatmap
@@ -296,7 +296,7 @@ Pour les **nouvelles** intégrations, préférer les chemins canoniques :
 
 ## Voir aussi
 
-- [`docs/architecture-cercles.md`](architecture-cercles.md) — cartographie
+- [`docs/architecture.md`](architecture.md) — cartographie
   des 3 cercles + critères d'assignation.
 - [`docs/architecture.md`](architecture.md) — vue d'ensemble post-chantiers.
 - [`tests/test_public_api.py`](../tests/test_public_api.py) — test

docs/architecture-cercles.md

@@ -1,229 +0,0 @@
-# Architecture en 3 cercles — chantier de refonte post-chantier 6
-
-Ce document **fige la cartographie** de chaque module Picarones dans son
-cercle d'appartenance. Il sert de référence stable pour les
-contributions futures : avant d'ajouter un module, consulter ce
-document pour identifier dans quel cercle il doit aller.
-
-## Principe — 3 cercles concentriques
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  Cercle 3 — Plugins (extras/)                               │
-│  ┌─────────────────────────────────────────────────────┐    │
-│  │  Cercle 2 — Modules officiels                       │    │
-│  │  ┌──────────────────────────────────────────┐       │    │
-│  │  │  Cercle 1 — Noyau invariant (core/)      │       │    │
-│  │  │  API publique stable, ~15 modules        │       │    │
-│  │  └──────────────────────────────────────────┘       │    │
-│  │  Adapters, mesures, rapport, CLI, web               │    │
-│  │  ~30 modules métriques + ~15 adapters/UI            │    │
-│  └─────────────────────────────────────────────────────┘    │
-│  Modules niche, gouvernance préventive, importers exotiques │
-│  Distribués via extras pip ou packages séparés à terme      │
-└─────────────────────────────────────────────────────────────┘
-```
-
-Plus on s'éloigne du cœur, plus c'est optionnel et plus c'est facile
-à supprimer/remplacer/externaliser.
-
-## Cercle 1 — Noyau invariant
-
-**Critères** : ce qui définit *ce qu'est* Picarones. API publique
-stable. Ne casse pas entre versions mineures.
-
-**Localisation** : `picarones/core/` (après phase E) — strictement
-~15 modules.
-
-**Contenu** :
-
-| Module | Rôle |
-|---|---|
-| `corpus.py` | Document, Corpus, GTLevel multi-niveaux |
-| `modules.py` | BaseModule, ArtifactType (contrat unique pour modules tiers) |
-| `results.py` | BenchmarkResult, EngineReport, DocumentResult |
-| `metrics.py` | CER/WER/MER/WIL via jiwer (métriques de base) |
-| `runner.py` | Orchestrateur (parallélisation, reprise, timeout) |
-| `pipeline_runner.py` | Banc d'essai mono-doc des pipelines composées |
-| `pipeline_benchmark.py` | Orchestration corpus-wide |
-| `pipeline_comparison.py` | Comparaison de N pipelines |
-| `pipeline_spec_loader.py` | Chargement YAML déclaratif |
-| `metric_registry.py` | Registre typé `(input_type, output_type) → metric` |
-| `metric_hooks.py` | Profils + registre de hooks document/corpus |
-| `builtin_metrics.py` | CER/WER/MER/WIL enregistrés sur registre typé |
-| `alto_metrics.py` | Métriques `(ALTO, ALTO)` (chantier 1) |
-
-**Discipline** :
-- Toute modification non rétrocompatible exige une **RFC** et bump majeur.
-- Test `test_public_api.py` (à créer en phase D) qui échoue si un nom disparaît.
-- Aucun import direct depuis `extras/` ou de modules optionnels.
-
-## Cercle 2 — Modules officiels
-
-**Critères** : maintenu par les mainteneurs Picarones, livré par
-défaut, mais peut techniquement vivre ailleurs (un fork peut le
-remplacer par un équivalent).
-
-**Localisation** :
-- `picarones/measurements/` (après phase E) — métriques au-delà du CER de base.
-- `picarones/engines/` — adapters OCR.
-- `picarones/llm/` — adapters LLM.
-- `picarones/modules/` — modules `BaseModule` de référence (chantier 1).
-- `picarones/report/` — génération HTML.
-- `picarones/cli/` — interface CLI.
-- `picarones/web/` — interface web FastAPI.
-- `picarones/pipelines/` — pipelines OCR+LLM legacy (à statuer en phase D).
-
-**Métriques officielles** (futur `picarones/measurements/`) :
-
-| Catégorie | Modules |
-|---|---|
-| Texte | `confusion`, `char_scores`, `taxonomy`, `structure`, `taxonomy_comparison` |
-| Lignes | `line_metrics`, `hallucination` |
-| Fiabilité | `calibration`, `reliability`, `robustness`, `robustness_projection` |
-| Structure ALTO/PAGE | `reading_order`, `layout`, `error_absorption` |
-| Recherche | `searchability`, `numerical_sequences`, `rare_tokens` |
-| Lisibilité | `readability` (Flesch), `specialization` |
-| Inter-moteurs | `inter_engine`, `worst_lines` |
-| Économie | `throughput`, `cost_projection`, `marginal_cost`, `pricing` |
-| Comparaison | `incremental_comparison` |
-| Narrative | `narrative/` (engine + 6 familles de détecteurs) |
-| Hooks | `builtin_hooks` |
-| Contexte corpus | `history`, `difficulty`, `image_quality`, `normalization` |
-| Statistiques | `statistics` |
-| Levers | `levers` |
-
-**Discipline** :
-- Modification libre sans RFC.
-- Nouveau module doit s'enregistrer via `@register_metric` ou
-  `@register_document_metric` plutôt qu'imports directs depuis `runner.py`.
-- Couvre les 4 axes du produit : viabilité prod, hallucinations VLM,
-  pipelines composées, projection coût/vitesse.
-
-## Cercle 3 — Plugins
-
-**Critères** : ne sert pas tout le monde, peut être désactivé sans
-amputer le produit principal.
-
-**Localisation** : `picarones/extras/` (sous-package interne pour
-l'instant ; packages PyPI séparés possibles à terme).
-
-**Sous-packages** :
-
-### `extras/academic/` — modules techniques sans cas d'usage prod
-
-| Module | Pourquoi en plugin |
-|---|---|
-| `taxonomy_intra_doc.py` | Heatmap classe×position. Question rare, peu actionnable |
-| `taxonomy_cooccurrence.py` | Jaccard inter-classes. Académique, info rare |
-| `image_predictive.py` | Score combiné avec poids éditoriaux arbitraires |
-
-### `extras/governance/` — gouvernance préventive
-
-| Module | Pourquoi en plugin |
-|---|---|
-| `module_policy.py` | Manifest + audit pour modules contribués externes. Inutile tant qu'il n'y a pas 5+ modules tiers réels |
-
-### `extras/historical/` — métriques philologiques (phase B)
-
-| Module | Public spécifique |
-|---|---|
-| `unicode_blocks.py` | Tous périodes |
-| `abbreviations.py` | Médiéval (Capelli) |
-| `mufi.py` | Médiéval (PUA) |
-| `early_modern_typography.py` | XVIᵉ-XVIIIᵉ siècles |
-| `modern_archives.py` | XIXᵉ-XXᵉ siècles |
-| `roman_numerals.py` | Toutes périodes |
-| `lexical_modernization.py` | Édition critique |
-| `philological_runner.py` | Orchestration des 6 modules ci-dessus |
-
-### `extras/importers/` — imports externes (phase C)
-
-| Module | Statut |
-|---|---|
-| `_http.py` | Helpers HTTP partagés (chantier 4) |
-| `iiif.py` | Maintenu |
-| `htr_united.py` | Maintenu |
-| `gallica.py` | Maintenu |
-| `huggingface.py` | Expérimental (à finir ou marqué unstable) |
-| `escriptorium.py` | Expérimental (à finir ou marqué unstable) |
-
-### `extras/render/` — renderers correspondants
-
-Renderers atomiques pour les modules `extras/`. Importés
-conditionnellement par les vues thématiques du chantier 3 (qui sont
-elles-mêmes dans `report/views/`, donc Cercle 2).
-
-## Distinguer un module Cercle 1 vs Cercle 2
-
-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 :
-- `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.
-
-## Distinguer un module Cercle 2 vs Cercle 3
-
-Test concret : ce module sert-il à répondre à la question
-*« peut-on déployer ce moteur en prod sur ce corpus dans nos
-contraintes ? »* — soit en mesurant un risque (hallucinations,
-stabilité), soit en projetant un coût (throughput, pricing), soit
-en évaluant la qualité (CER, calibration, structure) ?
-
-- **Oui** → Cercle 2.
-- **Non** → Cercle 3.
-
-Exemple :
-- `hallucination.py` : mesure un risque pour la prod VLM → Cercle 2.
-- `throughput.py` : projette un coût opérationnel → Cercle 2.
-- `taxonomy_intra_doc.py` : décrit une distribution sans implication
-  de décision → Cercle 3.
-
-## Disclaimer
-
-Cette cartographie est **une décision produit**, pas une vérité
-absolue. Elle peut évoluer si les usages réels d'institutions
-révèlent qu'un module Cercle 3 est en fait essentiel, ou
-inversement.
-
-Toute remise en cause doit passer par une RFC documentée, pas par
-une PR silencieuse.
-
-## Voir aussi
-
-- [`docs/architecture.md`](architecture.md) — vue d'ensemble post-chantiers 1-6.
-- [`docs/profiles.md`](profiles.md) — profils de calcul (chantier 2).
-- [`docs/views.md`](views.md) — vues HTML du rapport.
-- [`docs/cli-workflows.md`](cli-workflows.md) — commandes CLI.
-- `docs/api-stable.md` — *à créer en phase D* — engagement API publique du Cercle 1.

picarones/extras/__init__.py

@@ -15,9 +15,9 @@ Convention de rétrocompat
 Pour chaque module déplacé depuis ``picarones/core/`` ou
 ``picarones/report/`` vers ``picarones/extras/``, un fichier-shim est
 laissé à l'ancien emplacement qui réexporte les noms publics. Les
-imports historiques (``from picarones.core.taxonomy_intra_doc import
+imports historiques (``from picarones.measurements.taxonomy_intra_doc import
 ...``) continuent à fonctionner sans modification.
 
-Voir :doc:`docs/architecture-cercles.md` pour la cartographie complète
+Voir :doc:`docs/architecture.md` pour la cartographie complète
 et les critères d'assignation au Cercle 3.
 """

picarones/measurements/__init__.py

@@ -82,6 +82,6 @@ Tous les modules historiquement dans ``picarones.core.X`` restent
 accessibles via des fichiers-shims qui les redirigent vers le nouvel
 emplacement. Aucun import existant ne casse.
 
-Voir :doc:`docs/architecture-cercles.md` et la phase E du plan de
+Voir :doc:`docs/architecture.md` et la phase E du plan de
 refonte.
 """

tests/test_phaseC_migration.py

@@ -1,229 +0,0 @@
-"""Tests de la phase C — extras/importers/ (importers vers Cercle 3).
-
-Couvre :
-
-- 6 importers (``_http``, ``iiif``, ``htr_united``, ``gallica``,
-  ``huggingface``, ``escriptorium``) déplacés vers
-  ``picarones/extras/importers/``.
-- Identité préservée à travers les shims.
-- ``huggingface`` et ``escriptorium`` émettent un ``UserWarning``
-  ``experimental`` à l'import.
-- ``picarones.importers/__init__.py`` continue à réexporter les
-  noms historiques.
-- ``cli/_imports.py`` continue à fonctionner.
-- pyproject.toml déclare ``[importers]``.
-"""
-
-from __future__ import annotations
-
-import importlib
-import sys
-import warnings
-from pathlib import Path
-
-import pytest
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# 1. Imports historiques rétrocompat via shims
-# ──────────────────────────────────────────────────────────────────────────
-
-
-class TestImportersRetrocompat:
-    @pytest.mark.parametrize("module_path, attribute", [
-        ("picarones.importers.iiif", "IIIFImporter"),
-        ("picarones.importers.iiif", "import_iiif_manifest"),
-        ("picarones.importers.htr_united", "HTRUnitedEntry"),
-        ("picarones.importers.htr_united", "HTRUnitedCatalogue"),
-        ("picarones.importers.htr_united", "import_htr_united_corpus"),
-        ("picarones.importers.gallica", "GallicaClient"),
-        ("picarones.importers.gallica", "GallicaRecord"),
-        ("picarones.importers.gallica", "search_gallica"),
-        ("picarones.importers.gallica", "import_gallica_document"),
-        ("picarones.importers._http", "validate_http_url"),
-        ("picarones.importers._http", "download_url"),
-    ])
-    def test_legacy_path_works(self, module_path: str, attribute: str):
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore")
-            mod = importlib.import_module(module_path)
-        assert hasattr(mod, attribute)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# 2. Imports via le nouveau chemin extras/importers/
-# ──────────────────────────────────────────────────────────────────────────
-
-
-class TestExtrasImportersPath:
-    @pytest.mark.parametrize("new_path, attribute", [
-        ("picarones.extras.importers._http", "validate_http_url"),
-        ("picarones.extras.importers._http", "download_url"),
-        ("picarones.extras.importers.iiif", "IIIFImporter"),
-        ("picarones.extras.importers.iiif", "import_iiif_manifest"),
-        ("picarones.extras.importers.htr_united", "HTRUnitedCatalogue"),
-        ("picarones.extras.importers.gallica", "GallicaClient"),
-        ("picarones.extras.importers.huggingface", "HuggingFaceImporter"),
-        ("picarones.extras.importers.escriptorium", "EScriptoriumClient"),
-    ])
-    def test_extras_path_works(self, new_path: str, attribute: str):
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore")
-            mod = importlib.import_module(new_path)
-        assert hasattr(mod, attribute)
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# 3. Identité préservée
-# ──────────────────────────────────────────────────────────────────────────
-
-
-class TestIdentityThroughShim:
-    def test_iiif_identity(self):
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore")
-            from picarones.extras.importers.iiif import IIIFImporter as via_new
-            from picarones.importers.iiif import IIIFImporter as via_old
-        assert via_old is via_new
-
-    def test_gallica_identity(self):
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore")
-            from picarones.extras.importers.gallica import GallicaClient as via_new
-            from picarones.importers.gallica import GallicaClient as via_old
-        assert via_old is via_new
-
-    def test_http_helpers_identity(self):
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore")
-            from picarones.extras.importers._http import (
-                validate_http_url as via_new,
-            )
-            from picarones.importers._http import (
-                validate_http_url as via_old,
-            )
-        assert via_old is via_new
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# 4. Modules expérimentaux : UserWarning à l'import
-# ──────────────────────────────────────────────────────────────────────────
-
-
-def _force_reimport(module_name_substring: str) -> None:
-    """Vide le cache d'import pour pouvoir capturer le UserWarning."""
-    for name in list(sys.modules.keys()):
-        if module_name_substring in name:
-            del sys.modules[name]
-
-
-class TestExperimentalImporters:
-    def test_huggingface_emits_userwarning(self):
-        _force_reimport("huggingface")
-        with warnings.catch_warnings(record=True) as w:
-            warnings.simplefilter("always")
-            import picarones.extras.importers.huggingface  # noqa: F401
-        msgs = [str(x.message) for x in w if issubclass(x.category, UserWarning)]
-        assert any("experimental" in m for m in msgs), (
-            f"huggingface n'a pas émis de UserWarning experimental — "
-            f"warnings reçus : {[str(x.message) for x in w]}"
-        )
-
-    def test_escriptorium_emits_userwarning(self):
-        _force_reimport("escriptorium")
-        with warnings.catch_warnings(record=True) as w:
-            warnings.simplefilter("always")
-            import picarones.extras.importers.escriptorium  # noqa: F401
-        msgs = [str(x.message) for x in w if issubclass(x.category, UserWarning)]
-        assert any("experimental" in m for m in msgs)
-
-    def test_iiif_does_not_emit_warning(self):
-        """Les importers maintenus ne doivent PAS émettre de warning."""
-        _force_reimport("iiif")
-        with warnings.catch_warnings(record=True) as w:
-            warnings.simplefilter("always")
-            import picarones.extras.importers.iiif  # noqa: F401
-        msgs = [str(x.message) for x in w if issubclass(x.category, UserWarning)]
-        # Il peut y avoir d'autres warnings (deprecation Python, etc.)
-        # mais pas de "experimental" sur iiif
-        assert not any(
-            "iiif" in m and "experimental" in m for m in msgs
-        ), "iiif ne doit pas être marqué experimental"
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# 5. picarones.importers/__init__.py — réexports historiques
-# ──────────────────────────────────────────────────────────────────────────
-
-
-class TestImportersInitReexports:
-    def test_reexports_work(self):
-        """Le ``__init__`` réexporte des symboles via les shims, eux-mêmes
-        chargeant depuis extras."""
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore")
-            from picarones.importers import (
-                EScriptoriumClient,
-                GallicaClient,
-                IIIFImporter,
-            )
-        assert IIIFImporter is not None
-        assert GallicaClient is not None
-        assert EScriptoriumClient is not None
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# 6. cli/_imports.py — toujours fonctionnel
-# ──────────────────────────────────────────────────────────────────────────
-
-
-class TestCliImportsCommand:
-    def test_cli_imports_module_loads(self):
-        """``picarones.cli._imports`` importe IIIFImporter depuis
-        ``picarones.importers.iiif`` — doit fonctionner via shim."""
-        try:
-            with warnings.catch_warnings():
-                warnings.simplefilter("ignore")
-                import picarones.cli._imports  # noqa: F401
-        except ImportError as exc:
-            if "click" in str(exc):
-                pytest.skip("click absent")
-            raise
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# 7. pyproject.toml — extra [importers]
-# ─────────────────────────────────────────────────────���────────────────────
-
-
-class TestPyprojectExtra:
-    def test_importers_extra_declared(self):
-        path = Path(__file__).parent.parent / "pyproject.toml"
-        content = path.read_text(encoding="utf-8")
-        assert "importers = []" in content or 'importers = [' in content
-        assert "extras/importers" in content
-        assert "Cercle 3" in content
-
-
-# ──────────────────────────────────────────────────────────────────────────
-# 8. Originaux sont des shims minces
-# ──────────────────────────────────────────────────────────────────────────
-
-
-class TestOriginalsAreShims:
-    @pytest.mark.parametrize("path", [
-        "picarones/importers/_http.py",
-        "picarones/importers/iiif.py",
-        "picarones/importers/htr_united.py",
-        "picarones/importers/gallica.py",
-        "picarones/importers/huggingface.py",
-        "picarones/importers/escriptorium.py",
-    ])
-    def test_is_thin_shim(self, path):
-        repo_root = Path(__file__).parent.parent
-        content = (repo_root / path).read_text(encoding="utf-8")
-        n_lines = len([line for line in content.splitlines() if line.strip()])
-        assert n_lines < 30, (
-            f"{path} fait {n_lines} lignes — devrait être un shim mince"
-        )
-        assert "déplacé" in content or "extras" in content