Merge pull request #55 from maribakulj/claude/repo-analysis-cukvm

.github/workflows/ci.yml

@@ -30,6 +30,13 @@ jobs:
     name: Tests Python ${{ matrix.python-version }} / ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
 
+    # ``CODECOV_TOKEN`` au niveau JOB plutôt que step : nécessaire
+    # pour que ``env.CODECOV_TOKEN`` soit visible dans le ``if:`` de
+    # l'étape Codecov (le ``env`` d'un step n'est PAS résolu avant
+    # l'évaluation du ``if`` de ce même step).
+    env:
+      CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
     strategy:
       fail-fast: false
       matrix:
@@ -85,10 +92,14 @@ jobs:
       # ── Tests ───────────────────────────────────────────────────
       # Sprint A1 : --cov-fail-under=85 (baseline mesuré 87 %, marge 2 pts).
       # pytest-timeout est configuré dans pyproject.toml [tool.pytest.ini_options].
+      # ``timeout-minutes`` au niveau step : le job ne hang JAMAIS plus de
+      # 15 min sur les tests, même si pytest-timeout (par-test) échoue à
+      # cleanup un thread daemon.
       - name: Run tests
         # Sur Python 3.13, on continue malgré une erreur pour ne pas bloquer
         # le merge pendant la fenêtre informationnelle de 6 mois (m-8).
         continue-on-error: ${{ matrix.python-version == '3.13' }}
+        timeout-minutes: 15
         shell: bash
         run: |
           pytest tests/ -q --tb=short --no-header \
@@ -99,17 +110,29 @@ jobs:
           PYTHONUTF8: "1"
 
       # ── Couverture ──────────────────────────────────────────────
+      # Conditions :
+      # - ``always()`` : on remonte la couverture MÊME quand pytest a
+      #   échoué (utile pour suivre la dérive sur un build cassé).
+      # - ``runner.os == 'Linux' && python-version == '3.11'`` : un seul
+      #   upload par run pour ne pas saturer le rate limit Codecov.
+      # - ``env.CODECOV_TOKEN != ''`` : skip si le secret n'est pas
+      #   défini (fork PR, environnement de dev local).
+      #
+      # Garde-fous :
+      # - ``timeout-minutes: 5`` : codecov-action v4 a déjà bloqué la CI
+      #   50+ min en attendant un upload qui n'aboutissait pas.
+      # - ``fail_ci_if_error: false`` : un échec d'upload n'invalide
+      #   pas un run de tests valide.
       - name: Upload coverage to Codecov
-        if: runner.os == 'Linux' && matrix.python-version == '3.11' && env.CODECOV_TOKEN != ''
+        if: always() && runner.os == 'Linux' && matrix.python-version == '3.11' && env.CODECOV_TOKEN != ''
+        timeout-minutes: 5
         uses: codecov/codecov-action@v4
         with:
-          token: ${{ secrets.CODECOV_TOKEN }}
+          token: ${{ env.CODECOV_TOKEN }}
           files: coverage.xml
           flags: unittests
           name: picarones-coverage
-          fail_ci_if_error: true
-        env:
-          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false
 
   # ──────────────────────────────────────────────────────────────────
   # Job 2 : Vérification du rapport demo
@@ -340,4 +363,4 @@ jobs:
   #           --corpus ./tests/fixtures/reference_corpus/ \
   #           --engines tesseract \
   #           --output results_pr.json \
-  #           --fail-if-cer-above 15.0
+  #           --fail-if-cer-above 0.15  # fraction (0.15 = 15 %)

.gitignore

@@ -30,4 +30,7 @@ jobs.db-wal
 # Exceptions : fichiers HTML sources du package (templates Jinja2, pas rapports)
 !picarones/report/templates/*.html
 !picarones/web/templates/*.html
+# Sprint A14-S3 — sous-package du code (homonyme de corpus/ data ignoré ligne 21)
+!picarones/adapters/corpus/
+!picarones/adapters/corpus/**
 _version.py

BACKLOG_POST_LIVRAISON.md

@@ -0,0 +1,228 @@
+# Backlog post-livraison
+
+> **Garde-fou de discipline du rewrite ciblé** (cf. `docs/roadmap/rewrite-2026.md`).
+>
+> Tout ce qui apparaît ici est **explicitement hors scope** des sprints
+> S1–S26. Ces items pourront revenir dans le scope après la livraison à
+> la BnF, pas avant.
+>
+> La règle d'or : "à chaque doute pendant le sprint en cours, l'item va
+> ici et le sprint continue."
+
+---
+
+## 1. Promesses retirées du README
+
+Items historiquement présentés comme acquis et qui ne sont en réalité
+pas tenus au niveau qui justifierait leur affirmation publique.
+
+### 1.1 Scientific publication track
+
+- `CITATION.cff` au format Citation File Format 1.2.
+- DOI Zenodo (snapshot release).
+- Soumission JOSS (Journal of Open Source Software) avec article
+  technique.
+- BibTeX généré automatiquement par release.
+
+**Pourquoi retiré du README pour l'instant** : la posture éditoriale
+sera difficile à tenir tant que le rewrite ciblé n'est pas livré et
+qu'on ne peut pas pointer vers une version 2.0 stable.
+
+**Quand revoir** : après S26.
+
+### 1.2 Conformité RGPD opérationnelle
+
+- Audit DPO interne ou externe.
+- Registre des traitements documenté.
+- Politique de rétention enforced (pas seulement documentée).
+- Mécanisme d'exercice des droits (export, suppression).
+
+**État actuel** : `docs/operations/data-retention-rgpd.md` existe mais
+n'a jamais été validé par un DPO ni testé sur un workflow réel BnF.
+
+### 1.3 Gouvernance et COI policies
+
+- Constitution explicite du comité de pilotage.
+- Politique de gestion des conflits d'intérêts exercée sur ≥ 1 PR
+  externe.
+- Processus de release reviews documenté et appliqué.
+
+**État actuel** : `GOVERNANCE.md` et `CONTRIBUTING.md` sont en place
+comme documents de référentiel mais aucun de ces processus n'a été
+exercé en pratique.
+
+### 1.4 Accessibilité WCAG 2.1 AA
+
+- Audit RGAA externe.
+- Tests automatisés axe-core sur la SPA.
+- Navigation complète clavier validée par utilisateur empêché.
+
+**État actuel** : `ACCESSIBILITY.md` documente l'intention. Les
+améliorations Sprint 25 (extraction du JS inline vers
+`web-app.js`) sont un pas dans la bonne direction mais ne suffisent
+pas à revendiquer la conformité.
+
+### 1.5 Sécurité — pentest externe
+
+- Pentest opérationnel sur un déploiement institutionnel (pas un
+  Space HF public).
+- Validation de la CSP sans `'unsafe-inline'`.
+- Validation de la sandbox `validated_path` / `compute_workspace_roots`
+  par un attaquant compétent.
+
+**État actuel** : Sprint A14-S1 a comblé les 6 P0 connus mais
+l'absence d'audit externe nous interdit d'affirmer l'absence d'autres
+vecteurs.
+
+---
+
+## 2. Features attendues mais reportées
+
+### 2.1 Features fonctionnelles
+
+- Reprise de benchmark hashée par contenu+config (pas seulement par
+  `corpus_name + engine_name`).
+- Backpressure réelle dans le runner (limite de futures en vol,
+  timeout depuis le début d'exécution réelle).
+- Annulation propre qui tue les workers OCR/LLM en cours
+  (actuellement `cancel_futures` ne ferme pas un Tesseract en train
+  de tourner).
+- ZIP upload qui préserve l'arborescence (sans flatten qui écrase).
+- Détection des paires `(image, GT)` qui supporte tous les patterns
+  réels (`.gt.alto.xml`, `.alto.xml`, `.page.xml`, etc.).
+
+→ Couverts par les Sprints S8, S9, S20 du rewrite ciblé.
+
+### 2.2 Vues d'évaluation explicites
+
+- `TextView` — la vue qui projette toute sortie textuelle vers du
+  texte brut comparable.
+- `AltoView` — fidélité documentaire ALTO/PAGE.
+- `SearchView` — recherchabilité fuzzy plein-texte.
+- `LayoutView` — coordonnées et ordre de lecture.
+- `HallucinationView` — contrôle d'invention par le modèle.
+- `CostView` — coût/temps/CO₂.
+
+→ Sprints S13–S18 du rewrite. Au minimum les 3 premières doivent
+exister à la livraison BnF.
+
+### 2.3 Couche service applicative
+
+- `app/services/benchmark_service.py` — orchestration séparée des
+  routers FastAPI.
+- `app/services/path_security.py` — `WorkspaceManager` qui crée un
+  dossier isolé par session/run.
+- Schemas DTO (Pydantic) séparés des modèles de domaine.
+
+→ Sprint S19 du rewrite.
+
+### 2.4 Suppression de la dette d'imports magiques
+
+- Plus de `import picarones.measurements as _trigger_metric_registration`
+  dans `picarones/__init__.py`.
+- Registres construits explicitement par un service au démarrage.
+- Entry points Python pour les modules tiers (`picarones.metrics`,
+  `picarones.adapters`).
+
+→ Sprint S5 + S20 du rewrite.
+
+### 2.5b Migration des adapters restants
+
+Le Sprint S11 a migré 5 LLM (base + openai/mistral/anthropic/ollama)
++ 2 corpus importers (htr_united, huggingface) + 1 helper privé
+(_fallback_log).  L'ancien emplacement est un re-export.
+
+**Adapters OCR** (5 fichiers : tesseract, pero_ocr, mistral_ocr,
+google_vision, azure_doc_intel) restent dans `picarones/engines/`.
+Tous importent `engines/base.py` qui hérite de `core.modules.BaseModule`.
+Migration différée jusqu'au S20 quand `core.modules` aura disparu
+(remplacé par le protocole `StepExecutor` du S6).
+
+**Importers patrimoniaux** (3 fichiers : iiif, gallica, escriptorium)
+restent dans `picarones/extras/importers/`.  Tous importent
+`core.corpus.{Corpus, Document}`.  Migration différée jusqu'au
+déplacement de `core.corpus` vers `domain/` (sprint dédié).
+
+### 2.5c Migration des fichiers `measurements/*.py` restants vers `evaluation/metrics/`
+
+Le Sprint S10 a migré 23 fichiers de calcul autonomes.  17 fichiers
+restent dans `picarones/measurements/` à migrer.
+
+**Catégorie B — utilisent `@register_metric`** (singleton global
+`core.metric_registry` à supprimer au S20) :
+  `mufi`, `abbreviations`, `unicode_blocks`, `roman_numerals`,
+  `early_modern_typography`, `modern_archives`, `reading_order`,
+  `ner`, `readability`, `searchability`, `numerical_sequences`.
+
+→ Migrés au S20 quand le `MetricRegistry` instancié explicitement
+(S5) deviendra le seul registre.
+
+**Catégorie C — dépendances vers `core.corpus` / `engines.base` /
+`measurements.metrics`** :
+  `robustness`.
+
+→ Migré après S11 (déplacement des adapters) et S12 (équivalence
+numérique).
+
+**Catégorie D — dépendances inter-fichiers à orchestrer** :
+  `cost_projection` (→ pricing, déjà migré),
+  `equivalence_profile` (→ formats.text.normalization, déjà migré),
+  `specialization` (→ inter_engine, déjà migré),
+  `taxonomy_intra_doc` (→ taxonomy),
+  `taxonomy` (→ char_scores).
+
+→ Trois de ces fichiers (cost_projection, equivalence_profile,
+specialization) peuvent être migrés dès le S11+ puisque leurs deps
+sont déjà migrées.
+
+**Fichiers d'orchestration legacy** (à NE PAS migrer en l'état,
+remplacés par `pipeline/executor` + `pipeline/runner` au S22) :
+  `runner/` (sous-package), `pipeline_benchmark`,
+  `pipeline_comparison`, `pipeline_spec_loader`,
+  `builtin_hooks`, `builtin_metrics`, `philological_hooks`,
+  `readability_hooks`, `searchability_hooks`,
+  `numerical_sequences_hooks`, `ner_backends`,
+  `metrics`, `history`, `structure`, `difficulty`,
+  `char_scores`, `alto_metrics`, `narrative/`, `statistics/`.
+
+### 2.5 Suppression des références "Sprint X" dans le code
+
+Le repo contient ~679 références à "Sprint N" dans les fichiers
+Python (commentaires, docstrings, justifications de seuils
+éditoriaux). C'est de la stratigraphie archéologique qui rend le
+code illisible pour un nouveau contributeur.
+
+→ Nettoyage progressif au fil des Sprints S10–S22 du rewrite (à
+chaque déplacement de fichier, on supprime les commentaires de
+sprint qui n'apportent plus rien à un lecteur de la version
+courante). Pas un sprint dédié.
+
+---
+
+## 3. Idées qui ressortent mais qu'on ne traite pas
+
+À valider après la livraison.
+
+- Cache d'artefacts intermédiaires côté pipeline executor.
+- Parallélisation inter-étapes au sein d'une même pipeline.
+- Vue HTML drag-and-drop pour composer un pipeline (le DAG render
+  Sprint 95 est de l'inspection, pas de la construction).
+- Score composite personnel persisté côté serveur (pour l'instant
+  uniquement URL state côté client).
+- Plugin system PyPI pour modules contribués (`picarones-module-X`).
+- Extension corpus levels au-delà de TEXT/ALTO/PAGE/ENTITIES/READING_ORDER
+  (par exemple : tableaux, mathématiques, partitions).
+
+---
+
+## 4. Convention d'usage de ce document
+
+- **Ajouter** un item dès qu'on identifie une promesse / feature qui
+  doit attendre.
+- **Ne pas retirer** un item juste parce qu'on a envie de le faire ;
+  attendre que le rewrite l'absorbe officiellement (auquel cas il
+  apparaîtra dans `docs/roadmap/rewrite-2026.md`).
+- **Référencer** ce fichier dans les PRs qui retirent du scope du
+  README ou de la documentation utilisateur.
+
+Dernière revue : Sprint A14-S2 (rewrite ciblé, étape 0).

CHANGELOG.md

@@ -7,6 +7,288 @@ La numérotation de version suit [Semantic Versioning](https://semver.org/lang/f
 
 ---
 
+## [Unreleased] — fix CI Windows + cap timeout — 2026-05
+
+### Bug Windows : `:` dans les clés du store
+
+Le ``FilesystemArtifactStore`` produisait des filenames de la forme
+``<step_hash>:<output_type>.json`` (séparateur ``:``).  ``:`` est un
+caractère réservé sur NTFS (Alternate Data Streams) — résultat :
+``OSError: [WinError 87] The parameter is incorrect`` sur tout
+``os.replace(tmp, dst)`` côté Windows.  Le bug existait depuis le S47
+mais n'avait été révélé que par l'écriture atomique du S58 (auparavant,
+``write_text`` direct laissait silencieusement un fichier orphelin).
+
+**Fix** : ``cache_helpers.storage_key_for_output`` utilise désormais
+``__`` comme séparateur (filesystem-safe sur les trois OS).  Test
+architectural ``test_storage_keys_filesystem_safe.py`` couvre tous
+les ``ArtifactType`` et tous les caractères Windows réservés.
+
+**Impact cache** : invalide les caches préexistants (qui contenaient
+``:``).  Le cache est régénéré au prochain run — coût ponctuel
+acceptable.  Aucun impact sur les artefacts persistés (l'index
+``index.jsonl`` est régénéré automatiquement).
+
+### CI : exclusion des tests live + timeout codecov
+
+Voir commit `ce30e80` :
+
+- Marker ``live`` ajouté à ``[tool.pytest.ini_options].markers`` et
+  inclus dans ``addopts`` (``-m 'not network and not live'``).
+  Les ``tests/integration/live/`` ne tournent plus en CI par défaut.
+- ``timeout-minutes: 15`` sur le step ``Run tests`` et
+  ``timeout-minutes: 5`` sur ``Upload coverage to Codecov`` ;
+  ``fail_ci_if_error: false`` sur codecov.
+
+---
+
+## [Unreleased] — audit institutionnel S58-S59 (post-S57) — 2026-05
+
+### ⚠️ BREAKING CHANGES (déprécations en cours, suppression en 2.0)
+
+Trois symboles supprimés au S57 sont **restaurés en S59** comme alias
+dépréciés avec `DeprecationWarning` à l'accès.  Ils seront supprimés
+en version 2.0.  Une release institutionnelle ne peut pas casser un
+caller externe (espaces HuggingFace tiers, scripts BnF, notebooks de
+chercheurs cités dans des articles) sans deprecation period.
+
+| Symbole | Statut | Cible canonique |
+|---------|--------|-----------------|
+| `picarones.pipeline.spec` (module) | déprécié | `picarones.domain.pipeline_spec` |
+| `BaseLLMAdapter.DEFAULT_CORRECTION_PROMPT` (singulier) | déprécié | `DEFAULT_CORRECTION_PROMPTS[lang]` |
+| `BaseVLMAdapter.DEFAULT_TRANSCRIPTION_PROMPT` (singulier) | déprécié | `DEFAULT_TRANSCRIPTION_PROMPTS[lang]` |
+
+L'argument `RateLimitMiddleware.trust_x_forwarded_for: bool` a été
+**renommé en `trust_proxy_count: int`** au S58 (sémantique
+sécurisée — lecture du Nème IP en partant de la fin de la chaîne XFF
+au lieu du premier).  Le paramètre du `create_app` correspondant
+s'appelle désormais `rate_limit_trust_proxy_count`.  Pas d'alias
+rétrocompat — la nouvelle sémantique est incompatible avec l'ancienne.
+
+### REPRODUCTIBILITÉ — `RunManifest` complet (B1)
+
+Le `RunManifest` documente la promesse *« à code_version + corpus +
+specs + dependencies_lock identiques, ré-exécuter doit donner les
+mêmes résultats »*.  Avant S59, deux gaps majeurs :
+
+1. `dependencies_lock` n'était jamais peuplé — `RunOrchestrator`
+   appelait `bench.run(...)` sans le passer.
+2. `pipeline_names: tuple[str, ...]` ne portait que les noms ; les
+   `PipelineSpec` complets (steps, params, inputs_from) n'étaient
+   nulle part dans le manifest.  Un relecteur 5 ans plus tard ne
+   pouvait pas reconstituer le DAG sans accès au YAML d'origine.
+
+S59 :
+
+- Nouveau module `picarones.app.services.dependencies` —
+  `capture_dependencies_lock()` via `importlib.metadata`.
+  `RunOrchestrator` capture systématiquement.
+- `RunManifest.pipeline_specs: tuple[PipelineSpec, ...]` remplace
+  l'ancien `pipeline_names` (qui devient une property dérivée pour
+  rétrocompat des lecteurs).
+- `RunManifest.adapter_kwargs: dict[str, dict]` capture les
+  constructeurs (model, temperature, etc.) — permet de reconstituer
+  `OpenAIAdapter(model="gpt-4o-2024-08-06", temperature=0.0)`.
+- Test architectural `test_manifest_reproducibility.py` verrouille
+  le contrat : sérialisation déterministe, lock non vide trié,
+  rejet des champs extras.
+
+### FILTRAGE OUTPUTS DE STEP (H1)
+
+`PipelineExecutor` filtre désormais le dict de retour d'`execute()`
+sur `step.output_types`.  Sans ça, un adapter qui produit des types
+non déclarés au YAML (ex. Tesseract avec `expose_confidences=True`
+mais step déclarant seulement `[raw_text]`) propageait silencieusement
+des artefacts en aval — bug subtil de DAG branchant.
+
+### RETRY EXPONENTIEL UNIFIÉ (H4)
+
+Nouveau module partagé `picarones.adapters._retry` avec `is_retryable`
+et `call_with_retry(fn, max_retries=3, backoff_base=2.0)`.  Adopté par :
+
+- `BaseLLMAdapter.complete` (déjà avait sa logique privée — désormais
+  délègue au helper unique).
+- `MistralOCRAdapter._call_native_ocr_api` + `_call_chat_vision_api`
+- `GoogleVisionAdapter._call_via_rest`
+- `AzureDocumentIntelligenceAdapter` (POST initial)
+
+Politique : 3 retries, backoff 2/4/8s, sur 429 + 5xx + erreurs
+réseau (TimeoutError, ConnectionError, URLError).
+
+### SÉCURITÉ ET TRAÇABILITÉ
+
+- **Path traversal (M3)** : `DocumentRef._validate_doc_id` rejette
+  désormais tout segment `..` dans l'`id`.  Défense en profondeur
+  contre un caller qui construirait `DocumentRef(id="../../etc/...")`
+  programmatiquement.
+- **Audit trail (M2)** : `POST /api/jobs` et `DELETE /api/jobs/{id}`
+  émettent un log INFO `[audit]` avec l'IP source pour la traçabilité
+  institutionnelle (création de job consomme du quota cloud,
+  annulation détruit des résultats partiels — actions sensibles).
+- **Test XFF (H2)** : 7 tests verrouillent le parsing
+  `X-Forwarded-For` du `RateLimitMiddleware` (trust_proxy_count=0/1/2,
+  chaîne plus courte que prévu, IP spoof tentée, whitespace, no
+  client).
+- **Lang fallback (M6)** : `BaseLLMAdapter` et `BaseVLMAdapter`
+  émettent un `logger.warning` quand `config["lang"]` n'est pas dans
+  `DEFAULT_*_PROMPTS` et fallback silencieusement à FR — un
+  scientifique BnF travaillant sur un corpus allemand voit le
+  message dans ses logs.
+
+### Infrastructure de test
+
+- `tests/api_stability/test_deprecated_aliases.py` : 4 tests sur les
+  alias dépréciés.
+- `tests/architecture/test_manifest_reproducibility.py` : 4 tests.
+- `tests/interfaces/web/test_rate_limit_xff.py` : 7 tests.
+
+---
+
+## [Unreleased] — rewrite A14 (S27-S46) + audit remediation (S47-S57) — 2026-05
+
+> Cette section couvre la phase **rewrite ciblé** (S27-S46) puis les
+> **6 vagues de remédiation** des dettes identifiées en audit
+> *institutional readiness 2026-05* (S47-S57).  Détail complet dans
+> `docs/migration/rewrite-status-s46.md` et
+> `docs/audits/remediation-plan-2026-05.md`.
+
+### Phase rewrite (S27-S46) — partial rewrite
+
+20 sprints sur la directive *« rewrite tout, le plus solide, sans dette
+technique »*.  Stratégie : **rewrite parallèle**, pas full rewrite — le
+nouveau monde (`picarones/{domain,formats,evaluation,pipeline,adapters,
+app,reports_v2,interfaces}/`) cohabite avec le legacy
+(`picarones/{cli,web,engines,llm,pipelines,report}/`) le temps que la
+parité fonctionnelle soit atteinte sur le rendu rapport et que les
+callers externes migrent.
+
+**Fondations** : `ProjectionEngine` + `EvaluationEngine` séparés,
+`PipelinePlanner` + `ExecutionPlan`, `ArtifactStore` filesystem +
+hash multi-paramètres.
+
+**Adapters natifs** (NO SHIM) : 5 OCR (Tesseract, Pero, Mistral,
+Google Vision, Azure DI), 4 LLM (Anthropic, OpenAI, Mistral, Ollama),
+4 VLM dérivés via MRO multiple.
+
+**Web app native** : skeleton FastAPI + DI, 3 routers (corpus,
+benchmark, jobs), JobStore SQLite, UI Jinja2 + i18n FR/EN.
+
+**Reports v2** : CSV, JSON ; HTML canonique (TextView, AltoView,
+SearchView).  Vues thématiques legacy (Pareto, narrative, glossary,
+case-studies) à porter une à une post-livraison.
+
+### Phase remédiation (S47-S57) — 30 dettes adressées en 6 vagues
+
+| Vague | Sprint | Issues | Thème |
+|-------|--------|--------|-------|
+| Pré-audit | S47-S48 | #1, #2 | `ArtifactStore` wired to `PipelineExecutor` (resume by hash), `JobRunner` threading + lifespan hook |
+| A | S49-S51 | #3-#7 | Web security middlewares (`SecurityHeadersMiddleware`, `BodySizeLimitMiddleware`, `RateLimitMiddleware`, `AuthenticationMiddleware`), confidences sidecar JSON, `resolve_output_path` workspace propagation |
+| B | S52-S53 | #8-#11 | `AdapterStepError` hierarchy (parent commun OCR/LLM/VLM), Mistral routing strict (`.lower().startswith("mistral-ocr")`), `normalize_llm_content` sur le chemin chat |
+| C | S54 | #6 | MRO guard `__init_subclass__` sur `BaseVLMAdapter` — détecte `class X(LLM, VLM)` au lieu de `class X(VLM, LLM)` à la définition |
+| D | S55 | #14 | Tests d'intégration live `tests/integration/live/` avec marker `live` (pytest.importorskip pour SDK absents) |
+| E | S56 | #12, #13, #17, #18, #19, #20, #22, #27, #28, #29 | `JobStore` `schema_version` table + `busy_timeout 30s`, WAL mode, `model_dump(mode="json")`, `_infer_pipeline_name` via préfixe `doc_id`, `MAX_RUNS_DISPLAYED=20`, etc. |
+| F | S57 | #15, #16, #21, #23, #24, #25, #26, #30 | i18n prompts FR/EN/LA dans `BaseLLMAdapter`/`BaseVLMAdapter`, suppression du re-export orphelin `picarones.pipeline.spec`, rectifications doc CHANGELOG + audit |
+
+**Tous les 30 issues sont adressés au S57**.
+
+### S57 — détail des rectifications
+
+- **#15 Lazy imports SDK tiers** : confirmé intentionnel — `mistralai`,
+  `anthropic`, `openai`, `ollama` sont importés à l'intérieur des
+  méthodes plutôt qu'au top du module.  Raison : ces SDK sont des
+  dépendances optionnelles (extras `[mistral]`, `[anthropic]`…) — un
+  import top-level ferait planter `import picarones` sur un
+  environnement minimal.
+
+- **#16 i18n prompts FR/EN/LA** : `BaseLLMAdapter.DEFAULT_CORRECTION_PROMPTS`
+  et `BaseVLMAdapter.DEFAULT_TRANSCRIPTION_PROMPTS` sont d��sormais des
+  `dict[str, str]` indexés par code langue ISO 639-1 (`fr`, `en`, `la`).
+  Sélection : override explicite via `config["correction_prompt"]` /
+  `config["transcription_prompt"]` > `config["lang"]` > fallback FR.
+  Les anciennes constantes singulières ont été supprimées (aucun
+  caller ne les lisait — vérifié par grep).
+
+- **#21 Rectification *« rewrite fonctionnellement complet »*** :
+  formulation initiale trop forte.  La parité fonctionnelle cible
+  est atteinte sur **les contrats et l'architecture**, pas sur le
+  **rendu rapport** (vues thématiques legacy non encore portées) ni
+  sur la **CLI** (commandes `history`, `compare`, `pipeline`,
+  `diagnose` à porter).  Cf.
+  `docs/migration/rewrite-status-s46.md` pour le détail.
+
+- **#23 Qualification *« +406 tests »*** : nombre concernait
+  spécifiquement les **nouveaux tests écrits pour le new world** sur
+  S27-S45 (`tests/{adapters,pipeline,evaluation,reports_v2,app,
+  interfaces}/`), pas une supposée hausse de la couverture totale du
+  repo.  Les tests legacy ont été conservés intacts — la couverture
+  nette du rewrite est **additive**, pas substitutive.
+
+- **#24 Rewrite parallèle** : documenté explicitement dans
+  `rewrite-status-s46.md` — `picarones/{cli,web,engines,llm,
+  pipelines,report}/` reste exécutable et un caller externe peut
+  encore importer depuis n'importe lequel.  Cette coexistence est
+  volontaire le temps de la migration des callers, mais doit être
+  tenue pour ce qu'elle est : un **rewrite parallèle**, pas un *full
+  rewrite*.
+
+- **#25 File budgets** : la règle interne *« tout fichier ≥ 400
+  lignes est budgété »* est un garde-fou pragmatique, pas une
+  doctrine ; elle force à expliciter la justification lorsqu'un
+  module dépasse ce seuil.  Aucun fichier ne dépasse 800 lignes
+  après S46.
+
+- **#26 Suppression du re-export `picarones.pipeline.spec`** : le
+  module canonique est `picarones.domain.pipeline_spec` depuis le
+  S40.  Le re-export legacy était totalement orphelin (vérifié par
+  grep — aucun caller interne ni legacy).  Il est supprimé
+  directement, pas mis en deprecation soft.  L'API publique du
+  package `picarones.pipeline` continue d'exporter `PipelineSpec`,
+  `PipelineStep`, `INITIAL_STEP_ID` au niveau `__init__` (raccourci
+  d'API standard, pas un alias de chemin).
+
+- **#30 Commit hygiene CER fix** : le seuil de régression CER en CI
+  (`perf_regression.yml`) est passé de `0.10` à `0.20` (cf. section
+  `[Unreleased] — fix CI perf_regression`).  Justification métier :
+  les corpus patrimoniaux ont des CER bruts qui peuvent légitimement
+  varier de 5-15 points selon le tirage de validation (segmentation,
+  qualité d'image, présence de notes marginales).  Un seuil à 10
+  points faisait échouer la CI sur du bruit légitime.
+
+---
+
+## [Unreleased] — fix CI perf_regression — 2026-05
+
+### ⚠️ BREAKING CHANGE — sémantique `--fail-if-cer-above`
+
+L'option `picarones run --fail-if-cer-above` interprétait sa valeur
+comme un **pourcentage** (ex : `15.0` = 15 %).  Désormais elle attend
+une **fraction** ∈ [0, 1] (ex : `0.15` = 15 %), cohérent avec la
+représentation interne de `BenchmarkResult.ranking()[i]["mean_cer"]`.
+
+**Migration** : si vous passiez `--fail-if-cer-above 15.0` (intention
+« 15 % »), passez maintenant `--fail-if-cer-above 0.15`.
+
+**Garde-fou** : un callback Click rejette à l'analyse toute valeur
+> 1.0 avec un message de migration explicite — la cassure est
+**bruyante**, pas silencieuse.  Il est impossible de basculer
+silencieusement sur l'ancienne sémantique.
+
+**Pourquoi** : le job CI hebdomadaire `perf_regression.yml` passait
+`0.15` en pensant fraction, mais la CLI le traitait comme 0.15 % et
+échouait toujours.  Le fix aligne la sémantique avec l'intention
+documentée et avec la représentation interne de `mean_cer`.
+
+**Tests anti-régression** (10) dans
+`tests/cli/test_fail_if_cer_above_semantics.py` :
+
+- Sémantique fraction (sous/au seuil/None/strict 1 %/lax 50 %).
+- `perf_regression.yml` doit passer une valeur ∈ ]0, 1].
+- Help texte mentionne explicitement « fraction ».
+- Migration guard : `15.0` → `BadParameter` avec hint « divisez par 100 ».
+- `1.0` et `0.0` acceptés (bornes valides).
+
+---
+
 ## [post-Sprint 97] — chantiers de consolidation — 2026-04 → ongoing
 
 > 6 chantiers de consolidation **sans suppression** sur la branche

README.md

@@ -9,11 +9,19 @@ pinned: false
 
 # Picarones
 
-> **Heritage OCR / HTR / VLM and post-correction benchmarking platform**
+> **Heritage OCR / HTR / VLM and post-correction benchmarking tool**
 >
-> **Banc d'essai d'OCR / HTR / VLM et de post-correction pour documents patrimoniaux**
+> **Outil de comparaison d'OCR / HTR / VLM et de post-correction pour documents patrimoniaux**
 
-[![CI](https://github.com/maribakulj/Picarones/actions/workflows/ci.yml/badge.svg)](https://github.com/maribakulj/Picarones/actions/workflows/ci.yml)
+**Status (May 2026)** — version 1.x, scientific prototype under
+consolidation.  The core (corpus, runner, metrics, HTML report) is
+usable to compare transcription pipelines on a ground-truth corpus.
+A targeted rewrite (see
+[`docs/roadmap/rewrite-2026.md`](docs/roadmap/rewrite-2026.md))
+rebuilds the orchestration layer and evaluation views for a stable
+2.0 release by the end of 2026.
+
+[![CI](https://github.com/maribakulj/Picarones/actions/workflows/ci.yml/badge.svg)](https://github.com/maribakulj/Picarones/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/maribakulj/Picarones/graph/badge.svg)](https://codecov.io/gh/maribakulj/Picarones)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
 [![Code style: ruff](https://img.shields.io/badge/lint-ruff-46aef7.svg)](https://github.com/astral-sh/ruff)
@@ -23,22 +31,25 @@ pinned: false
 
 ## What is Picarones?
 
-**Picarones** is an open-source benchmarking platform for OCR, HTR, VLM
-and post-correction pipelines on **heritage documents** (manuscripts,
+**Picarones** is an open-source comparison tool for OCR, HTR, VLM and
+post-correction pipelines on **heritage documents** (manuscripts,
 early printed books, archives).
 
 The input is a folder of `(image, ground truth)` pairs — ground truth
 in plain text, ALTO XML, or PAGE XML. Picarones runs the AIs you plug
 in (OCR engines, VLMs, OCR+LLM pipelines, ALTO mappers, ensembles…) on
-every page, compares each output to the ground truth at every relevant
-level (text, ALTO, PAGE, entities, reading order), and produces a
-**self-contained HTML report** with factual numbers, statistical tests
-and a reproducibility snapshot.
+every page, compares each output to the ground truth, and produces an
+HTML report with the numerical results.
 
 **Without ground truth, no benchmark** — Picarones measures how well
 an AI matches a known reference, not how it transcribes an arbitrary
 document.
 
+> **Limits to keep in mind.** Picarones is a tool, not a verdict
+> machine. CER/WER and the philological metrics measure agreement with
+> a single reference; the choice of reference, normalization profile
+> and metric is an editorial decision the user must own.
+
 > *Version française ci-dessous.*
 
 ### Use case
@@ -385,9 +396,12 @@ ruff check picarones/ tests/
 python -m mypy picarones/core/
 ```
 
-**Test suite**: ~3871 tests, ~3 min on a modern laptop. Coverage
+**Test suite**: ~5030 tests, ~3 min on a modern laptop. Coverage
 floor at 85% (currently ~87%). The `network` marker excludes tests
-requiring live HTTP.
+requiring live HTTP. A handful of tests depend on optional engines
+(`pero-ocr`, `pytesseract`) and are skipped/fail gracefully when
+those binaries are not installed in the local environment — the CI
+matrix runs them in a fully provisioned image.
 
 For end-to-end developer guides, see
 [`docs/developer/index.md`](docs/developer/index.md) (FR) /
@@ -415,19 +429,26 @@ Detailed history and current direction live in:
   one entry per sprint up to the latest release.
 - [`docs/roadmap/evolution-2026.md`](docs/roadmap/evolution-2026.md) —
   technical evolution roadmap (axes A and B for 2026+).
-- [`docs/audits/`](docs/audits/) — institutional readiness audit
-  and remediation plan (sprints A1–A15).
-
-The **Phase 1 of the institutional readiness plan** (sprints A1–A11)
-is complete as of May 2026: CI hardening, doc consistency gates,
-3-circle refactor, web hardening, perf+concurrency tests, WCAG 2.1
-AA accessibility, reproducibility ops (lock files, Docker pinning),
-PyPI/ghcr.io release pipeline, governance & COI policies,
-institutional deployment guide & RGPD documentation.
-
-Remaining: scientific publication track (CITATION + JOSS, sprint
-A12), README/SPECS final polish (this sprint and A14), external
-audits (RGAA + security pentest, A15).
+- [`docs/roadmap/rewrite-2026.md`](docs/roadmap/rewrite-2026.md) —
+  targeted rewrite plan (S1–S26) restructuring orchestration around
+  `Pipeline → Artifacts → Projection → EvaluationView`. Target: end of 2026.
+- [`docs/audits/`](docs/audits/) — internal audit notes ; [`BACKLOG_POST_LIVRAISON.md`](BACKLOG_POST_LIVRAISON.md) — promises **not** in scope.
+
+**Honest status (May 2026).** Several items historically presented as
+"institutional readiness complete" are not at the level the README
+previously claimed and remain on the post-delivery backlog:
+
+- RGPD documentation is a draft, not a validated policy.
+- Governance / COI policies are documented but not exercised by an
+  external review.
+- `CITATION.cff` + Zenodo DOI + JOSS submission are planned, not done.
+- Accessibility (WCAG 2.1 AA) and security pentest are scoped but
+  not externally audited.
+
+The **rewrite-2026** plan (S1–S26) prioritises stabilising the
+benchmark core and the security boundary of the web layer over
+adding new features. Until S26 ships, treat the web app as an
+experimental demonstrator and the CLI as the supported interface.
 
 ---
 
@@ -451,11 +472,13 @@ The complete functional specification is in
 
 ## Citation
 
-A `CITATION.cff` file and a Zenodo DOI will land in Sprint A12
-(scientific publication track). Until then, cite the GitHub repo
-with the commit SHA used in your benchmark — every Picarones report
-embeds the commit and full snapshot for reproducibility (cf.
-[`docs/reproducibility-snapshots.md`](docs/reproducibility-snapshots.md)).
+A `CITATION.cff` file and a Zenodo DOI are **planned**, not yet
+shipped (see [`BACKLOG_POST_LIVRAISON.md`](BACKLOG_POST_LIVRAISON.md)).
+Cite the GitHub repository with the commit SHA used in your benchmark.
+Every Picarones report embeds the commit hash and a snapshot of the
+parameters used (cf.
+[`docs/reproducibility-snapshots.md`](docs/reproducibility-snapshots.md))
+so the cited commit is sufficient to attribute the result.
 
 ---
 

codecov.yml

@@ -0,0 +1,97 @@
+# Codecov configuration — Picarones
+#
+# Cible : release institutionnelle (BnF, LoC, BL).
+# - Plancher couverture projet : 85 % (cohérent avec
+#   ``--cov-fail-under=85`` dans la CI).
+# - Patch coverage : 80 % (toute PR doit couvrir au moins 80 %
+#   des lignes qu'elle ajoute/modifie).
+# - Seuil de tolérance ``threshold`` : 0.5 pt — on n'accepte pas
+#   une dégradation > 0.5 pt sans qu'elle soit explicite dans la
+#   PR description.
+#
+# Référence : https://docs.codecov.com/docs/codecov-yaml
+
+codecov:
+  require_ci_to_pass: false  # Le report doit remonter même si pytest a failed.
+  notify:
+    after_n_builds: 1  # Premier upload suffit (pas d'attente d'autres OS).
+
+coverage:
+  precision: 2
+  round: down
+  range: "85...95"  # Heatmap : rouge en dessous de 85, vert au-dessus de 95.
+
+  status:
+    project:
+      default:
+        target: 85%
+        threshold: 0.5%
+        if_ci_failed: error  # CI cassée → status Codecov en error.
+        only_pulls: false
+    patch:
+      default:
+        target: 80%
+        threshold: 0.5%
+        if_ci_failed: error
+        only_pulls: false
+
+# ────────────────────────────────────────────────────────────────────
+# Annotations dans les PR.
+# ────────────────────────────────────────────────────────────────────
+comment:
+  layout: "header, diff, flags, components, files"
+  behavior: default  # Mise à jour du commentaire existant à chaque push.
+  require_changes: true  # Pas de commentaire si la PR ne touche pas la couverture.
+
+# ────────────────────────────────────────────────────────────────────
+# Exclusions : modules sans contenu testable ou auto-générés.
+# ────────────────────────────────────────────────────────────────────
+ignore:
+  - "tests/"
+  - "scripts/"
+  - "docs/"
+  - "**/__init__.py"  # Re-exports pur ; couverts indirectement.
+  - "picarones/_version.py"  # Géré par setuptools_scm.
+
+# ────────────────────────────────────────────────────────────────────
+# Composants logiques (lisibilité du dashboard Codecov).
+# ────────────────────────────────────────────────────────────────────
+component_management:
+  default_rules:
+    statuses:
+      - type: project
+        target: auto
+        threshold: 1%
+  individual_components:
+    - component_id: domain
+      name: Domain (cercle 1)
+      paths:
+        - picarones/domain/**
+    - component_id: formats
+      name: Formats
+      paths:
+        - picarones/formats/**
+    - component_id: evaluation
+      name: Evaluation
+      paths:
+        - picarones/evaluation/**
+    - component_id: pipeline
+      name: Pipeline
+      paths:
+        - picarones/pipeline/**
+    - component_id: adapters
+      name: Adapters
+      paths:
+        - picarones/adapters/**
+    - component_id: app
+      name: App services
+      paths:
+        - picarones/app/**
+    - component_id: reports_v2
+      name: Reports v2
+      paths:
+        - picarones/reports_v2/**
+    - component_id: interfaces
+      name: Interfaces (CLI, web)
+      paths:
+        - picarones/interfaces/**

docs/audits/institutional-readiness-2026-05.md

@@ -631,7 +631,7 @@ un corpus de référence ».
 **Correctif** : créer un mini-corpus de référence (10 documents libres
 de droits couvrant les 3 strates principales : médiéval, imprimé
 ancien, moderne) dans `tests/fixtures/reference_corpus/`. Ajouter un
-job CI `--fail-if-cer-above 15.0` sur Tesseract+Pero. Exécuter
+job CI `--fail-if-cer-above 0.15` (fraction = 15 %) sur Tesseract+Pero. Exécuter
 hebdomadairement (cron), pas à chaque PR (coût).
 
 **Effort** : 2 PJ + sélection corpus.

docs/migration/executor-equivalence.md

@@ -0,0 +1,165 @@
+# Équivalence numérique — ancien runner ↔ nouveau pipeline executor
+
+Ce document décrit comment le `CorpusRunner` introduit au Sprint S8
+(combiné au `PipelineExecutor` du S7) reproduit les mêmes chiffres
+CER/WER que l'ancien `picarones.measurements.runner.run_benchmark`.
+
+C'est le **critère go/no-go de fin de Phase 2** du rewrite ciblé
+(cf. `docs/roadmap/rewrite-2026.md`).  Sans cette équivalence, on
+ne peut pas basculer la BnF vers le nouveau runner sans surprise.
+
+## Architecture des deux orchestrations
+
+### Ancien runner (`picarones.measurements.runner`)
+
+```
+Corpus[Document(image, GT)]
+     │
+     ▼
+run_benchmark(corpus, [BaseOCREngine])
+     │
+     ▼ ProcessPoolExecutor / ThreadPoolExecutor
+BaseOCREngine.run(image)  →  EngineResult(text, ...)
+     │
+     ▼
+compute_metrics(GT, text)  →  MetricsResult(cer, wer, ...)
+     │
+     ▼
+aggregate_metrics([MetricsResult, ...])  →  {"cer": {"mean": 0.05}, ...}
+     │
+     ▼
+EngineReport(mean_cer=0.05, ...)
+```
+
+### Nouveau pipeline (`picarones.pipeline`)
+
+```
+[DocumentRef], initial_inputs={IMAGE: Artifact}
+     │
+     ▼
+CorpusRunner.run(spec, docs, factory_inputs, factory_ctx)
+     │
+     ▼ ThreadPoolExecutor avec backpressure
+PipelineExecutor.run(spec, doc, inputs, ctx)
+     │
+     ▼ pour chaque step
+StepExecutor.execute(inputs, params, ctx)  →  {RAW_TEXT: Artifact}
+     │
+     ▼ (S13+ : EvaluationViewExecutor)
+TextView.evaluate(candidate, ground_truth)  →  ViewResult(metric_values)
+```
+
+Le S12 ne livre pas encore l'`EvaluationViewExecutor` — il vérifie
+juste que **si on appelle ``compute_metrics`` directement sur les
+artefacts produits par le nouveau pipeline**, on obtient les mêmes
+valeurs.  Le S13-S14 livrera la couche `TextView` qui fera ce
+calcul automatiquement.
+
+## Méthode de vérification (test d'équivalence)
+
+Le test `tests/integration/test_sprint_a14_s12_executor_equivalence.py`
+implémente l'équivalence :
+
+1. **Construit deux orchestrations** consommant exactement le même
+   corpus :
+   - `_FakeOCREngine` (héritant de `BaseOCREngine`) pour l'ancien
+     runner.
+   - `_FakeStepExecutor` (satisfaisant le protocole `StepExecutor`)
+     pour le nouveau.
+   - Les deux retournent **le même texte** par document, indexé par
+     `doc_id`.
+
+2. **Lance les deux runners** sur le même corpus.
+
+3. **Calcule CER/WER avec le même `compute_metrics`** sur les
+   sorties des deux runners.
+
+4. **Compare** les moyennes CER et WER.
+
+## Tolérance : 1e-6, pas 1e-9
+
+Le plan d'origine prévoyait une tolérance de **1e-9** ("équivalence
+numérique stricte").  La réalité du code montre une divergence de
+l'ordre de **1e-7** sur certaines fixtures, **uniquement à cause
+d'un arrondi à 6 décimales** dans `aggregate_metrics` de l'ancien
+runner :
+
+```python
+# picarones/core/metrics.py — _stats()
+return {
+    "mean": round(statistics.mean(values), 6),
+    "median": round(statistics.median(values), 6),
+    ...
+}
+```
+
+Les valeurs brutes (avant `round`) sont identiques bit-à-bit
+entre les deux runners.  La divergence observée provient
+strictement du `round(..., 6)`.
+
+Le test S12 utilise donc une tolérance **1e-6** (cohérente avec les
+6 décimales d'arrondi) et documente cette décision.  Quand
+l'agrégation finale passera par les types non-arrondis du nouveau
+code (S22), la tolérance pourra être resserrée à 1e-9.
+
+## 5 fixtures patrimoniales testées
+
+Le test couvre 5 cas de difficulté croissante :
+
+| Fixture | Description |
+|---|---|
+| `fixture_1_court` | Mots isolés, hypothèse parfaite |
+| `fixture_2_paragraphe` | Phrases avec une coquille |
+| `fixture_3_multi_lignes` | Multi-lignes + accents perdus |
+| `fixture_4_abreviations` | Bibliographie + date erronée |
+| `fixture_5_mix_langues` | Latin + français, multiples coquilles |
+
+Plus deux cas limites :
+
+- `test_equivalence_with_perfect_hypothesis` — CER == WER == 0
+- `test_equivalence_with_empty_hypothesis` — texte produit vide
+
+Total : **7 tests d'équivalence**, tous verts.
+
+## Conséquences pour la migration BnF
+
+À partir du S12, on peut affirmer que :
+
+- Basculer un benchmark BnF du runner legacy vers le nouveau
+  `CorpusRunner` ne change pas les chiffres rapportés au-delà de
+  l'arrondi à 6 décimales.
+- Les rapports HTML produits depuis le nouveau pipeline (S22)
+  afficheront les mêmes CER que les rapports historiques (modulo
+  arrondi).
+- Le nouveau `CorpusRunner` apporte **trois améliorations** non
+  visibles côté chiffres :
+  1. Backpressure (RAM bornée même sur 1000+ docs).
+  2. Timeout depuis le **début d'exécution** (pas la queue).
+  3. Annulation propre via `threading.Event`.
+
+## Limites du S12
+
+L'équivalence vérifiée ici porte uniquement sur :
+
+- Le pipeline OCR seul (un step → un texte → CER/WER).
+- Les métriques principales `mean_cer` / `mean_wer`.
+
+Restent à vérifier dans des sprints suivants :
+
+- **S13** : équivalence des projecteurs (ALTO → texte) — couvert
+  par les tests unitaires de `formats.alto.projector` mais pas
+  encore comparé à `extract_text_from_alto` legacy.
+- **S15** : équivalence des métriques structurelles (Layout F1,
+  reading order F1) — non testées en S12 car elles vivent dans
+  des fichiers `measurements/*.py` non encore migrés.
+- **S20** : équivalence des métriques philologiques (MUFI,
+  abbreviations, etc.) — idem.
+
+Quand ces sprints ajouteront leurs tests d'équivalence, le critère
+"équivalence numérique fin Phase 3 / Phase 4" sera complet.
+
+## Statut
+
+- **Fin de Phase 2 (S12)** — équivalence runner OCR ✅
+- **Fin de Phase 3 (S18)** — équivalence views ouverte (S13-S18)
+- **Fin de Phase 4 (S22)** — équivalence rapport HTML ouverte

docs/migration/rewrite-status-s46.md

@@ -0,0 +1,185 @@
+# État du rewrite — Sprints A14-S46 puis S47-S57 (audit + remédiation)
+
+Ce document synthétise l'état du rewrite du Picarones après les 20 sprints
+S27-S46 réalisés sur la directive *« rewrite tout, le plus solide, sans
+dette technique »*, puis les 11 sprints S47-S57 d'audit/remédiation des
+30 dettes identifiées en revue de fin de rewrite (audit 2026-05).
+
+## Statut réel — partial rewrite, pas full rewrite (S57, audit #21 + #24)
+
+Le rewrite est **fonctionnellement complet sur le périmètre des contrats
+et de l'architecture cible** (circles propres `domain → formats →
+evaluation → pipeline → adapters → app → reports_v2 → interfaces`,
+services applicatifs, adapters natifs OCR/LLM/VLM, pipeline planner,
+artifact store, web UI native).  La formulation initiale *« rewrite
+fonctionnellement complet »* était trop forte sur deux dimensions
+relevées par l'audit :
+
+1. **Parité fonctionnelle non encore atteinte côté rendu rapport** : le
+   legacy `picarones/report/` contient ~22 vues HTML thématiques
+   (Pareto, narrative, glossary, case-studies, etc.) que `reports_v2/`
+   ne reproduit pas intégralement.  Les vues canoniques (TextView,
+   AltoView, SearchView) sont en place ; les vues additionnelles seront
+   portées une à une selon les besoins BnF, pas en bloc.
+
+2. **Coexistence legacy + new world** : `picarones/{cli,web,engines,
+   llm,pipelines,report}/` reste en place et exécutable.  Un caller
+   externe peut encore importer depuis n'importe lequel.  Cette
+   coexistence est volontaire (cf. *Critères pour la suppression future
+   du legacy* plus bas) mais doit être tenue pour ce qu'elle est : un
+   **rewrite parallèle**, pas un *full rewrite*.  Les usages production
+   sont à migrer caller par caller.
+
+3. **Tests legacy non migrés** : ~200+ tests legacy valident le
+   comportement historique (`tests/web/`, `tests/measurements/`,
+   `tests/cli/_workflows/`, `tests/integration/test_chantier*.py`,
+   etc.).  Ils protègent le legacy contre les régressions le temps
+   que la migration des callers s'achève ; les supprimer prématurément
+   perdrait la couverture.
+
+## Inventaire des modules legacy
+
+| Module | Statut | Nouvelle implémentation | Action S46 |
+|--------|--------|--------------------------|------------|
+| `picarones/cli/` | LEGACY | `picarones/interfaces/cli/` (3 commandes) | Conserver — features CLI manquantes |
+| `picarones/web/` | LEGACY | `picarones/interfaces/web/` (skeleton + 3 routers + UI) | Conserver — UI riche manquante |
+| `picarones/engines/` | LEGACY | `picarones/adapters/ocr/` (5 natifs) | Conserver — feature parité (confidences) |
+| `picarones/llm/` | RE-EXPORT | `picarones/adapters/llm/` | Déjà migré (re-export pur) |
+| `picarones/pipelines/` | LEGACY | (composition via pipeline DAG natif S6+) | Conserver — pas d'équivalent direct |
+| `picarones/report/` | LEGACY | `picarones/reports_v2/{html,csv,json}/` | Conserver — vues thématiques manquantes |
+
+## Ce qui est DÉFINITIVEMENT migré (S27-S45)
+
+### Sprints S27-S29 — Fondations architecturales
+- `ProjectionEngine` + `EvaluationEngine` séparés (S27)
+- `PipelinePlanner` + `ExecutionPlan` (S28)
+- `ArtifactStore` avec hash multi-paramètres + persistance filesystem (S29)
+
+### Sprints S30-S34 — 5 OCR engines natifs (NO SHIM)
+- `TesseractAdapter` (S30)
+- `PeroOCRAdapter` (S31)
+- `MistralOCRAdapter` (S32)
+- `GoogleVisionAdapter` (S33)
+- `AzureDocIntelAdapter` (S34)
+
+Tous héritent directement de `BaseOCRAdapter` (S26), pas du legacy
+`BaseOCREngine`. Le legacy peut être supprimé une fois les confidences
+migrées vers `ConfidenceArtifact` (sprint dédié).
+
+### Sprints S35-S38 — Web app native (NO SHIM)
+- Skeleton FastAPI avec DI (`WebAppState`, `create_app`) — S35
+- Routers corpus + benchmark — S36
+- JobStore SQLite + jobs router — S37
+- UI Jinja2 + static + i18n FR/EN — S38
+
+### Sprints S39-S41 — Format YAML + domain cleanup
+- RunSpec étendu (`inputs_from`, `preferred_text_output`) — S39
+- `PipelineSpec` migré dans `domain/` — S40
+- `artifacts_index.jsonl` séparé — S41
+
+### Sprints S42-S43 — Reports CSV + JSON
+- `CsvReportRenderer` — S42
+- `JsonReportRenderer` — S43
+
+### Sprints S44-S45 — LLM/VLM nativement intégrés (NO SHIM)
+- Les 4 LLM adapters (Anthropic, OpenAI, Mistral, Ollama) ont désormais
+  un `execute()` natif compatible `StepExecutor` — S44
+- 4 VLM adapters dérivés via MRO multiple — S45
+
+## Critères pour la suppression future du legacy
+
+Pour chaque module legacy à supprimer, il faut :
+
+1. **Parité fonctionnelle** : tout ce que fait le legacy doit avoir un
+   équivalent dans le new world.
+2. **Migration des tests** : les tests legacy doivent soit migrer vers
+   le new world, soit être identifiés comme supprimables.
+3. **Migration des callers externes** : si des callers externes
+   importent depuis `picarones.web.app` (par ex. dans le HuggingFace
+   Space), ils doivent être migrés en amont.
+4. **Autorisation utilisateur explicite** : un commit qui supprime
+   ~4000 lignes de code en production exige une revue formelle.
+
+## Statistiques globales du rewrite (S1-S57)
+
+- **Tests** : ~4910 tests, 11 skipped, 0 failed au S46 (vs 4504 au
+  début du rewrite, S26).  Sprint S57 (audit #23) : la formulation
+  *« +406 nouveaux tests »* concernait spécifiquement les **nouveaux
+  tests écrits pour le new world** sur S27-S45 (`tests/{adapters,
+  pipeline,evaluation,reports_v2,app,interfaces}/`) ; elle ne dit
+  rien d'une supposée hausse de la couverture totale du repo.  Les
+  tests legacy (`tests/{web,cli,engines,measurements,...}/`) ont été
+  conservés intacts — la couverture nette du rewrite est donc
+  **additive**, pas substitutive.
+- **Lint** : `ruff check picarones/ tests/` clean.
+- **File budgets** (audit #25) : la règle interne *« tout fichier
+  ≥ 400 lignes est budgété »* est un garde-fou pragmatique, pas une
+  doctrine ; elle force à expliciter la justification lorsqu'un
+  module dépasse ce seuil (ex. `interfaces/web/app.py` ~480 lignes
+  — composé de routes/handlers/middlewares groupés par cohérence
+  fonctionnelle).  Aucun fichier ne dépasse 800 lignes après S46.
+- **Layer dependencies** : domain → formats → evaluation → pipeline
+  → adapters → app → reports_v2 → interfaces, vérifié par test
+  d'architecture.
+
+## Sprints d'audit/remédiation S47-S57 (audit institutional readiness)
+
+L'audit *institutional readiness 2026-05* a identifié 30 dettes
+techniques résiduelles après le rewrite ciblé.  Elles ont été
+adressées en 6 vagues (S47-S57) :
+
+| Vague | Sprint | Issues | Thème |
+|-------|--------|--------|-------|
+| pré-audit | S47-S48 | #1, #2 | ArtifactStore wired, JobRunner threading |
+| A | S49-S51 | #3-#7 | Web security middlewares, confidences sidecar, output paths |
+| B | S52-S53 | #8-#11 | AdapterStepError hierarchy, Mistral routing strict, normalize_llm_content path |
+| C | S54 | #6 | MRO guard `__init_subclass__` BaseVLMAdapter |
+| D | S55 | #14 | Live integration tests `tests/integration/live/` |
+| E | S56 | #12, #13, #17, #18, #19, #20, #22, #27, #28, #29 | JobStore schema_version, busy_timeout, model_dump(mode="json"), `_infer_pipeline_name`, etc. |
+| F | S57 | #15, #16, #21, #23, #24, #25, #26, #30 | i18n prompts FR/EN/LA, DeprecationWarning legacy spec.py, doc rectifications |
+
+**Tous les 30 issues sont adressés au S57**.  Les détails sont dans
+`docs/audits/remediation-plan-2026-05.md`.
+
+### Notes spécifiques (S57)
+
+- **#15 Lazy imports SDK tiers** : les imports `mistralai`, `anthropic`,
+  `openai`, `ollama` sont **intentionnellement à l'intérieur des
+  méthodes** (`MistralOCRAdapter._call_chat_vision_api`, etc.) plutôt
+  qu'au top du module.  Raison : ces SDK sont des dépendances
+  optionnelles (extras `[mistral]`, `[anthropic]`…) — un import top-level
+  ferait planter `import picarones` sur un environnement minimal.
+  Le coût (re-exécution de l'import à chaque appel) est négligé par
+  le cache d'imports Python.
+- **#16 i18n prompts FR/EN/LA** : `BaseLLMAdapter.DEFAULT_CORRECTION_PROMPTS`
+  et `BaseVLMAdapter.DEFAULT_TRANSCRIPTION_PROMPTS` sont des
+  `dict[str, str]` indexés par code langue.  Sélection : override
+  explicite via `config["correction_prompt"]`/`["transcription_prompt"]`
+  > `config["lang"]` (fr/en/la) > fallback FR.
+- **#26 Suppression du re-export `picarones.pipeline.spec`** : ce
+  module re-export orphelin (aucun caller interne ni legacy) a été
+  supprimé directement.  Le chemin canonique unique est
+  `picarones.domain.pipeline_spec`, re-exporté au niveau `__init__`
+  des packages `picarones.domain` et `picarones.pipeline` (API
+  publique standard).
+- **#30 Commit hygiene CER fix** : la modification du seuil de
+  régression CER en CI (de 0.10 à 0.20) est documentée dans le
+  CHANGELOG sous *« CER regression check threshold rationale »*
+  avec justification métier (corpus patrimoniaux ont des CER bruts
+  qui peuvent légitimement varier de 5-15 points selon le tirage de
+  validation).
+
+## Prochaines étapes possibles (post-rewrite)
+
+1. **Confidences typées** : créer un `ConfidenceArtifact` typé pour
+   réutiliser proprement les confidences exposées par chaque OCR
+   adapter, sans surcharger `BaseOCRAdapter.execute()`.
+2. **Vues HTML manquantes** : porter Pareto, Narrative, Glossary du
+   legacy `report/` vers `reports_v2/html/` une vue à la fois.
+3. **CLI complète** : porter les commandes manquantes (`history`,
+   `compare`, `pipeline`, `diagnose`, etc.) dans
+   `interfaces/cli/`.
+4. **Suppression effective du legacy** : après obtention de la
+   parité ci-dessus, retirer `picarones/{web,engines,pipelines,
+   report,cli}/` (en gardant `llm/` re-export pour compatibilité
+   historique).

docs/roadmap/rewrite-2026.md

@@ -0,0 +1,185 @@
+# Rewrite ciblé — plan S1 → S26
+
+> **Statut** — démarré au Sprint A14-S1 (mai 2026), livraison cible
+> **fin 2026** sur la branche `claude/repo-analysis-cukvm` puis fusion
+> sur `main` pour livraison BnF.
+>
+> **Doctrine** : pas de Big Rewrite. Pas non plus de migration douce
+> qui laisserait la dette en place. **Rewrite ciblé** : on réécrit
+> from scratch les zones cassées (~5–8 k lignes : runner d'orchestration,
+> couche web sécurité, gestion d'artefacts) et on **déplace** les zones
+> saines (~30–40 k lignes : calculs purs MUFI / philological /
+> statistics / etc.) sans toucher à leur logique.
+
+---
+
+## Pourquoi un rewrite ciblé ?
+
+Trois constats issus de l'audit (`docs/audits/`) et de la conversation
+de cadrage de mai 2026 :
+
+1. **Les promesses du README dépassaient la réalité du code.** Six bugs
+   P0 vérifiés dans l'audit invalidaient la promesse scientifique
+   (notamment : `normalization_profile` côté web silencieusement
+   ignoré, `compact()` qui amputait le JSON exporté, `compute_metrics`
+   qui retournait `0.0` indistinguable d'un score parfait en cas
+   d'erreur).
+2. **L'architecture à imports magiques.** `import picarones`
+   déclenche une chaîne d'imports par effet de bord qui charge le
+   registre de métriques. Une dépendance optionnelle manquante au fond
+   de la chaîne fait crasher l'import du package entier.
+3. **La dette narrative est trop lourde.** ~679 références à
+   "Sprint N" dans les fichiers Python, qui parasitent la lecture du
+   code par un nouveau contributeur et empêchent toute prise en main
+   par un mainteneur extérieur.
+
+Le rewrite ciblé attaque ces trois problèmes ensemble.
+
+---
+
+## Architecture cible
+
+À la fin du rewrite, l'arborescence Python sera :
+
+```
+picarones/
+  domain/            # Cercle 1 — types purs (Artifact, PipelineSpec,
+                     #   EvaluationSpec, DocumentRef, Provenance)
+  evaluation/        # Cercle 2 — vues, projecteurs, métriques
+    views/
+    projectors/
+    metrics/
+    registry.py
+  pipeline/          # Cercle 2 — exécution
+    executor.py
+    cache.py
+    spec.py
+  formats/           # Cercle 2 — ALTO, PAGE, normalisation texte
+    alto/
+    pagexml/
+    text/
+  adapters/          # Cercle 3 — moteurs OCR/LLM/VLM, importers, storage
+    ocr/
+    llm/
+    vlm/
+    corpus/
+    storage/
+  app/               # Cercle 4 — services applicatifs
+    services/
+    schemas/
+  interfaces/        # Cercle 5 — CLI, web, reports
+    cli/
+    web/
+  reports/
+    html/
+    json/
+    csv/
+```
+
+Pivot mental : l'objet central n'est plus `Engine + BenchmarkResult`,
+c'est `Pipeline → Artifacts → Projection → EvaluationView → Metrics`.
+
+---
+
+## Calendrier (26 semaines)
+
+### Phase 0 — Stabilisation de l'existant (S1 → S2)
+
+| Sprint | Objectif | État |
+|---|---|---|
+| **S1** | Boucher les 6 P0 sur `main` | ✅ Livré (commit `a2bea75`) |
+| **S2** | Recadrer le README, env propre, BACKLOG_POST_LIVRAISON | ⏳ En cours |
+
+À la fin de S2, l'outil actuel reste utilisable pour les tests BnF
+pendant que le rewrite avance sur `rewrite-2026`.
+
+### Phase 1 — Squelette et règles d'architecture (S3 → S6)
+
+| Sprint | Objectif |
+|---|---|
+| S3 | Créer les répertoires cibles + tests d'architecture qui interdisent le retour en arrière |
+| S4 | Modèle `Artifact` et types fondamentaux dans `domain/` |
+| S5 | `EvaluationView`, `EvaluationSpec`, `MetricSpec` typés |
+| S6 | `PipelineSpec`, `PipelineStep`, contrats d'exécution |
+
+Critère go/no-go fin de Phase 1 : les tests d'architecture passent,
+la BnF continue à utiliser `main`.
+
+### Phase 2 — Pipeline executor et migration des calculs (S7 → S12)
+
+| Sprint | Objectif |
+|---|---|
+| S7 | Pipeline executor v1 (séquentiel mono-document) |
+| S8 | Backpressure + timeout réel + annulation propre |
+| S9 | `formats/alto/` et `formats/pagexml/` |
+| S10 | Migration des calculs purs vers `evaluation/metrics/` (gros sprint) |
+| S11 | Migration des adapters dans `adapters/` |
+| S12 | Le nouvel executor reproduit l'ancien runner numériquement |
+
+Critère go/no-go fin de Phase 2 : équivalence CER/WER vérifiée à
+1e-9 près sur 5 fixtures + 1 corpus BnF réel.
+
+### Phase 3 — Vues d'évaluation (S13 → S18) — cœur de la valeur ajoutée
+
+| Sprint | Objectif |
+|---|---|
+| S13 | `EvaluationViewExecutor` et le moteur de vues |
+| S14 | `TextView` (vue canonique 1) |
+| S15 | `AltoView` (vue canonique 2) |
+| S16 | `SearchView` (vue canonique 3) + cohérence inter-vues |
+| S17 | Intégration runner + vues + nouveau format de résultat |
+| S18 | E2E sur le cas BnF central + recettage interne |
+
+Critère go/no-go fin de Phase 3 : ton cas d'usage central
+(Tesseract texte brut vs OCR+LLM+ALTO remappé vs VLM+ALTO reconstruit)
+fonctionne bout-en-bout, lisible, avec rapports de projection
+explicites.
+
+### Phase 4 — Web sandboxée + recettage (S19 → S24)
+
+| Sprint | Objectif |
+|---|---|
+| S19 | Couche `app/services/` |
+| S20 | Réécriture corpus upload + sandbox ZIP |
+| S21 | Nouveau `interfaces/web/` (CSRF on, CSP sans inline) |
+| S22 | `interfaces/cli/` + `reports/html/` migration |
+| S23 | Recettage BnF complet |
+| S24 | Corrections de recettage + documentation finale |
+
+### Buffer (S25 → S26)
+
+Imprévus + livraison. Ces deux semaines sont **non négociables**.
+
+---
+
+## Discipline du rewrite
+
+Quatre invariants permanents, valables pendant les 26 semaines :
+
+1. **`main` reste livrable.** Le rewrite vit sur `rewrite-2026` /
+   `claude/repo-analysis-cukvm`. Les P0 vont sur `main`.
+2. **Pas de feature nouvelle.** Si l'envie vient, écrire dans
+   [`BACKLOG_POST_LIVRAISON.md`](../../BACKLOG_POST_LIVRAISON.md) et
+   passer.
+3. **Fin de chaque sprint = un commit qui passe `pytest tests/ -q`.**
+4. **Chaque sprint a un livrable démontrable** en 5 minutes.
+
+Pour le détail à la semaine de chaque sprint (livrables, tests,
+définition de "done", risque principal), voir le plan complet livré
+en réponse à la question de cadrage du 2026-05-03 dans la session
+[`session_011XQZNitg1rCgia8ZD1a2hP`](https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP).
+
+---
+
+## Ce qui n'est *pas* dans le rewrite
+
+Cf. [`BACKLOG_POST_LIVRAISON.md`](../../BACKLOG_POST_LIVRAISON.md) pour
+la liste complète. En résumé :
+
+- Pas de feature nouvelle (NER cloud, VLM extras, etc.).
+- Pas de promesses institutionnelles (RGPD opérationnel, JOSS, COI
+  exercés).
+- Pas de réécriture des calculs purs (MUFI, philological, statistics)
+  — on les déplace, point.
+- Pas de refonte du rapport HTML au-delà de l'intégration des vues
+  (le rendu visuel reste celui d'aujourd'hui pour ne pas allonger).

docs/views/alto-view.md

@@ -0,0 +1,113 @@
+# AltoView — fidélité documentaire ALTO
+
+Sprint A14-S15 du rewrite ciblé livre `AltoView`, la deuxième vue
+canonique.  Elle répond à la question : **"quel pipeline produit
+le meilleur ALTO exploitable ?"**
+
+## Distinct de TextView
+
+| Aspect | TextView (S14) | AltoView (S15) |
+|---|---|---|
+| Question | "meilleur texte final ?" | "meilleur ALTO exploitable ?" |
+| Types acceptés | RAW_TEXT, CORRECTED_TEXT, ALTO, PAGE, CANONICAL | ALTO_XML uniquement |
+| Projection | tout → RAW_TEXT | aucune (compare ALTO direct) |
+| Mesure | qualité linguistique | fidélité structurelle |
+| Métriques | CER, WER, MER, WIL | alto_validity, line_count_ratio, word_box_coverage |
+
+Un même pipeline peut être évalué dans les deux vues.  Le rapport
+HTML (S22) présentera les deux côte-à-côte pour qu'un lecteur
+comprenne pourquoi deux pipelines avec le même CER peuvent
+produire des ALTO de qualités différentes.
+
+## Pattern d'omission explicite
+
+Un pipeline qui ne produit pas d'`ALTO_XML` (exemple : Tesseract
+texte brut sans ALTO) ne peut **pas** être évalué dans `AltoView`.
+Le caller (typiquement un service applicatif au S19) doit
+**omettre** ce pipeline du résultat, plutôt que de lui attribuer
+un score factice à 0.
+
+```python
+from picarones.evaluation.views import build_alto_view
+
+view = build_alto_view()
+
+pipelines = [
+    ("tesseract",       ArtifactType.RAW_TEXT),       # PAS d'ALTO
+    ("ocr_llm_alto",    ArtifactType.ALTO_XML),       # ALTO ✓
+    ("vlm_alto",        ArtifactType.ALTO_XML),       # ALTO ✓
+]
+
+eligible = [(n, t) for n, t in pipelines if view.accepts(t)]
+omitted  = [(n, t) for n, t in pipelines if not view.accepts(t)]
+
+# eligible: [("ocr_llm_alto", ALTO_XML), ("vlm_alto", ALTO_XML)]
+# omitted: [("tesseract", RAW_TEXT)]
+```
+
+Le caller affichera dans le rapport : *"Tesseract n'est pas
+évalué dans AltoView (ne produit pas d'ALTO)."*  Pas de score
+factice à 0 qui ferait passer Tesseract pour un mauvais ALTO,
+alors qu'il n'a juste pas pris part à la compétition.
+
+## Métriques par défaut
+
+### `alto_validity`
+
+L'hypothèse a-t-elle une structure ALTO cohérente ?  ≥ 1 page ET
+≥ 1 bloc ET ≥ 1 ligne.  Détecte les ALTO vides, tronqués, ou
+produits par un reconstructeur défaillant.
+
+- 1.0 = structure cohérente
+- 0.0 = vide ou tronqué
+
+### `alto_line_count_ratio`
+
+Ratio min/max du nombre de lignes : `min(n_hyp, n_ref) / max(n_hyp,
+n_ref)` ∈ [0, 1].  1.0 = même nombre de lignes.
+
+Permet de détecter un reconstructeur qui invente ou perd des
+lignes.  Ne dit rien sur l'**alignement spatial** — c'est
+`textline_alignment` (post-livraison) qui mesurera cette
+dimension.
+
+### `alto_word_box_coverage`
+
+Fraction des `AltoString` de l'hypothèse qui ont une `bbox`
+définie (HPOS, VPOS, WIDTH, HEIGHT).  1.0 = tous les mots ont
+une boîte (cas idéal pour un reconstructeur ALTO).
+
+Un VLM qui produit du markdown puis le reconstruit en ALTO sans
+coordonnées aura un `word_box_coverage` proche de 0.
+
+## Garde-fou méthodologique
+
+Le `ViewResult` produit par `AltoView` porte un `warnings`
+explicite :
+
+> Cette vue mesure la fidélité STRUCTURELLE de l'ALTO produit
+> (validité, nombre de lignes, bbox).  La qualité TEXTUELLE de
+> ce qui est dans cet ALTO est mesurée par TextView ; les deux
+> doivent être lues ensemble pour juger un pipeline.
+>
+> Les pipelines qui ne produisent pas d'ALTO sont OMIS de cette
+> vue.  Aucun score factice n'est attribué à un pipeline absent.
+
+## Limites assumées
+
+Reportées à des sprints suivants :
+
+- **`textline_alignment`** (IoU des bbox de lignes) — exige un
+  algorithme d'alignement bipartite par bbox.
+- **`reading_order_consistency`** (Kendall tau sur les IDs de
+  lignes) — exige un mapping ID → position.
+- **`layout_f1` (ICDAR 2015)** — déjà implémenté dans
+  `evaluation/metrics/layout.py` (migré au S10) sur des `Region`
+  génériques ; un wrapper ALTO peut être ajouté plus tard.
+
+## Statut
+
+- ✅ Sprint S15 — `AltoView` livré (3 métriques + pattern d'omission)
+- ⏳ Sprint S16 — `SearchView` (recherchabilité fuzzy)
+- ⏳ Sprint S17 — intégration runner + RunManifest
+- ⏳ Sprint S18 — tests E2E sur le cas BnF central

docs/views/comparing-views.md

@@ -0,0 +1,117 @@
+# Lire les 3 vues canoniques ensemble
+
+Sprint A14-S16 livre la troisième vue canonique du rewrite ciblé :
+`SearchView`.  Avec `TextView` (S14) et `AltoView` (S15), on a
+maintenant **trois lentilles complémentaires** pour évaluer un
+même pipeline.
+
+## Le tableau des 3 vues
+
+| Vue | Question | Métriques | Direction |
+|---|---|---|---|
+| **TextView** (S14) | Quel pipeline produit le meilleur **texte final** ? | CER, WER, MER, WIL | `lower_is_better` (erreurs) |
+| **AltoView** (S15) | Quel pipeline produit le meilleur **ALTO exploitable** ? | alto_validity, line_count_ratio, word_box_coverage | `higher_is_better` (qualité) |
+| **SearchView** (S16) | Quel pipeline maximise la **recherchabilité plein-texte** ? | searchability_recall, numerical_sequence_preservation | `higher_is_better` (rappel) |
+
+Aucune des trois vues ne dit toute la vérité sur un pipeline.
+**Ensemble, elles racontent l'histoire complète.**
+
+## Pourquoi les trois vues sont nécessaires
+
+Un même pipeline peut être **excellent dans une vue et médiocre
+dans une autre**.  C'est précisément ce qui rend la comparaison
+hétérogène utile pour la BnF — un seul score (CER global)
+masquerait des informations critiques.
+
+### Pattern 1 : CER excellent, recherchabilité numérique catastrophique
+
+Démontré dans le test
+`tests/evaluation/test_sprint_a14_s16_views_consistency.py::TestDivergencePattern::test_year_corruption_invisible_to_cer_visible_to_search` :
+
+- **GT** : *"Charte signée à Paris le 14 juillet 1789 en présence du roi"*
+- **Hypothèse** : *"Charte signée à Paris le 14 juillet 1798 en présence du roi"*
+
+Le LLM de post-correction a "amélioré" la date (1789 → 1798).
+Conséquences :
+
+| Vue | Métrique | Valeur | Lecture |
+|---|---|---|---|
+| TextView | CER | ~0.03 | Excellent (3 chars sur 58) |
+| TextView | WER | ~0.09 | Très bon (1 mot sur 11) |
+| SearchView | searchability_recall | ~0.91 | Bon (1798 fuzzy match 1789) |
+| SearchView | **numerical_sequence_preservation** | **0.0** | **Catastrophique** |
+
+Pour un historien qui veut indexer ses chartes par date, ce
+pipeline est **inutilisable** — l'année 1789 est silencieusement
+réécrite en 1798.  Le CER ne le révèle pas.  `SearchView` le
+révèle.
+
+### Pattern 2 : Texte parfait, ALTO inexistant
+
+Un OCR Tesseract qui ne produit que du texte brut :
+
+| Vue | Statut | Lecture |
+|---|---|---|
+| TextView | CER = 0.0 | Pipeline parfait pour la lecture |
+| SearchView | recall = 1.0 | Pipeline parfait pour l'indexation |
+| **AltoView** | **OMIS** | Pipeline non éligible |
+
+Pour un workflow IIIF / Mirador qui veut surligner les mots dans
+l'image, ce pipeline est **inutilisable** — pas de coordonnées.
+`AltoView` ne lui attribue pas un score factice à 0 ; le rapport
+affiche *"Tesseract texte brut n'est pas évalué dans AltoView
+(ne produit pas d'ALTO)"*.
+
+### Pattern 3 : ALTO valide mais texte hallucinant
+
+Un VLM avec module ALTO_reconstruction peut produire un ALTO
+structurellement parfait (validity=1, lignes correctes,
+coordonnées présentes) mais avec du texte inventé :
+
+| Vue | Métrique | Valeur | Lecture |
+|---|---|---|---|
+| AltoView | tous | 1.0 | Pipeline parfait structurellement |
+| TextView | CER | élevé | Pipeline mauvais textuellement |
+| SearchView | recall | bas | Pipeline inutile pour la recherche |
+
+`AltoView` seul ferait passer ce VLM pour le meilleur pipeline.
+Lire les trois vues ensemble révèle le vrai problème.
+
+## Recommandation de lecture pour le rapport BnF
+
+Le rapport HTML (S22) présentera les 3 vues côte-à-côte avec
+cette grille de lecture :
+
+1. **Tableau de synthèse** : un tableau par vue, chaque ligne =
+   un pipeline, chaque colonne = une métrique.  Les pipelines
+   omis sont indiqués explicitement (pas de valeur factice).
+
+2. **Encart "divergences notables"** : signale automatiquement
+   les pipelines dont le rang change fortement entre vues
+   (par exemple "rang 1 en TextView, rang 5 en SearchView").
+   C'est un signal pour l'utilisateur d'aller regarder en
+   détail ce qui se passe.
+
+3. **Pour chaque vue** : warnings explicites de ce qu'elle
+   **n'évalue pas** (cf. `ignored_dimensions` dans chaque
+   `ViewResult`).  L'utilisateur ne peut pas conclure
+   "TextView dit que X est le meilleur" sans avoir vu ce que
+   `TextView.ignored_dimensions` ne dit PAS.
+
+## Critères de choix selon l'usage
+
+| Usage cible | Vue principale | Vues secondaires |
+|---|---|---|
+| Lecture humaine (édition critique) | TextView | AltoView (si édition diplomatique) |
+| Indexation Elastic / Solr / Gallica | SearchView | TextView |
+| Réinjection IIIF / Mirador (mots cliquables) | AltoView | TextView |
+| Citation académique | TextView + SearchView | AltoView |
+| Reproduction d'un fac-similé | AltoView | TextView |
+
+## Statut
+
+- ✅ Sprint S14 — `TextView`
+- ✅ Sprint S15 — `AltoView`
+- ✅ Sprint S16 — `SearchView` + cohérence inter-vues
+- ⏳ Sprint S17 — intégration runner + RunManifest
+- ⏳ Sprint S18 — tests E2E sur le cas BnF central

docs/views/text-view.md

@@ -0,0 +1,144 @@
+# TextView — première vue canonique
+
+Sprint A14-S14 du rewrite ciblé livre `TextView`, la première vue
+d'évaluation canonique.  Elle répond à la question patrimoniale la
+plus fréquente : **"quel pipeline produit le meilleur texte
+final ?"**
+
+## Cas d'usage central BnF
+
+Une bibliothèque numérique veut comparer 3 pipelines hétérogènes
+sur le même corpus :
+
+1. **Tesseract** → texte brut (`RAW_TEXT`)
+2. **OCR + LLM + remapping ALTO** → ALTO XML enrichi (`ALTO_XML`)
+3. **VLM avec sortie markdown structurée** → `CANONICAL_DOCUMENT`
+
+Sans `TextView`, comparer ces 3 pipelines est trompeur : ils ne
+produisent pas le même type d'artefact.  Avec `TextView`, chaque
+sortie est **projetée vers du texte plat** avant calcul de
+CER/WER, et le rapport documente explicitement ce que la vue
+**ignore** (géométrie, structure de blocs, ordre de lecture, IDs,
+formatage).
+
+## API
+
+```python
+from picarones.evaluation.views import build_text_view
+
+# Vue canonique avec valeurs par défaut
+view = build_text_view()
+
+# Vue spécialisée (par exemple : OCR seul, sans ALTO/PAGE)
+from picarones.domain import ArtifactType
+view_ocr_only = build_text_view(
+    candidate_types=frozenset({
+        ArtifactType.RAW_TEXT,
+        ArtifactType.CORRECTED_TEXT,
+    }),
+    metric_names=("cer", "wer"),
+    normalization_profile="medieval_french",
+)
+```
+
+## Types acceptés (par défaut)
+
+| Type | Projection | Justification |
+|---|---|---|
+| `RAW_TEXT` | identité | déjà du texte |
+| `CORRECTED_TEXT` | identité | déjà du texte (modifié par un LLM) |
+| `ALTO_XML` | `AltoToText` | extraction par ordre de lecture, gestion césure |
+| `PAGE_XML` | `PageToText` | extraction depuis `<TextEquiv><Unicode>` |
+| `CANONICAL_DOCUMENT` | `CanonicalToText` | décode markdown, aplatit JSON canonique |
+
+## Métriques (par défaut)
+
+`cer`, `wer`, `mer`, `wil` — toutes typées `(RAW_TEXT, RAW_TEXT)`
+puisque la comparaison se fait toujours après projection vers
+texte plat.
+
+## Dimensions explicitement ignorées
+
+Le `ViewResult` propage dans `ignored_dimensions` les dimensions
+que cette vue **ne mesure pas** :
+
+- `geometry` — coordonnées HPOS/VPOS/WIDTH/HEIGHT des mots
+- `block_structure` — découpage en `TextBlock` / `TextRegion`
+- `reading_order` — ordre de lecture spatial
+- `ids` — identifiants stables des éléments
+- `confidence` — scores de confiance par mot
+- `formatting` — gras / italique / titre
+
+Ces dimensions sont éventuellement évaluées par d'autres vues :
+
+- `geometry`, `block_structure`, `reading_order`, `ids` →
+  **`AltoView`** (S15)
+- `confidence` → vue calibration (existante via S5 metrics)
+
+## Garde-fou méthodologique
+
+Chaque `ViewResult` produit par `TextView` porte un `warnings`
+explicite :
+
+> Cette vue compare les sorties textuelles finales après
+> projection éventuelle.  Les pipelines qui produisent
+> ALTO/PAGE/markdown sont projetés vers du texte plat — leurs
+> structures spatiale et documentaire ne sont PAS évaluées ici.
+> Pour évaluer la qualité ALTO, voir AltoView (S15).
+
+Ce warning sera affiché en tête du bloc TextView dans le rapport
+HTML (S22) pour signaler à un lecteur exactement la portée de la
+comparaison.
+
+## Exemple de `ViewResult`
+
+```python
+ViewResult(
+    view_name="text_final",
+    candidate_artifact_id="bnf_doc:vlm:canonical_document",
+    ground_truth_artifact_id="bnf_doc:gt:raw_text",
+    metric_values={
+        "cer": 0.04,
+        "wer": 0.12,
+        "mer": 0.04,
+        "wil": 0.18,
+    },
+    failed_metrics={},
+    projection_report=ProjectionReport(
+        source_artifact_id="bnf_doc:vlm:canonical_document",
+        source_type=ArtifactType.CANONICAL_DOCUMENT,
+        target_type=ArtifactType.RAW_TEXT,
+        projector_name="canonical_to_text",
+        lossy=True,
+        ignored_dimensions=("structure", "formatting", "headers", "links"),
+        warnings=("Markdown / JSON canonique projeté en texte plat...",),
+    ),
+    warnings=(
+        "Cette vue compare les sorties textuelles finales...",
+        "Markdown / JSON canonique projeté en texte plat...",
+    ),
+    ignored_dimensions=(
+        "geometry", "block_structure", "reading_order", "ids",
+        "confidence", "formatting", "structure", "headers", "links",
+    ),
+)
+```
+
+## Limites assumées
+
+- **Pas de comparaison fuzzy / search recall** — c'est `SearchView`
+  (S16).
+- **Pas d'évaluation structurelle ALTO** — c'est `AltoView` (S15).
+- **`CANONICAL_DOCUMENT` peut perdre beaucoup de structure** ; le
+  warning du `ProjectionReport` le signale.
+- **Pas de pondération inter-pipelines** — chaque pipeline est
+  évalué indépendamment ; le ranking et l'agrégation sont la
+  responsabilité du caller (typiquement le rapport HTML S22).
+
+## Statut
+
+- ✅ Sprint S14 — `TextView` livré (codé + testé)
+- ⏳ Sprint S15 — `AltoView` (fidélité documentaire)
+- ⏳ Sprint S16 — `SearchView` (recherchabilité fuzzy)
+- ⏳ Sprint S17 — intégration runner + RunManifest
+- ⏳ Sprint S18 — tests E2E sur le cas BnF central avec 3 pipelines

picarones/adapters/__init__.py

@@ -0,0 +1,28 @@
+"""Cercle 3 — Adapters.
+
+Implémentations concrètes des contrats du domain.  C'est ici que
+vivent les dépendances externes lourdes (pytesseract, pero_ocr,
+mistralai, openai, anthropic, google-cloud-vision, datasets, etc.).
+
+Sous-packages :
+
+- ``ocr/`` — Tesseract, Pero OCR, Kraken, Mistral OCR, Google
+  Vision, Azure Doc Intel.  Cible Sprint S11.
+- ``llm/`` — OpenAI, Anthropic, Mistral, Ollama.  Cible S11.
+- ``vlm/`` — Qwen-VL, Gemini, Claude vision, etc.  À remplir
+  post-livraison (dans la limite de ce qui justifie une vraie
+  comparaison avec OCR+LLM).
+- ``corpus/`` — local folder, IIIF, Gallica, HTR-United,
+  HuggingFace Datasets, eScriptorium.  Cible S11.
+- ``storage/`` — filesystem, SQLite (jobs, history).  Cible S20.
+
+Règles d'import : un adapter peut importer le domain et ses libs
+externes.  Il ne doit **jamais** importer ``app/`` ou
+``interfaces/``.  Il n'a aucune logique d'évaluation (un OCR
+adapter ne calcule pas le CER — il produit un artefact texte que
+``evaluation/`` consommera).
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

picarones/adapters/_retry.py

@@ -0,0 +1,143 @@
+"""Retry exponentiel partagé par les adapters cloud (OCR + LLM).
+
+Pour une release institutionnelle (BnF, LoC, BL), un benchmark de
+N milliers de documents face à un service cloud (Google Vision,
+Azure Document Intelligence, Mistral OCR, Anthropic, OpenAI) doit
+absorber les erreurs transitoires (429, 5xx, timeout réseau) sans
+faire échouer le doc — sinon les résultats partiels ne sont pas
+reproductibles d'un run à l'autre.
+
+Ce module fournit la politique commune.  Il vit au top du package
+``adapters/`` (et non sous ``llm/`` ou ``ocr/``) parce qu'il est
+consommé par les deux familles indistinctement.
+
+API
+---
+- ``is_retryable(exc)`` : True si l'exception est typique d'un
+  problème transitoire.
+- ``call_with_retry(callable, max_retries, backoff_base, label)`` :
+  exécute le callable, retry exponentiel jusqu'à ``max_retries``
+  tentatives.  Lève la dernière exception si épuisé.
+
+Politique
+---------
+- ``max_retries=3`` (4 tentatives au total : 0 + 1 + 2 + 3 retries).
+- ``backoff_base=2.0`` → 2s, 4s, 8s entre les retries (16s cumul max).
+- Logs WARNING à chaque retry avec contexte.
+
+Anti-sur-ingénierie
+-------------------
+- Pas de jitter randomisé : pas indispensable à ce volume ; ajouter
+  si un caller en a concrètement besoin.
+- Pas de circuit breaker : un caller qui voit 100 % d'échec sur 5000
+  documents arrête le run lui-même.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Callable, TypeVar
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_BACKOFF_BASE = 2.0  # secondes : 2, 4, 8
+
+T = TypeVar("T")
+
+
+def is_retryable(exc: Exception) -> bool:
+    """``True`` si l'exception est typique d'un problème transitoire.
+
+    Détection sur trois axes :
+
+    1. Code HTTP exposé par les SDK cloud (``status_code`` ou
+       ``http_status``) : 429 (rate limit) et tout 5xx.
+    2. Type d'exception réseau : ``TimeoutError``, ``ConnectionError``,
+       ``URLError`` (urllib).
+    3. Heuristique sur le message (fallback pour les SDK qui ne
+       structurent pas) : présence des codes 429/502/503 ou des
+       motifs ``rate limit``, ``timeout``, ``connection``.
+    """
+    status = (
+        getattr(exc, "status_code", None)
+        or getattr(exc, "http_status", None)
+    )
+    if status is not None:
+        return status == 429 or status >= 500
+
+    exc_name = type(exc).__name__
+    if exc_name in ("TimeoutError", "ConnectionError", "URLError"):
+        return True
+
+    msg = str(exc).lower()
+    if "rate" in msg and "limit" in msg:
+        return True
+    if "timeout" in msg or "connection" in msg:
+        return True
+    if "429" in msg or "503" in msg or "502" in msg:
+        return True
+
+    return False
+
+
+def call_with_retry(
+    fn: Callable[[], T],
+    *,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+    backoff_base: float = DEFAULT_BACKOFF_BASE,
+    label: str = "adapter",
+) -> T:
+    """Exécute ``fn`` avec retry exponentiel sur erreurs retryables.
+
+    Parameters
+    ----------
+    fn:
+        Callable sans argument qui retourne le résultat ou lève.
+    max_retries:
+        Nombre de retries après la première tentative.  ``0`` =
+        une seule tentative (pas de retry).
+    backoff_base:
+        Base de l'attente exponentielle.  Tentative ``i`` → attente
+        ``backoff_base ** (i + 1)`` secondes avant retry.
+    label:
+        Étiquette du caller pour le logging (typiquement
+        ``self.name`` de l'adapter).
+
+    Returns
+    -------
+    Résultat de ``fn``.
+
+    Raises
+    ------
+    Exception
+        La dernière exception levée si tous les retries sont
+        épuisés ou si l'erreur n'est pas retryable.
+    """
+    last_exc: Exception | None = None
+    for attempt in range(max_retries + 1):
+        try:
+            return fn()
+        except Exception as exc:  # noqa: BLE001
+            last_exc = exc
+            if attempt < max_retries and is_retryable(exc):
+                wait = backoff_base ** (attempt + 1)
+                logger.warning(
+                    "[%s] erreur retryable (tentative %d/%d, "
+                    "attente %.1fs) : %s",
+                    label, attempt + 1, max_retries + 1, wait, exc,
+                )
+                time.sleep(wait)
+            else:
+                break
+    assert last_exc is not None
+    raise last_exc
+
+
+__all__ = [
+    "DEFAULT_BACKOFF_BASE",
+    "DEFAULT_MAX_RETRIES",
+    "call_with_retry",
+    "is_retryable",
+]

picarones/adapters/corpus/__init__.py

@@ -0,0 +1,16 @@
+"""Adaptateurs corpus — Sprint S11.
+
+Cible : déplacement de ``picarones.extras.importers.{iiif,gallica,
+htr_united,huggingface,escriptorium}``.  Un corpus adapter charge
+un corpus depuis une source distante (manifeste IIIF, dataset HF,
+catalogue HTR-United, eScriptorium, ZIP utilisateur) et retourne
+un ``CorpusSpec`` (références aux images + GT par niveau).
+
+Règle : pas de pré-calcul.  Pas d'OCR.  Le corpus adapter ne sait
+que **nommer et localiser** les paires (image, GT).  L'exécution
+des moteurs est faite plus tard par le pipeline executor.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

picarones/adapters/corpus/_fallback_log.py

@@ -0,0 +1,98 @@
+"""Journal en mémoire des fallbacks d'importer (Sprint A3, item B-3).
+
+Quand un importer (HuggingFace, HTR-United, Gallica, eScriptorium…)
+bascule en mode dégradé (timeout réseau, JSON mal formé, ZIP corrompu,
+catalogue distant indisponible…), il enregistre un incident ici via
+:func:`record_fallback`. Le moteur narratif consomme ces incidents via
+:func:`consume_fallback_log`, qui **vide** la liste pour qu'un benchmark
+suivant ne remonte pas les incidents du précédent.
+
+Conception volontairement minimale :
+
+- Pas de persistance disque (les incidents sont contextuels à un run).
+- Pas de structure complexe (juste un ``list[dict]`` thread-safe).
+- Le runner / le rapport peuvent ignorer la liste sans casser.
+
+Le détecteur de Fact correspondant (``FactType.IMPORTER_FALLBACK_TRIGGERED``)
+est implémenté dans
+:mod:`picarones.measurements.narrative.detectors.history`.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_lock = threading.Lock()
+_fallbacks: list[dict[str, Any]] = []
+
+
+def record_fallback(
+    importer: str,
+    operation: str,
+    error: BaseException | None = None,
+    *,
+    extra: dict[str, Any] | None = None,
+) -> None:
+    """Enregistre un incident de mode dégradé.
+
+    Logge également via ``logger.warning`` pour qu'un opérateur voit
+    l'incident en temps réel sans dépendre du rapport.
+
+    Parameters
+    ----------
+    importer:
+        Nom court de l'importer (ex : ``"huggingface"``, ``"htr_united"``).
+    operation:
+        Description courte de l'opération (ex : ``"yaml_catalogue_parse"``,
+        ``"image_save"``, ``"hub_search"``).
+    error:
+        Exception originelle (utilisée pour le message log et stockée dans
+        le payload sous forme de chaîne — pas l'objet, pour éviter les
+        références persistantes).
+    extra:
+        Champs additionnels (URL distante, identifiant dataset…) qui peuvent
+        être utiles à un détecteur de Fact ultérieur.
+    """
+    error_repr = repr(error) if error is not None else None
+    logger.warning(
+        "[importers/%s] %s a échoué (mode dégradé) : %s",
+        importer,
+        operation,
+        error_repr,
+    )
+    entry: dict[str, Any] = {
+        "importer": importer,
+        "operation": operation,
+        "error": error_repr,
+    }
+    if extra:
+        entry["extra"] = dict(extra)
+    with _lock:
+        _fallbacks.append(entry)
+
+
+def consume_fallback_log() -> list[dict[str, Any]]:
+    """Retourne ET vide la liste des incidents accumulés.
+
+    Le moteur narratif appelle cette fonction au moment de construire
+    la synthèse pour transformer chaque incident en ``Fact``."""
+    with _lock:
+        out = list(_fallbacks)
+        _fallbacks.clear()
+    return out
+
+
+def peek_fallback_log() -> list[dict[str, Any]]:
+    """Retourne une copie sans vider — utile pour les tests."""
+    with _lock:
+        return list(_fallbacks)
+
+
+def reset_fallback_log() -> None:
+    """Vide la liste sans rien retourner — utile pour les fixtures pytest."""
+    with _lock:
+        _fallbacks.clear()

picarones/adapters/corpus/htr_united.py

@@ -0,0 +1,473 @@
+"""Import depuis le catalogue HTR-United.
+
+HTR-United est un catalogue communautaire de vérités terrain HTR/OCR publiées
+sur GitHub sous licence ouverte. Les métadonnées sont stockées dans un fichier
+YAML (catalogue.yml) sur https://github.com/HTR-United/htr-united.
+
+Ce module fournit :
+- :class:`HTRUnitedCatalogue` — chargement et recherche dans le catalogue
+- :func:`fetch_catalogue` — téléchargement du catalogue depuis GitHub
+- :func:`import_htr_united_corpus` — téléchargement et import d'un corpus
+
+Exemple
+-------
+    catalogue = HTRUnitedCatalogue.from_remote()
+    results = catalogue.search("français médiéval")
+    corpus = import_htr_united_corpus(results[0], output_dir="./corpus/")
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Catalogue remote URL
+# ---------------------------------------------------------------------------
+
+_CATALOGUE_URL = (
+    "https://raw.githubusercontent.com/HTR-United/htr-united/master/htr-united.yml"
+)
+_CATALOGUE_API_URL = (
+    "https://api.github.com/repos/HTR-United/htr-united/contents/htr-united.yml"
+)
+
+# Catalogue de démonstration / fallback (hors-ligne)
+_DEMO_CATALOGUE: list[dict] = [
+    {
+        "id": "lectaurep-repertoires",
+        "title": "Lectaurep — Répertoires de notaires parisiens",
+        "url": "https://github.com/HTR-United/lectaurep-repertoires",
+        "language": ["French"],
+        "script": ["Cursiva"],
+        "century": [17, 18],
+        "institution": "Archives nationales (France)",
+        "description": "Transcriptions de répertoires de notaires, XVIIe-XVIIIe siècles.",
+        "license": "CC-BY 4.0",
+        "lines": 12400,
+        "format": "ALTO",
+        "tags": ["notaires", "Paris", "cursive", "imprimé"],
+    },
+    {
+        "id": "bvmm-manuscripts",
+        "title": "BVMM — Manuscrits enluminés",
+        "url": "https://github.com/HTR-United/bvmm-manuscripts",
+        "language": ["Latin", "French"],
+        "script": ["Gothic"],
+        "century": [13, 14, 15],
+        "institution": "IRHT",
+        "description": "Manuscrits médiévaux latins et français, XIIIe-XVe siècles.",
+        "license": "CC-BY 4.0",
+        "lines": 8700,
+        "format": "ALTO",
+        "tags": ["manuscrits", "latin", "médiéval", "enluminure"],
+    },
+    {
+        "id": "cremma-medieval",
+        "title": "CREMMA Médiéval",
+        "url": "https://github.com/HTR-United/cremma-medieval",
+        "language": ["French", "Latin"],
+        "script": ["Gothic", "Humanistica"],
+        "century": [12, 13, 14, 15],
+        "institution": "École des chartes / Inria",
+        "description": "Corpus CREMMA de manuscrits médiévaux français et latins.",
+        "license": "CC-BY 4.0",
+        "lines": 6200,
+        "format": "ALTO",
+        "tags": ["médiéval", "chartes", "manuscrits"],
+    },
+    {
+        "id": "simssa-ocr-printed",
+        "title": "SIMSSA — Imprimés anciens (XVe-XVIIe)",
+        "url": "https://github.com/HTR-United/simssa-printed",
+        "language": ["French", "Latin"],
+        "script": ["Rotunda", "Roman"],
+        "century": [15, 16, 17],
+        "institution": "McGill University",
+        "description": "Corpus d'imprimés anciens romains et gothiques.",
+        "license": "CC-BY 4.0",
+        "lines": 4500,
+        "format": "PAGE",
+        "tags": ["imprimés", "incunables", "roman", "gothique"],
+    },
+    {
+        "id": "fonds-gallica-presse",
+        "title": "Presse ancienne — Gallica (XIXe)",
+        "url": "https://github.com/HTR-United/gallica-presse-xix",
+        "language": ["French"],
+        "script": ["Roman"],
+        "century": [19],
+        "institution": "Gallica",
+        "description": "Numérisations de journaux du XIXe siècle (Gallica).",
+        "license": "etalab-2.0",
+        "lines": 31000,
+        "format": "ALTO",
+        "tags": ["presse", "XIXe", "Gallica", "journaux"],
+    },
+    {
+        "id": "archives-departem-correspondances",
+        "title": "Correspondances administratives (XVIIIe-XIXe)",
+        "url": "https://github.com/HTR-United/correspondances-admin",
+        "language": ["French"],
+        "script": ["Cursiva"],
+        "century": [18, 19],
+        "institution": "Archives départementales",
+        "description": "Lettres et correspondances administratives manuscrites.",
+        "license": "CC-BY 4.0",
+        "lines": 9800,
+        "format": "ALTO",
+        "tags": ["correspondances", "administratif", "cursive"],
+    },
+    {
+        "id": "e-codices-latin",
+        "title": "e-codices — Manuscrits latins (Suisse)",
+        "url": "https://github.com/HTR-United/e-codices-latin",
+        "language": ["Latin"],
+        "script": ["Caroline", "Gothic"],
+        "century": [9, 10, 11, 12],
+        "institution": "Bibliothèque cantonale universitaire de Lausanne",
+        "description": "Manuscrits carolingiens et gothiques des bibliothèques suisses.",
+        "license": "CC-BY 4.0",
+        "lines": 3100,
+        "format": "ALTO",
+        "tags": ["caroline", "latin", "médiéval", "Suisse"],
+    },
+    {
+        "id": "registres-paroissiaux-17",
+        "title": "Registres paroissiaux — Bretagne (XVIIe)",
+        "url": "https://github.com/HTR-United/registres-paroissiaux-bretagne",
+        "language": ["French", "Latin"],
+        "script": ["Cursiva"],
+        "century": [17],
+        "institution": "Archives départementales du Finistère",
+        "description": "Registres paroissiaux bretons du XVIIe siècle.",
+        "license": "CC-BY 4.0",
+        "lines": 15600,
+        "format": "ALTO",
+        "tags": ["registres", "Bretagne", "paroissial", "cursive"],
+    },
+]
+
+
+# ---------------------------------------------------------------------------
+# Dataclass entrée catalogue
+# ---------------------------------------------------------------------------
+
+@dataclass
+class HTRUnitedEntry:
+    """Une entrée dans le catalogue HTR-United."""
+
+    id: str
+    title: str
+    url: str
+    language: list[str] = field(default_factory=list)
+    script: list[str] = field(default_factory=list)
+    century: list[int] = field(default_factory=list)
+    institution: str = ""
+    description: str = ""
+    license: str = ""
+    lines: int = 0
+    format: str = "ALTO"
+    tags: list[str] = field(default_factory=list)
+
+    def as_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "url": self.url,
+            "language": self.language,
+            "script": self.script,
+            "century": self.century,
+            "institution": self.institution,
+            "description": self.description,
+            "license": self.license,
+            "lines": self.lines,
+            "format": self.format,
+            "tags": self.tags,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "HTRUnitedEntry":
+        return cls(
+            id=d.get("id", ""),
+            title=d.get("title", ""),
+            url=d.get("url", ""),
+            language=d.get("language", []),
+            script=d.get("script", []),
+            century=d.get("century", []),
+            institution=d.get("institution", ""),
+            description=d.get("description", ""),
+            license=d.get("license", ""),
+            lines=d.get("lines", 0),
+            format=d.get("format", "ALTO"),
+            tags=d.get("tags", []),
+        )
+
+    @property
+    def century_str(self) -> str:
+        """Siècles formatés en chiffres romains."""
+        roman = {
+            1: "Ier", 2: "IIe", 3: "IIIe", 4: "IVe", 5: "Ve",
+            6: "VIe", 7: "VIIe", 8: "VIIIe", 9: "IXe", 10: "Xe",
+            11: "XIe", 12: "XIIe", 13: "XIIIe", 14: "XIVe", 15: "XVe",
+            16: "XVIe", 17: "XVIIe", 18: "XVIIIe", 19: "XIXe", 20: "XXe",
+        }
+        return ", ".join(roman.get(c, f"{c}e") for c in self.century)
+
+
+# ---------------------------------------------------------------------------
+# Catalogue
+# ---------------------------------------------------------------------------
+
+class HTRUnitedCatalogue:
+    """Catalogue HTR-United avec recherche et filtrage."""
+
+    def __init__(self, entries: list[HTRUnitedEntry], source: str = "demo") -> None:
+        self.entries = entries
+        self.source = source  # "remote" | "demo" | "cache"
+
+    def __len__(self) -> int:
+        return len(self.entries)
+
+    @classmethod
+    def from_demo(cls) -> "HTRUnitedCatalogue":
+        """Charge le catalogue de démonstration intégré."""
+        entries = [HTRUnitedEntry.from_dict(d) for d in _DEMO_CATALOGUE]
+        return cls(entries, source="demo")
+
+    @classmethod
+    def from_remote(cls, timeout: int = 10) -> "HTRUnitedCatalogue":
+        """Télécharge le catalogue depuis GitHub.
+
+        En cas d'erreur réseau, retourne le catalogue de démonstration.
+        """
+        try:
+            req = urllib.request.Request(
+                _CATALOGUE_URL,
+                headers={"User-Agent": "picarones-htr-united-importer/1.0"},
+            )
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                raw = resp.read().decode("utf-8")
+            entries = _parse_yml_catalogue(raw)
+            return cls(entries, source="remote")
+        except (urllib.error.URLError, Exception) as exc:
+            # Fallback démo avec avertissement
+            logger.warning(
+                "[HTR-United] impossible de charger le catalogue distant (%s) : %s. "
+                "Utilisation des données de démonstration.",
+                _CATALOGUE_URL, exc,
+            )
+            return cls.from_demo()
+
+    def search(
+        self,
+        query: str = "",
+        language: Optional[str] = None,
+        script: Optional[str] = None,
+        century_min: Optional[int] = None,
+        century_max: Optional[int] = None,
+    ) -> list[HTRUnitedEntry]:
+        """Recherche dans le catalogue avec filtres optionnels."""
+        results = self.entries
+
+        if query:
+            q = query.lower()
+            results = [
+                e for e in results
+                if (q in e.title.lower()
+                    or q in e.description.lower()
+                    or q in e.institution.lower()
+                    or any(q in t.lower() for t in e.tags)
+                    or any(q in lang.lower() for lang in e.language))
+            ]
+
+        if language:
+            lang_lower = language.lower()
+            results = [
+                e for e in results
+                if any(lang_lower in lg.lower() for lg in e.language)
+            ]
+
+        if script:
+            sc_lower = script.lower()
+            results = [
+                e for e in results
+                if any(sc_lower in s.lower() for s in e.script)
+            ]
+
+        if century_min is not None:
+            results = [
+                e for e in results
+                if any(c >= century_min for c in e.century)
+            ]
+
+        if century_max is not None:
+            results = [
+                e for e in results
+                if any(c <= century_max for c in e.century)
+            ]
+
+        return results
+
+    def get_by_id(self, entry_id: str) -> Optional[HTRUnitedEntry]:
+        """Retourne une entrée par son identifiant."""
+        for e in self.entries:
+            if e.id == entry_id:
+                return e
+        return None
+
+    def available_languages(self) -> list[str]:
+        seen: set[str] = set()
+        result: list[str] = []
+        for e in self.entries:
+            for lang in e.language:
+                if lang not in seen:
+                    seen.add(lang)
+                    result.append(lang)
+        return sorted(result)
+
+    def available_scripts(self) -> list[str]:
+        seen: set[str] = set()
+        result: list[str] = []
+        for e in self.entries:
+            for sc in e.script:
+                if sc not in seen:
+                    seen.add(sc)
+                    result.append(sc)
+        return sorted(result)
+
+
+# ---------------------------------------------------------------------------
+# Import de corpus
+# ---------------------------------------------------------------------------
+
+def import_htr_united_corpus(
+    entry: HTRUnitedEntry,
+    output_dir: str | Path,
+    max_samples: int = 100,
+    show_progress: bool = True,
+) -> dict:
+    """Importe un corpus HTR-United dans un dossier local.
+
+    Retourne un dict avec les métadonnées de l'import.
+    Note : en l'absence d'accès réseau au dépôt GitHub, génère des fichiers
+    placeholder (pour tests et démo).
+    """
+    output_path = Path(output_dir)
+    output_path.mkdir(parents=True, exist_ok=True)
+
+    # Sauvegarder les métadonnées
+    meta = {
+        "source": "htr-united",
+        "entry_id": entry.id,
+        "title": entry.title,
+        "url": entry.url,
+        "language": entry.language,
+        "script": entry.script,
+        "century": entry.century,
+        "institution": entry.institution,
+        "license": entry.license,
+        "format": entry.format,
+        "imported_at": _iso_now(),
+    }
+    (output_path / "htr_united_meta.json").write_text(
+        json.dumps(meta, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+
+    # Essai de téléchargement réel depuis GitHub (archive releases)
+    downloaded = _try_download_corpus(entry, output_path, max_samples, show_progress)
+
+    return {
+        "entry_id": entry.id,
+        "title": entry.title,
+        "output_dir": str(output_path),
+        "files_imported": downloaded,
+        "metadata_file": str(output_path / "htr_united_meta.json"),
+    }
+
+
+def _try_download_corpus(
+    entry: HTRUnitedEntry,
+    output_path: Path,
+    max_samples: int,
+    show_progress: bool,
+) -> int:
+    """Tente de télécharger le corpus depuis GitHub. Retourne le nombre de fichiers importés."""
+    # Construit l'URL de l'archive ZIP du dépôt GitHub
+    repo_path = _extract_github_repo(entry.url)
+    if not repo_path:
+        return 0
+
+    zip_url = f"https://github.com/{repo_path}/archive/refs/heads/main.zip"
+    try:
+        req = urllib.request.Request(
+            zip_url,
+            headers={"User-Agent": "picarones-htr-united-importer/1.0"},
+        )
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            import io
+            import zipfile
+
+            data = resp.read()
+            with zipfile.ZipFile(io.BytesIO(data)) as zf:
+                # Extraire les fichiers ALTO/PAGE/GT
+                gt_files = [
+                    n for n in zf.namelist()
+                    if n.endswith((".alto.xml", ".page.xml", ".gt.txt", ".xml"))
+                    and not n.endswith("/")
+                ][:max_samples]
+                for i, fname in enumerate(gt_files):
+                    dest = output_path / Path(fname).name
+                    dest.write_bytes(zf.read(fname))
+                return len(gt_files)
+    except Exception as exc:  # noqa: BLE001 — large surface (réseau, ZIP, FS)
+        # Sprint A3 (B-3) : on documente l'incident plutôt que de le
+        # masquer ; le caller reçoit toujours 0 pour préserver le
+        # contrat numérique de retour.
+        from picarones.adapters.corpus._fallback_log import record_fallback
+        record_fallback(
+            importer="htr_united",
+            operation="download_zip_samples",
+            error=exc,
+            extra={"output_path": str(output_path)},
+        )
+        return 0
+
+
+def _extract_github_repo(url: str) -> Optional[str]:
+    """Extrait 'owner/repo' depuis une URL GitHub."""
+    m = re.match(r"https?://github\.com/([^/]+/[^/]+?)(?:\.git)?/?$", url)
+    return m.group(1) if m else None
+
+
+def _parse_yml_catalogue(raw: str) -> list[HTRUnitedEntry]:
+    """Parse rudimentaire du YAML catalogue HTR-United."""
+    try:
+        import yaml
+        data = yaml.safe_load(raw)
+        if isinstance(data, list):
+            return [HTRUnitedEntry.from_dict(d) for d in data if isinstance(d, dict)]
+    except Exception as exc:  # noqa: BLE001 — yaml + parsing user-supplied
+        # Sprint A3 (B-3) : un YAML mal formé bascule en mode démo
+        # sans que l'utilisateur en soit averti — on logge et on émet
+        # un Fact pour que la synthèse du rapport mentionne l'incident.
+        from picarones.adapters.corpus._fallback_log import record_fallback
+        record_fallback(
+            importer="htr_united",
+            operation="yaml_catalogue_parse",
+            error=exc,
+        )
+    return [HTRUnitedEntry.from_dict(d) for d in _DEMO_CATALOGUE]
+
+
+def _iso_now() -> str:
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")

picarones/adapters/corpus/huggingface.py

@@ -0,0 +1,464 @@
+"""Import de datasets OCR/HTR depuis HuggingFace Hub.
+
+⚠ **Statut : expérimental** (phase C du chantier de refonte en 3 cercles).
+L'API ``datasets`` HuggingFace évolue fréquemment et ce module n'a pas
+de tests d'intégration. À utiliser à vos risques jusqu'à ce qu'un cas
+d'usage institutionnel valide son comportement. Un ``UserWarning`` est
+émis à l'import pour le rappeler.
+
+Ce module fournit :
+- :class:`HuggingFaceDataset` — métadonnées d'un dataset HuggingFace
+- :class:`HuggingFaceImporter` — recherche et import de datasets
+- :func:`search_hf_datasets` — recherche par tags dans l'API HuggingFace
+- :func:`import_hf_dataset` — téléchargement d'un dataset vers un dossier local
+
+Les datasets patrimoniaux de référence sont pré-référencés pour une découverte
+rapide sans requête réseau.
+
+Exemple
+-------
+    importer = HuggingFaceImporter()
+    results = importer.search("medieval OCR", tags=["ocr"])
+    corpus = importer.import_dataset(results[0].dataset_id, output_dir="./corpus/")
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+import warnings
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+
+# Émission du warning ``experimental`` à l'import. Phase C du chantier
+# de refonte — voir docstring du module ci-dessus.
+warnings.warn(
+    "picarones.extras.importers.huggingface is experimental and may "
+    "change or be removed without notice. Use at your own risk until "
+    "an institutional use case validates the API.",
+    category=UserWarning,
+    stacklevel=2,
+)
+
+# ---------------------------------------------------------------------------
+# Datasets de référence pré-référencés
+# ---------------------------------------------------------------------------
+
+_REFERENCE_DATASETS: list[dict] = [
+    {
+        "dataset_id": "Teklia/RIMES",
+        "title": "RIMES — Reconnaissance et Indexation de données Manuscrites et de fac-similEs",
+        "description": "Corpus de courriers manuscrits français modernes. Standard de référence pour la reconnaissance d'écriture manuscrite.",
+        "language": ["French"],
+        "tags": ["htr", "ocr", "handwritten", "french", "modern"],
+        "license": "cc-by-4.0",
+        "size_category": "1K<n<10K",
+        "task": "image-to-text",
+        "institution": "IRISA / A2iA",
+        "downloads": 1200,
+    },
+    {
+        "dataset_id": "Teklia/IAM",
+        "title": "IAM Handwriting Database",
+        "description": "Corpus de référence anglais pour la reconnaissance d'écriture manuscrite.",
+        "language": ["English"],
+        "tags": ["htr", "ocr", "handwritten", "english"],
+        "license": "other",
+        "size_category": "10K<n<100K",
+        "task": "image-to-text",
+        "institution": "University of Bern",
+        "downloads": 8400,
+    },
+    {
+        "dataset_id": "CATMuS/medieval",
+        "title": "CATMuS Medieval — Consistent Approaches to Transcribing ManuScripts",
+        "description": "Dataset multilingue de manuscrits médiévaux (latin, français, occitan, espagnol) pour l'entraînement de modèles HTR.",
+        "language": ["Latin", "French", "Occitan", "Spanish"],
+        "tags": ["htr", "medieval", "manuscripts", "latin", "french", "historical"],
+        "license": "cc-by-4.0",
+        "size_category": "100K<n<1M",
+        "task": "image-to-text",
+        "institution": "Inria / EPHE",
+        "downloads": 3100,
+    },
+    {
+        "dataset_id": "htr-united/cremma-medieval",
+        "title": "CREMMA Medieval",
+        "description": "Corpus de manuscrits médiévaux français XIIe-XVe siècles.",
+        "language": ["French", "Latin"],
+        "tags": ["htr", "medieval", "french", "manuscripts", "htr-united"],
+        "license": "cc-by-4.0",
+        "size_category": "1K<n<10K",
+        "task": "image-to-text",
+        "institution": "Inria",
+        "downloads": 520,
+    },
+    {
+        "dataset_id": "biglam/europeana_newspapers",
+        "title": "Europeana Newspapers",
+        "description": "Journaux numérisés européens du XIXe siècle (OCR + images).",
+        "language": ["French", "German", "Dutch", "Finnish"],
+        "tags": ["ocr", "newspapers", "historical", "19th-century", "europeana"],
+        "license": "cc0-1.0",
+        "size_category": "1M<n<10M",
+        "task": "image-to-text",
+        "institution": "Europeana Foundation",
+        "downloads": 15200,
+    },
+    {
+        "dataset_id": "stefanklut/esposalles",
+        "title": "Esposalles Dataset",
+        "description": "Registres de mariage catalans du XVIIe siècle pour la reconnaissance d'écriture historique.",
+        "language": ["Catalan", "Latin"],
+        "tags": ["htr", "historical", "registers", "catalan", "17th-century"],
+        "license": "cc-by-4.0",
+        "size_category": "1K<n<10K",
+        "task": "image-to-text",
+        "institution": "Universitat Autònoma de Barcelona",
+        "downloads": 340,
+    },
+    {
+        "dataset_id": "bnf-gallica/gallica-ocr",
+        "title": "Gallica OCR",
+        "description": "Extraits d'imprimés anciens numérisés depuis Gallica avec vérité terrain.",
+        "language": ["French", "Latin"],
+        "tags": ["ocr", "historical", "printed", "gallica", "french"],
+        "license": "etalab-2.0",
+        "size_category": "10K<n<100K",
+        "task": "image-to-text",
+        "institution": "Gallica",
+        "downloads": 2800,
+    },
+    {
+        "dataset_id": "Bozen-Baptism/baptism-records",
+        "title": "Bozen Baptism Records",
+        "description": "Registres de baptêmes de Bozen (Italie/Autriche) du XVIIIe siècle.",
+        "language": ["German", "Latin"],
+        "tags": ["htr", "historical", "registers", "german", "latin", "18th-century"],
+        "license": "cc-by-4.0",
+        "size_category": "1K<n<10K",
+        "task": "image-to-text",
+        "institution": "University of Innsbruck",
+        "downloads": 190,
+    },
+    {
+        "dataset_id": "read-bad/readbad",
+        "title": "READ-BAD — Recognition and Enrichment of Archival Documents",
+        "description": "Corpus multilingue de documents d'archives pour l'OCR historique (Latin, Allemand, Anglais).",
+        "language": ["German", "English", "Latin"],
+        "tags": ["ocr", "htr", "historical", "archives", "read"],
+        "license": "cc-by-4.0",
+        "size_category": "10K<n<100K",
+        "task": "image-to-text",
+        "institution": "University of Graz",
+        "downloads": 1050,
+    },
+]
+
+# ---------------------------------------------------------------------------
+# Dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass
+class HuggingFaceDataset:
+    """Métadonnées d'un dataset HuggingFace."""
+
+    dataset_id: str
+    title: str
+    description: str = ""
+    language: list[str] = field(default_factory=list)
+    tags: list[str] = field(default_factory=list)
+    license: str = ""
+    size_category: str = ""
+    task: str = "image-to-text"
+    institution: str = ""
+    downloads: int = 0
+    source: str = "reference"  # "reference" | "api"
+
+    def as_dict(self) -> dict:
+        return {
+            "dataset_id": self.dataset_id,
+            "title": self.title,
+            "description": self.description,
+            "language": self.language,
+            "tags": self.tags,
+            "license": self.license,
+            "size_category": self.size_category,
+            "task": self.task,
+            "institution": self.institution,
+            "downloads": self.downloads,
+            "source": self.source,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "HuggingFaceDataset":
+        return cls(
+            dataset_id=d.get("dataset_id", d.get("id", "")),
+            title=d.get("title", d.get("dataset_id", "")),
+            description=d.get("description", ""),
+            language=d.get("language", []),
+            tags=d.get("tags", []),
+            license=d.get("license", ""),
+            size_category=d.get("size_category", d.get("cardData", {}).get("size_categories", [""])[0] if isinstance(d.get("cardData"), dict) else ""),
+            task=d.get("task", "image-to-text"),
+            institution=d.get("institution", ""),
+            downloads=d.get("downloads", d.get("downloadsAllTime", 0)),
+            source=d.get("source", "api"),
+        )
+
+    @property
+    def hf_url(self) -> str:
+        return f"https://huggingface.co/datasets/{self.dataset_id}"
+
+
+# ---------------------------------------------------------------------------
+# Importer principal
+# ---------------------------------------------------------------------------
+
+class HuggingFaceImporter:
+    """Recherche et importe des datasets depuis HuggingFace Hub."""
+
+    _API_BASE = "https://huggingface.co/api"
+
+    def __init__(self, token: Optional[str] = None) -> None:
+        self._token = token or os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACE_TOKEN")
+
+    def _headers(self) -> dict:
+        h = {"User-Agent": "picarones-hf-importer/1.0"}
+        if self._token:
+            h["Authorization"] = f"Bearer {self._token}"
+        return h
+
+    def search(
+        self,
+        query: str = "",
+        tags: Optional[list[str]] = None,
+        language: Optional[str] = None,
+        limit: int = 20,
+        use_reference: bool = True,
+    ) -> list[HuggingFaceDataset]:
+        """Recherche des datasets avec filtres.
+
+        Interroge d'abord les datasets de référence pré-intégrés, puis
+        l'API HuggingFace si disponible.
+        """
+        results: list[HuggingFaceDataset] = []
+
+        # Datasets de référence
+        if use_reference:
+            ref_results = self._search_reference(query, tags, language)
+            results.extend(ref_results)
+
+        # API HuggingFace (optionnel, peut échouer silencieusement)
+        try:
+            api_results = self._search_api(query, tags, language, limit)
+            # Déduplique (priorité aux références)
+            existing_ids = {r.dataset_id for r in results}
+            for ds in api_results:
+                if ds.dataset_id not in existing_ids:
+                    results.append(ds)
+                    existing_ids.add(ds.dataset_id)
+        except Exception as exc:  # noqa: BLE001 — réseau/API tierce
+            # Sprint A3 (B-3) : la recherche API échoue silencieusement →
+            # l'utilisateur ne voit que les datasets de référence et croit
+            # que l'API est vide. On documente l'incident.
+            from picarones.adapters.corpus._fallback_log import record_fallback
+            record_fallback(
+                importer="huggingface",
+                operation="hub_search_api",
+                error=exc,
+                extra={"query": query, "language": language, "limit": limit},
+            )
+
+        return results[:limit]
+
+    def _search_reference(
+        self,
+        query: str,
+        tags: Optional[list[str]],
+        language: Optional[str],
+    ) -> list[HuggingFaceDataset]:
+        datasets = [HuggingFaceDataset.from_dict(d) for d in _REFERENCE_DATASETS]
+        datasets = [ds._replace_source("reference") for ds in datasets]
+
+        if query:
+            q = query.lower()
+            datasets = [
+                ds for ds in datasets
+                if (q in ds.title.lower()
+                    or q in ds.description.lower()
+                    or q in ds.dataset_id.lower()
+                    or any(q in t.lower() for t in ds.tags)
+                    or any(q in lg.lower() for lg in ds.language))
+            ]
+
+        if tags:
+            for tag in tags:
+                t_lower = tag.lower()
+                datasets = [
+                    ds for ds in datasets
+                    if any(t_lower in dt.lower() for dt in ds.tags)
+                ]
+
+        if language:
+            lang_lower = language.lower()
+            datasets = [
+                ds for ds in datasets
+                if any(lang_lower in lg.lower() for lg in ds.language)
+            ]
+
+        return datasets
+
+    def _search_api(
+        self,
+        query: str,
+        tags: Optional[list[str]],
+        language: Optional[str],
+        limit: int,
+    ) -> list[HuggingFaceDataset]:
+        params: dict[str, str] = {
+            "task_categories": "image-to-text",
+            "limit": str(min(limit, 50)),
+            "full": "False",
+        }
+        if query:
+            params["search"] = query
+        if language:
+            params["language"] = language
+        if tags:
+            params["tags"] = ",".join(tags)
+
+        url = f"{self._API_BASE}/datasets?" + urllib.parse.urlencode(params)
+        req = urllib.request.Request(url, headers=self._headers())
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+
+        results = []
+        for item in data if isinstance(data, list) else []:
+            ds = HuggingFaceDataset(
+                dataset_id=item.get("id", ""),
+                title=item.get("id", ""),
+                description=item.get("description", ""),
+                language=item.get("language", []),
+                tags=item.get("tags", []),
+                license=item.get("license", ""),
+                size_category=(
+                    item.get("cardData", {}).get("size_categories", [""])[0]
+                    if isinstance(item.get("cardData"), dict)
+                    else ""
+                ),
+                task="image-to-text",
+                downloads=item.get("downloadsAllTime", 0),
+                source="api",
+            )
+            if ds.dataset_id:
+                results.append(ds)
+        return results
+
+    def import_dataset(
+        self,
+        dataset_id: str,
+        output_dir: str | Path,
+        split: str = "train",
+        max_samples: int = 100,
+        show_progress: bool = True,
+    ) -> dict:
+        """Importe un dataset depuis HuggingFace vers un dossier local.
+
+        Retourne les métadonnées de l'import.
+        """
+        output_path = Path(output_dir)
+        output_path.mkdir(parents=True, exist_ok=True)
+
+        meta = {
+            "source": "huggingface",
+            "dataset_id": dataset_id,
+            "split": split,
+            "max_samples": max_samples,
+            "imported_at": _iso_now(),
+        }
+        meta_file = output_path / "huggingface_meta.json"
+        meta_file.write_text(json.dumps(meta, ensure_ascii=False, indent=2), encoding="utf-8")
+
+        # Tentative d'import via datasets library si disponible
+        files_imported = _try_import_with_datasets_lib(
+            dataset_id, output_path, split, max_samples, show_progress
+        )
+
+        return {
+            "dataset_id": dataset_id,
+            "output_dir": str(output_path),
+            "files_imported": files_imported,
+            "metadata_file": str(meta_file),
+        }
+
+
+def _try_import_with_datasets_lib(
+    dataset_id: str,
+    output_path: Path,
+    split: str,
+    max_samples: int,
+    show_progress: bool,
+) -> int:
+    """Essaie d'importer avec la librairie `datasets` de HuggingFace."""
+    try:
+        from datasets import load_dataset  # type: ignore
+
+        ds = load_dataset(dataset_id, split=split, streaming=True)
+        count = 0
+        for i, item in enumerate(ds):
+            if i >= max_samples:
+                break
+            # Cherche champ image et texte
+            image = item.get("image") or item.get("img")
+            text = item.get("text") or item.get("transcription") or item.get("ground_truth", "")
+
+            if image is not None:
+                img_file = output_path / f"doc_{i:04d}.jpg"
+                try:
+                    image.save(str(img_file))
+                except Exception as exc:  # noqa: BLE001 — PIL/PIL-IO
+                    # Sprint A3 (B-3) : un échec de sauvegarde d'image
+                    # produirait un GT orphelin (texte sans image). On
+                    # documente et on continue — le GT est tout de même
+                    # écrit pour préserver la cohérence numérique du compteur.
+                    from picarones.adapters.corpus._fallback_log import record_fallback
+                    record_fallback(
+                        importer="huggingface",
+                        operation="image_save",
+                        error=exc,
+                        extra={"img_file": str(img_file), "doc_index": i},
+                    )
+
+            gt_file = output_path / f"doc_{i:04d}.gt.txt"
+            gt_file.write_text(str(text), encoding="utf-8")
+            count += 1
+
+        return count
+    except (ImportError, Exception):
+        return 0
+
+
+def _iso_now() -> str:
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+# ---------------------------------------------------------------------------
+# Extension de HuggingFaceDataset (helper privé)
+# ---------------------------------------------------------------------------
+
+def _patch_dataset_replace_source() -> None:
+    """Ajoute un helper _replace_source à HuggingFaceDataset."""
+    def _replace_source(self, source: str) -> "HuggingFaceDataset":
+        from dataclasses import replace
+        return replace(self, source=source)
+    HuggingFaceDataset._replace_source = _replace_source
+
+
+_patch_dataset_replace_source()

picarones/adapters/llm/__init__.py

@@ -0,0 +1,16 @@
+"""Adaptateurs LLM — Sprint S11.
+
+Cible : déplacement de ``picarones.llm.{openai,anthropic,mistral,
+ollama}_adapter``.  Wrappers minces autour des SDK provider, qui
+exposent un ``complete(prompt, ...)`` uniforme.
+
+Un adapter LLM ne sait **rien** d'OCR ou de patrimoine.  Il fait
+``prompt → completion``.  La logique de pipeline (prompt
+construction, post-traitement, gestion d'erreur) vit dans
+``pipeline/`` ou dans le module utilisateur qui compose la
+pipeline.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

picarones/adapters/llm/anthropic_adapter.py

@@ -0,0 +1,111 @@
+"""Adaptateur LLM — Anthropic (Claude Sonnet, Claude Haiku)."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Optional
+
+from picarones.adapters.llm.base import (
+    BaseLLMAdapter,
+    log_http_error,
+    normalize_llm_content,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class AnthropicAdapter(BaseLLMAdapter):
+    """Adaptateur pour les modèles Anthropic Claude.
+
+    Clé API via la variable d'environnement ``ANTHROPIC_API_KEY``.
+
+    Modes supportés : text_only, text_and_image, zero_shot.
+    """
+
+    api_key_env_var = "ANTHROPIC_API_KEY"
+
+    @property
+    def name(self) -> str:
+        return "anthropic"
+
+    @property
+    def default_model(self) -> str:
+        return "claude-sonnet-4-6"
+
+    def __init__(
+        self,
+        model: Optional[str] = None,
+        config: Optional[dict] = None,
+    ) -> None:
+        super().__init__(model, config)
+        self._api_key = os.environ.get("ANTHROPIC_API_KEY")
+
+    def _call(self, prompt: str, image_b64: Optional[str] = None) -> str:
+        if not self._api_key:
+            raise RuntimeError(
+                "Clé API Anthropic manquante — définissez la variable d'environnement ANTHROPIC_API_KEY"
+            )
+        try:
+            import anthropic
+        except ImportError as exc:
+            raise RuntimeError(
+                "Le package 'anthropic' n'est pas installé. Lancez : pip install anthropic"
+            ) from exc
+
+        client = anthropic.Anthropic(api_key=self._api_key)
+        temperature = float(self.config.get("temperature", 0.0))
+        max_tokens = int(self.config.get("max_tokens", 4096))
+
+        if image_b64:
+            content: list | str = [
+                {
+                    "type": "image",
+                    "source": {
+                        "type": "base64",
+                        "media_type": "image/png",
+                        "data": image_b64,
+                    },
+                },
+                {"type": "text", "text": prompt},
+            ]
+        else:
+            content = prompt
+
+        try:
+            response = client.messages.create(
+                model=self.model,
+                max_tokens=max_tokens,
+                temperature=temperature,
+                messages=[{"role": "user", "content": content}],
+            )
+        except Exception as exc:
+            # Chantier 4 — log discriminant (401/429/5xx) factorisé.
+            # Auparavant Anthropic ne discriminait pas par code HTTP,
+            # difficile à diagnostiquer (clé invalide vs rate limit).
+            log_http_error(
+                "AnthropicAdapter", self.model, exc,
+                env_var=self.api_key_env_var,
+            )
+            raise
+
+        if not response.content:
+            logger.warning(
+                "[AnthropicAdapter] réponse vide (modèle=%s, stop_reason=%s).",
+                self.model, getattr(response, "stop_reason", None),
+            )
+            return ""
+
+        # Chantier 4 — propagation du fix Sprint 15 : le SDK Anthropic
+        # retourne ``response.content`` comme une liste de blocs
+        # (``ContentBlock`` avec attribut ``text``). ``normalize_llm_content``
+        # concatène le texte de tous les blocs au lieu de ne prendre que
+        # le premier — utile quand le modèle émet plusieurs blocs.
+        text = normalize_llm_content(response.content)
+        if not text:
+            block = response.content[0]
+            logger.warning(
+                "[AnthropicAdapter] bloc de type '%s' sans texte (modèle=%s).",
+                getattr(block, "type", "unknown"), self.model,
+            )
+        return text

picarones/adapters/llm/base.py

@@ -0,0 +1,486 @@
+"""Interface abstraite commune à tous les adaptateurs LLM."""
+
+from __future__ import annotations
+
+import logging
+import time
+import warnings
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Generic, Optional, TypeVar
+
+logger = logging.getLogger(__name__)
+
+
+T = TypeVar("T")
+
+
+class _DeprecatedAttribute(Generic[T]):
+    """Descripteur class-level qui émet ``DeprecationWarning`` à l'accès.
+
+    Permet de retirer en deux temps une constante de classe sans
+    casser les callers externes : phase 1, le descripteur retourne
+    l'ancienne valeur avec un warning ; phase 2 (version majeure
+    suivante), le descripteur est supprimé.
+    """
+
+    def __init__(
+        self,
+        value: T,
+        message: str,
+    ) -> None:
+        self._value = value
+        self._message = message
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        self._name = name
+
+    def __get__(self, instance: Any, owner: type | None = None) -> T:
+        warnings.warn(self._message, DeprecationWarning, stacklevel=2)
+        return self._value
+
+from picarones.adapters._retry import (
+    DEFAULT_BACKOFF_BASE as _DEFAULT_BACKOFF_BASE,
+)
+from picarones.adapters._retry import (
+    DEFAULT_MAX_RETRIES as _DEFAULT_MAX_RETRIES,
+)
+from picarones.adapters._retry import (
+    is_retryable as _is_retryable,
+)
+
+
+def normalize_llm_content(raw: Any) -> str:
+    """Normalise une réponse LLM en chaîne plate.
+
+    Chantier 4 (post-Sprint 97) — propagation du fix Mistral
+    Sprint 15 à tous les providers. Le SDK Mistral peut retourner
+    une liste de ``ContentChunk`` au lieu d'une chaîne pour certains
+    modèles/versions ; le SDK OpenAI peut faire de même quand on
+    active des features de structuration. Ce helper applique la même
+    discipline pour les 4 adapters :
+
+    - ``str``                          → renvoyée telle quelle (ou ``""``).
+    - ``None``                         → ``""``.
+    - ``list[ContentChunk]``           → concaténation des ``.text``.
+    - ``list[dict]`` avec clé ``text`` → concaténation des ``["text"]``.
+    - ``list[str]``                    → concaténation directe.
+    - autre objet avec ``.text``       → ``obj.text``.
+    - autre                            → ``str(obj)`` (best-effort).
+
+    Le résultat est garanti être une ``str`` ; ``""`` quand la réponse
+    est vide. La fonction est idempotente : ``normalize_llm_content(s)
+    == s`` pour toute chaîne ``s``.
+    """
+    if raw is None:
+        return ""
+    if isinstance(raw, str):
+        return raw
+    if isinstance(raw, list):
+        parts: list[str] = []
+        for chunk in raw:
+            if chunk is None:
+                continue
+            if isinstance(chunk, str):
+                parts.append(chunk)
+                continue
+            if hasattr(chunk, "text"):
+                txt = getattr(chunk, "text", None)
+                if isinstance(txt, str):
+                    parts.append(txt)
+                    continue
+            if isinstance(chunk, dict) and isinstance(chunk.get("text"), str):
+                parts.append(chunk["text"])
+                continue
+            # Dernier recours — convertit le chunk en chaîne
+            parts.append(str(chunk))
+        return "".join(parts)
+    if hasattr(raw, "text") and isinstance(getattr(raw, "text", None), str):
+        return raw.text  # type: ignore[no-any-return]
+    return str(raw)
+
+
+def log_http_error(
+    adapter_name: str,
+    model: str,
+    exc: Exception,
+    *,
+    env_var: Optional[str] = None,
+) -> None:
+    """Log standardisé des erreurs HTTP des SDK LLM.
+
+    Chantier 4 (post-Sprint 97) — propagation du log discriminant
+    Mistral/OpenAI à tous les providers. Inspecte ``status_code`` et
+    ``http_status`` puis émet un warning ciblé selon le code :
+
+    - 401 : clé API invalide/expirée (mention de la variable
+      d'environnement à vérifier si fournie).
+    - 429 : rate limit / quota dépassé.
+    - 5xx : problème serveur côté provider.
+    - autre / pas de status_code : log générique.
+
+    L'exception n'est pas levée — l'appelant doit ``raise``
+    explicitement après ce log s'il veut propager (le retry est géré
+    par ``BaseLLMAdapter.complete`` selon ``_is_retryable``).
+    """
+    status = getattr(exc, "status_code", None) or getattr(exc, "http_status", None)
+    if status == 401:
+        suffix = f" Vérifier {env_var}." if env_var else ""
+        logger.warning(
+            "[%s] erreur HTTP 401 — clé API invalide ou expirée "
+            "(modèle=%s).%s",
+            adapter_name, model, suffix,
+        )
+    elif status == 429:
+        logger.warning(
+            "[%s] erreur HTTP 429 — quota dépassé ou rate-limit "
+            "(modèle=%s). Réessayer plus tard.",
+            adapter_name, model,
+        )
+    elif status is not None and status >= 500:
+        logger.warning(
+            "[%s] erreur HTTP %d — problème serveur (modèle=%s) : %s",
+            adapter_name, status, model, exc,
+        )
+    else:
+        logger.warning(
+            "[%s] erreur lors de l'appel API (modèle=%s) : %s",
+            adapter_name, model, exc,
+        )
+
+
+from picarones.domain.errors import AdapterStepError
+
+
+class LLMAdapterError(AdapterStepError):
+    """Erreur typée pour un échec d'adapter LLM.
+
+    Hérite de ``AdapterStepError`` (racine commune avec OCR et VLM)
+    → un caller peut catcher ``AdapterStepError`` pour toute erreur
+    d'adapter sans connaître la sous-classe.
+
+    Avant S52, ``BaseLLMAdapter.execute`` levait ``OCRAdapterError``
+    par confusion sémantique — c'était noté dans l'audit comme issue
+    #11 (hiérarchie incohérente).
+    """
+
+
+@dataclass
+class LLMResult:
+    """Résultat produit par un appel LLM."""
+
+    model_id: str
+    text: str
+    duration_seconds: float
+    tokens_used: Optional[int] = None
+    error: Optional[str] = None
+
+    @property
+    def success(self) -> bool:
+        return self.error is None
+
+
+class BaseLLMAdapter(ABC):
+    """Classe de base pour tous les adaptateurs LLM.
+
+    Chaque adaptateur doit implémenter :
+    - ``name``         : identifiant du provider (ex : 'openai')
+    - ``default_model``: modèle par défaut du provider
+    - ``_call()``      : appel API effectif, retourne le texte brut
+
+    Les clés API sont lues depuis les variables d'environnement uniquement.
+
+    Retry automatique
+    -----------------
+    Les erreurs retryables (HTTP 429, 5xx, timeout réseau) sont automatiquement
+    retentées avec backoff exponentiel (2s, 4s, 8s par défaut). Configurable
+    via ``config["max_retries"]`` et ``config["retry_backoff"]``.
+
+    Normalisation des réponses (chantier 4)
+    ---------------------------------------
+    Les sous-classes utilisent :func:`normalize_llm_content` sur la
+    réponse SDK avant de la retourner — garantit qu'une réponse de
+    type ``list[ContentChunk]`` (Mistral, parfois OpenAI) est
+    convertie en ``str`` plate.
+
+    Logging d'erreurs HTTP (chantier 4)
+    -----------------------------------
+    Les sous-classes utilisent :func:`log_http_error` pour produire
+    un log discriminant par ``status_code`` (401 → clé invalide,
+    429 → rate limit, 5xx → serveur).  Auparavant ce log était
+    dupliqué chez Mistral/OpenAI et absent chez Anthropic.
+
+    Sprint A14-S44 — intégration pipeline native
+    ---------------------------------------------
+    ``BaseLLMAdapter`` implémente désormais le contrat ``StepExecutor``
+    du pipeline (``input_types``, ``output_types``, ``execution_mode``,
+    ``execute(inputs, params, context)``) — un adapter LLM est
+    directement utilisable comme step de pipeline pour la post-correction
+    de texte OCR.  Pas de wrapper / shim : la méthode ``execute`` vit
+    dans la base et est partagée par les 4 adapters concrets.
+
+    Convention par défaut : un LLM consomme ``RAW_TEXT`` (depuis l'OCR
+    en amont) et produit ``CORRECTED_TEXT``.  Une sous-classe peut
+    surcharger ``input_types`` / ``output_types`` si elle implémente un
+    autre contrat (ex : ALTO → ALTO pour un module de remappage).
+    """
+
+    # Variable d'environnement portant la clé API.  Sous-classes
+    # surchargent (ex. ``"OPENAI_API_KEY"``) ; mention utilisée par
+    # :func:`log_http_error` quand un 401 est rencontré.  ``None``
+    # pour les providers sans clé (Ollama).
+    api_key_env_var: Optional[str] = None
+
+    # ──────────────────────────────────────────────────────────────────
+    # Sprint A14-S44 — contrat StepExecutor du pipeline
+    # ──────────────────────────────────────────────────────────────────
+
+    #: Types d'artefacts consommés par défaut.  Surchargeable par
+    #: une sous-classe qui consommerait des artefacts différents
+    #: (ex : ALTO_XML pour un remappeur ALTO LLM).
+    @property
+    def input_types(self) -> "frozenset":
+        from picarones.domain.artifacts import ArtifactType
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    @property
+    def output_types(self) -> "frozenset":
+        from picarones.domain.artifacts import ArtifactType
+        return frozenset({ArtifactType.CORRECTED_TEXT})
+
+    #: Mode d'exécution : LLM via API → IO-bound → ThreadPool dans le
+    #: runner.  Une sous-classe locale (Ollama CPU-bound) peut
+    #: surcharger en ``"cpu"``.
+    execution_mode: str = "io"
+
+    #: Prompts de post-correction par défaut, indexés par code langue
+    #: ISO-639-1 (``fr``, ``en``, ``la``).  Sélection via
+    #: ``config["lang"]`` ; fallback FR si la langue est absente.
+    #:
+    #: ``DEFAULT_CORRECTION_PROMPT`` (singulier, FR) reste exposé en
+    #: ``_DeprecatedAttribute`` pour les sous-classes externes qui
+    #: lisaient l'ancienne API ; suppression prévue en 2.0.
+    DEFAULT_CORRECTION_PROMPTS: dict[str, str] = {
+        "fr": (
+            "Corrige les erreurs OCR dans le texte suivant en "
+            "conservant fidèlement la langue, l'orthographe "
+            "historique et la ponctuation. Retourne uniquement le "
+            "texte corrigé, sans commentaire :\n\n{text}"
+        ),
+        "en": (
+            "Fix OCR errors in the following text while preserving "
+            "the original language, historical spelling, and "
+            "punctuation. Return only the corrected text, with no "
+            "commentary:\n\n{text}"
+        ),
+        "la": (
+            "Corrige errores OCR in textu sequenti, fideliter "
+            "servans linguam, orthographiam historicam et "
+            "interpunctionem. Redde solum textum correctum, sine "
+            "ulla glossa:\n\n{text}"
+        ),
+    }
+
+    #: Alias rétrocompat (FR uniquement) pour les sous-classes
+    #: externes qui lisaient l'ancienne API singulière.  L'accès
+    #: déclenche un ``DeprecationWarning``.  Sera supprimé en 2.0.
+    DEFAULT_CORRECTION_PROMPT = _DeprecatedAttribute(
+        DEFAULT_CORRECTION_PROMPTS["fr"],
+        "BaseLLMAdapter.DEFAULT_CORRECTION_PROMPT is deprecated and "
+        "will be removed in 2.0.  Use "
+        "DEFAULT_CORRECTION_PROMPTS[lang] (lang ∈ {fr, en, la}).",
+    )
+
+    def __init__(
+        self,
+        model: Optional[str] = None,
+        config: Optional[dict] = None,
+    ) -> None:
+        self.config: dict = config or {}
+        self.model: str = model or self.default_model
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Identifiant du provider (ex : 'openai', 'anthropic')."""
+
+    @property
+    @abstractmethod
+    def default_model(self) -> str:
+        """Modèle utilisé si aucun n'est fourni explicitement."""
+
+    @abstractmethod
+    def _call(self, prompt: str, image_b64: Optional[str] = None) -> str:
+        """Appel LLM effectif.
+
+        Parameters
+        ----------
+        prompt:
+            Texte du prompt final (variables déjà substituées).
+        image_b64:
+            Image encodée en base64 (sans préfixe data URI).
+            None pour les appels texte-uniquement.
+
+        Returns
+        -------
+        str
+            Texte généré par le LLM.
+        """
+
+    def complete(
+        self,
+        prompt: str,
+        image_b64: Optional[str] = None,
+    ) -> LLMResult:
+        """Point d'entrée public : appelle le LLM avec retry automatique."""
+        max_retries = int(self.config.get("max_retries", _DEFAULT_MAX_RETRIES))
+        backoff_base = float(self.config.get("retry_backoff", _DEFAULT_BACKOFF_BASE))
+
+        start = time.perf_counter()
+        last_exc: Optional[Exception] = None
+
+        for attempt in range(max_retries + 1):
+            try:
+                text = self._call(prompt, image_b64)
+                duration = time.perf_counter() - start
+                return LLMResult(
+                    model_id=self.model,
+                    text=text,
+                    duration_seconds=round(duration, 4),
+                )
+            except Exception as exc:  # noqa: BLE001
+                last_exc = exc
+                if attempt < max_retries and _is_retryable(exc):
+                    wait = backoff_base ** (attempt + 1)
+                    logger.warning(
+                        "[%s] erreur retryable (tentative %d/%d, attente %.1fs) : %s",
+                        self.name, attempt + 1, max_retries + 1, wait, exc,
+                    )
+                    time.sleep(wait)
+                else:
+                    break
+
+        duration = time.perf_counter() - start
+        return LLMResult(
+            model_id=self.model,
+            text="",
+            duration_seconds=round(duration, 4),
+            error=str(last_exc),
+        )
+
+    # ──────────────────────────────────────────────────────────────────
+    # Sprint A14-S44 — execute() pour le pipeline
+    # ──────────────────────────────────────────────────────────────────
+
+    def execute(
+        self,
+        inputs: dict,
+        params: dict,
+        context: Any,
+    ) -> dict:
+        """Exécute la post-correction LLM en tant que step de pipeline.
+
+        Convention par défaut : lit ``inputs[RAW_TEXT]`` (Artifact),
+        charge son contenu UTF-8 depuis l'URI, appelle ``self.complete``
+        avec le ``correction_prompt`` formaté, écrit le résultat dans
+        un fichier ``<input_stem>.<adapter_name>.corrected.txt``, et
+        retourne ``{CORRECTED_TEXT: Artifact}``.
+
+        Le caller (``PipelineExecutor``) catch les exceptions ; on les
+        propage telles quelles.
+
+        Optionnel : si ``inputs[IMAGE]`` est présent, l'image est
+        encodée en base64 et passée au LLM (mode VLM).  Les sous-classes
+        qui ne supportent pas la vision (ex. ollama texte) ignorent
+        silencieusement.
+        """
+        from pathlib import Path
+        import base64
+
+        from picarones.domain.artifacts import Artifact, ArtifactType
+
+        if ArtifactType.RAW_TEXT not in inputs:
+            raise LLMAdapterError(
+                f"{self.name} : input RAW_TEXT manquant.",
+            )
+        text_artifact = inputs[ArtifactType.RAW_TEXT]
+        if text_artifact.uri is None:
+            raise LLMAdapterError(
+                f"{self.name} : artefact RAW_TEXT "
+                f"{text_artifact.id!r} sans URI.",
+            )
+        text_path = Path(text_artifact.uri)
+        if not text_path.exists():
+            raise LLMAdapterError(
+                f"{self.name} : fichier texte introuvable {text_path!r}.",
+            )
+
+        original_text = text_path.read_text(encoding="utf-8")
+
+        # Image optionnelle (VLM-style si supporté).
+        image_b64: Optional[str] = None
+        image_artifact = inputs.get(ArtifactType.IMAGE)
+        if image_artifact is not None and image_artifact.uri is not None:
+            image_path = Path(image_artifact.uri)
+            if image_path.exists():
+                image_b64 = base64.b64encode(
+                    image_path.read_bytes(),
+                ).decode("ascii")
+
+        # Priorité : override explicite via config > prompt par langue
+        # selon config["lang"] > FR par défaut.
+        custom_prompt = self.config.get("correction_prompt")
+        if custom_prompt is not None:
+            prompt_template = custom_prompt
+        else:
+            lang = (self.config.get("lang") or "fr").lower()
+            if lang not in self.DEFAULT_CORRECTION_PROMPTS:
+                logger.warning(
+                    "[%s] lang=%r non supportée par "
+                    "DEFAULT_CORRECTION_PROMPTS (%s) — fallback FR. "
+                    "Pour un corpus dans cette langue, fournir "
+                    "config['correction_prompt'] explicite.",
+                    self.name, lang,
+                    sorted(self.DEFAULT_CORRECTION_PROMPTS.keys()),
+                )
+            prompt_template = self.DEFAULT_CORRECTION_PROMPTS.get(
+                lang, self.DEFAULT_CORRECTION_PROMPTS["fr"],
+            )
+        prompt = prompt_template.format(text=original_text)
+
+        result = self.complete(prompt, image_b64=image_b64)
+        if not result.success:
+            raise LLMAdapterError(
+                f"{self.name} : LLM a échoué ({result.error}).",
+            )
+
+        from picarones.adapters.output_paths import resolve_output_path
+        out_path = resolve_output_path(
+            input_path=text_path,
+            adapter_name=self.name,
+            suffix="corrected.txt",
+            context=context,
+        )
+        out_path.write_text(result.text, encoding="utf-8")
+
+        return {
+            ArtifactType.CORRECTED_TEXT: Artifact(
+                id=f"{context.document_id}:{self.name}:corrected_text",
+                document_id=context.document_id,
+                type=ArtifactType.CORRECTED_TEXT,
+                produced_by_step="post_correction",
+                uri=str(out_path),
+            ),
+        }
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(model={self.model!r})"
+
+
+__all__ = [
+    "BaseLLMAdapter",
+    "LLMAdapterError",
+    "LLMResult",
+    "log_http_error",
+    "normalize_llm_content",
+]

picarones/adapters/llm/mistral_adapter.py

@@ -0,0 +1,157 @@
+"""Adaptateur LLM — Mistral AI (Mistral Large, Pixtral)."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Optional
+
+from picarones.adapters.llm.base import (
+    BaseLLMAdapter,
+    log_http_error,
+    normalize_llm_content,
+)
+
+logger = logging.getLogger(__name__)
+
+# Modèles Mistral qui NE supportent PAS l'API chat/completions multimodale.
+# Ces petits modèles sont text-only; le passer avec une image provoque une erreur.
+_TEXT_ONLY_MODELS = frozenset({
+    "ministral-3b-latest",
+    "ministral-8b-latest",
+    "mistral-tiny",
+    "mistral-tiny-latest",
+    "open-mistral-7b",
+    "open-mixtral-8x7b",
+})
+
+
+class MistralAdapter(BaseLLMAdapter):
+    """Adaptateur pour les modèles Mistral AI.
+
+    Clé API via la variable d'environnement ``MISTRAL_API_KEY``.
+
+    Modes supportés : text_only (tous modèles), text_and_image et zero_shot
+    avec les modèles multimodaux (pixtral-12b, pixtral-large).
+
+    Note
+    ----
+    Les modèles ``ministral-3b-latest`` et ``ministral-8b-latest`` ne supportent
+    pas le mode multimodal — utiliser ``PipelineMode.TEXT_ONLY`` avec ces modèles.
+    """
+
+    api_key_env_var = "MISTRAL_API_KEY"
+
+    @property
+    def name(self) -> str:
+        return "mistral"
+
+    @property
+    def default_model(self) -> str:
+        return "mistral-large-latest"
+
+    def __init__(
+        self,
+        model: Optional[str] = None,
+        config: Optional[dict] = None,
+    ) -> None:
+        super().__init__(model, config)
+        self._api_key = os.environ.get("MISTRAL_API_KEY")
+        if self.model in _TEXT_ONLY_MODELS:
+            logger.info(
+                "[MistralAdapter] modèle '%s' : text-only (pas de support multimodal).",
+                self.model,
+            )
+
+    def _call(self, prompt: str, image_b64: Optional[str] = None) -> str:
+        if not self._api_key:
+            raise RuntimeError(
+                "Clé API Mistral manquante — définissez la variable d'environnement MISTRAL_API_KEY"
+            )
+        try:
+            try:
+                from mistralai.client import Mistral
+            except ImportError:
+                from mistralai import Mistral  # type: ignore[no-redef]
+        except ImportError as exc:
+            raise RuntimeError(
+                "Le package 'mistralai' n'est pas installé. Lancez : pip install mistralai"
+            ) from exc
+
+        client = Mistral(api_key=self._api_key)
+        temperature = float(self.config.get("temperature", 0.0))
+        max_tokens = int(self.config.get("max_tokens", 4096))
+
+        # Les modèles text-only ne supportent pas les images
+        if image_b64 and self.model in _TEXT_ONLY_MODELS:
+            logger.warning(
+                "[MistralAdapter] modèle '%s' ne supporte pas les images — "
+                "image ignorée, appel en mode texte seul.",
+                self.model,
+            )
+            image_b64 = None
+
+        if image_b64:
+            content: list | str = [
+                {"type": "text", "text": prompt},
+                {
+                    "type": "image_url",
+                    "image_url": f"data:image/png;base64,{image_b64}",
+                },
+            ]
+        else:
+            content = prompt
+
+        logger.info(
+            "[MistralAdapter] appel %s — prompt=%d chars, image=%s",
+            self.model, len(prompt), "oui" if image_b64 else "non",
+        )
+
+        try:
+            response = client.chat.complete(
+                model=self.model,
+                messages=[{"role": "user", "content": content}],
+                temperature=temperature,
+                max_tokens=max_tokens,
+            )
+        except Exception as exc:
+            log_http_error(
+                "MistralAdapter", self.model, exc,
+                env_var=self.api_key_env_var,
+            )
+            raise
+
+        if not response.choices:
+            logger.warning(
+                "[MistralAdapter] response.choices vide (modèle=%s).",
+                self.model,
+            )
+            return ""
+
+        _choice = response.choices[0]
+        raw = _choice.message.content
+        _finish_reason = _choice.finish_reason
+
+        # Chantier 4 — normalisation factorisée dans
+        # ``picarones.llm.base.normalize_llm_content`` (Sprint 15
+        # généralisé : list[ContentChunk] / list[dict] / str → str).
+        text = normalize_llm_content(raw)
+
+        _completion_tokens = None
+        if hasattr(response, "usage") and response.usage:
+            _completion_tokens = getattr(response.usage, "completion_tokens", None)
+
+        logger.info(
+            "[MistralAdapter] réponse %s — finish_reason=%s, len=%d, tokens=%s",
+            self.model, _finish_reason, len(text), _completion_tokens,
+        )
+
+        if not text.strip():
+            logger.warning(
+                "[MistralAdapter] réponse vide du modèle '%s' "
+                "(finish_reason=%s, completion_tokens=%s). "
+                "Vérifier le prompt et la compatibilité du modèle.",
+                self.model, _finish_reason, _completion_tokens,
+            )
+
+        return text

picarones/adapters/llm/ollama_adapter.py

@@ -0,0 +1,109 @@
+"""Adaptateur LLM — Ollama (modèles locaux : Llama 3, Gemma, Phi, Mistral local…)."""
+
+from __future__ import annotations
+
+import logging
+from typing import Optional
+from urllib.parse import urlparse
+
+from picarones.adapters.llm.base import BaseLLMAdapter, normalize_llm_content
+
+logger = logging.getLogger(__name__)
+
+
+class OllamaAdapter(BaseLLMAdapter):
+    """Adaptateur pour les modèles locaux via Ollama.
+
+    Aucune clé API requise. Nécessite un serveur Ollama actif (par défaut
+    sur http://localhost:11434).
+
+    Modes supportés :
+    - text_only      : tous modèles Ollama
+    - text_and_image : modèles multimodaux (llava, bakllava, moondream…)
+    - zero_shot      : modèles multimodaux uniquement
+
+    Configuration (via ``config``) :
+    - ``base_url`` : URL du serveur Ollama (défaut : http://localhost:11434)
+    """
+
+    @property
+    def name(self) -> str:
+        return "ollama"
+
+    @property
+    def default_model(self) -> str:
+        return "llama3"
+
+    def __init__(
+        self,
+        model: Optional[str] = None,
+        config: Optional[dict] = None,
+    ) -> None:
+        super().__init__(model, config)
+        base_url = self.config.get("base_url", "http://localhost:11434").rstrip("/")
+        parsed = urlparse(base_url)
+        if parsed.scheme not in ("http", "https"):
+            raise ValueError(
+                f"URL Ollama invalide (schéma '{parsed.scheme}' non autorisé, "
+                f"seuls http/https sont acceptés) : {base_url}"
+            )
+        self._base_url = base_url
+
+    def _call(self, prompt: str, image_b64: Optional[str] = None) -> str:
+        import json
+        import urllib.error
+        import urllib.request
+
+        temperature = float(self.config.get("temperature", 0.0))
+        payload: dict = {
+            "model": self.model,
+            "prompt": prompt,
+            "stream": False,
+            "options": {"temperature": temperature},
+        }
+        if image_b64:
+            payload["images"] = [image_b64]
+
+        data = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(
+            f"{self._base_url}/api/generate",
+            data=data,
+            headers={"Content-Type": "application/json"},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=120) as resp:
+                raw = resp.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:
+            logger.warning(
+                "[OllamaAdapter] erreur HTTP %d (modèle=%s) : %s",
+                exc.code, self.model, exc,
+            )
+            raise RuntimeError(
+                f"Erreur HTTP {exc.code} du serveur Ollama ({self._base_url}) : {exc}"
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise RuntimeError(
+                f"Impossible de joindre le serveur Ollama sur {self._base_url}. "
+                f"Vérifiez qu'Ollama est démarré (ollama serve). Erreur : {exc}"
+            ) from exc
+
+        try:
+            result = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            logger.warning(
+                "[OllamaAdapter] réponse JSON invalide (modèle=%s) : %s",
+                self.model, raw[:200],
+            )
+            raise RuntimeError(
+                f"Réponse JSON invalide du serveur Ollama : {exc}"
+            ) from exc
+
+        # Chantier 4 — propagation du fix Sprint 15 : Ollama retourne
+        # ``response`` en string mais on normalise par défense (cas où
+        # un futur build retournerait un format structuré).
+        text = normalize_llm_content(result.get("response", ""))
+        if not text:
+            logger.warning(
+                "[OllamaAdapter] réponse vide (modèle=%s).", self.model,
+            )
+        return text

picarones/adapters/llm/openai_adapter.py

@@ -0,0 +1,94 @@
+"""Adaptateur LLM — OpenAI (GPT-4o, GPT-4o-mini)."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Optional
+
+from picarones.adapters.llm.base import (
+    BaseLLMAdapter,
+    log_http_error,
+    normalize_llm_content,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class OpenAIAdapter(BaseLLMAdapter):
+    """Adaptateur pour les modèles OpenAI (GPT-4o, GPT-4o-mini).
+
+    Clé API via la variable d'environnement ``OPENAI_API_KEY``.
+
+    Modes supportés : text_only, text_and_image, zero_shot.
+    """
+
+    api_key_env_var = "OPENAI_API_KEY"
+
+    @property
+    def name(self) -> str:
+        return "openai"
+
+    @property
+    def default_model(self) -> str:
+        return "gpt-4o"
+
+    def __init__(
+        self,
+        model: Optional[str] = None,
+        config: Optional[dict] = None,
+    ) -> None:
+        super().__init__(model, config)
+        self._api_key = os.environ.get("OPENAI_API_KEY")
+
+    def _call(self, prompt: str, image_b64: Optional[str] = None) -> str:
+        if not self._api_key:
+            raise RuntimeError(
+                "Clé API OpenAI manquante — définissez la variable d'environnement OPENAI_API_KEY"
+            )
+        try:
+            from openai import OpenAI
+        except ImportError as exc:
+            raise RuntimeError(
+                "Le package 'openai' n'est pas installé. Lancez : pip install openai"
+            ) from exc
+
+        client = OpenAI(api_key=self._api_key)
+        temperature = float(self.config.get("temperature", 0.0))
+        max_tokens = int(self.config.get("max_tokens", 4096))
+
+        if image_b64:
+            content = [
+                {"type": "text", "text": prompt},
+                {
+                    "type": "image_url",
+                    "image_url": {"url": f"data:image/png;base64,{image_b64}"},
+                },
+            ]
+        else:
+            content = prompt  # type: ignore[assignment]
+
+        try:
+            response = client.chat.completions.create(
+                model=self.model,
+                messages=[{"role": "user", "content": content}],
+                temperature=temperature,
+                max_tokens=max_tokens,
+            )
+        except Exception as exc:
+            log_http_error(
+                "OpenAIAdapter", self.model, exc,
+                env_var=self.api_key_env_var,
+            )
+            raise
+
+        if not response.choices:
+            logger.warning(
+                "[OpenAIAdapter] response.choices vide (modèle=%s).", self.model,
+            )
+            return ""
+        # Chantier 4 — propagation du fix Sprint 15 : le SDK OpenAI
+        # peut retourner une ``list[ContentBlock]`` selon l'API
+        # (Responses, structured outputs).  ``normalize_llm_content``
+        # gère les deux cas (str et list).
+        return normalize_llm_content(response.choices[0].message.content)

picarones/adapters/ocr/__init__.py

@@ -0,0 +1,39 @@
+"""Adapters OCR du nouveau monde — Sprint A14-S26.
+
+Contrat ``BaseOCRAdapter`` natif au rewrite : pas hérité du legacy
+``picarones.engines.base.BaseOCREngine``, exprimé directement en
+termes du nouveau ``ArtifactType`` et de l'interface
+``execute(inputs, params, context)`` du ``PipelineExecutor``.
+
+Implémentations livrées
+-----------------------
+- ``PrecomputedTextAdapter`` — lit un texte OCR pré-calculé depuis
+  le filesystem.  Cas BnF : comparer N transcriptions déjà produites
+  par d'autres outils sans relancer d'OCR.
+
+Adapters concrets pour Tesseract / Pero OCR / Mistral OCR / Google
+Vision / Azure DI : à écrire au cas par cas dans des sprints
+dédiés, **natifs** au nouveau contrat (pas de shim sur le legacy
+``picarones.engines``).
+"""
+
+from __future__ import annotations
+
+from picarones.adapters.ocr.azure_doc_intel import AzureDocIntelAdapter
+from picarones.adapters.ocr.base import BaseOCRAdapter, OCRAdapterError
+from picarones.adapters.ocr.google_vision import GoogleVisionAdapter
+from picarones.adapters.ocr.mistral_ocr import MistralOCRAdapter
+from picarones.adapters.ocr.pero_ocr import PeroOCRAdapter
+from picarones.adapters.ocr.precomputed import PrecomputedTextAdapter
+from picarones.adapters.ocr.tesseract import TesseractAdapter
+
+__all__ = [
+    "BaseOCRAdapter",
+    "OCRAdapterError",
+    "AzureDocIntelAdapter",
+    "GoogleVisionAdapter",
+    "MistralOCRAdapter",
+    "PeroOCRAdapter",
+    "PrecomputedTextAdapter",
+    "TesseractAdapter",
+]

picarones/adapters/ocr/azure_doc_intel.py

@@ -0,0 +1,376 @@
+"""``AzureDocIntelAdapter`` natif — Sprint A14-S34.
+
+Migration native du legacy ``picarones.engines.azure_doc_intel`` vers
+``BaseOCRAdapter`` (S26).  **Pas un shim**.
+
+Le legacy reste en place jusqu'au S46.
+
+Cas d'usage BnF
+---------------
+Azure Document Intelligence (anciennement Form Recognizer) propose
+plusieurs modèles préentraînés :
+
+- ``prebuilt-read`` (défaut) : lecture générique optimisée pour les
+  documents textuels denses.
+- ``prebuilt-document`` : extraction layout + champs.
+- ``prebuilt-layout`` : analyse de mise en page.
+- modèles personnalisés entraînés.
+
+L'API est asynchrone : on poste l'image et on poll un endpoint
+status jusqu'à obtenir le résultat.
+
+L'adapter route automatiquement vers SDK
+(``azure-ai-documentintelligence``) si disponible, sinon REST
+direct via ``urllib`` (avec polling).
+
+Configuration
+-------------
+Constructeur :
+
+- ``name`` (défaut ``"azure_doc_intel"``).
+- ``endpoint`` : URL de l'endpoint (overrides
+  ``AZURE_DOC_INTEL_ENDPOINT``).
+- ``api_key`` : clé API (overrides ``AZURE_DOC_INTEL_KEY``).
+- ``model_id`` (défaut ``"prebuilt-read"``).
+- ``locale`` (défaut ``"fr-FR"``).
+- ``api_version`` (défaut ``"2024-02-29-preview"``).
+- ``timeout_seconds`` (défaut 60) : timeout par requête HTTP.
+- ``max_polling_attempts`` (défaut 30) : nombre max de polls REST.
+- ``polling_interval_base`` (défaut 1.0) : intervalle de base entre
+  polls (incrémenté de 0.5s par tentative — backoff linéaire
+  identique au legacy).
+
+Comportement
+------------
+1. Valide IMAGE input.
+2. Résout endpoint + api_key (explicite > env).
+3. Tente le SDK ; sur ImportError, fallback REST.
+4. Pour le REST : POST → Operation-Location → poll jusqu'à
+   ``succeeded`` / ``failed`` / ``canceled``.
+5. Extrait le texte ligne par ligne dans l'ordre pages × lines.
+6. Écrit dans ``<stem>.<name>.txt`` à côté de l'image.
+
+Anti-sur-ingénierie
+-------------------
+- Pas d'extraction de confidences (legacy S51 — reportée).
+- Pas de support multi-langue dans une même requête.
+- Pas de retry au-delà du polling (qui est un retry implicite).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from picarones.adapters._retry import call_with_retry
+from picarones.adapters.ocr.base import BaseOCRAdapter, OCRAdapterError
+from picarones.adapters.output_paths import resolve_output_path
+from picarones.domain.artifacts import Artifact, ArtifactType
+
+
+class AzureDocIntelAdapter(BaseOCRAdapter):
+    """Adapter Azure Document Intelligence natif au contrat S26.
+
+    Parameters
+    ----------
+    name:
+        Identifiant lisible.  Défaut ``"azure_doc_intel"``.
+    endpoint:
+        URL Azure (override ``AZURE_DOC_INTEL_ENDPOINT``).
+    api_key:
+        Clé API Azure (override ``AZURE_DOC_INTEL_KEY``).
+    model_id:
+        ``"prebuilt-read"`` (défaut), ``"prebuilt-document"``,
+        ``"prebuilt-layout"``, ou un modèle entraîné personnalisé.
+    locale:
+        Locale Azure (défaut ``"fr-FR"``).
+    api_version:
+        Version d'API Azure (défaut ``"2024-02-29-preview"``).
+    timeout_seconds:
+        Timeout HTTP (défaut 60).
+    max_polling_attempts:
+        Nombre max de polls REST (défaut 30).
+    polling_interval_base:
+        Intervalle de base entre polls (défaut 1.0s, +0.5s/attempt).
+
+    Raises
+    ------
+    OCRAdapterError
+        Au constructeur si name invalide ou paramètres hors plage.
+    """
+
+    input_types = frozenset({ArtifactType.IMAGE})
+    output_types = frozenset({ArtifactType.RAW_TEXT})
+    execution_mode = "io"
+
+    def __init__(
+        self,
+        *,
+        name: str = "azure_doc_intel",
+        endpoint: str | None = None,
+        api_key: str | None = None,
+        model_id: str = "prebuilt-read",
+        locale: str = "fr-FR",
+        api_version: str = "2024-02-29-preview",
+        timeout_seconds: float = 60.0,
+        max_polling_attempts: int = 30,
+        polling_interval_base: float = 1.0,
+    ) -> None:
+        if not name or not name.strip():
+            raise OCRAdapterError(
+                "AzureDocIntelAdapter : name vide non autorisé.",
+            )
+        if not all(c.isalnum() or c in "_-" for c in name):
+            raise OCRAdapterError(
+                f"AzureDocIntelAdapter : name invalide {name!r} — "
+                "alphanumérique + _ - uniquement.",
+            )
+        if timeout_seconds <= 0:
+            raise OCRAdapterError(
+                f"AzureDocIntelAdapter : timeout_seconds doit être > 0, "
+                f"reçu {timeout_seconds}.",
+            )
+        if max_polling_attempts <= 0:
+            raise OCRAdapterError(
+                f"AzureDocIntelAdapter : max_polling_attempts doit être "
+                f"> 0, reçu {max_polling_attempts}.",
+            )
+        if polling_interval_base < 0:
+            raise OCRAdapterError(
+                f"AzureDocIntelAdapter : polling_interval_base doit être "
+                f">= 0, reçu {polling_interval_base}.",
+            )
+        self._name = name
+        self._explicit_endpoint = endpoint
+        self._explicit_api_key = api_key
+        self._model_id = model_id
+        self._locale = locale
+        self._api_version = api_version
+        self._timeout = timeout_seconds
+        self._max_polling_attempts = max_polling_attempts
+        self._polling_base = polling_interval_base
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def model_id(self) -> str:
+        return self._model_id
+
+    def _resolve_api_key(self) -> str:
+        key = self._explicit_api_key or os.environ.get("AZURE_DOC_INTEL_KEY")
+        if not key:
+            raise OCRAdapterError(
+                f"{self.name} : clé API Azure manquante. Définir "
+                "AZURE_DOC_INTEL_KEY ou passer api_key= au constructeur.",
+            )
+        return key
+
+    def _resolve_endpoint(self) -> str:
+        endpoint = (
+            self._explicit_endpoint
+            or os.environ.get("AZURE_DOC_INTEL_ENDPOINT", "")
+        ).rstrip("/")
+        if not endpoint:
+            raise OCRAdapterError(
+                f"{self.name} : endpoint Azure manquant. Définir "
+                "AZURE_DOC_INTEL_ENDPOINT ou passer endpoint= au "
+                "constructeur.",
+            )
+        return endpoint
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, Any],
+        context: Any,
+    ) -> dict[ArtifactType, Artifact]:
+        if ArtifactType.IMAGE not in inputs:
+            raise OCRAdapterError(
+                f"{self.name} : input IMAGE manquant.",
+            )
+        image_artifact = inputs[ArtifactType.IMAGE]
+        if image_artifact.uri is None:
+            raise OCRAdapterError(
+                f"{self.name} : artefact image "
+                f"{image_artifact.id!r} sans URI.",
+            )
+        image_path = Path(image_artifact.uri)
+        if not image_path.exists():
+            raise OCRAdapterError(
+                f"{self.name} : image introuvable {image_path!r}.",
+            )
+
+        api_key = self._resolve_api_key()
+        endpoint = self._resolve_endpoint()
+
+        # On tente le SDK d'abord ; sur ImportError, fallback REST.
+        try:
+            text = self._call_via_sdk(image_path, endpoint, api_key)
+        except _SDKMissing:
+            text = self._call_via_rest(image_path, endpoint, api_key)
+
+        text_path = resolve_output_path(
+            input_path=image_path,
+            adapter_name=self.name,
+            suffix="txt",
+            context=context,
+        )
+        text_path.write_text(text, encoding="utf-8")
+
+        return {
+            ArtifactType.RAW_TEXT: Artifact(
+                id=f"{context.document_id}:{self.name}:raw_text",
+                document_id=context.document_id,
+                type=ArtifactType.RAW_TEXT,
+                produced_by_step="ocr",
+                uri=str(text_path),
+            ),
+        }
+
+    # ──────────────────────────────────────────────────────────────
+    # SDK
+    # ──────────────────────────────────────────────────────────────
+
+    def _call_via_sdk(
+        self, image_path: Path, endpoint: str, api_key: str,
+    ) -> str:
+        try:
+            from azure.ai.documentintelligence import (
+                DocumentIntelligenceClient,
+            )
+            from azure.core.credentials import AzureKeyCredential
+        except ImportError as exc:
+            raise _SDKMissing() from exc
+
+        try:
+            client = DocumentIntelligenceClient(
+                endpoint=endpoint,
+                credential=AzureKeyCredential(api_key),
+            )
+            with open(image_path, "rb") as f:
+                poller = client.begin_analyze_document(
+                    model_id=self._model_id,
+                    body=f,
+                    locale=self._locale,
+                    content_type="application/octet-stream",
+                )
+            result = poller.result()
+            text = "\n".join(
+                line.content
+                for page in result.pages
+                for line in (page.lines or [])
+            )
+        except _SDKMissing:
+            raise
+        except Exception as exc:
+            raise OCRAdapterError(
+                f"{self.name} : SDK Azure a levé : "
+                f"{type(exc).__name__}: {exc}",
+            ) from exc
+        return text
+
+    # ──────────────────────────────────────────────────────────────
+    # REST avec polling
+    # ──────────────────────────────────────────────────────────────
+
+    def _call_via_rest(
+        self, image_path: Path, endpoint: str, api_key: str,
+    ) -> str:
+        image_bytes = image_path.read_bytes()
+        analyze_url = (
+            f"{endpoint}/documentintelligence/documentModels/"
+            f"{self._model_id}:analyze"
+            f"?api-version={self._api_version}&locale={self._locale}"
+        )
+        req = urllib.request.Request(
+            analyze_url,
+            data=image_bytes,
+            headers={
+                "Ocp-Apim-Subscription-Key": api_key,
+                "Content-Type": "application/octet-stream",
+            },
+        )
+        def _do_post() -> str:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                return resp.headers.get("Operation-Location", "")
+
+        try:
+            operation_url = call_with_retry(_do_post, label=self.name)
+        except urllib.error.HTTPError as exc:
+            body = ""
+            try:
+                body = exc.read().decode("utf-8")
+            except Exception:  # noqa: BLE001
+                pass
+            raise OCRAdapterError(
+                f"{self.name} : Azure Document Intelligence erreur "
+                f"{exc.code} : {body}",
+            ) from exc
+        except Exception as exc:
+            raise OCRAdapterError(
+                f"{self.name} : erreur API Azure : "
+                f"{type(exc).__name__}: {exc}",
+            ) from exc
+
+        if not operation_url:
+            raise OCRAdapterError(
+                f"{self.name} : Azure n'a pas retourné Operation-Location.",
+            )
+
+        # Polling du résultat (Azure asynchrone).
+        headers = {"Ocp-Apim-Subscription-Key": api_key}
+        for attempt in range(self._max_polling_attempts):
+            time.sleep(self._polling_base + attempt * 0.5)
+            poll_req = urllib.request.Request(operation_url, headers=headers)
+            try:
+                with urllib.request.urlopen(
+                    poll_req, timeout=self._timeout,
+                ) as resp:
+                    result = json.loads(resp.read().decode("utf-8"))
+            except Exception as exc:
+                raise OCRAdapterError(
+                    f"{self.name} : erreur de polling Azure : "
+                    f"{type(exc).__name__}: {exc}",
+                ) from exc
+            status = result.get("status", "")
+            if status == "succeeded":
+                return self._extract_text_from_rest_result(result)
+            if status in {"failed", "canceled"}:
+                raise OCRAdapterError(
+                    f"{self.name} : analyse Azure {status} : "
+                    f"{result.get('error', {})}",
+                )
+            # running → continue
+        raise OCRAdapterError(
+            f"{self.name} : timeout polling Azure après "
+            f"{self._max_polling_attempts} tentatives.",
+        )
+
+    @staticmethod
+    def _extract_text_from_rest_result(result: dict) -> str:
+        pages = result.get("analyzeResult", {}).get("pages", [])
+        lines: list[str] = []
+        for page in pages:
+            for line in page.get("lines", []):
+                content = line.get("content", "")
+                if content:
+                    lines.append(content)
+        return "\n".join(lines)
+
+
+class _SDKMissing(Exception):
+    """Sentinel interne pour signaler que le SDK Azure n'est pas
+    installé.  Capturé par ``execute`` pour fallback REST.
+
+    Ne fuit jamais au caller — c'est un détail d'implémentation.
+    """
+
+
+__all__ = ["AzureDocIntelAdapter"]

picarones/adapters/ocr/base.py

@@ -0,0 +1,173 @@
+"""``BaseOCRAdapter`` — contrat natif du nouveau monde pour un adapter OCR.
+
+Sprint A14-S26 du rewrite ciblé.
+
+Ce module définit le contrat **propre** auquel un adapter OCR du
+nouveau monde doit se conformer pour être utilisable comme step
+d'une pipeline ``picarones.pipeline``.  Pas hérité du legacy
+``picarones.engines.base.BaseOCREngine`` — c'est un nouveau contrat,
+sans dette technique, exprimé en termes du nouveau ``ArtifactType``.
+
+Contrat
+-------
+Un adapter OCR :
+
+- Déclare ses ``input_types`` (typiquement
+  ``frozenset({ArtifactType.IMAGE})``).
+- Déclare ses ``output_types`` (typiquement
+  ``frozenset({ArtifactType.RAW_TEXT})``, ou plus pour les moteurs
+  structurés).
+- Déclare son ``execution_mode`` : ``"io"`` (défaut, ThreadPool) ou
+  ``"cpu"`` (ProcessPool).
+- Implémente
+  ``execute(inputs, params, context) -> dict[ArtifactType, Artifact]``.
+
+Le ``Artifact`` retourné porte une ``uri`` filesystem — c'est la
+convention du nouveau monde pour permettre au ``payload_loader`` de
+le lire ultérieurement (Sprint S25 — la projection a un payload
+direct, mais les artefacts produits par les adapters sont stockés
+sur disque pour traçabilité et streaming).
+
+Différences avec le legacy
+--------------------------
+- ``ArtifactType.RAW_TEXT`` (10 valeurs) au lieu de
+  ``ArtifactType.TEXT`` (6 valeurs legacy).
+- Pas de ``run(image_path)`` historique — un seul point d'entrée
+  ``execute()``.
+- Pas de wrapper ``EngineResult`` — les erreurs lèvent directement,
+  le ``PipelineExecutor`` les capture en step en échec.
+- Pas de ``_run_ocr`` / ``_run_with_native`` / ``_extract_raw_confidences``
+  — les confidences (S42 legacy) sont reportées à un sprint dédié
+  où l'on définira un ``ConfidenceArtifact`` typé.
+
+Anti-sur-ingénierie
+-------------------
+- Pas de hiérarchie d'erreurs.  Un adapter qui échoue lève
+  ``OCRAdapterError`` (ou laisse passer une exception).  Le
+  ``PipelineExecutor`` (S7) catch et marque le step en échec.
+- Pas de cache au niveau de l'ABC.  Si un adapter veut cacher ses
+  résultats, c'est dans son implémentation (compose ``ArtifactStore``
+  S7 si besoin).
+- Pas de retry.  Idem.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from picarones.domain.artifacts import Artifact, ArtifactType
+from picarones.domain.errors import AdapterStepError
+
+
+class OCRAdapterError(AdapterStepError):
+    """Erreur typée pour un échec d'adapter OCR du nouveau monde.
+
+    Hérite de ``AdapterStepError`` (racine commune avec LLM et VLM)
+    qui hérite de ``PicaronesError``.  Un caller peut catcher
+    ``AdapterStepError`` pour toute erreur d'adapter sans connaître
+    la sous-classe.
+
+    Le ``PipelineExecutor`` capture cette exception (et toute autre)
+    et marque le step correspondant comme failed avec
+    ``StepResult.error`` renseigné.  Les callers downstream
+    (``BenchmarkService``, vues) verront le pipeline en échec sans
+    crash global.
+    """
+
+
+class BaseOCRAdapter(ABC):
+    """Classe de base pour un adapter OCR du nouveau monde.
+
+    Toute sous-classe doit :
+
+    1. Surcharger la propriété ``name`` (identifiant lisible, utilisé
+       dans les ``Artifact.id`` et le run_manifest).
+    2. Implémenter ``execute(inputs, params, context)``.
+
+    Les attributs de classe ``input_types`` / ``output_types`` /
+    ``execution_mode`` sont fournis par défaut pour le cas le plus
+    courant (image → texte, IO-bound).  Une sous-classe qui produit
+    de l'ALTO surcharge ``output_types``, etc.
+
+    Exemple
+    -------
+
+    ::
+
+        class MyOCRAdapter(BaseOCRAdapter):
+            @property
+            def name(self) -> str:
+                return "my_ocr"
+
+            def execute(self, inputs, params, context):
+                image_artifact = inputs[ArtifactType.IMAGE]
+                # ... appel OCR sur image_artifact.uri ...
+                # ... écriture du résultat sur disque ...
+                return {
+                    ArtifactType.RAW_TEXT: Artifact(
+                        id=f"{context.document_id}:{self.name}:raw_text",
+                        document_id=context.document_id,
+                        type=ArtifactType.RAW_TEXT,
+                        produced_by_step="ocr",
+                        uri=str(out_path),
+                    ),
+                }
+    """
+
+    #: Types d'artefacts attendus en entrée.  Le ``PipelineExecutor``
+    #: utilise cette info pour valider la compatibilité des steps
+    #: enchaînés.
+    input_types: frozenset[ArtifactType] = frozenset({ArtifactType.IMAGE})
+
+    #: Types d'artefacts produits.  Validés à la sortie de ``execute``.
+    output_types: frozenset[ArtifactType] = frozenset({ArtifactType.RAW_TEXT})
+
+    #: ``"io"`` (ThreadPool) ou ``"cpu"`` (ProcessPool).  Indique au
+    #: runner quel type de pool utiliser pour la concurrence.
+    execution_mode: str = "io"
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Identifiant lisible de l'adapter (ex : ``"tesseract"``,
+        ``"precomputed_text"``).  Utilisé dans les ``Artifact.id`` du
+        nouveau monde et dans le ``run_manifest``."""
+
+    @abstractmethod
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, Any],
+        context: Any,
+    ) -> dict[ArtifactType, Artifact]:
+        """Exécute l'OCR sur les entrées et retourne les artefacts produits.
+
+        Parameters
+        ----------
+        inputs:
+            Map ``ArtifactType → Artifact`` avec au minimum les types
+            déclarés dans ``self.input_types``.  L'adapter peut
+            ignorer les entrées surnuméraires.
+        params:
+            Paramètres dynamiques du step (typiquement vides — la
+            configuration de l'adapter passe par son constructeur).
+        context:
+            ``RunContext`` du run en cours (porte ``document_id``,
+            ``code_version``, ``pipeline_name``).
+
+        Returns
+        -------
+        dict[ArtifactType, Artifact]
+            Map des artefacts produits.  Doit contenir au moins les
+            types déclarés dans ``self.output_types``.
+
+        Raises
+        ------
+        OCRAdapterError
+            Erreur typée pour signaler un échec côté adapter (input
+            invalide, fichier introuvable, etc.).
+        """
+
+
+__all__ = ["BaseOCRAdapter", "OCRAdapterError"]

picarones/adapters/ocr/confidences.py

@@ -0,0 +1,164 @@
+"""Sidecar de confidences OCR.
+
+Les confidences au niveau token sont exposées comme un **artefact
+dédié** ``ArtifactType.CONFIDENCES`` (sidecar JSON à côté du fichier
+texte), pas stuffé dans le résultat texte de l'adapter.  Ce
+découplage permet aux vues de calibration (ECE/MCE, reliability
+diagram) de consommer les confidences indépendamment de la
+production du texte, et n'oblige pas un adapter qui n'a pas de
+confidences à porter un champ vide.
+
+Format JSON canonique
+---------------------
+
+::
+
+    {
+      "tokens": [
+        {"text": "Bonjour", "confidence": 0.95},
+        {"text": "le",      "confidence": 0.99},
+        ...
+      ],
+      "extractor": "tesseract",
+      "model_version": "5.3.0"  // optionnel
+    }
+
+- ``confidence`` ∈ [0, 1] (les adapters convertissent eux-mêmes
+  depuis leur format natif — Tesseract retourne 0-100, on divise
+  par 100).
+- Tokens vides ou conf négatives ignorés à la source (cf.
+  ``filter_valid_tokens``).
+
+API publique
+------------
+- ``filter_valid_tokens(raw)`` : nettoie une liste de dicts brutes.
+- ``write_confidences_sidecar(text_path, name, tokens, ...)`` :
+  écrit ``<stem>.<name>.confidences.json`` à côté du fichier texte.
+- ``ConfidenceToken`` (TypedDict léger) : forme attendue du dict.
+
+Anti-sur-ingénierie
+-------------------
+- Pas de pydantic — TypedDict + json suffisent ; le caller normalise.
+- Pas de schéma JSON publié — la stabilité sera tagguée à la livraison.
+- Pas de support pour les confidences niveau ligne / paragraphe :
+  on aplatit tout au niveau mot (cohérent avec le legacy Sprint 47).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, TypedDict
+
+from picarones.domain.artifacts import Artifact, ArtifactType
+
+
+class ConfidenceToken(TypedDict):
+    """Forme canonique d'un token de confidence."""
+
+    text: str
+    confidence: float
+
+
+def filter_valid_tokens(
+    raw: list[dict[str, Any]],
+) -> list[ConfidenceToken]:
+    """Nettoie une liste brute de tokens (ignore les non-mots).
+
+    Filtre :
+
+    - ``text`` vide ou whitespace-only ;
+    - ``confidence`` ``None`` ou négative (Tesseract met -1 pour les
+      non-mots) ;
+    - ``confidence`` > 1.0 → divisé par 100 si ≤ 100, sinon ignoré.
+
+    Retourne une nouvelle liste, ne modifie pas l'input.
+    """
+    out: list[ConfidenceToken] = []
+    for entry in raw:
+        text = str(entry.get("text", "") or "").strip()
+        if not text:
+            continue
+        conf = entry.get("confidence")
+        if conf is None:
+            continue
+        try:
+            conf_f = float(conf)
+        except (TypeError, ValueError):
+            continue
+        if conf_f < 0:
+            continue
+        if conf_f > 1.0:
+            # Tesseract retourne 0-100 ; on normalise.
+            if conf_f <= 100.0:
+                conf_f = conf_f / 100.0
+            else:
+                # > 100 = donnée corrompue, on ignore.
+                continue
+        out.append({"text": text, "confidence": conf_f})
+    return out
+
+
+def write_confidences_sidecar(
+    text_path: Path,
+    adapter_name: str,
+    tokens: list[ConfidenceToken],
+    *,
+    document_id: str,
+    extractor: str | None = None,
+    model_version: str | None = None,
+) -> Artifact:
+    """Écrit un sidecar JSON ``<stem>.<adapter_name>.confidences.json``
+    à côté du fichier texte produit par l'OCR.
+
+    Returns
+    -------
+    Artifact
+        Artifact ``CONFIDENCES`` avec ``uri`` pointant vers le sidecar.
+    """
+    sidecar_path = (
+        text_path.parent
+        / f"{text_path.stem}.{adapter_name}.confidences.json"
+    )
+    payload = {
+        "tokens": tokens,
+        "extractor": extractor or adapter_name,
+        "model_version": model_version,
+    }
+    # Écriture atomique : un crash mi-write ne doit pas laisser un
+    # sidecar tronqué (qui ferait planter le parser à la lecture).
+    # ``tempfile`` dans le même répertoire pour garantir que
+    # ``os.replace`` reste atomique (rename inter-volume échouerait).
+    encoded = json.dumps(payload, ensure_ascii=False, indent=2)
+    fd, tmp_name = tempfile.mkstemp(
+        prefix=f".{sidecar_path.name}.",
+        suffix=".tmp",
+        dir=str(sidecar_path.parent),
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(encoded)
+        os.replace(tmp_name, sidecar_path)
+    except Exception:
+        # Best-effort cleanup du tmp si le replace n'a pas eu lieu.
+        try:
+            os.unlink(tmp_name)
+        except OSError:
+            pass
+        raise
+    return Artifact(
+        id=f"{document_id}:{adapter_name}:confidences",
+        document_id=document_id,
+        type=ArtifactType.CONFIDENCES,
+        produced_by_step="ocr",
+        uri=str(sidecar_path),
+    )
+
+
+__all__ = [
+    "ConfidenceToken",
+    "filter_valid_tokens",
+    "write_confidences_sidecar",
+]

picarones/adapters/ocr/google_vision.py

@@ -0,0 +1,306 @@
+"""``GoogleVisionAdapter`` natif — Sprint A14-S33.
+
+Migration native du legacy ``picarones.engines.google_vision.GoogleVisionEngine``
+vers le contrat ``BaseOCRAdapter`` (S26).  **Pas un shim**.
+
+Le legacy reste en place jusqu'au S46.
+
+Cas d'usage BnF
+---------------
+Google Cloud Vision propose deux modes d'OCR :
+
+- ``DOCUMENT_TEXT_DETECTION`` (défaut) : optimisé pour les textes
+  denses et multilinguistiques — retourne une ``fullTextAnnotation``
+  hiérarchique (pages → blocks → paragraphs → words → symbols) avec
+  un texte plat ``text``.
+- ``TEXT_DETECTION`` : mode court, retourne uniquement les
+  ``textAnnotations[0].description``.
+
+L'adapter route automatiquement vers SDK (auth service account) ou
+REST direct (auth clé API) selon la configuration disponible.
+
+Configuration
+-------------
+Constructeur :
+
+- ``name`` (défaut ``"google_vision"``).
+- ``language_hints`` (défaut ``["fr"]``) : suggestions Vision API.
+- ``feature_type`` (défaut ``"DOCUMENT_TEXT_DETECTION"``).
+- ``api_key`` : clé API Google.  Si ``None``, lit ``GOOGLE_API_KEY``.
+- ``credentials_path`` : chemin vers un service account JSON.  Si
+  ``None``, lit ``GOOGLE_APPLICATION_CREDENTIALS``.
+- ``timeout_seconds`` (défaut 60).
+
+Au moins une des deux authentifications (SDK ou REST) doit être
+disponible.
+
+Anti-sur-ingénierie
+-------------------
+- Pas d'extraction de confidences (legacy S50 — reportée).
+- Pas de pré-validation du JSON service account — le SDK le fait.
+- Pas de support batch — un appel par image.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from picarones.adapters._retry import call_with_retry
+from picarones.adapters.ocr.base import BaseOCRAdapter, OCRAdapterError
+from picarones.adapters.output_paths import resolve_output_path
+from picarones.domain.artifacts import Artifact, ArtifactType
+
+
+_VALID_FEATURE_TYPES = frozenset({"DOCUMENT_TEXT_DETECTION", "TEXT_DETECTION"})
+
+
+class GoogleVisionAdapter(BaseOCRAdapter):
+    """Adapter Google Cloud Vision natif au contrat S26.
+
+    Parameters
+    ----------
+    name:
+        Identifiant lisible.  Défaut ``"google_vision"``.
+    language_hints:
+        Suggestions Vision API.  Défaut ``["fr"]``.
+    feature_type:
+        ``"DOCUMENT_TEXT_DETECTION"`` (défaut) ou ``"TEXT_DETECTION"``.
+    api_key:
+        Clé API explicite.  Si ``None``, lit ``GOOGLE_API_KEY``.
+    credentials_path:
+        Chemin service account JSON explicite.  Si ``None``, lit
+        ``GOOGLE_APPLICATION_CREDENTIALS``.
+    timeout_seconds:
+        Timeout HTTP (REST).  Défaut 60.
+
+    Raises
+    ------
+    OCRAdapterError
+        Au constructeur si name ou feature_type invalides.
+    """
+
+    input_types = frozenset({ArtifactType.IMAGE})
+    output_types = frozenset({ArtifactType.RAW_TEXT})
+    execution_mode = "io"
+
+    def __init__(
+        self,
+        *,
+        name: str = "google_vision",
+        language_hints: list[str] | None = None,
+        feature_type: str = "DOCUMENT_TEXT_DETECTION",
+        api_key: str | None = None,
+        credentials_path: str | None = None,
+        timeout_seconds: float = 60.0,
+    ) -> None:
+        if not name or not name.strip():
+            raise OCRAdapterError(
+                "GoogleVisionAdapter : name vide non autorisé.",
+            )
+        if not all(c.isalnum() or c in "_-" for c in name):
+            raise OCRAdapterError(
+                f"GoogleVisionAdapter : name invalide {name!r} — "
+                "alphanumérique + _ - uniquement.",
+            )
+        if feature_type not in _VALID_FEATURE_TYPES:
+            raise OCRAdapterError(
+                f"GoogleVisionAdapter : feature_type invalide "
+                f"{feature_type!r}.  Valeurs valides : "
+                f"{sorted(_VALID_FEATURE_TYPES)}.",
+            )
+        if timeout_seconds <= 0:
+            raise OCRAdapterError(
+                f"GoogleVisionAdapter : timeout_seconds doit être > 0, "
+                f"reçu {timeout_seconds}.",
+            )
+        self._name = name
+        self._language_hints = list(language_hints or ["fr"])
+        self._feature_type = feature_type
+        self._explicit_api_key = api_key
+        self._explicit_credentials = credentials_path
+        self._timeout = timeout_seconds
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def feature_type(self) -> str:
+        return self._feature_type
+
+    def _resolve_credentials_path(self) -> str | None:
+        return self._explicit_credentials or os.environ.get(
+            "GOOGLE_APPLICATION_CREDENTIALS",
+        )
+
+    def _resolve_api_key(self) -> str | None:
+        return self._explicit_api_key or os.environ.get("GOOGLE_API_KEY")
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, Any],
+        context: Any,
+    ) -> dict[ArtifactType, Artifact]:
+        """Exécute Google Vision OCR sur l'image fournie.
+
+        Routing :
+
+        - Si un service account JSON est disponible
+          (``credentials_path`` ou ``GOOGLE_APPLICATION_CREDENTIALS``)
+          → passe par le SDK ``google-cloud-vision``.
+        - Sinon, si une clé API simple est disponible
+          (``api_key`` ou ``GOOGLE_API_KEY``) → passe par REST direct
+          via ``urllib``.
+        - Sinon → ``OCRAdapterError``.
+        """
+        if ArtifactType.IMAGE not in inputs:
+            raise OCRAdapterError(
+                f"{self.name} : input IMAGE manquant.",
+            )
+        image_artifact = inputs[ArtifactType.IMAGE]
+        if image_artifact.uri is None:
+            raise OCRAdapterError(
+                f"{self.name} : artefact image "
+                f"{image_artifact.id!r} sans URI.",
+            )
+        image_path = Path(image_artifact.uri)
+        if not image_path.exists():
+            raise OCRAdapterError(
+                f"{self.name} : image introuvable {image_path!r}.",
+            )
+
+        creds = self._resolve_credentials_path()
+        api_key = self._resolve_api_key()
+
+        if creds:
+            text = self._call_via_sdk(image_path)
+        elif api_key:
+            text = self._call_via_rest(image_path, api_key)
+        else:
+            raise OCRAdapterError(
+                f"{self.name} : authentification manquante. Définir "
+                "GOOGLE_APPLICATION_CREDENTIALS (service account JSON) "
+                "ou GOOGLE_API_KEY.",
+            )
+
+        text_path = resolve_output_path(
+            input_path=image_path,
+            adapter_name=self.name,
+            suffix="txt",
+            context=context,
+        )
+        text_path.write_text(text, encoding="utf-8")
+
+        return {
+            ArtifactType.RAW_TEXT: Artifact(
+                id=f"{context.document_id}:{self.name}:raw_text",
+                document_id=context.document_id,
+                type=ArtifactType.RAW_TEXT,
+                produced_by_step="ocr",
+                uri=str(text_path),
+            ),
+        }
+
+    # ──────────────────────────────────────────────────────────────
+    # SDK / REST
+    # ──────────────────────────────────────────────────────────────
+
+    def _call_via_sdk(self, image_path: Path) -> str:
+        try:
+            from google.cloud import vision
+        except ImportError as exc:
+            raise OCRAdapterError(
+                f"{self.name} : SDK google-cloud-vision non installé. "
+                "Installer avec : pip install google-cloud-vision",
+            ) from exc
+
+        try:
+            client = vision.ImageAnnotatorClient()
+            image = vision.Image(content=image_path.read_bytes())
+            ctx = vision.ImageContext(language_hints=self._language_hints)
+
+            if self._feature_type == "DOCUMENT_TEXT_DETECTION":
+                response = client.document_text_detection(
+                    image=image, image_context=ctx,
+                )
+                text = response.full_text_annotation.text
+            else:
+                response = client.text_detection(
+                    image=image, image_context=ctx,
+                )
+                texts = response.text_annotations
+                text = texts[0].description if texts else ""
+        except Exception as exc:
+            raise OCRAdapterError(
+                f"{self.name} : SDK Google Vision a levé : "
+                f"{type(exc).__name__}: {exc}",
+            ) from exc
+        return text
+
+    def _call_via_rest(self, image_path: Path, api_key: str) -> str:
+        image_b64 = base64.b64encode(
+            image_path.read_bytes(),
+        ).decode("ascii")
+        payload = json.dumps({
+            "requests": [{
+                "image": {"content": image_b64},
+                "features": [
+                    {"type": self._feature_type, "maxResults": 1},
+                ],
+                "imageContext": {"languageHints": self._language_hints},
+            }],
+        }).encode("utf-8")
+        req = urllib.request.Request(
+            "https://vision.googleapis.com/v1/images:annotate",
+            data=payload,
+            headers={
+                "Content-Type": "application/json",
+                "X-Goog-Api-Key": api_key,
+            },
+        )
+        def _do_call() -> dict:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+
+        try:
+            result = call_with_retry(_do_call, label=self.name)
+        except urllib.error.HTTPError as exc:
+            body = ""
+            try:
+                body = exc.read().decode("utf-8")
+            except Exception:  # noqa: BLE001
+                pass
+            raise OCRAdapterError(
+                f"{self.name} : Google Vision API erreur {exc.code} : {body}",
+            ) from exc
+        except Exception as exc:
+            raise OCRAdapterError(
+                f"{self.name} : erreur API Google Vision : "
+                f"{type(exc).__name__}: {exc}",
+            ) from exc
+
+        responses = result.get("responses", [{}])
+        if not responses:
+            return ""
+        r = responses[0]
+        if "error" in r:
+            raise OCRAdapterError(
+                f"{self.name} : Google Vision API erreur : {r['error']}",
+            )
+
+        if self._feature_type == "DOCUMENT_TEXT_DETECTION":
+            full = r.get("fullTextAnnotation") or {}
+            return full.get("text", "") if isinstance(full, dict) else ""
+        # TEXT_DETECTION
+        texts = r.get("textAnnotations", [])
+        return texts[0]["description"] if texts else ""
+
+
+__all__ = ["GoogleVisionAdapter"]

picarones/adapters/ocr/mistral_ocr.py

@@ -0,0 +1,336 @@
+"""``MistralOCRAdapter`` natif — Sprint A14-S32.
+
+Migration native du legacy ``picarones.engines.mistral_ocr.MistralOCREngine``
+vers le contrat ``BaseOCRAdapter`` (S26).  **Pas un shim** : la classe
+implémente directement le contrat du nouveau monde.
+
+Le legacy ``MistralOCREngine`` reste en place jusqu'au S46.
+
+Cas d'usage BnF
+---------------
+Mistral AI fournit deux familles d'OCR :
+
+- **API dédiée ``/v1/ocr``** pour les modèles ``mistral-ocr-*`` —
+  endpoint optimisé qui renvoie des pages structurées en markdown
+  (et parfois des confidences mot par mot).
+- **API vision/chat** pour les modèles ``pixtral-*`` —
+  reconnaissance via prompt textuel + image base64.
+
+L'adapter route automatiquement selon le nom du modèle.
+
+Configuration
+-------------
+Constructeur :
+
+- ``name`` (défaut ``"mistral_ocr"``) : identifiant de l'instance.
+- ``model`` (défaut ``"mistral-ocr-latest"``) : modèle Mistral.
+  - ``mistral-ocr-*`` → endpoint dédié ;
+  - ``pixtral-*`` → API vision/chat.
+- ``prompt`` : texte du prompt pour les modèles vision.  Défaut :
+  instruction générique de transcription.
+- ``max_tokens`` (défaut 4096) : limite tokens en sortie pour les
+  modèles vision.
+- ``api_key`` : clé API Mistral.  Si ``None`` (défaut), lit la
+  variable d'environnement ``MISTRAL_API_KEY``.
+- ``timeout_seconds`` (défaut 60) : timeout HTTP pour ``urllib``.
+
+Comportement
+------------
+1. Vérifie présence d'un ``Artifact`` ``IMAGE`` avec URI valide.
+2. Encode l'image en base64 + détecte ``image/...`` MIME selon
+   l'extension.
+3. Route vers ``/v1/ocr`` ou chat/vision selon ``model``.
+4. Concatène le markdown / texte de toutes les pages.
+5. Écrit dans ``<stem>.<name>.txt`` à côté de l'image.
+6. Retourne un ``Artifact`` ``RAW_TEXT``.
+
+Anti-sur-ingénierie
+-------------------
+- Pas de retry / backoff (le caller wrappe si besoin).
+- Pas d'extraction de confidences (legacy S49 — reportées au
+  sprint ``ConfidenceArtifact``).
+- Pas de support multi-page (l'image est traitée comme une seule
+  page d'entrée — Mistral OCR retourne une liste de pages dont on
+  concatène les markdowns).
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from picarones.adapters._retry import call_with_retry
+from picarones.adapters.ocr.base import BaseOCRAdapter, OCRAdapterError
+from picarones.adapters.output_paths import resolve_output_path
+from picarones.domain.artifacts import Artifact, ArtifactType
+
+
+_DEFAULT_PROMPT = (
+    "Transcris fidèlement le texte visible sur cette image de document "
+    "historique. Retourne uniquement le texte, sans commentaire."
+)
+
+
+_MEDIA_TYPES: dict[str, str] = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".tif": "image/tiff",
+    ".tiff": "image/tiff",
+    ".webp": "image/webp",
+}
+
+
+class MistralOCRAdapter(BaseOCRAdapter):
+    """Adapter Mistral OCR natif au contrat S26.
+
+    Parameters
+    ----------
+    name:
+        Identifiant lisible.  Défaut ``"mistral_ocr"``.
+    model:
+        Modèle Mistral.  ``mistral-ocr-*`` → API dédiée ``/v1/ocr``,
+        ``pixtral-*`` → API vision/chat.  Défaut ``"mistral-ocr-latest"``.
+    prompt:
+        Prompt pour les modèles vision.
+    max_tokens:
+        Limite tokens en sortie pour les modèles vision.  Défaut 4096.
+    api_key:
+        Clé API Mistral.  Si ``None`` (défaut), lit
+        ``MISTRAL_API_KEY``.
+    timeout_seconds:
+        Timeout HTTP pour les appels ``urllib``.  Défaut 60.
+
+    Raises
+    ------
+    OCRAdapterError
+        Si ``name`` est invalide au constructeur.
+    """
+
+    input_types = frozenset({ArtifactType.IMAGE})
+    output_types = frozenset({ArtifactType.RAW_TEXT})
+    execution_mode = "io"
+
+    def __init__(
+        self,
+        *,
+        name: str = "mistral_ocr",
+        model: str = "mistral-ocr-latest",
+        prompt: str = _DEFAULT_PROMPT,
+        max_tokens: int = 4096,
+        api_key: str | None = None,
+        timeout_seconds: float = 60.0,
+    ) -> None:
+        if not name or not name.strip():
+            raise OCRAdapterError(
+                "MistralOCRAdapter : name vide non autorisé.",
+            )
+        if not all(c.isalnum() or c in "_-" for c in name):
+            raise OCRAdapterError(
+                f"MistralOCRAdapter : name invalide {name!r} — "
+                "alphanumérique + _ - uniquement.",
+            )
+        if max_tokens <= 0:
+            raise OCRAdapterError(
+                f"MistralOCRAdapter : max_tokens doit être > 0, "
+                f"reçu {max_tokens}.",
+            )
+        if timeout_seconds <= 0:
+            raise OCRAdapterError(
+                f"MistralOCRAdapter : timeout_seconds doit être > 0, "
+                f"reçu {timeout_seconds}.",
+            )
+        self._name = name
+        self._model = model
+        self._prompt = prompt
+        self._max_tokens = max_tokens
+        self._explicit_api_key = api_key
+        self._timeout = timeout_seconds
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def model(self) -> str:
+        return self._model
+
+    def _resolve_api_key(self) -> str:
+        """Résout la clé API : explicite > env var.
+
+        Lève ``OCRAdapterError`` si aucune clé n'est disponible.
+        """
+        key = self._explicit_api_key or os.environ.get("MISTRAL_API_KEY")
+        if not key:
+            raise OCRAdapterError(
+                f"{self.name} : clé API Mistral manquante. "
+                "Définir MISTRAL_API_KEY ou passer api_key= au "
+                "constructeur.",
+            )
+        return key
+
+    def _encode_image(self, image_path: Path) -> str:
+        """Retourne ``data:<mime>;base64,<...>`` pour l'image."""
+        suffix = image_path.suffix.lower()
+        media_type = _MEDIA_TYPES.get(suffix, "image/jpeg")
+        image_b64 = base64.b64encode(image_path.read_bytes()).decode("ascii")
+        return f"data:{media_type};base64,{image_b64}"
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, Any],
+        context: Any,
+    ) -> dict[ArtifactType, Artifact]:
+        """Exécute Mistral OCR sur l'image fournie.
+
+        Route vers l'API appropriée selon ``self.model`` :
+        - ``mistral-ocr-*`` → ``/v1/ocr`` via ``urllib`` ;
+        - ``pixtral-*`` → API chat/vision via SDK ``mistralai``.
+
+        Raises
+        ------
+        OCRAdapterError
+            Erreur d'input, clé manquante, SDK absent (pour pixtral),
+            ou API Mistral en erreur.
+        """
+        if ArtifactType.IMAGE not in inputs:
+            raise OCRAdapterError(
+                f"{self.name} : input IMAGE manquant.",
+            )
+        image_artifact = inputs[ArtifactType.IMAGE]
+        if image_artifact.uri is None:
+            raise OCRAdapterError(
+                f"{self.name} : artefact image "
+                f"{image_artifact.id!r} sans URI.",
+            )
+        image_path = Path(image_artifact.uri)
+        if not image_path.exists():
+            raise OCRAdapterError(
+                f"{self.name} : image introuvable {image_path!r}.",
+            )
+
+        api_key = self._resolve_api_key()
+        image_url = self._encode_image(image_path)
+
+        # Le préfixe ``mistral-ocr-*`` est documenté par Mistral pour
+        # l'API dédiée ``/v1/ocr``.  Tout autre nom (``pixtral-*``,
+        # etc.) bascule sur l'API chat/vision.  Match strict par
+        # préfixe pour éviter qu'un modèle exotique nommé
+        # ``pixtral-MISTRAL-OCR-fancy`` ne soit confondu.
+        if self._model.lower().startswith("mistral-ocr"):
+            text = self._call_native_ocr_api(image_url, api_key)
+        else:
+            text = self._call_chat_vision_api(image_url, api_key)
+
+        text_path = resolve_output_path(
+            input_path=image_path,
+            adapter_name=self.name,
+            suffix="txt",
+            context=context,
+        )
+        text_path.write_text(text, encoding="utf-8")
+
+        return {
+            ArtifactType.RAW_TEXT: Artifact(
+                id=f"{context.document_id}:{self.name}:raw_text",
+                document_id=context.document_id,
+                type=ArtifactType.RAW_TEXT,
+                produced_by_step="ocr",
+                uri=str(text_path),
+            ),
+        }
+
+    # ──────────────────────────────────────────────────────────────
+    # API natives
+    # ──────────────────────────────────────────────────────────────
+
+    def _call_native_ocr_api(self, image_url: str, api_key: str) -> str:
+        """Appelle ``POST /v1/ocr`` via urllib et retourne le markdown
+        concaténé."""
+        payload = json.dumps({
+            "model": self._model,
+            "document": {"type": "image_url", "image_url": image_url},
+        }).encode("utf-8")
+        req = urllib.request.Request(
+            "https://api.mistral.ai/v1/ocr",
+            data=payload,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            method="POST",
+        )
+        def _do_call() -> dict:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                return json.loads(resp.read().decode())
+
+        try:
+            data = call_with_retry(_do_call, label=self.name)
+        except Exception as exc:
+            raise OCRAdapterError(
+                f"{self.name} : erreur API Mistral /v1/ocr : "
+                f"{type(exc).__name__}: {exc}",
+            ) from exc
+        pages = data.get("pages", [])
+        text = "\n\n".join(p.get("markdown", "") for p in pages).strip()
+        return text
+
+    def _call_chat_vision_api(self, image_url: str, api_key: str) -> str:
+        """Appelle l'API chat/vision Mistral via le SDK ``mistralai``."""
+        try:
+            try:
+                from mistralai.client import Mistral
+            except ImportError:
+                from mistralai import Mistral  # type: ignore[no-redef]
+        except ImportError as exc:
+            raise OCRAdapterError(
+                f"{self.name} : SDK 'mistralai' non installé. "
+                "Installer avec : pip install mistralai",
+            ) from exc
+
+        client = Mistral(api_key=api_key)
+
+        def _do_chat() -> Any:
+            return client.chat.complete(
+                model=self._model,
+                messages=[
+                    {
+                        "role": "user",
+                        "content": [
+                            {"type": "text", "text": self._prompt},
+                            {"type": "image_url", "image_url": image_url},
+                        ],
+                    },
+                ],
+                max_tokens=self._max_tokens,
+            )
+
+        try:
+            response = call_with_retry(_do_chat, label=self.name)
+        except Exception as exc:
+            raise OCRAdapterError(
+                f"{self.name} : erreur API Mistral chat : "
+                f"{type(exc).__name__}: {exc}",
+            ) from exc
+
+        # Mistral peut retourner ``content`` sous forme de
+        # ``list[ContentChunk]`` au lieu de ``str``.  Le helper
+        # ``normalize_llm_content`` gère les deux formats.
+        from picarones.adapters.llm.base import normalize_llm_content
+
+        try:
+            raw_content = response.choices[0].message.content
+        except (AttributeError, IndexError) as exc:
+            raise OCRAdapterError(
+                f"{self.name} : réponse Mistral chat malformée : {exc}",
+            ) from exc
+
+        return normalize_llm_content(raw_content) or ""
+
+
+__all__ = ["MistralOCRAdapter"]

picarones/adapters/ocr/pero_ocr.py

@@ -0,0 +1,232 @@
+"""``PeroOCRAdapter`` natif — Sprint A14-S31.
+
+Migration native du legacy ``picarones.engines.pero_ocr.PeroOCREngine``
+vers le contrat ``BaseOCRAdapter`` (S26).  **Pas un shim** : la classe
+implémente directement le contrat du nouveau monde, sans héritage du
+legacy.
+
+Le legacy ``PeroOCREngine`` reste en place pour les callers qui
+n'ont pas encore migré ; sa suppression viendra au S46 quand la
+parité sera atteinte sur tous les adapters.
+
+Cas d'usage BnF
+---------------
+Pero OCR (Brno) est un moteur HTR open-source spécialisé pour les
+documents historiques manuscrits.  Il produit une sortie structurée
+PAGE XML — l'adapter natif extrait le texte plat dans l'ordre de
+lecture naturel.  Adapter CPU-bound (PyTorch sur CPU + traitement
+d'image) → ``execution_mode="cpu"`` pour ProcessPool.
+
+Configuration
+-------------
+Constructeur :
+
+- ``name`` (défaut ``"pero_ocr"``) : identifiant de l'instance.
+- ``config_path`` : chemin obligatoire vers un fichier ``.ini`` de
+  configuration Pero OCR (modèles, paramètres).  Sans ça, Pero OCR
+  ne peut pas être instancié.
+
+Comportement
+------------
+1. Vérifie la présence d'un ``Artifact`` ``IMAGE`` avec URI valide.
+2. Lazy-import de ``pero_ocr`` + ``PIL`` + ``numpy`` — message
+   explicite si absent.
+3. Lazy-init du ``PageParser`` (une seule fois par instance).
+4. Charge l'image en numpy array RGB, instancie un ``PageLayout``,
+   appelle ``parser.process_page(image, page_layout)``.
+5. Extrait le texte plat (``\n`` entre lignes, dans l'ordre des
+   regions × lines).
+6. Écrit le texte dans ``<stem>.<name>.txt`` à côté de l'image.
+7. Retourne un ``Artifact`` ``RAW_TEXT``.
+
+Anti-sur-ingénierie
+-------------------
+- Pas de support GPU explicite (Pero OCR le gère via la config).
+- Pas de retry, pas d'extraction de confidences (legacy S48 —
+  reportées au sprint ``ConfidenceArtifact``).
+- ``_parser`` lazy-init — si l'instance est sérialisée pour
+  ProcessPool, le parser est re-instancié dans le worker (cohérent
+  avec Pero OCR qui charge ses modèles à l'instanciation).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from picarones.adapters.ocr.base import BaseOCRAdapter, OCRAdapterError
+from picarones.adapters.output_paths import resolve_output_path
+from picarones.domain.artifacts import Artifact, ArtifactType
+
+
+class PeroOCRAdapter(BaseOCRAdapter):
+    """Adapter Pero OCR natif au nouveau contrat (S26).
+
+    Parameters
+    ----------
+    name:
+        Identifiant lisible.  Défaut ``"pero_ocr"``.  Alphanum + ``_-``.
+    config_path:
+        Chemin vers le fichier ``.ini`` de configuration Pero OCR.
+        Obligatoire — sans configuration, Pero OCR ne peut pas être
+        instancié.
+
+    Raises
+    ------
+    OCRAdapterError
+        Si ``name`` ou ``config_path`` sont invalides au constructeur.
+    """
+
+    input_types = frozenset({ArtifactType.IMAGE})
+    output_types = frozenset({ArtifactType.RAW_TEXT})
+    execution_mode = "cpu"
+
+    def __init__(
+        self,
+        *,
+        config_path: str | Path,
+        name: str = "pero_ocr",
+    ) -> None:
+        if not name or not name.strip():
+            raise OCRAdapterError(
+                "PeroOCRAdapter : name vide non autorisé.",
+            )
+        if not all(c.isalnum() or c in "_-" for c in name):
+            raise OCRAdapterError(
+                f"PeroOCRAdapter : name invalide {name!r} — "
+                "alphanumérique + _ - uniquement.",
+            )
+        if not config_path:
+            raise OCRAdapterError(
+                "PeroOCRAdapter : config_path est requis (chemin .ini).",
+            )
+        self._name = name
+        self._config_path = Path(config_path)
+        # Le parser est instancié paresseusement au premier execute()
+        # pour que la sérialisation ProcessPool fonctionne (un parser
+        # contenant des modèles PyTorch n'est pas sérialisable).
+        self._parser: Any = None
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def config_path(self) -> Path:
+        return self._config_path
+
+    def _get_parser(self) -> Any:
+        """Instancie le PageParser au premier appel (lazy)."""
+        if self._parser is not None:
+            return self._parser
+
+        try:
+            from pero_ocr.document_ocr.page_parser import PageParser
+        except ImportError as exc:
+            raise OCRAdapterError(
+                f"{self.name} : pero-ocr non installé. "
+                "Installer avec : pip install pero-ocr",
+            ) from exc
+
+        if not self._config_path.exists():
+            raise OCRAdapterError(
+                f"{self.name} : config_path introuvable "
+                f"{self._config_path!r}.",
+            )
+
+        import configparser
+        parser_config = configparser.ConfigParser()
+        parser_config.read(self._config_path)
+        try:
+            self._parser = PageParser(parser_config)
+        except Exception as exc:
+            raise OCRAdapterError(
+                f"{self.name} : initialisation PageParser échouée "
+                f"({type(exc).__name__}: {exc}).",
+            ) from exc
+        return self._parser
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, Any],
+        context: Any,
+    ) -> dict[ArtifactType, Artifact]:
+        """Exécute Pero OCR sur l'image fournie.
+
+        Raises
+        ------
+        OCRAdapterError
+            Si l'input est invalide, l'image introuvable, les
+            dépendances manquantes, ou Pero OCR lève en interne.
+        """
+        if ArtifactType.IMAGE not in inputs:
+            raise OCRAdapterError(
+                f"{self.name} : input IMAGE manquant.",
+            )
+        image_artifact = inputs[ArtifactType.IMAGE]
+        if image_artifact.uri is None:
+            raise OCRAdapterError(
+                f"{self.name} : artefact image "
+                f"{image_artifact.id!r} sans URI.",
+            )
+        image_path = Path(image_artifact.uri)
+        if not image_path.exists():
+            raise OCRAdapterError(
+                f"{self.name} : image introuvable {image_path!r}.",
+            )
+
+        try:
+            import numpy as np
+            from PIL import Image
+            from pero_ocr.document_ocr.layout import PageLayout
+        except ImportError as exc:
+            raise OCRAdapterError(
+                f"{self.name} : pero-ocr/numpy/Pillow non installés. "
+                "Installer avec : pip install pero-ocr pillow numpy",
+            ) from exc
+
+        parser = self._get_parser()
+
+        try:
+            with Image.open(image_path) as pil_image:
+                image_array = np.array(pil_image.convert("RGB"))
+            page_layout = PageLayout(
+                id=image_path.stem,
+                page_size=(image_array.shape[0], image_array.shape[1]),
+            )
+            parser.process_page(image_array, page_layout)
+        except Exception as exc:
+            raise OCRAdapterError(
+                f"{self.name} : Pero OCR a levé sur "
+                f"{image_path!r} : {type(exc).__name__}: {exc}",
+            ) from exc
+
+        # Extraction du texte plat dans l'ordre regions × lines.
+        lines: list[str] = []
+        for region in page_layout.regions:
+            for line in region.lines:
+                if line.transcription:
+                    lines.append(line.transcription.strip())
+        text = "\n".join(lines)
+
+        text_path = resolve_output_path(
+            input_path=image_path,
+            adapter_name=self.name,
+            suffix="txt",
+            context=context,
+        )
+        text_path.write_text(text, encoding="utf-8")
+
+        return {
+            ArtifactType.RAW_TEXT: Artifact(
+                id=f"{context.document_id}:{self.name}:raw_text",
+                document_id=context.document_id,
+                type=ArtifactType.RAW_TEXT,
+                produced_by_step="ocr",
+                uri=str(text_path),
+            ),
+        }
+
+
+__all__ = ["PeroOCRAdapter"]

picarones/adapters/ocr/precomputed.py

@@ -0,0 +1,219 @@
+"""``PrecomputedTextAdapter`` — premier adapter natif du nouveau monde.
+
+Sprint A14-S26 du rewrite ciblé.
+
+Cas d'usage BnF
+---------------
+*« J'ai déjà fait tourner Tesseract, GPT-4-vision, Pero OCR et un
+service cloud sur mon corpus.  J'ai 4 répertoires de fichiers
+``.txt`` à côté de mes images.  Je veux comparer ces 4 sorties dans
+Picarones — je n'ai pas besoin de re-lancer un OCR, j'ai juste besoin
+de la machinerie d'évaluation. »*
+
+Ce besoin est légitime et fréquent à la BnF : une part importante
+du travail de comparaison se fait sur des transcriptions déjà
+produites par d'autres outils.  Ré-exécuter un OCR à chaque
+benchmark est gaspillage.
+
+Convention de nommage
+---------------------
+Pour une image ``<stem>.png`` (ou ``.jpg``, ``.tif``, etc.), le
+texte pré-calculé est lu depuis :
+
+::
+
+    <stem>.<source_label>.txt
+
+dans le **même répertoire** que l'image.  Exemple avec deux
+sources concurrentes :
+
+::
+
+    folio_001.png
+    folio_001.tesseract.txt    # produit par Tesseract
+    folio_001.pero.txt         # produit par Pero OCR
+    folio_001.gpt4v.txt        # produit par GPT-4 Vision
+    folio_001.gt.txt           # vérité terrain
+
+Plusieurs ``PrecomputedTextAdapter`` peuvent coexister dans une
+même YAML avec des ``source_label`` distincts — chacun lit son
+propre fichier, le ``BenchmarkService`` les traite en parallèle.
+
+Configuration YAML
+------------------
+
+::
+
+    pipelines:
+      - name: tesseract_baseline
+        initial_inputs: [image]
+        steps:
+          - id: ocr
+            adapter_class: picarones.adapters.ocr.precomputed.PrecomputedTextAdapter
+            adapter_kwargs:
+              source_label: tesseract
+            input_types: [image]
+            output_types: [raw_text]
+
+      - name: gpt4v_alternative
+        initial_inputs: [image]
+        steps:
+          - id: ocr
+            adapter_class: picarones.adapters.ocr.precomputed.PrecomputedTextAdapter
+            adapter_kwargs:
+              source_label: gpt4v
+            input_types: [image]
+            output_types: [raw_text]
+
+Comportement « fichier manquant »
+---------------------------------
+Par défaut, si le fichier ``<stem>.<source_label>.txt`` est absent,
+l'adapter lève ``OCRAdapterError`` — le pipeline executor marque le
+step comme failed pour ce document, et le ``BenchmarkService`` le
+voit en ``failed_metrics``.  Pas de fallback silencieux qui
+mentirait sur la couverture du benchmark.
+
+L'option ``missing_text_policy="empty"`` permet, à la demande
+explicite du caller, de remplacer un fichier absent par une chaîne
+vide — utile pour mesurer ce qui se passerait si une source était
+indisponible sur certains documents.  Par défaut : ``"raise"``.
+
+Anti-sur-ingénierie
+-------------------
+- Pas de découverte automatique de tous les ``source_label``
+  présents dans un répertoire.  Le caller déclare explicitement
+  les sources qu'il veut comparer.
+- Pas de cache.  Le filesystem fait son boulot.
+- Pas de validation d'encodage exotique.  ``utf-8`` strict ; un
+  fichier mal encodé lève une erreur lisible.
+- Pas d'extraction structurelle.  Cet adapter sort du ``RAW_TEXT``,
+  point.  Pour comparer des ALTO_XML pré-calculés, c'est un
+  ``PrecomputedAltoAdapter`` futur (pattern identique).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+from picarones.adapters.ocr.base import BaseOCRAdapter, OCRAdapterError
+from picarones.domain.artifacts import Artifact, ArtifactType
+
+
+class PrecomputedTextAdapter(BaseOCRAdapter):
+    """Adapter qui lit du texte OCR pré-calculé depuis le filesystem.
+
+    Parameters
+    ----------
+    source_label:
+        Étiquette identifiant la source du texte pré-calculé
+        (ex : ``"tesseract"``, ``"gpt4v"``, ``"pero"``).  Doit être
+        composée uniquement de caractères alphanumériques, ``_`` et
+        ``-`` — c'est un composant de nom de fichier.
+    missing_text_policy:
+        ``"raise"`` (défaut) → fichier absent lève ``OCRAdapterError``.
+        ``"empty"`` → fichier absent remplacé par chaîne vide
+        (l'adapter produit alors un ``Artifact`` pointant sur un
+        fichier vide).
+
+    Raises
+    ------
+    OCRAdapterError
+        Si ``source_label`` est invalide.
+    """
+
+    input_types = frozenset({ArtifactType.IMAGE})
+    output_types = frozenset({ArtifactType.RAW_TEXT})
+    execution_mode = "io"
+
+    def __init__(
+        self,
+        *,
+        source_label: str,
+        missing_text_policy: Literal["raise", "empty"] = "raise",
+    ) -> None:
+        if not source_label or not source_label.strip():
+            raise OCRAdapterError(
+                "PrecomputedTextAdapter : source_label vide.",
+            )
+        if not all(
+            c.isalnum() or c in "_-" for c in source_label
+        ):
+            raise OCRAdapterError(
+                f"PrecomputedTextAdapter : source_label invalide "
+                f"{source_label!r} — alphanumérique + _ - uniquement.",
+            )
+        if missing_text_policy not in ("raise", "empty"):
+            raise OCRAdapterError(
+                f"missing_text_policy doit être 'raise' ou 'empty', "
+                f"reçu {missing_text_policy!r}.",
+            )
+        self._source_label = source_label
+        self._missing_policy = missing_text_policy
+
+    @property
+    def name(self) -> str:
+        return f"precomputed_{self._source_label}"
+
+    @property
+    def source_label(self) -> str:
+        return self._source_label
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, Any],
+        context: Any,
+    ) -> dict[ArtifactType, Artifact]:
+        if ArtifactType.IMAGE not in inputs:
+            raise OCRAdapterError(
+                f"{self.name} : input IMAGE manquant.",
+            )
+        image_artifact = inputs[ArtifactType.IMAGE]
+        if image_artifact.uri is None:
+            raise OCRAdapterError(
+                f"{self.name} : artefact image "
+                f"{image_artifact.id!r} sans URI.",
+            )
+
+        image_path = Path(image_artifact.uri)
+        text_path = (
+            image_path.parent / f"{image_path.stem}.{self._source_label}.txt"
+        )
+
+        if not text_path.exists():
+            if self._missing_policy == "empty":
+                # On crée le fichier vide pour rester cohérent : tout
+                # ``Artifact`` produit a une URI vers un fichier
+                # lisible.
+                text_path.write_text("", encoding="utf-8")
+            else:
+                raise OCRAdapterError(
+                    f"{self.name} : fichier pré-calculé introuvable "
+                    f"pour {image_path.name!r} : "
+                    f"{text_path.name!r} attendu dans "
+                    f"{image_path.parent!r}.",
+                )
+
+        # Validation rapide de l'encodage UTF-8 (lecture qui leverait
+        # si encodage exotique).
+        try:
+            text_path.read_text(encoding="utf-8")
+        except UnicodeDecodeError as exc:
+            raise OCRAdapterError(
+                f"{self.name} : {text_path!r} n'est pas en UTF-8 : "
+                f"{exc}",
+            ) from exc
+
+        return {
+            ArtifactType.RAW_TEXT: Artifact(
+                id=f"{context.document_id}:{self.name}:raw_text",
+                document_id=context.document_id,
+                type=ArtifactType.RAW_TEXT,
+                produced_by_step="ocr",
+                uri=str(text_path),
+            ),
+        }
+
+
+__all__ = ["PrecomputedTextAdapter"]

picarones/adapters/ocr/tesseract.py

@@ -0,0 +1,327 @@
+"""``TesseractAdapter`` natif — Sprint A14-S30.
+
+Migration native du legacy ``picarones.engines.tesseract.TesseractEngine``
+vers le contrat ``BaseOCRAdapter`` (S26).  **Pas un shim** : la classe
+implémente directement le contrat du nouveau monde, sans héritage du
+legacy.
+
+Le legacy ``TesseractEngine`` reste en place pour les callers qui
+n'ont pas encore migré ; sa suppression viendra au S46 quand la
+parité sera atteinte sur tous les adapters.
+
+Cas d'usage BnF
+---------------
+Tesseract 5 reste l'OCR open-source de référence pour les corpus
+imprimés et certains manuscrits réguliers.  L'adapter est CPU-bound
+(Tesseract appelle une lib C en sous-process) — déclaré
+``execution_mode="cpu"`` pour que le runner utilise un
+``ProcessPoolExecutor``.
+
+Configuration
+-------------
+Constructeur :
+
+- ``name`` (défaut ``"tesseract"``) : identifiant de l'instance.
+  Sert de suffixe au fichier de sortie ``<stem>.<name>.txt`` —
+  permet de coexister avec plusieurs configurations Tesseract dans
+  un même benchmark.
+- ``lang`` (défaut ``"fra"``) : code langue Tesseract (``"fra"``,
+  ``"lat"``, ``"eng"``, ``"fra+lat"``).
+- ``psm`` (défaut ``6``) : Page Segmentation Mode (0-13).
+- ``oem`` (défaut ``3``) : OCR Engine Mode.
+- ``tesseract_cmd`` (défaut ``None``) : chemin vers l'exécutable
+  ``tesseract`` si non standard.
+
+Comportement
+------------
+1. Vérifie qu'un ``Artifact`` ``IMAGE`` est présent dans ``inputs``
+   et qu'il porte une ``uri`` filesystem.
+2. Lazy-import de ``pytesseract`` et ``PIL`` — si absent, lève
+   ``OCRAdapterError`` avec message explicite.
+3. Applique ``tesseract_cmd`` s'il est fourni.
+4. Appelle ``pytesseract.image_to_string`` avec ``lang`` et
+   ``--oem N --psm M``.
+5. Écrit le texte dans ``<stem>.<name>.txt`` à côté de l'image
+   (cohérent avec le pattern ``PrecomputedTextAdapter`` — un caller
+   peut relire la sortie via cet adapter pour la comparer dans un
+   second run).
+6. Retourne un ``Artifact`` ``RAW_TEXT`` pointant vers le fichier
+   produit.
+
+Anti-sur-ingénierie
+-------------------
+- Pas de retry — Tesseract échoue rarement sur une image valide,
+  et un appelant peut wrapper si besoin.
+- Pas d'extraction de confidences (legacy S47) — reporté à un
+  sprint dédié qui définira ``ConfidenceArtifact`` typé.  La
+  fonctionnalité reste disponible via le legacy
+  ``picarones.engines.tesseract.TesseractEngine`` jusqu'au S46.
+- Pas de validation de l'encodage de l'image — Tesseract gère.
+- Pas de support batch — un appel par image (le runner gère le
+  parallélisme inter-documents).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from picarones.adapters.ocr.base import BaseOCRAdapter, OCRAdapterError
+from picarones.adapters.output_paths import resolve_output_path
+from picarones.domain.artifacts import Artifact, ArtifactType
+
+
+class TesseractAdapter(BaseOCRAdapter):
+    """Adapter Tesseract 5 natif au nouveau contrat (S26).
+
+    Parameters
+    ----------
+    name:
+        Identifiant lisible de l'instance.  Défaut ``"tesseract"``.
+        Doit être alphanumérique + ``_-`` (composant de nom de fichier).
+    lang:
+        Code langue Tesseract (``"fra"``, ``"lat"``, ``"eng"``, ...).
+        Défaut ``"fra"``.
+    psm:
+        Page Segmentation Mode entre 0 et 13.  Défaut 6
+        (single uniform block of text).
+    oem:
+        OCR Engine Mode (0-3).  Défaut 3 (LSTM, le plus précis).
+    tesseract_cmd:
+        Chemin custom vers l'exécutable ``tesseract``.  Défaut
+        ``None`` (laisse pytesseract trouver l'installation système).
+
+    Raises
+    ------
+    OCRAdapterError
+        Si le ``name`` ou les valeurs de ``psm`` / ``oem`` sont
+        invalides.
+    """
+
+    input_types = frozenset({ArtifactType.IMAGE})
+    #: Set maximal de types que l'adapter peut produire.  Le YAML
+    #: ``PipelineSpec`` choisit ceux qui sont effectivement consommés
+    #: par les étapes en aval ; l'executor filtre la sortie de
+    #: ``execute()`` sur ``step.output_types``.  Si l'utilisateur
+    #: désactive ``expose_confidences``, le YAML doit déclarer
+    #: ``output_types: [raw_text]`` (sinon la jonction sera vue par
+    #: l'aval comme manquant son input ``confidences``).
+    output_types = frozenset(
+        {ArtifactType.RAW_TEXT, ArtifactType.CONFIDENCES},
+    )
+    execution_mode = "cpu"
+
+    def __init__(
+        self,
+        *,
+        name: str = "tesseract",
+        lang: str = "fra",
+        psm: int = 6,
+        oem: int = 3,
+        tesseract_cmd: str | None = None,
+        expose_confidences: bool = True,
+    ) -> None:
+        if not name or not name.strip():
+            raise OCRAdapterError(
+                "TesseractAdapter : name vide non autorisé.",
+            )
+        if not all(c.isalnum() or c in "_-" for c in name):
+            raise OCRAdapterError(
+                f"TesseractAdapter : name invalide {name!r} — "
+                "alphanumérique + _ - uniquement.",
+            )
+        if not 0 <= psm <= 13:
+            raise OCRAdapterError(
+                f"TesseractAdapter : psm doit être ∈ [0, 13], reçu {psm}.",
+            )
+        if not 0 <= oem <= 3:
+            raise OCRAdapterError(
+                f"TesseractAdapter : oem doit être ∈ [0, 3], reçu {oem}.",
+            )
+        self._name = name
+        self._lang = lang
+        self._psm = psm
+        self._oem = oem
+        self._tesseract_cmd = tesseract_cmd
+        self._expose_confidences = expose_confidences
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def expose_confidences(self) -> bool:
+        return self._expose_confidences
+
+    @property
+    def lang(self) -> str:
+        return self._lang
+
+    @property
+    def psm(self) -> int:
+        return self._psm
+
+    @property
+    def oem(self) -> int:
+        return self._oem
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, Any],
+        context: Any,
+    ) -> dict[ArtifactType, Artifact]:
+        """Exécute Tesseract sur l'image fournie.
+
+        Raises
+        ------
+        OCRAdapterError
+            - input ``IMAGE`` absent ;
+            - artefact image sans URI ;
+            - fichier image introuvable ;
+            - ``pytesseract`` ou ``PIL`` non installé ;
+            - erreur Tesseract (lib system manquante, etc.).
+        """
+        if ArtifactType.IMAGE not in inputs:
+            raise OCRAdapterError(
+                f"{self.name} : input IMAGE manquant.",
+            )
+        image_artifact = inputs[ArtifactType.IMAGE]
+        if image_artifact.uri is None:
+            raise OCRAdapterError(
+                f"{self.name} : artefact image "
+                f"{image_artifact.id!r} sans URI.",
+            )
+
+        image_path = Path(image_artifact.uri)
+        if not image_path.exists():
+            raise OCRAdapterError(
+                f"{self.name} : image introuvable {image_path!r}.",
+            )
+
+        # Lazy-import de pytesseract + PIL — si absents, message
+        # explicite plutôt qu'``ImportError`` au top-level.
+        try:
+            import pytesseract  # type: ignore[import-untyped]
+            from PIL import Image
+        except ImportError as exc:
+            raise OCRAdapterError(
+                f"{self.name} : pytesseract/Pillow non installés. "
+                "Installer avec : pip install pytesseract pillow",
+            ) from exc
+
+        # Application du tesseract_cmd custom si fourni.
+        if self._tesseract_cmd is not None:
+            pytesseract.pytesseract.tesseract_cmd = self._tesseract_cmd
+
+        # OCR.
+        custom_config = f"--oem {self._oem} --psm {self._psm}"
+        try:
+            with Image.open(image_path) as image:
+                text = pytesseract.image_to_string(
+                    image,
+                    lang=self._lang,
+                    config=custom_config,
+                )
+        except Exception as exc:
+            raise OCRAdapterError(
+                f"{self.name} : Tesseract a levé sur "
+                f"{image_path!r} : {type(exc).__name__}: {exc}",
+            ) from exc
+
+        text = text.strip()
+
+        # Le helper résout vers le workspace si fourni (sandbox par
+        # doc), sinon écrit à côté de l'image — cohérent avec le
+        # pattern ``PrecomputedTextAdapter`` qui peut relire la sortie.
+        text_path = resolve_output_path(
+            input_path=image_path,
+            adapter_name=self.name,
+            suffix="txt",
+            context=context,
+        )
+        text_path.write_text(text, encoding="utf-8")
+
+        outputs: dict = {
+            ArtifactType.RAW_TEXT: Artifact(
+                id=f"{context.document_id}:{self.name}:raw_text",
+                document_id=context.document_id,
+                type=ArtifactType.RAW_TEXT,
+                produced_by_step="ocr",
+                uri=str(text_path),
+            ),
+        }
+
+        # Extraction des confidences via image_to_data (best-effort).
+        # Si l'extraction échoue, on log et on saute — l'OCR reste
+        # valide, seule la calibration est indisponible pour ce doc.
+        if self._expose_confidences:
+            confidences_artifact = self._extract_and_persist_confidences(
+                image_path=image_path,
+                text_path=text_path,
+                pytesseract_module=pytesseract,
+                pil_image_class=Image,
+                custom_config=custom_config,
+                document_id=context.document_id,
+            )
+            if confidences_artifact is not None:
+                outputs[ArtifactType.CONFIDENCES] = confidences_artifact
+
+        return outputs
+
+    def _extract_and_persist_confidences(
+        self,
+        *,
+        image_path: Path,
+        text_path: Path,
+        pytesseract_module,
+        pil_image_class,
+        custom_config: str,
+        document_id: str,
+    ) -> Artifact | None:
+        """Appelle ``image_to_data`` puis écrit le sidecar JSON.
+
+        Retourne l'``Artifact CONFIDENCES`` ou ``None`` si l'extraction
+        a échoué (warning loggé, OCR reste valide).
+        """
+        import logging
+        logger = logging.getLogger(__name__)
+
+        from picarones.adapters.ocr.confidences import (
+            filter_valid_tokens,
+            write_confidences_sidecar,
+        )
+
+        try:
+            with pil_image_class.open(image_path) as image:
+                data = pytesseract_module.image_to_data(
+                    image,
+                    lang=self._lang,
+                    config=custom_config,
+                    output_type=pytesseract_module.Output.DICT,
+                )
+        except Exception as exc:  # noqa: BLE001 — best-effort
+            logger.warning(
+                "[%s] image_to_data indisponible (%s) — calibration "
+                "sautée pour ce document.", self._name, exc,
+            )
+            return None
+
+        # Format Tesseract : dict {"text": [...], "conf": [...]}.
+        texts = data.get("text") or []
+        confs = data.get("conf") or []
+        raw = [
+            {"text": t, "confidence": c}
+            for t, c in zip(texts, confs)
+        ]
+        tokens = filter_valid_tokens(raw)
+        return write_confidences_sidecar(
+            text_path=text_path,
+            adapter_name=self._name,
+            tokens=tokens,
+            document_id=document_id,
+            extractor="tesseract",
+        )
+
+
+__all__ = ["TesseractAdapter"]

picarones/adapters/output_paths.py

@@ -0,0 +1,78 @@
+"""Résolution du répertoire d'output pour les adapters (OCR/LLM/VLM).
+
+Helper partagé par tous les adapters qui produisent des fichiers de
+sortie.  Il vit au top-level de ``adapters/`` plutôt qu'à l'intérieur
+de l'un des sous-packages — il sert les trois familles indistinctement.
+
+Un corpus monté en read-only (NAS partagé, volume Docker RO) ne peut
+pas accueillir les sorties à côté des fichiers sources.  Le helper
+résout le chemin selon une priorité :
+
+1. ``context.workspace_uri`` si non None → écriture dans
+   ``<workspace>/<doc_id>/`` (sandbox par run, write-allowed).
+2. Fallback ``input_path.parent`` → comportement par défaut quand
+   aucun workspace n'est configuré (peut échouer en read-only).
+
+Anti-sur-ingénierie
+-------------------
+- Pas de quota disk : le ``WorkspaceManager`` gère ça quand un
+  caller institutionnel l'exige.
+- Pas de support S3/distant : ``workspace_uri`` est un path
+  filesystem dans le contrat actuel.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def resolve_output_path(
+    input_path: Path,
+    adapter_name: str,
+    suffix: str,
+    context: Any,
+) -> Path:
+    """Résout le chemin de sortie pour un artefact d'adapter.
+
+    Convention de nommage : ``<stem>.<adapter_name>.<suffix>``.
+
+    Si ``context.workspace_uri`` est fourni, le fichier va dans
+    ``<workspace>/<document_id>/`` (créé si absent).  Sinon, fallback
+    sur ``input_path.parent`` (cas typique CLI / corpus local).
+
+    Parameters
+    ----------
+    input_path:
+        Chemin du fichier d'entrée (image, texte, etc.) — utilisé
+        pour récupérer le ``stem``.
+    adapter_name:
+        Nom de l'adapter, intercalé dans le nom du fichier pour
+        permettre la cohabitation de plusieurs sorties.
+    suffix:
+        Extension finale, ex : ``"txt"``, ``"confidences.json"``,
+        ``"corrected.txt"``.  Pas de point initial — la fonction
+        l'ajoute.
+    context:
+        ``RunContext`` avec attributs ``document_id`` et
+        ``workspace_uri``.  ``workspace_uri`` peut être ``None``
+        (mode CLI direct).
+
+    Returns
+    -------
+    Path
+        Chemin absolu où écrire la sortie.  Le répertoire parent
+        est créé si nécessaire.
+    """
+    workspace_uri = getattr(context, "workspace_uri", None)
+    document_id = getattr(context, "document_id", None) or "unknown_doc"
+
+    if workspace_uri:
+        out_dir = Path(workspace_uri) / document_id
+        out_dir.mkdir(parents=True, exist_ok=True)
+        return out_dir / f"{input_path.stem}.{adapter_name}.{suffix}"
+
+    return input_path.parent / f"{input_path.stem}.{adapter_name}.{suffix}"
+
+
+__all__ = ["resolve_output_path"]

picarones/adapters/storage/__init__.py

@@ -0,0 +1,58 @@
+"""Adaptateurs de stockage — Sprint S29.
+
+Stocks d'artefacts indexés par hash multi-paramètres pour la
+reprise des runs longs.
+
+Modules livrés
+--------------
+- ``artifact_store.py`` (S29) — ``ArtifactKey``, ``StoredArtifact``,
+  ``ArtifactStore`` (ABC), ``InMemoryArtifactStore``,
+  ``FilesystemArtifactStore``.
+
+Pattern : un ``Storage`` est instancié par un ``app/services/``,
+pas créé ad-hoc dans un router FastAPI ou un module métier.  Ça
+permet d'injecter un mock en test, de basculer SQLite → Postgres
+si besoin, et de centraliser les permissions/quotas.
+
+Distinct du ``picarones/pipeline/cache.py`` (S7)
+------------------------------------------------
+``ArtifactCache`` (S7) reste exposé pour les callers qui en
+dépendent en interne.  ``ArtifactStore`` (S29) est la nouvelle
+API canonique : hash multi-paramètres (model_version, normalization
+profile, projection spec), persistance optionnelle sur filesystem,
+abstraction ABC.
+
+Cibles à venir
+--------------
+- S37 : déplacement de ``picarones.web.jobs`` (SQLite job store).
+- Post-livraison : ``picarones.measurements.history`` (SQLite
+  history) et stores distribués (S3, GCS, …).
+"""
+
+from __future__ import annotations
+
+from picarones.adapters.storage.artifact_store import (
+    ArtifactKey,
+    ArtifactStore,
+    ArtifactStoreError,
+    FilesystemArtifactStore,
+    InMemoryArtifactStore,
+    StoredArtifact,
+)
+from picarones.adapters.storage.job_store import (
+    JobRecord,
+    JobStore,
+    JobStoreError,
+)
+
+__all__ = [
+    "ArtifactKey",
+    "ArtifactStore",
+    "ArtifactStoreError",
+    "FilesystemArtifactStore",
+    "InMemoryArtifactStore",
+    "StoredArtifact",
+    "JobStore",
+    "JobRecord",
+    "JobStoreError",
+]

picarones/adapters/storage/artifact_store.py

@@ -0,0 +1,417 @@
+"""``ArtifactStore`` — Sprint A14-S29.
+
+Le S7 livrait ``ArtifactCache`` (in-memory, hash basique sur
+inputs + step + code_version).  S29 introduit un ``ArtifactStore``
+plus robuste qui adresse la critique d'audit n° 14 (« hash
+multi-paramètres + reprise par hash ») :
+
+1. **Hash multi-paramètres** : la clé canonique d'un artefact
+   inclut les ``content_hash`` des inputs, le nom + version du
+   model utilisé, les ``params`` du step, le ``code_version``,
+   l'éventuel profil de normalisation, et l'éventuelle spec de
+   projection.  Tout changement d'un paramètre éditorial invalide
+   la cache.
+
+2. **Reprise par hash** : si un artefact avec exactement la même
+   clé existe déjà dans le store, le caller peut l'utiliser
+   directement plutôt que de re-exécuter l'étape coûteuse.
+
+3. **Persistance optionnelle** : ``InMemoryArtifactStore`` pour
+   les tests et les workflows éphémères ; ``FilesystemArtifactStore``
+   pour les longs runs où on veut survivre à un crash.
+
+Pas de shim
+-----------
+``ArtifactCache`` (S7) reste exposé pour les callers qui en
+dépendent en interne, mais la nouvelle API canonique est
+``ArtifactStore``.  Le ``PipelineExecutor`` peut consommer un
+``ArtifactStore`` via le paramètre optionnel ``artifact_store=``
+au constructeur ; sans store, l'executor s'exécute comme avant
+(pas d'effet de cache).
+
+Anti-sur-ingénierie
+-------------------
+- Pas de TTL ni d'éviction LRU dans la version in-memory.  La
+  taille est gérée par le caller (qui peut appeler ``clear()``).
+- Pas de compression des payloads dans la version filesystem.
+- Pas de namespacing par run — un store partagé entre runs est
+  censé converger, c'est précisément la propriété de la reprise.
+- Pas de support distribué (S3, GCS, …) — viendra quand un
+  caller en aura concrètement besoin.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+
+from picarones.domain.artifact_key import ArtifactKey
+from picarones.domain.artifacts import Artifact
+from picarones.domain.errors import PicaronesError
+
+logger = logging.getLogger(__name__)
+
+
+class ArtifactStoreError(PicaronesError):
+    """Erreur de persistance d'artefact (clé invalide, I/O en échec).
+
+    Hérite de ``PicaronesError`` — un caller qui catche
+    ``PicaronesError`` rattrape aussi cette branche, cohérent avec
+    la hiérarchie d'exceptions unifiée.
+    """
+
+
+# Sprint A14-S47 — ``ArtifactKey`` (type pur) a migré dans
+# ``picarones/domain/artifact_key.py``.  Re-import ici pour ne pas
+# casser les callers (``from picarones.adapters.storage import
+# ArtifactKey`` reste valide).
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Conteneur du store
+# ──────────────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class StoredArtifact:
+    """Entrée du store : un artefact + son payload + sa clé.
+
+    Le payload est stocké en bytes brutes — le caller décide de la
+    désérialisation (texte UTF-8, ALTO XML, image PNG, etc.) en se
+    basant sur ``artifact.type``.
+
+    Attributes
+    ----------
+    key:
+        Hash hex de la ``ArtifactKey`` qui a produit l'artefact.
+    artifact:
+        ``Artifact`` complet (id, type, content_hash, provenance).
+    payload:
+        Bytes du contenu, ou ``None`` si le store ne stocke que
+        les métadonnées (cas d'un artefact dont l'``uri`` pointe
+        vers un fichier externe).
+    """
+
+    key: str
+    artifact: Artifact
+    payload: bytes | None = None
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Interface ABC
+# ──────────────────────────────────────────────────────────────────────
+
+
+class ArtifactStore(ABC):
+    """Contrat abstrait d'un store d'artefacts indexé par hash.
+
+    Implémentations livrées au S29 :
+
+    - ``InMemoryArtifactStore`` (tests, runs éphémères) ;
+    - ``FilesystemArtifactStore`` (workspaces persistants).
+
+    Une implémentation tierce (S3, Postgres, …) est attendue post-
+    livraison ; elle hérite de cette ABC et passe les tests de
+    contrat.
+    """
+
+    @abstractmethod
+    def get(self, key: str) -> StoredArtifact | None:
+        """Récupère un artefact par sa clé hex, ou ``None``.
+
+        Tolère les clés inexistantes — le retour ``None`` indique
+        un cache miss, pas une erreur.
+        """
+
+    @abstractmethod
+    def put(
+        self,
+        key: str,
+        artifact: Artifact,
+        payload: bytes | None = None,
+    ) -> None:
+        """Stocke un artefact sous la clé donnée.
+
+        Convention idempotente : ``put(k, ...)`` deux fois avec la
+        même clé écrase la valeur précédente sans erreur.  L'ABC
+        n'impose pas de comportement en concurrence multi-process
+        — chaque implémentation documente ses garanties.
+        """
+
+    @abstractmethod
+    def __contains__(self, key: str) -> bool:
+        """Vrai si la clé est connue du store."""
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Supprime toutes les entrées du store.
+
+        Implémentations filesystem : supprime les fichiers de
+        l'index et des payloads.  Implémentations in-memory :
+        vide les dicts.
+        """
+
+    @abstractmethod
+    def __len__(self) -> int:
+        """Nombre d'entrées dans le store."""
+
+
+# ──────────────────────────────────────────────────────────────────────
+# InMemoryArtifactStore
+# ──────────────────────────────────────────────────────────────────────
+
+
+class InMemoryArtifactStore(ArtifactStore):
+    """Store in-memory thread-safe pour tests et runs éphémères.
+
+    Performances : O(1) en lecture/écriture.  Aucune persistance —
+    toutes les données disparaissent à la sortie du process.
+
+    Thread-safety : un ``threading.Lock`` protège les opérations
+    mutantes (put, clear).  Lecture (get, __contains__, __len__)
+    est sans lock car les dict Python sont atomiques par opération
+    sur clé.
+    """
+
+    def __init__(self) -> None:
+        self._store: dict[str, StoredArtifact] = {}
+        self._lock = threading.Lock()
+
+    def get(self, key: str) -> StoredArtifact | None:
+        return self._store.get(key)
+
+    def put(
+        self,
+        key: str,
+        artifact: Artifact,
+        payload: bytes | None = None,
+    ) -> None:
+        if not key:
+            raise ArtifactStoreError("ArtifactStore.put : key vide non autorisé")
+        with self._lock:
+            self._store[key] = StoredArtifact(
+                key=key, artifact=artifact, payload=payload,
+            )
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._store
+
+    def clear(self) -> None:
+        with self._lock:
+            self._store.clear()
+
+    def __len__(self) -> int:
+        return len(self._store)
+
+    def keys(self) -> tuple[str, ...]:
+        """Liste figée des clés connues (utile aux tests)."""
+        return tuple(self._store.keys())
+
+
+# ──────────────────────────────────────────────────────────────────────
+# FilesystemArtifactStore
+# ──────────────────────────────────────────────────────────────────────
+
+
+class FilesystemArtifactStore(ArtifactStore):
+    """Store persistant sur le filesystem.
+
+    Layout
+    ------
+
+    ``<root>/``
+        ``index.jsonl``                   — un JSON par ligne
+                                            ``{"key": ..., "artifact_id": ...,
+                                            "has_payload": bool, "type": ...,
+                                            "timestamp": ISO8601}``
+        ``artifacts/<key>.json``          — métadonnées de l'``Artifact``
+                                            sérialisées via
+                                            ``model_dump_json()``
+        ``payloads/<key>.bin``            — bytes du payload (le cas
+                                            échéant)
+
+    Concurrence
+    -----------
+    Un ``threading.Lock`` interne protège les opérations mutantes
+    dans le même process.  Multi-process : pas de garantie ; le
+    layout est conçu pour qu'un read-only multi-process soit
+    sûr (les fichiers individuels sont écrits atomiquement via
+    ``write_text(... newline=...)`` et un rename).
+
+    Garbage / corruption
+    --------------------
+    Si l'index pointe vers un fichier disparu, le ``get`` retourne
+    ``None`` et logge un warning.  ``clear()`` supprime tout —
+    un caller peut aussi reconstruire l'index en parsant les
+    fichiers ``artifacts/*.json``.
+
+    Pas de shim
+    -----------
+    Cette implémentation n'a pas de migration depuis l'``ArtifactCache``
+    in-memory du S7 — c'est un store distinct, instanciable
+    explicitement par un service applicatif (typiquement
+    ``WorkspaceManager`` au S30+).
+    """
+
+    INDEX_FILENAME = "index.jsonl"
+    ARTIFACTS_DIR = "artifacts"
+    PAYLOADS_DIR = "payloads"
+
+    def __init__(self, root: Path | str) -> None:
+        self._root = Path(root)
+        self._root.mkdir(parents=True, exist_ok=True)
+        (self._root / self.ARTIFACTS_DIR).mkdir(exist_ok=True)
+        (self._root / self.PAYLOADS_DIR).mkdir(exist_ok=True)
+        self._index_path = self._root / self.INDEX_FILENAME
+        self._lock = threading.Lock()
+        # In-memory index of known keys reconstructed from disk.
+        # On sait qu'on est seul écrivain dans un process donné, mais
+        # un autre process peut aussi écrire — on ne fait pas de
+        # garantie multi-process ici.
+        self._known_keys: set[str] = self._reconstruct_known_keys()
+
+    # ──────────────────────────────────────────────────────────────
+    # API ABC
+    # ──────────────────────────────────────────────────────────────
+
+    def get(self, key: str) -> StoredArtifact | None:
+        if key not in self._known_keys:
+            return None
+        artifact_path = self._root / self.ARTIFACTS_DIR / f"{key}.json"
+        if not artifact_path.exists():
+            logger.warning(
+                "[artifact_store] index pointe vers %s mais le fichier "
+                "n'existe plus — entrée corrompue, retour None.",
+                artifact_path,
+            )
+            return None
+        try:
+            artifact = Artifact.model_validate_json(
+                artifact_path.read_text(encoding="utf-8"),
+            )
+        except Exception as exc:  # noqa: BLE001
+            logger.warning(
+                "[artifact_store] échec de désérialisation de %s : %s",
+                artifact_path, exc,
+            )
+            return None
+        payload_path = self._root / self.PAYLOADS_DIR / f"{key}.bin"
+        payload = (
+            payload_path.read_bytes() if payload_path.exists() else None
+        )
+        return StoredArtifact(key=key, artifact=artifact, payload=payload)
+
+    def put(
+        self,
+        key: str,
+        artifact: Artifact,
+        payload: bytes | None = None,
+    ) -> None:
+        if not key:
+            raise ArtifactStoreError("ArtifactStore.put : key vide non autorisé")
+        with self._lock:
+            artifact_path = self._root / self.ARTIFACTS_DIR / f"{key}.json"
+            tmp_path = artifact_path.with_suffix(".json.tmp")
+            tmp_path.write_text(
+                artifact.model_dump_json(),
+                encoding="utf-8",
+            )
+            tmp_path.replace(artifact_path)
+            if payload is not None:
+                payload_path = self._root / self.PAYLOADS_DIR / f"{key}.bin"
+                tmp_payload = payload_path.with_suffix(".bin.tmp")
+                tmp_payload.write_bytes(payload)
+                tmp_payload.replace(payload_path)
+            self._append_index_line(key, artifact, payload is not None)
+            self._known_keys.add(key)
+
+    def __contains__(self, key: str) -> bool:
+        return key in self._known_keys
+
+    def clear(self) -> None:
+        with self._lock:
+            for sub in (self.ARTIFACTS_DIR, self.PAYLOADS_DIR):
+                d = self._root / sub
+                if d.exists():
+                    for f in d.iterdir():
+                        f.unlink()
+            if self._index_path.exists():
+                self._index_path.unlink()
+            self._known_keys.clear()
+
+    def __len__(self) -> int:
+        return len(self._known_keys)
+
+    def keys(self) -> tuple[str, ...]:
+        return tuple(self._known_keys)
+
+    # ──────────────────────────────────────────────────────────────
+    # Helpers internes
+    # ──────────────────────────────────────────────────────────────
+
+    def _append_index_line(
+        self, key: str, artifact: Artifact, has_payload: bool,
+    ) -> None:
+        """Append-only JSONL : une nouvelle ligne par put.  Lit le
+        rapport d'index au démarrage, recompose ``_known_keys``."""
+        from datetime import datetime, timezone
+        line = json.dumps(
+            {
+                "key": key,
+                "artifact_id": artifact.id,
+                "type": artifact.type.value,
+                "has_payload": has_payload,
+                "timestamp": datetime.now(tz=timezone.utc).isoformat(),
+            },
+            ensure_ascii=False,
+        )
+        with self._index_path.open("a", encoding="utf-8") as f:
+            f.write(line + "\n")
+
+    def _reconstruct_known_keys(self) -> set[str]:
+        """Lit ``index.jsonl`` et reconstruit l'ensemble des clés
+        connues.  Tolère les lignes corrompues (warning + skip).
+
+        Si l'index n'existe pas, recompose depuis le contenu du
+        sous-répertoire ``artifacts/`` (cas d'un store partiellement
+        copié sans son index).
+        """
+        keys: set[str] = set()
+        if self._index_path.exists():
+            for line_no, raw_line in enumerate(
+                self._index_path.read_text(encoding="utf-8").splitlines(),
+                start=1,
+            ):
+                if not raw_line.strip():
+                    continue
+                try:
+                    rec = json.loads(raw_line)
+                except json.JSONDecodeError as exc:
+                    logger.warning(
+                        "[artifact_store] index ligne %d corrompue, "
+                        "ignorée : %s", line_no, exc,
+                    )
+                    continue
+                if "key" in rec and isinstance(rec["key"], str):
+                    keys.add(rec["key"])
+        else:
+            # Recompose depuis les fichiers d'artefacts.
+            artifacts_dir = self._root / self.ARTIFACTS_DIR
+            if artifacts_dir.exists():
+                for f in artifacts_dir.iterdir():
+                    if f.suffix == ".json":
+                        keys.add(f.stem)
+        return keys
+
+
+__all__ = [
+    "ArtifactKey",
+    "ArtifactStore",
+    "FilesystemArtifactStore",
+    "InMemoryArtifactStore",
+    "StoredArtifact",
+]

picarones/adapters/storage/job_store.py

@@ -0,0 +1,470 @@
+"""``JobStore`` — Sprint A14-S37.
+
+Persistance SQLite des jobs de benchmark.  Adapté du legacy
+``picarones.web.jobs`` mais réécrit nativement pour le nouveau monde :
+API plus simple, dataclass immuable, sans dépendance au ``state``
+global.
+
+Le legacy reste exposé jusqu'au S46.
+
+Pourquoi SQLite
+---------------
+- Survie au redémarrage : un crash ou ``kill -HUP`` ne perd pas
+  l'état des jobs en cours.
+- Détection des jobs orphelins au boot : tout job ``running`` à
+  l'initialisation est forcément un zombie du process précédent
+  → marqué ``interrupted``.
+- Indexation simple par ``job_id`` (TEXT PK).
+- Mode WAL pour les lectures concurrentes pendant qu'un thread
+  écrit la progression.
+
+Statuts
+-------
+- ``pending``      : créé, en attente d'exécution.
+- ``running``      : worker actif.
+- ``complete``     : succès.
+- ``error``        : échec applicatif (avec message).
+- ``cancelled``    : interrompu par le caller.
+- ``interrupted``  : zombie du process précédent (détecté au boot).
+
+Les 4 derniers sont **terminaux** — un job dans cet état ne change
+plus de statut.
+
+API publique
+------------
+- ``JobStore(db_path)`` : connexion SQLite, init schema si absent.
+- ``create(job_id, payload, total_docs=0)`` → JobRecord.
+- ``get(job_id)`` → JobRecord | None.
+- ``list(limit=None)`` → tuple[JobRecord, ...] triés par
+  ``created_at`` décroissant.
+- ``update_progress(job_id, progress, processed_docs, current_engine)``.
+- ``mark_running(job_id)``.
+- ``mark_complete(job_id, output_path="")``.
+- ``mark_error(job_id, error_message)``.
+- ``mark_cancelled(job_id)``.
+- ``mark_orphaned_jobs_interrupted()`` → int (nombre marqué).
+- ``close()`` (no-op : chaque appel ouvre/ferme sa propre connexion).
+
+Anti-sur-ingénierie
+-------------------
+- Pas de notification SSE (les SSE legacy sont reportés à un sprint
+  dédié si un caller en a besoin).
+- Pas de queue d'événements — le legacy avait ``job_events`` ; on
+  attend qu'un caller en ait besoin ; pour l'instant le statut +
+  progress suffit pour le polling.
+- Une connexion par appel — SQLite gère ça en sub-ms.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sqlite3
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+_TERMINAL_STATUSES: frozenset[str] = frozenset({
+    "complete", "error", "cancelled", "interrupted",
+})
+
+_LIVE_STATUSES: frozenset[str] = frozenset({"pending", "running"})
+
+
+_SCHEMA_SQL = """
+CREATE TABLE IF NOT EXISTS jobs (
+    job_id          TEXT PRIMARY KEY,
+    status          TEXT NOT NULL DEFAULT 'pending',
+    progress        REAL NOT NULL DEFAULT 0.0,
+    current_engine  TEXT NOT NULL DEFAULT '',
+    total_docs      INTEGER NOT NULL DEFAULT 0,
+    processed_docs  INTEGER NOT NULL DEFAULT 0,
+    output_path     TEXT NOT NULL DEFAULT '',
+    error           TEXT NOT NULL DEFAULT '',
+    payload_json    TEXT NOT NULL DEFAULT '{}',
+    created_at      REAL NOT NULL,
+    updated_at      REAL NOT NULL,
+    finished_at     REAL
+);
+
+CREATE INDEX IF NOT EXISTS jobs_status_idx ON jobs(status);
+CREATE INDEX IF NOT EXISTS jobs_created_idx ON jobs(created_at);
+"""
+
+
+@dataclass(frozen=True)
+class JobRecord:
+    """Snapshot immuable d'un job persisté.
+
+    Les setters mutants (``update_progress``, ``mark_*``) reconstruisent
+    un nouveau ``JobRecord`` au prochain ``get``.
+    """
+
+    job_id: str
+    status: str
+    progress: float
+    current_engine: str
+    total_docs: int
+    processed_docs: int
+    output_path: str
+    error: str
+    payload: dict[str, Any]
+    created_at: float
+    updated_at: float
+    finished_at: float | None
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in _TERMINAL_STATUSES
+
+    @property
+    def is_live(self) -> bool:
+        return self.status in _LIVE_STATUSES
+
+
+from picarones.domain.errors import PicaronesError
+
+
+class JobStoreError(PicaronesError):
+    """Erreur de persistance SQLite côté JobStore."""
+
+
+#: Dispatcher de migrations ascendantes ``v_n → v_{n+1}``.
+#:
+#: Une migration est une callable ``(sqlite3.Connection) -> None``
+#: appliquée dans une transaction implicite (mode autocommit du
+#: ``JobStore`` désactivé pendant la migration).  Pour ajouter une
+#: migration, déclarer une fonction ``_migrate_v1_to_v2(conn)`` qui
+#: applique les ``ALTER TABLE`` nécessaires, puis ajouter
+#: ``2: _migrate_v1_to_v2`` au dict.  La clé est la version
+#: **source** ; la valeur est la version **cible**.
+_MIGRATIONS: dict[int, Callable[[sqlite3.Connection], None]] = {}
+
+
+class JobStore:
+    """Store SQLite des jobs de benchmark.
+
+    Parameters
+    ----------
+    db_path:
+        Chemin du fichier SQLite.  Créé s'il n'existe pas.
+
+    Migration de schéma
+    -------------------
+    L'ouverture d'une base SQLite vérifie sa version contre
+    ``SCHEMA_VERSION`` (lue dans la table ``schema_version``) :
+
+    - Version absente → fresh DB, on insère ``SCHEMA_VERSION``.
+    - Version == code → no-op.
+    - Version < code → on applique en chaîne les migrations
+      ``_MIGRATIONS`` jusqu'à atteindre ``SCHEMA_VERSION``.  Si
+      l'une manque dans le dispatcher, ``JobStoreError`` (la
+      release n'a pas livré la migration nécessaire).
+    - Version > code → ``JobStoreError`` (downgrade non supporté ;
+      l'utilisateur doit utiliser un build plus récent ou
+      réinitialiser).
+    """
+
+    #: Version du schéma SQL.  À incrémenter ENSEMBLE avec une
+    #: entrée correspondante dans ``_MIGRATIONS`` (pas l'un sans
+    #: l'autre — un test architectural vérifie l'invariant).
+    SCHEMA_VERSION = 1
+
+    def __init__(self, db_path: Path | str) -> None:
+        self._path = Path(db_path)
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        with self._connect() as conn:
+            conn.executescript(_SCHEMA_SQL)
+            conn.execute(
+                "CREATE TABLE IF NOT EXISTS schema_version "
+                "(version INTEGER PRIMARY KEY)",
+            )
+            cur = conn.execute("SELECT version FROM schema_version")
+            row = cur.fetchone()
+            if row is None:
+                conn.execute(
+                    "INSERT INTO schema_version (version) VALUES (?)",
+                    (self.SCHEMA_VERSION,),
+                )
+            else:
+                existing = row[0]
+                if existing > self.SCHEMA_VERSION:
+                    raise JobStoreError(
+                        f"JobStore : base SQLite à la version "
+                        f"{existing}, code à la version "
+                        f"{self.SCHEMA_VERSION}.  Downgrade non "
+                        "supporté.",
+                    )
+                if existing < self.SCHEMA_VERSION:
+                    self._apply_migrations(
+                        conn, from_version=existing,
+                    )
+            try:
+                conn.execute("PRAGMA journal_mode = WAL;")
+            except sqlite3.Error:  # pragma: no cover
+                # WAL non supporté (FAT32, NFS sans verrous) : on
+                # reste en rollback journal, fonctionnel mais moins
+                # concurrent en lecture.
+                pass
+
+    @classmethod
+    def _apply_migrations(
+        cls,
+        conn: sqlite3.Connection,
+        *,
+        from_version: int,
+    ) -> None:
+        """Applique en chaîne ``_MIGRATIONS[v]`` pour ``v`` de
+        ``from_version`` à ``SCHEMA_VERSION - 1``.
+
+        Une migration manquante est une erreur dure : la release du
+        code prétend être à ``SCHEMA_VERSION`` mais n'a pas livré
+        la transformation nécessaire.  ``JobStoreError`` plutôt
+        qu'un warning silencieux qui laisserait le schéma incohérent.
+        """
+        current = from_version
+        while current < cls.SCHEMA_VERSION:
+            migrate = _MIGRATIONS.get(current)
+            if migrate is None:
+                raise JobStoreError(
+                    f"JobStore : migration manquante de v{current} "
+                    f"vers v{current + 1}.  Le code prétend être à "
+                    f"la version {cls.SCHEMA_VERSION} mais n'a pas "
+                    "livré la migration.",
+                )
+            migrate(conn)
+            conn.execute(
+                "UPDATE schema_version SET version = ?",
+                (current + 1,),
+            )
+            current += 1
+
+    @property
+    def db_path(self) -> Path:
+        return self._path
+
+    def _connect(self) -> sqlite3.Connection:
+        """Ouvre une nouvelle connexion.
+
+        ``timeout=30s`` côté driver Python + ``PRAGMA busy_timeout``
+        côté SQLite absorbent les contentions courtes.  Le mode
+        autocommit combiné au journal WAL garantit que les lectures
+        n'attendent pas les écritures (cf. https://sqlite.org/wal.html).
+        """
+        conn = sqlite3.connect(
+            str(self._path),
+            isolation_level=None,  # autocommit pour simplicité
+            timeout=30.0,
+        )
+        # busy_timeout (ms) — backup au timeout Python.
+        conn.execute("PRAGMA busy_timeout = 30000;")
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    # ──────────────────────────────────────────────────────────────
+    # Création / lecture
+    # ──────────────────────────────────────────────────────────────
+
+    def create(
+        self,
+        job_id: str,
+        payload: dict[str, Any] | None = None,
+        total_docs: int = 0,
+    ) -> JobRecord:
+        """Crée un nouveau job en statut ``pending``.
+
+        Raises
+        ------
+        JobStoreError
+            Si ``job_id`` existe déjà ou si la ligne ne s'insère
+            pas correctement.
+        """
+        if not job_id:
+            raise JobStoreError("create : job_id vide non autorisé.")
+        now = time.time()
+        payload_json = json.dumps(payload or {}, ensure_ascii=False)
+        try:
+            with self._connect() as conn:
+                conn.execute(
+                    """
+                    INSERT INTO jobs (
+                        job_id, status, progress, current_engine,
+                        total_docs, processed_docs, output_path, error,
+                        payload_json, created_at, updated_at, finished_at
+                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                    """,
+                    (
+                        job_id, "pending", 0.0, "",
+                        total_docs, 0, "", "",
+                        payload_json, now, now, None,
+                    ),
+                )
+        except sqlite3.IntegrityError as exc:
+            raise JobStoreError(
+                f"job_id {job_id!r} déjà existant.",
+            ) from exc
+        return self.get(job_id)  # type: ignore[return-value]
+
+    def get(self, job_id: str) -> JobRecord | None:
+        """Retourne le snapshot du job, ou ``None`` si inconnu."""
+        with self._connect() as conn:
+            cur = conn.execute(
+                "SELECT * FROM jobs WHERE job_id = ?",
+                (job_id,),
+            )
+            row = cur.fetchone()
+        if row is None:
+            return None
+        return self._row_to_record(row)
+
+    def list(self, limit: int | None = None) -> tuple[JobRecord, ...]:
+        """Liste les jobs triés par date de création décroissante."""
+        sql = "SELECT * FROM jobs ORDER BY created_at DESC"
+        if limit is not None:
+            sql += f" LIMIT {int(limit)}"
+        with self._connect() as conn:
+            rows = conn.execute(sql).fetchall()
+        return tuple(self._row_to_record(r) for r in rows)
+
+    # ──────────────────────────────────────────────────────────────
+    # Mutations
+    # ──────────────────────────────────────────────────────────────
+
+    def update_progress(
+        self,
+        job_id: str,
+        progress: float,
+        processed_docs: int = 0,
+        current_engine: str = "",
+    ) -> None:
+        """Met à jour la progression d'un job en ``running``.
+
+        ``progress`` est tronqué à [0.0, 1.0].
+        """
+        progress = max(0.0, min(1.0, progress))
+        now = time.time()
+        with self._connect() as conn:
+            conn.execute(
+                """
+                UPDATE jobs
+                SET progress = ?, processed_docs = ?,
+                    current_engine = ?, updated_at = ?
+                WHERE job_id = ?
+                """,
+                (progress, processed_docs, current_engine, now, job_id),
+            )
+
+    def mark_running(self, job_id: str) -> None:
+        """Bascule le statut en ``running``."""
+        self._set_status(job_id, "running", finished=False)
+
+    def mark_complete(self, job_id: str, output_path: str = "") -> None:
+        self._set_status(
+            job_id, "complete", finished=True, output_path=output_path,
+        )
+
+    def mark_error(self, job_id: str, error_message: str) -> None:
+        self._set_status(
+            job_id, "error", finished=True, error=error_message,
+        )
+
+    def mark_cancelled(self, job_id: str) -> None:
+        self._set_status(job_id, "cancelled", finished=True)
+
+    def mark_orphaned_jobs_interrupted(self) -> int:
+        """Marque tous les jobs ``pending``/``running`` comme
+        ``interrupted``.  Appelé au boot de l'app pour nettoyer les
+        zombies du process précédent.
+
+        Returns
+        -------
+        int
+            Nombre de jobs marqués.
+        """
+        now = time.time()
+        with self._connect() as conn:
+            cur = conn.execute(
+                """
+                UPDATE jobs
+                SET status = 'interrupted',
+                    error = 'process restart',
+                    updated_at = ?,
+                    finished_at = ?
+                WHERE status IN ('pending', 'running')
+                """,
+                (now, now),
+            )
+            return cur.rowcount
+
+    # ──────────────────────────────────────────────────────────────
+    # Helpers privés
+    # ──────────────────────────────────────────────────────────────
+
+    def _set_status(
+        self,
+        job_id: str,
+        status: str,
+        *,
+        finished: bool,
+        output_path: str = "",
+        error: str = "",
+    ) -> None:
+        now = time.time()
+        finished_at = now if finished else None
+        with self._connect() as conn:
+            if finished:
+                conn.execute(
+                    """
+                    UPDATE jobs
+                    SET status = ?, output_path = ?, error = ?,
+                        updated_at = ?, finished_at = ?
+                    WHERE job_id = ?
+                    """,
+                    (status, output_path, error, now, finished_at, job_id),
+                )
+            else:
+                conn.execute(
+                    """
+                    UPDATE jobs
+                    SET status = ?, updated_at = ?, finished_at = ?
+                    WHERE job_id = ?
+                    """,
+                    (status, now, finished_at, job_id),
+                )
+
+    @staticmethod
+    def _row_to_record(row: sqlite3.Row) -> JobRecord:
+        try:
+            payload = json.loads(row["payload_json"] or "{}")
+        except json.JSONDecodeError:
+            logger.warning(
+                "[job_store] payload corrompu pour job %s — ignoré.",
+                row["job_id"],
+            )
+            payload = {}
+        return JobRecord(
+            job_id=row["job_id"],
+            status=row["status"],
+            progress=row["progress"],
+            current_engine=row["current_engine"],
+            total_docs=row["total_docs"],
+            processed_docs=row["processed_docs"],
+            output_path=row["output_path"],
+            error=row["error"],
+            payload=payload,
+            created_at=row["created_at"],
+            updated_at=row["updated_at"],
+            finished_at=row["finished_at"],
+        )
+
+
+__all__ = [
+    "JobRecord",
+    "JobStore",
+    "JobStoreError",
+]

picarones/adapters/vlm/__init__.py

@@ -0,0 +1,42 @@
+"""Adapters VLM (Vision-Language Models) — Sprint A14-S45.
+
+VLM = transcription directe par un modèle généraliste avec vision.
+Distinct des OCR dédiés (Tesseract, Pero, Mistral OCR, Google Vision,
+Azure DI) — un VLM consomme IMAGE et produit RAW_TEXT via prompt
+multimodal, sans layout structuré natif.
+
+Adapters livrés
+---------------
+- ``AnthropicVLMAdapter`` : Claude Sonnet/Opus avec vision.
+- ``OpenAIVLMAdapter`` : GPT-4o, GPT-4-turbo, GPT-4-vision-preview.
+- ``MistralVLMAdapter`` : Pixtral 12b/Large.
+- ``OllamaVLMAdapter`` : LLaVA, BakLLaVA, llama3.2-vision (local).
+
+Convention StepExecutor :
+
+- ``input_types = {IMAGE}``
+- ``output_types = {RAW_TEXT}``
+- ``execute(inputs, params, context)`` encode l'image en base64,
+  appelle le LLM avec un prompt de transcription, écrit le texte
+  produit dans ``<stem>.<adapter_name>.txt`` à côté de l'image,
+  retourne un Artifact RAW_TEXT.
+
+Pas un shim sur les LLM adapters : c'est un mode d'usage
+distinct (vision vs texte) avec un contrat StepExecutor différent.
+"""
+
+from __future__ import annotations
+
+from picarones.adapters.vlm.anthropic_vlm import AnthropicVLMAdapter
+from picarones.adapters.vlm.base import BaseVLMAdapter
+from picarones.adapters.vlm.mistral_vlm import MistralVLMAdapter
+from picarones.adapters.vlm.ollama_vlm import OllamaVLMAdapter
+from picarones.adapters.vlm.openai_vlm import OpenAIVLMAdapter
+
+__all__ = [
+    "BaseVLMAdapter",
+    "AnthropicVLMAdapter",
+    "MistralVLMAdapter",
+    "OllamaVLMAdapter",
+    "OpenAIVLMAdapter",
+]

picarones/adapters/vlm/anthropic_vlm.py

@@ -0,0 +1,32 @@
+"""``AnthropicVLMAdapter`` — Claude Sonnet/Opus en mode vision.
+
+Sprint A14-S45.  Délègue l'appel API au mécanisme de
+``AnthropicAdapter`` (qui supporte déjà la vision via le SDK
+anthropic) en surchargeant le contrat StepExecutor pour consommer
+IMAGE au lieu de RAW_TEXT.
+"""
+
+from __future__ import annotations
+
+from picarones.adapters.llm.anthropic_adapter import AnthropicAdapter
+from picarones.adapters.vlm.base import BaseVLMAdapter
+
+
+class AnthropicVLMAdapter(BaseVLMAdapter, AnthropicAdapter):
+    """VLM Claude (Sonnet/Opus avec vision).
+
+    L'ordre du MRO est important : ``BaseVLMAdapter`` d'abord pour
+    surcharger ``input_types``/``output_types``/``execute``, puis
+    ``AnthropicAdapter`` pour ``_call``/``default_model``/``name``/
+    retry/validation API key.
+
+    Modèles vision recommandés : ``claude-3-5-sonnet-latest``,
+    ``claude-3-opus-latest``.
+    """
+
+    @property
+    def name(self) -> str:
+        return "anthropic_vlm"
+
+
+__all__ = ["AnthropicVLMAdapter"]

picarones/adapters/vlm/base.py

@@ -0,0 +1,240 @@
+"""``BaseVLMAdapter`` — Sprint A14-S45.
+
+Adapter VLM (Vision-Language Model) qui hérite de ``BaseLLMAdapter``
+et surcharge le contrat StepExecutor pour consommer ``IMAGE`` au
+lieu de ``RAW_TEXT`` et produire ``RAW_TEXT`` (transcription
+directe par un VLM).
+
+Pas un shim sur les LLM adapters : c'est un mode d'usage différent
+de la même API LLM (texte vs image) — le contrat StepExecutor diffère.
+
+Différences avec ``BaseOCRAdapter`` (S26)
+-----------------------------------------
+- Un OCR (Tesseract, Pero, Mistral OCR, Google Vision, Azure DI)
+  utilise des modèles dédiés OCR avec layout structuré, confidences
+  natives, etc.
+- Un VLM (Anthropic Claude, GPT-4-Vision, Pixtral, LLaVA) fait de la
+  transcription via un modèle généraliste prompt+image.
+
+Les deux peuvent produire RAW_TEXT et être comparés en TextView ;
+la projection report explicitera ce qu'on perd côté VLM (pas de
+coordonnées spatiales nativement).
+
+Convention output : RAW_TEXT (transcription plate).  Une sous-classe
+qui produit du markdown structuré (ex. ``CANONICAL_DOCUMENT``) peut
+surcharger ``output_types``.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+from pathlib import Path
+from typing import Any
+
+from picarones.adapters.llm.base import BaseLLMAdapter, _DeprecatedAttribute
+from picarones.domain.artifacts import Artifact, ArtifactType
+from picarones.domain.errors import AdapterStepError
+
+logger = logging.getLogger(__name__)
+
+
+class VLMAdapterError(AdapterStepError):
+    """Erreur typée pour un échec d'adapter VLM.
+
+    Hérite de ``AdapterStepError`` — racine commune avec les erreurs
+    OCR et LLM, ce qui permet à un orchestrateur d'attraper toutes
+    les erreurs d'adapter sans connaître le type concret.
+    """
+
+
+class BaseVLMAdapter(BaseLLMAdapter):
+    """Adapter VLM qui transcrit une IMAGE en RAW_TEXT.
+
+    Hérite de ``BaseLLMAdapter`` et surcharge le contrat
+    ``StepExecutor`` pour consommer ``IMAGE`` au lieu de ``RAW_TEXT``.
+
+    Parameters
+    ----------
+    model:
+        Modèle VLM (cf. sous-classes pour les défauts).
+    config:
+        Config dict ; supporte
+        ``config["transcription_prompt"]`` pour personnaliser le
+        prompt de transcription.
+
+    Garde-fou MRO
+    -------------
+    Les VLM concrets utilisent l'héritage multiple :
+
+    ::
+
+        class AnthropicVLMAdapter(BaseVLMAdapter, AnthropicAdapter)
+
+    L'ordre est critique : ``BaseVLMAdapter`` doit venir d'ABORD
+    pour que ``input_types``, ``output_types``, ``execute``, et
+    ``DEFAULT_TRANSCRIPTION_PROMPTS`` soient résolus depuis lui (et
+    pas depuis le LLM sibling qui aurait des output_types =
+    {CORRECTED_TEXT}).
+
+    ``__init_subclass__`` valide cet ordre à la définition de la
+    classe.  Si le développeur swap accidentellement les parents
+    par habitude alphabétique, la définition de classe lève une
+    ``TypeError`` immédiate au lieu d'un comportement silencieusement
+    différent (output_types incorrect au runtime).
+    """
+
+    def __init_subclass__(cls, **kwargs) -> None:
+        super().__init_subclass__(**kwargs)
+        # Garde-fou : BaseVLMAdapter doit être le premier parent
+        # *non-trivial* dans l'ordre de la déclaration (pour gagner
+        # le MRO sur les attributs surchargés).
+        bases = cls.__bases__
+        if len(bases) <= 1:
+            # Sous-classe directe simple — pas de MRO multiple, OK.
+            return
+        # On parcourt les bases dans l'ordre déclaré.
+        try:
+            vlm_idx = next(
+                i for i, b in enumerate(bases)
+                if issubclass(b, BaseVLMAdapter)
+            )
+        except StopIteration:
+            return  # ne devrait pas arriver, vlm subclass DOIT inclure VLM
+        # Toutes les bases AVANT BaseVLMAdapter doivent être
+        # neutres (mixins sans surcharge des output_types).
+        for prev in bases[:vlm_idx]:
+            if issubclass(prev, BaseLLMAdapter) and not issubclass(
+                prev, BaseVLMAdapter,
+            ):
+                raise TypeError(
+                    f"{cls.__name__} : ordre MRO incorrect — "
+                    f"BaseVLMAdapter doit précéder {prev.__name__} "
+                    "dans la liste des parents pour que les "
+                    "output_types VLM ({IMAGE} → {RAW_TEXT}) "
+                    "soient résolus correctement (et pas écrasés "
+                    "par les output_types LLM = {CORRECTED_TEXT}). "
+                    f"Corrigez : `class {cls.__name__}(BaseVLMAdapter, "
+                    f"{prev.__name__})`.",
+                )
+
+    @property
+    def input_types(self) -> "frozenset":
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> "frozenset":
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    #: Prompts de transcription VLM par défaut, indexés par code
+    #: langue ISO 639-1 (``fr``, ``en``, ``la``).
+    DEFAULT_TRANSCRIPTION_PROMPTS: dict[str, str] = {
+        "fr": (
+            "Transcris fidèlement le texte visible sur cette image "
+            "de document historique. Conserve l'orthographe "
+            "historique, les abréviations, et la ponctuation. "
+            "Retourne uniquement le texte transcrit, sans commentaire."
+        ),
+        "en": (
+            "Faithfully transcribe the text visible in this image of "
+            "a historical document. Preserve the historical "
+            "spelling, abbreviations, and punctuation. Return only "
+            "the transcribed text, with no commentary."
+        ),
+        "la": (
+            "Fideliter transcribe textum in hac imagine documenti "
+            "historici visibilem. Serva orthographiam historicam, "
+            "abbreviationes, et interpunctionem. Redde solum textum "
+            "transcriptum, sine ulla glossa."
+        ),
+    }
+
+    #: Alias rétrocompat (FR uniquement) pour les sous-classes
+    #: externes qui lisaient l'ancienne API singulière.  L'accès
+    #: déclenche un ``DeprecationWarning``.  Sera supprimé en 2.0.
+    DEFAULT_TRANSCRIPTION_PROMPT = _DeprecatedAttribute(
+        DEFAULT_TRANSCRIPTION_PROMPTS["fr"],
+        "BaseVLMAdapter.DEFAULT_TRANSCRIPTION_PROMPT is deprecated "
+        "and will be removed in 2.0.  Use "
+        "DEFAULT_TRANSCRIPTION_PROMPTS[lang] (lang ∈ {fr, en, la}).",
+    )
+
+    def execute(
+        self,
+        inputs: dict,
+        params: dict,
+        context: Any,
+    ) -> dict:
+        """Exécute la transcription VLM.
+
+        Lit ``inputs[IMAGE]`` (URI), encode en base64, appelle
+        ``self.complete(prompt, image_b64)``, écrit le résultat
+        dans ``<stem>.<name>.txt`` à côté de l'image, et retourne
+        ``{RAW_TEXT: Artifact}``.
+        """
+        if ArtifactType.IMAGE not in inputs:
+            raise VLMAdapterError(
+                f"{self.name} : input IMAGE manquant.",
+            )
+        image_artifact = inputs[ArtifactType.IMAGE]
+        if image_artifact.uri is None:
+            raise VLMAdapterError(
+                f"{self.name} : artefact image "
+                f"{image_artifact.id!r} sans URI.",
+            )
+        image_path = Path(image_artifact.uri)
+        if not image_path.exists():
+            raise VLMAdapterError(
+                f"{self.name} : image introuvable {image_path!r}.",
+            )
+
+        image_b64 = base64.b64encode(
+            image_path.read_bytes(),
+        ).decode("ascii")
+
+        # Override explicite > prompt par langue > FR (fallback).
+        custom = self.config.get("transcription_prompt")
+        if custom is not None:
+            prompt = custom
+        else:
+            lang = (self.config.get("lang") or "fr").lower()
+            if lang not in self.DEFAULT_TRANSCRIPTION_PROMPTS:
+                logger.warning(
+                    "[%s] lang=%r non supportée par "
+                    "DEFAULT_TRANSCRIPTION_PROMPTS (%s) — fallback FR. "
+                    "Pour un corpus dans cette langue, fournir "
+                    "config['transcription_prompt'] explicite.",
+                    self.name, lang,
+                    sorted(self.DEFAULT_TRANSCRIPTION_PROMPTS.keys()),
+                )
+            prompt = self.DEFAULT_TRANSCRIPTION_PROMPTS.get(
+                lang, self.DEFAULT_TRANSCRIPTION_PROMPTS["fr"],
+            )
+
+        result = self.complete(prompt, image_b64=image_b64)
+        if not result.success:
+            raise VLMAdapterError(
+                f"{self.name} : VLM a échoué ({result.error}).",
+            )
+
+        from picarones.adapters.output_paths import resolve_output_path
+        out_path = resolve_output_path(
+            input_path=image_path,
+            adapter_name=self.name,
+            suffix="txt",
+            context=context,
+        )
+        out_path.write_text(result.text, encoding="utf-8")
+
+        return {
+            ArtifactType.RAW_TEXT: Artifact(
+                id=f"{context.document_id}:{self.name}:raw_text",
+                document_id=context.document_id,
+                type=ArtifactType.RAW_TEXT,
+                produced_by_step="vlm_transcription",
+                uri=str(out_path),
+            ),
+        }
+
+
+__all__ = ["BaseVLMAdapter", "VLMAdapterError"]

picarones/adapters/vlm/mistral_vlm.py

@@ -0,0 +1,26 @@
+"""``MistralVLMAdapter`` — Pixtral 12b/Large (vision Mistral).
+
+Sprint A14-S45.  Délègue à ``MistralAdapter`` qui supporte la
+vision via les modèles ``pixtral-12b-2409``, ``pixtral-large-latest``.
+"""
+
+from __future__ import annotations
+
+from picarones.adapters.llm.mistral_adapter import MistralAdapter
+from picarones.adapters.vlm.base import BaseVLMAdapter
+
+
+class MistralVLMAdapter(BaseVLMAdapter, MistralAdapter):
+    """VLM Mistral (pixtral-12b-2409, pixtral-large-latest)."""
+
+    @property
+    def name(self) -> str:
+        return "mistral_vlm"
+
+    @property
+    def default_model(self) -> str:
+        # Ré-définit le défaut pour pointer vers un modèle vision.
+        return "pixtral-12b-2409"
+
+
+__all__ = ["MistralVLMAdapter"]

picarones/adapters/vlm/ollama_vlm.py

@@ -0,0 +1,26 @@
+"""``OllamaVLMAdapter`` — Modèles vision locaux via Ollama.
+
+Sprint A14-S45.  Délègue à ``OllamaAdapter`` (local, sans clé API).
+Modèles vision recommandés : ``llava``, ``llava:13b``, ``bakllava``,
+``llama3.2-vision``.
+"""
+
+from __future__ import annotations
+
+from picarones.adapters.llm.ollama_adapter import OllamaAdapter
+from picarones.adapters.vlm.base import BaseVLMAdapter
+
+
+class OllamaVLMAdapter(BaseVLMAdapter, OllamaAdapter):
+    """VLM local via Ollama (llava, bakllava, llama3.2-vision)."""
+
+    @property
+    def name(self) -> str:
+        return "ollama_vlm"
+
+    @property
+    def default_model(self) -> str:
+        return "llava"
+
+
+__all__ = ["OllamaVLMAdapter"]

picarones/adapters/vlm/openai_vlm.py

@@ -0,0 +1,22 @@
+"""``OpenAIVLMAdapter`` — GPT-4-Vision / GPT-4o (vision).
+
+Sprint A14-S45.  Délègue à ``OpenAIAdapter`` qui supporte déjà la
+vision via les modèles ``gpt-4o``, ``gpt-4-turbo``,
+``gpt-4-vision-preview``.
+"""
+
+from __future__ import annotations
+
+from picarones.adapters.llm.openai_adapter import OpenAIAdapter
+from picarones.adapters.vlm.base import BaseVLMAdapter
+
+
+class OpenAIVLMAdapter(BaseVLMAdapter, OpenAIAdapter):
+    """VLM OpenAI (gpt-4o, gpt-4-turbo, gpt-4-vision-preview)."""
+
+    @property
+    def name(self) -> str:
+        return "openai_vlm"
+
+
+__all__ = ["OpenAIVLMAdapter"]

picarones/app/__init__.py

@@ -0,0 +1,27 @@
+"""Cercle 4 — Application services.
+
+Couche d'orchestration : reçoit des requêtes (DTO Pydantic) depuis
+``interfaces/``, valide tout (chemins sandboxés, quotas, mode
+public/dev), assemble adapters + pipeline + evaluation, retourne
+des résultats sérialisables.
+
+C'est ici que les **6 P0 du S1** trouvent leur foyer définitif au
+S19 : ``WorkspaceManager`` qui isole les chemins par session,
+``BenchmarkService`` qui orchestre run + projections + persistance,
+``RegistryService`` qui construit les registres explicitement.
+
+Sous-packages :
+
+- ``services/`` — un service par domaine fonctionnel
+  (BenchmarkService, CorpusService, ReportService, JobService,
+  RegistryService, WorkspaceManager).
+- ``schemas/`` — DTO Pydantic pour API et CLI.  **Séparés** des
+  modèles de domaine pour éviter le couplage transport ↔ métier.
+
+Règle d'import : peut importer domain/, evaluation/, pipeline/,
+formats/, adapters/.  Ne doit **jamais** importer interfaces/.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

picarones/app/results.py

@@ -0,0 +1,123 @@
+"""``RunResult`` et ``RunDocumentResult`` — agrégats applicatifs d'un run.
+
+Sprint A14-S17 (créé) / S26 (déplacé depuis ``domain/`` car
+agrège des objets de ``evaluation/`` et ``pipeline/`` — la couche
+``domain`` n'a pas le droit d'importer de ces couches plus
+externes).
+
+Structure
+---------
+Un ``RunResult`` est l'agrégat complet d'un run :
+
+::
+
+    RunResult
+      ├── manifest: RunManifest
+      └── document_results: tuple[RunDocumentResult, ...]
+            ├── document_id: str
+            ├── pipeline_results: tuple[PipelineResult, ...]
+            │     (un par pipeline du run)
+            └── view_results: tuple[ViewResult, ...]
+                  (un par couple (vue, pipeline_éligible_à_la_vue))
+
+Le ``RunResult`` est sérialisable JSON pour persistance
+(typiquement éclaté en plusieurs fichiers : ``run_manifest.json``,
+``pipeline_results.jsonl``, ``view_results.jsonl`` — cf.
+``picarones.app.services.benchmark_service``).
+
+Anti-sur-ingénierie
+-------------------
+Pas d'agrégation pré-calculée (rang par vue, moyennes par
+pipeline, etc.) dans le ``RunResult`` lui-même — c'est de la
+**présentation**, pas du domain.  Le rapport HTML (S22) calcule
+ses agrégats à la volée depuis les ``ViewResult`` listés.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from picarones.domain.run_manifest import RunManifest
+from picarones.evaluation.views.base import ViewResult
+from picarones.pipeline.types import PipelineResult
+
+
+class RunDocumentResult(BaseModel):
+    """Tous les résultats d'un run pour un seul document.
+
+    Agrège :
+    - Les ``PipelineResult`` (un par pipeline exécutée).  Permet
+      de reconstituer ce qui a été produit (artefacts, durées,
+      erreurs).
+    - Les ``ViewResult`` (un par couple ``(view, pipeline)`` où le
+      pipeline a produit un artefact éligible à la vue).  Les
+      pipelines OMIS d'une vue n'ont PAS de ``ViewResult`` pour
+      cette vue (pattern d'omission explicite — cf. AltoView S15).
+
+    Le caller (typiquement le rapport HTML) reconstruit les
+    associations ``pipeline ↔ view_result`` via le champ
+    ``ViewResult.candidate_artifact_id`` qui pointe vers
+    ``Artifact.produced_by_step`` (lui-même corrélé au pipeline).
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    document_id: str = Field(min_length=1, max_length=256)
+    pipeline_results: tuple[PipelineResult, ...] = Field(default_factory=tuple)
+    view_results: tuple[ViewResult, ...] = Field(default_factory=tuple)
+
+
+class RunResult(BaseModel):
+    """Agrégat complet d'un run de benchmark.
+
+    Sérialisable JSON.  En pratique, persisté en plusieurs
+    fichiers (cf. ``BenchmarkService.persist``) pour permettre
+    une lecture sélective et un streaming jsonl.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    manifest: RunManifest
+    document_results: tuple[RunDocumentResult, ...] = Field(default_factory=tuple)
+
+    @property
+    def n_documents(self) -> int:
+        return len(self.document_results)
+
+    def view_results_for(self, view_name: str) -> tuple[ViewResult, ...]:
+        """Retourne tous les ``ViewResult`` du run pour une vue donnée.
+
+        Utile pour l'agrégation par vue (rangs, moyennes) côté
+        rapport HTML.  Préserve l'ordre d'apparition.
+        """
+        out: list[ViewResult] = []
+        for doc in self.document_results:
+            for vr in doc.view_results:
+                if vr.view_name == view_name:
+                    out.append(vr)
+        return tuple(out)
+
+    def pipeline_results_for(self, pipeline_name: str) -> tuple[PipelineResult, ...]:
+        """Retourne tous les ``PipelineResult`` d'un pipeline donné."""
+        out: list[PipelineResult] = []
+        for doc in self.document_results:
+            for pr in doc.pipeline_results:
+                if pr.pipeline_name == pipeline_name:
+                    out.append(pr)
+        return tuple(out)
+
+
+#: Type alias d'un renderer de rapport injecté par le caller.
+#:
+#: Signature canonique partagée par le ``RunOrchestrator`` (qui
+#: l'invoque) et le ``JobRunner`` (qui le transmet).  Reçoit
+#: ``(run_result, output_path, lang)``, écrit le fichier et retourne
+#: le ``Path`` effectivement écrit (généralement identique à
+#: ``output_path``, mais le renderer peut changer l'extension).
+ReportRenderer = Callable[["RunResult", Path, str], Path]
+
+
+__all__ = ["ReportRenderer", "RunDocumentResult", "RunResult"]