Déploiement de la vitrine Cinoc

.gitattributes

@@ -0,0 +1,8 @@
+*.pdf filter=lfs diff=lfs merge=lfs -text
+*.woff2 filter=lfs diff=lfs merge=lfs -text
+*.woff filter=lfs diff=lfs merge=lfs -text
+*.otf filter=lfs diff=lfs merge=lfs -text
+*.ttf filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,90 @@
+# Image **moteur** Cinoc pour un Hugging Face Space (SDK: docker).
+#
+# ≠ la vitrine lecture seule (deploy/Dockerfile{,.space}) : celle-ci **bake un vrai
+# moteur OCR gratuit** (Tesseract 5 + langues fra/lat/eng) pour qu'un visiteur du
+# Space public lance un run Tesseract **sans clé ni installation**. Les moteurs
+# cloud et les plugins tiers restent *gated* (mode public, fail-closed côté appli).
+#
+# Contexte de build « racine plate » (Dockerfile / requirements.txt / pyproject.toml
+# / cinoc / reports TOUS à la racine) — assemblé par .github/workflows/deploy-space.yml,
+# comme Dockerfile.space.
+FROM python:3.11-slim
+
+# ── Dépendances système : Tesseract 5 + langues + libs image (Pillow) ──────────
+# Les langues sont baquées (pas téléchargées au runtime) : un Space free-tier n'a
+# pas d'accès réseau garanti au démarrage, et le déterminisme exige une version de
+# binaire figée. ``fra`` est le besoin patrimonial central ; ``lat`` (latin) et
+# ``eng`` complètent. Pas de pin de version exacte (Debian point-release rebump
+# fréquemment ``5.3.0-2`` → ``+deb12u1`` → casse le build) : la repro repose sur la
+# capture de ``tesseract --version`` dans ``RunManifest.system_binaries_lock``.
+RUN apt-get update -o Acquire::Retries=3 \
+    && apt-get install -y --no-install-recommends -o Acquire::Retries=3 \
+        tesseract-ocr \
+        tesseract-ocr-fra \
+        tesseract-ocr-lat \
+        tesseract-ocr-eng \
+        libtiff6 \
+        libjpeg62-turbo \
+        libpng16-16 \
+        libwebp7 \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── Variables d'exécution ──────────────────────────────────────────────────────
+# TESSDATA_PREFIX : emplacement Debian bookworm des modèles Tesseract 5.
+ENV TESSDATA_PREFIX=/usr/share/tesseract-ocr/5/tessdata
+# OMP_THREAD_LIMIT=1 : OBLIGATOIRE sur free-tier 2 vCPU. Tesseract LSTM (oem 3)
+# parallélise via OpenMP ; non borné sur un CPU partagé il **deadlock** (incident
+# documenté côté Picarones, 2026-05-16) — l'OCR gèle et chaque document timeoute.
+# Mono-thread par appel = plus rapide ET déterministe ici.
+ENV OMP_THREAD_LIMIT=1
+# Mode public (verrou *fail-closed*) **non forcé** : par défaut l'instance exécute
+# ses moteurs (cloud compris) avec la clé de l'opérateur — pas de 403. Qui expose
+# un Space **public** et veut protéger sa clé d'un visiteur pose lui-même
+# CINOC_PUBLIC_MODE=true (alors seul le socle gratuit tesseract s'exécute).
+ENV PYTHONUNBUFFERED=1
+
+# ── Smoke-test du binaire au BUILD (fail-fast) ─────────────────────────────────
+# Un Tesseract cassé OU figé doit casser le BUILD (le Space garde l'image
+# précédente fonctionnelle), pas déployer une image qui gèle en silence :
+#   (a) le binaire charge ses libs et expose la langue ``fra`` (sinon build refusé) ;
+#   (b) une reconnaissance réelle sur une image générée se TERMINE sous 30 s — un
+#       timeout (rc 124) = deadlock OpenMP / libs incohérentes → build refusé.
+RUN set -eu; \
+    timeout 30 tesseract --version; \
+    timeout 30 tesseract --list-langs 2>&1 | grep -qx fra; \
+    printf 'P1\n16 16\n' > /tmp/smoke.pbm; \
+    i=0; while [ "$i" -lt 16 ]; do \
+        printf '1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0\n' >> /tmp/smoke.pbm; \
+        i=$((i + 1)); \
+    done; \
+    rc=0; \
+    timeout 30 tesseract /tmp/smoke.pbm - -l fra --psm 6 >/dev/null 2>&1 || rc=$?; \
+    rm -f /tmp/smoke.pbm; \
+    if [ "$rc" = 124 ]; then \
+        echo "FATAL: tesseract a gelé (timeout) — build refusé, libs incohérentes." >&2; \
+        exit 1; \
+    fi
+
+# ── Utilisateur non-root (sécurité d'un service exposé) ────────────────────────
+RUN useradd --create-home --uid 1000 cinoc
+WORKDIR /home/cinoc/app
+
+# ── Dépendances Python d'abord (cache de couche) ───────────────────────────────
+# requirements.txt fige le cœur + l'extra [serve] + pytesseract (wrapper du binaire).
+COPY requirements.txt ./requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+# ── Code + paquet (sans deps : tout est déjà figé ci-dessus) ───────────────────
+COPY pyproject.toml README.md ./
+COPY cinoc ./cinoc
+RUN pip install --no-cache-dir --no-deps .
+
+# ── Rapports bakés (lecture seule) — dossier toujours présent ──────────────────
+COPY reports ./reports
+ENV CINOC_REPORTS_DIR=/home/cinoc/app/reports
+
+USER cinoc
+EXPOSE 7860
+# 0.0.0.0 attendu en conteneur (le réseau est géré par la plateforme).
+CMD ["cinoc", "serve", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,52 @@
+---
+title: Cinoc — banc d'essai OCR/HTR/VLM
+emoji: 📜
+colorFrom: indigo
+colorTo: gray
+sdk: docker
+app_port: 7860
+pinned: false
+license: apache-2.0
+---
+
+# Cinoc — banc d'essai OCR/HTR/VLM
+
+Banc d'essai **déterministe** de pipelines de transcription (OCR / HTR / VLM).
+Ce Space **exécute un vrai OCR Tesseract gratuitement** — **sans clé ni
+installation** : déposez un corpus, lancez Tesseract, obtenez un rapport CER/WER/MER
+réel. Il sert aussi des rapports `RunResult` pré-calculés, rendus en HTML autonome.
+
+- `/` — liste des rapports disponibles
+- `/library` — préparer un corpus (upload ZIP)
+- `/benchmark` — lancer un run **Tesseract** (gratuit, local) sur un corpus
+- `/reports/<nom>` — un rapport rendu en HTML
+- `/health` — sonde de vivacité
+
+**Par défaut, l'instance exécute ses moteurs avec la clé de son opérateur** —
+aucun blocage. Sans clé posée, seul le **socle gratuit** tourne (Tesseract, aucun
+secret, aucun appel facturé) ; dès qu'une clé est présente (`MISTRAL_API_KEY`,
+`OPENAI_API_KEY`…), les moteurs **cloud** (OCR→LLM, VLM) s'exécutent normalement.
+
+## Utiliser un moteur cloud (Mistral, OpenAI…)
+
+1. **Secret** : `MISTRAL_API_KEY` = votre clé (Settings → Variables and secrets).
+   Le SDK `mistralai` est déjà dans `requirements.txt`. Redéployez.
+2. C'est tout : le menu déroulant « Modèle » du Banc d'essai se remplit directement
+   depuis l'API Mistral (`models.list`) et les prompts sont éditables par concurrent.
+
+> 🔴 **Sécurité** : sur un Space **public**, la clé que vous posez est dépensable par
+> n'importe quel visiteur. Rendez le Space **Private** (Settings → Visibility →
+> Private) si vous y posez une clé facturée, **ou** activez le verrou ci-dessous.
+
+## Verrou « mode public » — opt-in, pour protéger une clé sur un Space public
+
+Si vous tenez à exposer un Space **public** *tout en* gardant une clé posée sans
+qu'un visiteur puisse la dépenser, activez le verrou **fail-closed** : variable
+`CINOC_PUBLIC_MODE` = `true` (Settings → Variables and secrets). Alors seul le
+**socle gratuit** (Tesseract) s'exécute ; les moteurs **cloud**, les **imports
+distants** (IIIF/Gallica/…) et les **plugins tiers** sont **refusés** (`403`). Le
+verrou est **désactivé par défaut** : ne le posez que si ce scénario est le vôtre.
+
+> Ce fichier est l'en-tête de configuration du Space Hugging Face (`sdk: docker`).
+> Au déploiement, il devient le `README.md` racine du dépôt du Space ; le
+> `Dockerfile` et `requirements.txt` vivent dans `deploy/`.

cinoc/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.1.dev1+gea3d42207'
+__version_tuple__ = version_tuple = (0, 1, 1, 'dev1', 'gea3d42207')
+
+__commit_id__ = commit_id = 'gea3d42207'

cinoc/adapters/ANALYSE_COUCHE_5.md

@@ -0,0 +1,271 @@
+# ANALYSE_COUCHE_5.md — `adapters/` (Picarones → Cinoc)
+
+> **Type** : session d'ANALYSE (ne code rien). Guide de portage **durable**.
+> **Couche** : 5 = `adapters` (cf. `CLAUDE.md` §3 : `domain(1) ← formats(2) ← evaluation(3) ← pipeline(4) ← adapters(5) ← app(6) ← reports(7) ← interfaces(8)`).
+> **Source gelée** : `../Picarones/picarones/adapters/` — **41 fichiers, 9 682 LOC** (mesuré).
+> **Cible** : `cinoc/adapters/`.
+> **Couches amont mergées dont on dépend** : `domain` (mergée), `formats` (mergée), `evaluation` (plan acté `MIGRATION_COUCHE_3.md`), `pipeline` (à venir — porte le **contrat de module**).
+> **Partie 1 = durable** (source figée). **Partie 2 = périssable** (« à confirmer à la tranche »).
+
+---
+
+## 0. Drapeaux à lever AVANT toute construction (lire en premier)
+
+| # | Drapeau | Statut | Action |
+|---|---|---|---|
+| **F-0** | La consigne d'analyse disait « Couche4 », le titre/ livrable disent « couche 5 ». | Coquille. `CLAUDE.md` §3 + `PROMPT_ANALYSE_COUCHE.md` confirment **couche 5 = `adapters`**. | Aucun conflit. Analysé = `adapters`. |
+| **F-1** | `CLAUDE.md` D1 décrit le legacy comme « double contrat **`BaseOCRAdapter`→`BaseModule`** ». **Le code gelé ne contient PAS cet héritage.** | `base.py:58` = `class BaseOCRAdapter(ABC)` ; `llm/base.py:202` = `class BaseLLMAdapter(ABC)` ; **aucun n'hérite de `BaseModule`**. Le vrai contrat runtime est **`StepExecutor`** (`pipeline/protocols.py:42`, `execute(...)`). `BaseModule` (`domain/module_protocol.py`, `process(...)`) est **vestigial** : sa docstring `:24-27` *prétend* (à tort) que les adapters en sont des cas particuliers ; ses seuls usages sont un ré-export dans `__init__` + `evaluation/metrics/module_policy.py` (lui-même classé « mort » par `MIGRATION_COUCHE_3.md` §11). | **Ne PAS s'arrêter** : la *décision* D1 (un seul `Protocol` en couche 4, `BaseModule` supprimé) reste **correcte et même renforcée** — Picarones a déjà ce `Protocol` unique (`StepExecutor`). Seule la *caractérisation factuelle* de la source est à corriger : il s'agit d'un contrat **vestigial parallèle** (`BaseModule.process`), pas d'un emballage. Documenté §1.2. |
+| **F-2** | `CLAUDE.md` §8.8 dit « 8+8+8 adapters LLM/VLM ». | Réalité : **8 OCR + 4 LLM + 4 VLM**. | Direction (« → minimal/starter ») valide ; chiffres rectifiés §1.1. |
+| **F-3** | `_fallback_log.py` n'a qu'un consommateur final : le **détecteur narratif** `IMPORTER_FALLBACK_TRIGGERED`. | Or le **moteur narratif est SUPPRIMÉ** (`CLAUDE.md` §6, D2). | ⇒ « pas de consommateur = supprimé ». Verdict **SUPPRIMER** (remplacé par `logger.warning`). §1.3-corpus. |
+
+Aucun de ces points ne contredit une couche **mergée** ni une décision actée → analyse poursuivie.
+
+---
+
+# PARTIE 1 — ANALYSE DE LA SOURCE PICARONES (durable)
+
+## 1.1 Inventaire exact (41 fichiers / 9 682 LOC)
+
+| Sous-paquet | Fichiers | LOC | Rôle vérifié |
+|---|---|---|---|
+| **`/` (utils racine)** | 6 | **866** | I/O atomique, retry, http(x), downscale image, résolution de chemins. Mutualisés OCR+LLM. |
+| **`ocr/`** | 12 | **3 206** | Contrat `BaseOCRAdapter` + factory + 8 moteurs + sidecar confidences. |
+| **`corpus/`** | 8 | **3 045** | Importeurs de corpus patrimoniaux (IIIF, Gallica, eScriptorium, HTR-United, HuggingFace) + http urllib anti-SSRF + journal fallback. |
+| **`llm/`** | 6 | **1 208** | Post-correction texte (`RAW_TEXT → CORRECTED_TEXT`). Base + 4 providers. |
+| **`storage/`** | 3 | **964** | `ArtifactStore` (cache fichier) + `JobStore` (SQLite jobs web). |
+| **`vlm/`** | 6 | **393** | Transcription `IMAGE → RAW_TEXT` zéro-OCR. Base + 4 manifestes de composition. |
+
+Libs externes (toutes confinées à `adapters/`, conforme `CLAUDE.md` §3) : `pytesseract`+`PIL` (tesseract), `kraken`, `calamari-ocr`+TF, `pero-ocr`+torch, `google-cloud-vision`, `azure-ai-documentintelligence`, `mistralai`, `openai`, `anthropic`, `httpx` (ollama — **dép. cœur**, pas un extra), `datasets` (hf), `yaml`/`tqdm` (corpus). Le **noyau de contrat** (`ocr/base.py`, `factory.py`, `confidences.py`, `llm/base.py`, `vlm/base.py`, utils racine) n'importe **aucune** lib tierce sauf `httpx`/`PIL`.
+
+## 1.2 Le contrat réel (la couture décisive `domain↔pipeline↔adapters`)
+
+**Trois contrats coexistent ; un seul est vivant côté runtime.**
+
+| Contrat | Lieu | Forme | Statut réel |
+|---|---|---|---|
+| `BaseModule` | `domain/module_protocol.py:39` | `process(inputs)→outputs`, types `tuple`, **aucun** concern d'exécution | **Vestigial.** Aucun adapter ne l'hérite ni ne l'implémente. Consommateurs : ré-export `__init__` + `module_policy.py` (mort). |
+| **`StepExecutor`** | `pipeline/protocols.py:42` | `name`,`input_types`/`output_types` (`frozenset`), **`execute(inputs, params, context: RunContext, control: RunControl) → dict[ArtifactType, Artifact]`** | **Contrat vivant.** Porte deadline (`context.deadline`) + annulation (`control`). Satisfait par **duck-typing** (jamais hérité). |
+| `BaseOCRAdapter` / `BaseLLMAdapter` / `BaseVLMAdapter` | `adapters/{ocr,llm,vlm}/base.py` | ABC d'**implémentation** (défauts `input_types`/`output_types`, helpers, `name`/`execute` abstraits) | Ce sont des **mixins d'implémentation**, **pas** un second contrat. `BaseVLMAdapter(BaseLLMAdapter)` ; les deux autres `(ABC)`. |
+
+**Résolution `adapter_name → executor`** : pas de registre. `build_adapter_resolver(engines)` (`app/services/_benchmark_adapter_resolver.py:215`) construit un `dict[str, StepExecutor]` à partir d'**instances** d'engines fabriquées en amont, et lève `PicaronesError` sur collision de `name` à configs distinctes. La factory `ocr_adapter_from_name` (`ocr/factory.py:64`) est une **cascade `if/elif` codée en dur** (anti-OCP). **Aucune découverte de plugins entry-points** (`registry_service.py:39` le dit explicitement). Seule extensibilité « tierce » : `adapter_class: dotted.path` dans le YAML `run_spec` (`app/schemas/run_spec.py:32-62`), classe importable dans le venv.
+
+> ⚠️ **Conséquence pour Cinoc** : le `Protocol` de module que `CLAUDE.md` D1 veut construire en **couche 4** ≈ **`StepExecutor` déjà existant**. Les adapters l'implémentent **directement**. `BaseModule` est **supprimé sans perte**. *(`version` manque dans `StepExecutor`/`BaseOCRAdapter` → à **ajouter** pour la repro `RunManifest`, cf. §2.1.)*
+
+## 1.3 Verdicts fichier par fichier — **PROVISOIRE — à confirmer au build**
+
+Légende verdict : **G**=garder · **M**=modifier · **C**=changer de couche · **S**=supprimer · **I**=incrémental (porter à la tranche qui le consomme, pas avant).
+
+### Utils racine (`adapters/*.py`)
+
+| Fichier | LOC | Rôle vérifié | Consommateurs réels (hors tests) | Bugs / dette | Verdict |
+|---|---|---|---|---|---|
+| `__init__.py` | 28 | Docstring de paquet, `__all__=[]`. | 0 (imports par chemin complet). | — | **G** (mince) |
+| `_atomic_io.py` | 151 | `atomic_write_text` (tmp+`fsync`+`os.replace`). | `atomic_write_text` : **11 adapters**. | `atomic_write_bytes` = **0 conso** (mort). Corps dupliqué text/bytes. | **M** : garder `atomic_write_text`, **S** `atomic_write_bytes`. **`storage/` doit l'utiliser** (cf. infra). |
+| `_httpx_helpers.py` | 213 | Client httpx deadline-aware + cancel cross-thread (`make_httpx_client`, `translate_or_reraise`). | **1** (`llm/ollama_adapter`). | Détection « close » par **heuristique de message** (`:179-190`) fragile. Couple `adapters→pipeline.run_control`. | **G+M** (revoir l'heuristique ; unifier la trad. d'erreur). |
+| `_image.py` | 87 | Downscale image base64 (`PIL` lazy, dégradable). | **3** (ollama/openai/mistral LLM). | Bloc d'appel `if max_edge>0: downscale` **copié 3×** chez les callers. | **G** (factoriser l'appel dans la base LLM). |
+| `_retry.py` | 274 | Retry exponentiel + `Retry-After` + jitter, deadline-aware (`call_with_retry`, `is_retryable`, `compute_retry_wait`). | `call_with_retry` : **3 OCR cloud** ; primitives : `llm/base.py`. | **Bug** : jitter `×[1.0,1.5)` appliqué **après** le plafond → `DEFAULT_MAX_WAIT` (120 s) dépassé jusqu'à **180 s** (`:138-139`). `retry_after_seconds`/`DEFAULT_MAX_WAIT` exportés sans conso externe. **Boucle ré-implémentée** dans `llm/base.py:384-429` ET `corpus/_http.download_url`. | **M** : corriger le jitter ; **unifier les 3 implémentations** ; resserrer l'API publique. |
+| `output_paths.py` | 113 | `resolve_output_path` (segment par pipeline anti-collision). | **9 adapters**. | `context: Any` (duck-typing `RunContext`) → dégrade en silence si attribut absent. | **G**. |
+
+### `ocr/`
+
+| Fichier | LOC | Rôle / sortie | Consommateurs réels | Bugs / dette | Verdict |
+|---|---|---|---|---|---|
+| `__init__.py` | 48 | Façade ; ré-exporte les 8 adapters + base + factory. | traversé par `llm_pipeline_config`. | **Import eager** des 8 classes (sûr car les modules n'importent pas la lib lourde au top-level) mais court-circuite la robustesse lazy de la factory. | **M** (mince ; aligner sur le registre). |
+| `base.py` | 189 | `BaseOCRAdapter(ABC)` + `OCRAdapterError`. **`effective_output_types`** = sous-ensemble **garanti** (vs maximal). | 8 adapters + resolver + factory + cli + robustness. | **Pas d'attribut `version`** (repro). `control` jamais honoré (cf. dette §1.4). | **M** : = mixin d'impl ; **ajouter `version`** ; garder `effective_output_types`. Contrat = `Protocol` couche 4. |
+| `factory.py` | 194 | `ocr_adapter_from_name(name) → BaseOCRAdapter`. | cli + web + `__init__`. | **Cascade `if/elif`** (anti-OCP) ; alias incohérents (`calamari_ocr`→`calamari`, pas de court `kraken`) ; `_SUPPORTED`/`_ALIASES` divergent à la main ; message Azure cite `azure-ai-formrecognizer` ≠ SDK réel. | **C→app** : remplacer par **registre + entry-points** (`CLAUDE.md` §3 : registre = app/adapters, découverte = app). |
+| `confidences.py` | 164 | Sidecar JSON de confidences. `ConfidenceToken`=TypedDict `{text, confidence∈[0,1]}`, **niveau mot**, normalisation Tesseract 0-100→0-1. | **1** (tesseract). Artefact `CONFIDENCES` lu par `evaluation/calibration`. | `model_version:null` toujours sérialisé ; entrée `list[dict]` non typée. | **G+M** : logique en adapters ; **promouvoir `ConfidenceToken`→`domain`** quand la calibration est consommée (backlog domain `CLAUDE.md`). |
+| `precomputed.py` | 221 | **Starter.** Lit `<stem>.<label>.txt`. `IMAGE→RAW_TEXT`. 0 dép externe. | factory + builders. | Nommage `name` = `precomputed_<label>` (`_`) ≠ doc factory (`:`). `control` inutilisé ; double I/O policy `empty`. | **G** (starter) ; corriger nommage. |
+| `tesseract.py` | 548 | **Starter.** `pytesseract` (binaire). `RAW_TEXT` (+`CONFIDENCES`/`ALTO_XML` **opt-in** via `effective_output_types`). | factory + cli + web. | >400 LOC. `control` inutilisé (timeout subprocess compense). | **G** (starter) ; **trim/split <400**. |
+| `kraken.py` | 237 | HTR ML local (torch). `RAW_TEXT`. Extra `[kraken]`. | factory + web. | Deadline **ignorée** (inférence non interruptible) ; API Kraken 4.x fragile vs 5.x. | **G+I** (incrémental). |
+| `calamari.py` | 253 | OCR ligne (TF). `RAW_TEXT`. Extra `[calamari]`. | factory + web. | Parsing résultat fragile (`getattr(...,"sentence","")`) ; deadline ignorée. | **G+I**. |
+| `pero_ocr.py` | 226 | HTR ML local (torch, PAGE aplati). `RAW_TEXT`. | factory + web. | Docstring tronquée (`:1-3`) ; deadline ignorée ; ordre `page_size=(h,w)` à vérifier. | **G+I**. |
+| `google_vision.py` | 330 | Cloud (SDK **ou** REST/urllib). `RAW_TEXT`. | factory + web. | SDK path ignore la deadline ; motif HTTP dupliqué (cf. azure/mistral). | **G+I**. |
+| `azure_doc_intel.py` | 425 | Cloud async + polling (SDK ou REST). `RAW_TEXT`. | factory + web. | >400. **Meilleure gestion deadline** (REST) ; SDK path l'ignore. Backoff maison. | **G+I** ; trim<400. |
+| `mistral_ocr.py` | 371 | `/v1/ocr` (urllib) **ou** chat/vision (SDK). `RAW_TEXT`. | factory + web. | SDK chat ignore deadline. **Importe `adapters.llm.base.normalize_llm_content`** (couplage cross-famille). | **G+I** ; sortir `normalize_*` en helper partagé. |
+
+### `llm/` + `vlm/`
+
+| Fichier | LOC | Rôle / contrat | Consommateurs réels | Bugs / dette | Verdict |
+|---|---|---|---|---|---|
+| `llm/__init__.py` | 16 | Docstring cadrage. | 0. | — | **G**. |
+| `llm/base.py` | 582 | **Cœur.** `BaseLLMAdapter(ABC)`. **Double API** : `complete(prompt, image_b64, *, deadline, control)→LLMResult` (appel + retry) **et** `execute(...)` (orchestration fichier→complete→fichier). `RAW_TEXT→CORRECTED_TEXT`. | pipeline (llm_config/builder) + VLM + `mistral_ocr` (helper). | >400. `LLMResult.tokens_used` **jamais peuplé** (`:194` vs `:396`) → coût non remonté. `except Exception`(`:401`) intentionnel+tracé. | **M** : **split <400** (helpers / `LLMResult` / base / orchestration) ; **peupler ou supprimer `tokens_used`**. |
+| `llm/openai_adapter.py` | 123 | **Starter.** SDK `openai`, extra `[llm]`, `temperature=0`. | web factory. | `del control` (SDK non câblé, documenté). | **G** (starter). |
+| `llm/ollama_adapter.py` | 160 | **Starter.** httpx brut (**dép. cœur**), **seul à câbler `control`** (cancel cross-thread). | web factory. | `except (TimeoutException, HTTPError): pass` (`:131-132`) — re-raise délégué, à mieux commenter. | **G** (starter). |
+| `llm/anthropic_adapter.py` | 129 | Idem motif, extra `[llm]`. | web factory. | `del control`. | **G+I**. |
+| `llm/mistral_adapter.py` | 198 | Idem + table `_TEXT_ONLY_MODELS` (dégradé multimodal). | web factory. | Logs verbeux ; instance client par appel. | **G+I**. |
+| `vlm/__init__.py` | 42 | Façade ré-export. | 0 (hors tests). | — | **G+I**. |
+| `vlm/base.py` | 245 | `BaseVLMAdapter(BaseLLMAdapter)` : `IMAGE→RAW_TEXT`, override `execute` + prompts ; **garde-fou MRO** (`__init_subclass__`). | 0 instanciateur (2 docs). | — | **G+I** (porter à la tranche `zero_shot`). Conserver le garde MRO. |
+| `vlm/openai_vlm.py` | 22 | `(BaseVLMAdapter, OpenAIAdapter)` + `name`. | **0**. | — | **I/S** : ~90 % hérité, **0 conso** → ne **pas** porter spéculativement (porter à la tranche zero_shot). |
+| `vlm/anthropic_vlm.py` | 32 | idem. | **0**. | — | **I/S** idem. |
+| `vlm/mistral_vlm.py` | 26 | idem + `default_model=pixtral`. | **0**. | — | **I/S** idem. |
+| `vlm/ollama_vlm.py` | 26 | idem + `default_model=llava`. | **0**. | — | **I/S** idem. |
+
+### `corpus/`
+
+| Fichier | LOC | Source / sortie | Consommateurs réels | Bugs / dette | Verdict |
+|---|---|---|---|---|---|
+| `__init__.py` | 24 | Docstring « nommer/localiser (image, GT) » ; `__all__=[]`. | 0. | — | **G** (mince). |
+| `_http.py` | 270 | urllib + **anti-SSRF** (`validate_http_url`, blocage IP réservées, revalidation redirects) + retry deadline-aware. | iiif, gallica, escriptorium. | `install_opener` = **effet de bord global au process** (`:159`). Boucle retry ≈ `_retry`. | **G+M** : brique sécurité réutilisable (invariant `CLAUDE.md`) ; retirer l'`install_opener` global ; unifier le retry. |
+| `_fallback_log.py` | 98 | Journal mémoire des dégradations d'importeur. | `consume`←app `_benchmark_converter` → **détecteur narratif**. `record`←htr_united/hf. | Seul débouché = narratif. | **S** (narratif supprimé `CLAUDE.md` §6 → plus de consommateur ; remplacer par `logger.warning`). |
+| `iiif.py` | 567 | Manifeste IIIF v2/v3 → **`Corpus`**. | CLI (`import iiif`) + web + gallica. | >400. **Fuite de fichiers temp** si `output_dir=None` (`NamedTemporaryFile(delete=False)`, `:465`). `tqdm` lazy. | **G+I+M** : trim<400 ; corriger la fuite temp. Référence du contrat « → Corpus ». |
+| `gallica.py` | 563 | SRU+IIIF+OCR brut BnF → **`Corpus`** (délègue à `IIIFImporter`). | web seulement. | >400. **Bug latent** `selected_indices[i]+1` (additionne `IIIFCanvas`+int, `:415`). `_fetch_url` force `retries=1`. Beaucoup de surface morte (`search_gallica`, `get_metadata`…). | **M+I** : corriger le bug ; **S** des fonctions sans conso ; trim<400. |
+| `escriptorium.py` | 571 | API REST eScriptorium → **`Corpus`** + écriture distante (export couche OCR). | web (`import_document` seul). | >400. **BUG dur** `Corpus(source=...)` (champ = `source_path`, `:450`) → `TypeError` au 1ᵉʳ appel réel, **masqué par les mocks**. `image_path:str` ≠ domain `Path`. ~40 % surface API morte. | **M+I** : corriger le bug ; **S** `export_benchmark_as_layer`/`list_*`/`connect_*` (0 conso) ; trim<400. |
+| `htr_united.py` | 488 | Catalogue HTR-United (GitHub) → **dict-manifeste** (pas `Corpus`) + GT extraits (sans images). | web. | >400. **Pas de `_http`** (ni anti-SSRF ni retry). `except (URLError, Exception)`. ZIP **chargé entier en RAM**. `_DEMO_CATALOGUE`=**113 LOC de données fabriquées** dans le code. | **M+I** : sortie unifiée `Corpus` ; **données démo → `data/` (S du code)** ; passer par `_http` ; borner le download. |
+| `huggingface.py` | 464 | HF Hub (lib `datasets`) → **dict-manifeste** + paires `.jpg`/`.gt.txt`. | web. | >400. **Monkey-patch au load** (`_patch_dataset_replace_source`, `:456`). `except (ImportError, Exception): return 0` **muet** (lib absente indistinguable de dataset cassé). GT orphelin si `image.save` échoue. `_REFERENCE_DATASETS`=**109 LOC** en dur. Docstring annonce des fonctions inexistantes. | **M+I** : sortie unifiée `Corpus` ; extra `[hf]` + message clair ; supprimer le monkey-patch ; données → `data/`. |
+
+### `storage/`
+
+| Fichier | LOC | Backend / type | Consommateurs réels | Bugs / dette | Verdict |
+|---|---|---|---|---|---|
+| `__init__.py` | 58 | Façade ré-export. Docstring annonce 2 cibles **non livrées** (migration `web/jobs`, rapatriement history SQLite). | — | — | **G**. |
+| `artifact_store.py` | 417 | **Filesystem** (`index.jsonl` + `artifacts/<key>.json` + `payloads/<key>.bin`) indexé par `ArtifactKey.hash_hex()`. Expose `StoredArtifact{key, artifact, payload}`. | **0 direct** : consommé via le **Protocol `ArtifactCachePort`** (`pipeline/cache_protocol.py`) injecté dans l'executor (inversion de dépendance). | >400. **`put` non atomique** (3 écritures sous simple `Lock`) ; **pas de `fsync`** (réimplémente un écriture inférieure au lieu d'utiliser `_atomic_io`) ; **path-traversal non gardé** (`f"{key}.json"`) ; index non borné ; pas de concurrence multi-process. | **G+M** : **utiliser `_atomic_io`** ; **valider la clé / `validated_path`** (invariant `CLAUDE.md`) ; implémente un **port défini en couche 4**. Tranche *cache*. |
+| `job_store.py` | 489 | **SQLite** (table `jobs`, WAL, `schema_version`). `JobRecord`, `JobStore`. États `pending→running→{complete\|error\|cancelled\|interrupted}`. | **1** : `app/services/job_runner.py`. | >400. **Doublon** : un **2ᵉ `JobStore` legacy** vit en `interfaces/web/jobs.py:103` et c'est **lui** que l'app web tournante câble (`state.py:138`). `LIMIT` interpolé (neutralisé par `int()`). Pas de validation des transitions. | **G+M** : **UN seul** job store (celui-ci) ; **S** le doublon legacy (couche 8, hors périmètre mais à acter) — ⚠️ mais le canonical **n'a ni `job_events` ni reprise SSE `Last-Event-ID`** (assumé `job_store.py:48-54`), capacités que porte le legacy `web/jobs.py` **et dont dépend le stream SSE du web** (cf. `ANALYSE_COUCHE_8` §0/§1.3 D-γ) → **réabsorber l'événementiel AVANT** de supprimer le legacy ; valider les transitions. Tranche *web/async*. |
+
+`StoredArtifact` : **non-candidat domain confirmé** (`domain/artifact_key.py:22-24` : « infrastructures, pas des types purs » ; le pipeline le touche via Protocol, pas en direct). Reste en `adapters/storage`.
+
+## 1.4 Dette transverse vérifiée (durable)
+
+| # | Dette | Preuve | Portée |
+|---|---|---|---|
+| **D-A** | **`control: RunControl` jamais honoré** : tous les `execute()` OCR + LLM/VLM cloud le reçoivent mais **n'appellent jamais** `register_cancel_handle`. **Seul `ollama_adapter` câble l'annulation** (via `_httpx_helpers`). | `base.py:82-86` documente le contrat ; aucun adapter ne l'honore sauf ollama. | Gap d'annulation cross-thread généralisé. |
+| **D-B** | **Deadline asymétrique** : Tesseract (timeout subprocess) + Azure-REST (polling clampé) la respectent ; **tous les paths SDK** (Azure SDK, Google SDK, Mistral chat) l'ignorent (limite SDK) ; kraken/calamari/pero l'ignorent totalement. | `azure_doc_intel.py:366-379` (bon) vs `:261` (SDK ignore) ; `mistral_ocr.py:310-316`. | Un run ML local/SDK peut dépasser le budget en silence. |
+| **D-C** | **Retry implémenté 3×** : `_retry.call_with_retry`, `llm/base.py:384-429` (inline), `corpus/_http.download_url`. | grep. | Triple maintenance du même algorithme. |
+| **D-D** | **Deux piles HTTP** dans la même couche : `httpx` (`_httpx_helpers`+`_retry`, pour OCR/LLM cloud) vs `urllib` (`corpus/_http`, anti-SSRF, pour importeurs). Aucune ne réutilise l'autre. | grep : `corpus/*` n'importe jamais `_retry`/`_httpx_helpers`. | Scission lib/menace **assumée** mais coûteuse. |
+| **D-E** | **`__init__` à effet de bord** : `corpus/_http.py:159` fait `install_opener` **global** au process à l'import. | `:153-161`. | Viole l'esprit « `__init__` minces, aucun effet de bord » (`CLAUDE.md` §7). |
+| **D-F** | **Fracture du contrat de sortie corpus** : iiif/gallica/escriptorium → `Corpus` ; **htr_united/huggingface → `dict`-manifeste** + effets disque. 3/5 écrivent des fichiers. | tableaux §1.3-corpus. | Pas de contrat unique d'ingestion. |
+| **D-G** | **Code mort / surface non câblée** : `atomic_write_bytes` ; exports `_retry` sans conso ; ~40 % d'`escriptorium.py` ; commodités `gallica`/`hf` ; `JobRecord.is_terminal/is_live` ; `_MIGRATIONS` vide. | greps agents. | « pas de consommateur = supprimé ». |
+| **D-H** | **Données fabriquées dans le code** : `_DEMO_CATALOGUE` (113 LOC) + `_REFERENCE_DATASETS` (109 LOC) = ~220 LOC de fausses données servies en repli. | `htr_united.py:44`, `huggingface.py`. | Risque d'afficher du faux contenu ; doit être de la **donnée** (`data/`) ou supprimé. |
+| **D-I** | **Bugs latents masqués par les mocks** : `escriptorium Corpus(source=...)` (`:450`) ; `gallica selected_indices[i]+1` (`:415`). | lecture code + tests mockés. | Régression garantie au 1ᵉʳ appel réel → à corriger au portage. |
+| **D-J** | **`execution_mode` : déjà retiré** (« mensonge structurel », commit `5e13c0d`, mai 2026 — attribut décoratif jamais lu par le runner thread-only). 0 occurrence prod ; garde-fou de test anti-résurrection. | git show. | **Leçon** : ne **jamais** réintroduire d'attribut « au cas où » non câblé. |
+
+---
+
+# PARTIE 2 — RÉORGANISATION CIBLE Cinoc (périssable — « à confirmer à la tranche »)
+
+> Conforme `CLAUDE.md` : **deux axes**, **tranches verticales** (jamais « finir la couche de haut en bas »), **budgets <400 LOC**, **rupture nette zéro shim**, **narrative supprimé**, **« pas de consommateur = supprimé »**. La couche 5 se **remplit par tranches** (chaque adapter naît avec le pipeline qui le consomme), pas en bloc.
+
+## 2.1 Enveloppe (axe 1 — dimensionnée plein-scope, mais **définie en couche 4**)
+
+Le **contrat de module exécutable** n'est **pas** un livrable de la couche 5 : il vit en **couche 4** (`pipeline`, cf. `CLAUDE.md` D1). La couche 5 ne fait que **l'implémenter**. À acter quand on conçoit la couche 4 (rappelé ici car il façonne tous les adapters) :
+
+- **`Protocol` unique** ≈ `StepExecutor` de Picarones : `name`, **`version`** (➕ vs Picarones, repro `RunManifest`), `input_types`/`output_types` (`frozenset[ArtifactType]`), `execute(inputs, params, context, control) → dict`.
+- **`BaseModule` supprimé** (vestigial). Les ABC `Base*Adapter` deviennent de **simples mixins d'implémentation** (défauts + helpers + `_write_text_artifact()`), **pas** un contrat.
+- **`effective_output_types`** (garanti ⊂ maximal) **conservé** — sinon `missing_output` casse les steps quand un extra opt-in (Tesseract `CONFIDENCES`/`ALTO_XML`) n'est pas produit.
+- **Trancher la dette d'annulation `control`** (D-A/D-B) : soit honorer `control` partout où l'opération est annulable, soit assumer explicitement « best-effort deadline » (documenté, testé). Ne pas traîner un paramètre non câblé.
+
+**Registre + découverte (couche `app`, cf. `CLAUDE.md` §3)** : remplacer la cascade `if/elif` + les factories CLI/web dispersées par **un registre type-driven `adapter_name → factory`** + **découverte entry-points `cinoc.modules`** + `register()` local. **Seul point d'extension tiers = les briques de pipeline** (OCR/HTR/VLM/post-correction/segmentation/ordre de lecture/NER). **Corpus, métriques, sections, stores = first-party, non pluggables.**
+
+## 2.2 Surface (axe 2 — incrémentale, par tranches)
+
+**Starter pack** (le strict nécessaire au squelette ambulant) :
+
+| Brique | Fichiers source | Extra | Tranche |
+|---|---|---|---|
+| `precomputed` (OCR 0 dép) | `ocr/precomputed.py` | — | **squelette texte** (corpus pré-calculé → CER) |
+| `tesseract` (OCR binaire) | `ocr/tesseract.py` + `confidences.py` | binaire système | tôt (1ᵉʳ vrai moteur) |
+| `openai` + `ollama` (LLM) | `llm/base.py` + `openai_adapter.py` + `ollama_adapter.py` | `[llm]` (openai) ; `httpx`=cœur (ollama) | tranche OCR+LLM `text_only` |
+| utils racine | `_atomic_io`(text), `_retry`(corrigé+unifié), `output_paths`, `_image`, `_httpx_helpers` | — | portés **en bloc** avec le starter |
+
+**Incrémental (porter à la tranche qui le consomme)** : anthropic/mistral (LLM) ; kraken/calamari/pero/google/azure/mistral_ocr (OCR — extras dédiés) ; **VLM** (tranche `zero_shot` — ~90 % gratuit une fois le LLM porté, **0 conso aujourd'hui → ne pas porter avant**) ; importeurs corpus (un par un) ; `artifact_store` (tranche *cache*) ; `job_store` (tranche *web/async*) ; **store longitudinal *tidy*** (tranche *longitudinal*, **rapatrié** de `evaluation/metrics/history.py` → `adapters/storage`, cf. `MIGRATION_COUCHE_3.md` §8).
+
+## 2.3 Arborescence cible proposée (à confirmer)
+
+```
+cinoc/adapters/
+├── _atomic_io.py        atomic_write_text (+fsync)         [G, -atomic_write_bytes]
+├── _retry.py            retry unifié, jitter corrigé       [M, unifie les 3]
+├── _http.py             transport + anti-SSRF + retry      [fusion _httpx_helpers + corpus/_http ?]
+├── _image.py            downscale (PIL lazy)               [G]
+├── output_paths.py      resolve_output_path                [G]
+├── ocr/                 base(mixin)+precomputed+tesseract  [starter] ; reste incrémental
+│   └── confidences.py   (ConfidenceToken→domain à terme)
+├── llm/                 base+openai+ollama [starter] ; anthropic/mistral incrémental
+├── vlm/                 base+manifestes — tranche zero_shot uniquement
+├── corpus/              importeurs first-party, sortie UNIQUE = Corpus, 1 par tranche
+│                        [_fallback_log SUPPRIMÉ ; données démo → data/]
+└── storage/             artifact_store + job_store (UNIQUE) + history tidy (rapatrié)
+```
+*Note* : la **factory/registre** ne vit **pas** ici mais en `app/` (résolution `adapter_name`) ; la couche 5 ne fait qu'exposer des classes implémentant le `Protocol` couche 4.
+
+## 2.4 Application des 5 garde-fous
+
+- **Rupture nette / zéro shim** : un seul `JobStore` (S le legacy `web/jobs.py`) ; un seul contrat de sortie corpus (`Corpus`, S les dict-manifestes) ; pas de `BaseModule` ; une seule pile HTTP si possible (D-D).
+- **Budgets <400** : `llm/base.py`(582), `escriptorium`(571), `iiif`(567), `gallica`(563), `tesseract`(548), `job_store`(489), `htr_united`(488), `huggingface`(464), `azure`(425), `artifact_store`(417) **dépassent**. La plupart **rétrécissent** après retrait du code mort (D-G), des données démo (D-H) et dédup du boilerplate (`_write_text_artifact`, retry, HTTP). Sinon split ou entrée justifiée `test_file_budgets`.
+- **Pas de consommateur = supprimé** : `atomic_write_bytes`, `_fallback_log`, surface morte d'escriptorium/gallica/hf, exports `_retry` inutiles, VLM concrets tant que `zero_shot` n'existe pas.
+- **Tests d'archi jour 1** : whitelist `adapters/` = `domain` + `pipeline` + `formats` (+ `evaluation` pour le type `Corpus` chargé, **à expliciter** — Picarones le tolérait par wildcard) ; `no-side-effect-import` (tue le `install_opener` global D-E) ; `no-broad-except` (htr/hf `except Exception`) ; `file-budgets`.
+- **Feature entière + élaguée** : chaque adapter porté **avec** sa correction de bug (D-I), son extra optionnel, son message clair d'absence de dép, sans annotation de sprint.
+
+## 2.5 Libs cibles & arbitrages (périssable — « à confirmer à la tranche »)
+
+> Rappel : la minceur de la couche vient surtout de l'**élagage** (code mort, données démo, dédup), **pas** de l'ajout de libs. Une lib ne paie que si elle **retire plus de code que le wrapper qu'elle impose**. Contreparties transverses à toute dép : **supply-chain** (cf. `fastapi==0.136.3` / `MAL-2026-4750` exclue dans le `pyproject` Picarones ; `pip-audit` à tenir), **reproductibilité** (`dependencies_lock` du `RunManifest` → **épingler serré**), **code tiers in-process** (entry-points).
+
+| Lib / appel | Verdict | Raison / condition |
+|---|---|---|
+| `httpx` (transport REST unique) | ✅ **conditionnel** | Pour le REST à **auth simple** (ollama, mistral `/v1/ocr`, HF, eScriptorium, htr_united, openai-compatible). Unifie les 2 piles HTTP (D-D), corrige la deadline (D-B). **Garder le SDK** pour Google/Azure (auth JWT service-account / AD lourde). Anti-SSRF toujours à coder (transport dédié, **sans `install_opener` global** — D-E). |
+| Drop dual SDK/REST cloud | ✅ **conditionnel** | Seulement où le SDK n'offre ni timeout-par-appel ni annulation **et** l'auth est simple. Pas systématique. |
+| `huggingface_hub` | ✅ **extra `[hf]`** | Remplace le REST urllib maison de `huggingface.py` (pagination tronquée, `except` muet, monkey-patch — D-G). Lib lourde/mouvante → confinée à l'extra, épinglée. |
+| `importlib.metadata.entry_points` (stdlib) | ✅ **gaté** | Outil du point d'extension `cinoc.modules`. **Désactiver la découverte en mode public** (in-process = sécurité, `CLAUDE.md` §3) ; capter la **version** du plugin pour le `RunManifest`. |
+| `pydantic` v2 | ✅ **configs** / ❌ **par-token** | OK pour les **configs d'adapter** (petites, 1×, aligne le repo). **Pas** pour `ConfidenceToken` (milliers/page → coût de validation, cf. `MIGRATION_COUCHE_2.md` G-D) : `TypedDict`/`dataclass(slots=True)`, valider une fois à la frontière. |
+| `tenacity` (retry) | ❌ **garder maison** | Le retry doit être deadline/cancel-aware (`clamp_to_remaining`, `RunControl`), honorer `Retry-After`, et **testable déterministe** (horloge injectable). Tenacity impose un wrapper custom qui annule le gain. `_retry.py` maison (bug jitter corrigé) reste plus aligné. |
+| anti-SSRF · parseur IIIF · subprocess Tesseract | ❌ **garder maison** | Pas de lib mainstream fiable (SSRF, IIIF) ; le subprocess `pytesseract` est **ce qui honore la deadline** pour Tesseract — un binding C-API (`tesserocr`) la perdrait. |
+| ORM (SQLAlchemy) · async (`anyio`) | ❌ | `sqlite3` brut suffit (2 tables) ; runner **thread-only** acté (retrait `execution_mode`, D-J) → async = rupture injustifiée. |
+
+**Cible LOC** (rappel, périssable) : enveloppe + starter pack utile ≈ **3 700 LOC** ; parité complète nettoyée ≈ **6 500–7 000 LOC** (vs **9 682** Picarones, ≈ **−30 %**). La couche se remplit par tranches — elle n'a jamais besoin de revoir les 9,7k. *(Détail des leviers de coupe : §1.4 + §2.4.)*
+
+---
+
+# PARTIE 3 — RISQUES DE TRANSFERT & DETTES (avec détection)
+
+| Risque | Détail | Comment détecter / désamorcer |
+|---|---|---|
+| **R-1 Contrat couche 4 manquant** | La couche 5 ne peut être portée **qu'après** le `Protocol` de module (couche 4) + `RunContext`/`RunControl`/`Deadline`. | Construire d'abord la tranche pipeline minimale ; un adapter starter (`precomputed`) sert de **premier client** du `Protocol`. |
+| **R-2 `version` absent** | Picarones n'a pas d'attribut `version` sur les adapters → repro `RunManifest` incomplète. | Test : `RunManifest` doit capter `name+version` de chaque step ; refuser un module sans `version`. |
+| **R-3 Annulation/deadline (D-A/D-B)** | `control` non câblé partout sauf ollama ; deadline ignorée par SDK/ML local. | Test d'annulation : lancer un step long, déclencher `control.cancel()`, vérifier l'arrêt < N s. Décider par adapter : annulable ou « best-effort » documenté. |
+| **R-4 `ConfidenceToken`** | TypedDict local mot-niveau, échelle [0,1], normalisation Tesseract. À promouvoir en `domain` **quand** la métrique calibration le consomme. | Ne pas figer la forme avant le consommateur (backlog domain). Test de normalisation 0-100→0-1 + rejet <0/>100. |
+| **R-5 Sortie corpus non uniforme (D-F)** | Choisir **`Corpus`** comme sortie unique ; pousser l'**orchestration disque** (download→write→manifest) en **service `app`**, garder en couche 5 le **transport + parsing schéma**. | Test : tout importeur retourne un `Corpus` valide (pas de `dict`). Séparer « localiser » (adapter) de « matérialiser » (app). |
+| **R-6 Sécurité (anti-SSRF + chemins)** | `corpus/_http` porte l'anti-SSRF ; `artifact_store`/eScriptorium ne valident pas les chemins/URL. Invariant `CLAUDE.md` : `validated_path()` + URL contrôlée. | Test : URL loopback/IP réservée rejetée ; clé d'artefact `../` rejetée ; pas d'`install_opener` global (no-side-effect-import). |
+| **R-7 Bugs latents (D-I)** | ✅ **entièrement clos**. `Corpus(source=)` eScriptorium (sortie `CorpusSpec`, `source` ∈ `metadata` → `TypeError` impossible). `selected_indices[i]+1` Gallica : mapping vue↔`f{n}` direct (position 1-based = numéro de vue), **aucune indirection** portée. Les deux prouvés non-mockés (`test_escriptorium_local_server.py`, `test_gallica_local_server.py`). | **Test d'intégration non-mocké** : loopback réel (`http.server`) par source — préféré au `live` quand la source exige auth/instance privée. |
+| **R-8 Dérive de budget** | Fichiers riches >400. | `test_file_budgets` actif dès le 1ᵉʳ commit d'adapters ; budgets honnêtes, pas de gonflement silencieux. |
+| **R-9 Couplage cross-famille** | `mistral_ocr` importe `llm.base.normalize_llm_content`. | Extraire la normalisation de contenu LLM en helper neutre partagé ; test d'archi sur les imports inter-sous-paquets. |
+| **R-10 Deux JobStores** | Le legacy `interfaces/web/jobs.py` est celui réellement câblé. | Au portage : un seul store (`adapters/storage`), l'app web le consomme ; supprimer le legacy ; test qu'aucun `JobStore` ne vit hors `adapters/storage`. **⚠️ Le canonical doit d'abord réabsorber la table d'événements + la reprise `Last-Event-ID`** (absentes aujourd'hui), sinon le **stream SSE régresse** (cf. `ANALYSE_COUCHE_8` §0). |
+| **R-11 Données démo en dur (D-H)** | ~220 LOC de faux catalogues. | Les sortir en `data/*.yaml` **ou** supprimer ; un repli démo ne doit jamais se faire passer pour de la vraie donnée (champ `is_demo` explicite). |
+| **R-12 Numérique non rétro-compatible** | Comme la couche 2 (`MIGRATION_COUCHE_2.md` MIG-2) : Cinoc change normalisation/contrats → **toute « validation » par égalité de chiffres avec Picarones est invalide**. | Goldens **refaits**, pas hérités. |
+
+---
+
+## Résumé pour la session de CONSTRUCTION (3-5 points)
+
+1. **Le « double contrat » à tuer n'est pas un héritage** : Picarones a déjà **un** contrat runtime unique = `StepExecutor` (`pipeline/protocols.py`, `execute(inputs, params, context, control)`), que les adapters implémentent par duck-typing. `BaseModule` est **vestigial** (à supprimer sans perte). ⇒ Le `Protocol` couche 4 de Cinoc ≈ `StepExecutor` **+ un attribut `version`** ; les `Base*Adapter` deviennent de simples **mixins d'implémentation**.
+2. **Construire par tranches, starter pack d'abord** : `precomputed` + `tesseract`(+`confidences`) + `openai`+`ollama`, avec les utils racine (`_atomic_io`/`_retry` corrigé/`output_paths`/`_image`/`_httpx_helpers`) portés **en bloc**. Tout le reste (kraken/calamari/pero/cloud OCR, anthropic/mistral, **VLM**, importeurs, stores) est **incrémental — porté à la tranche qui le consomme**, jamais d'avance. **VLM = 0 consommateur aujourd'hui → ne pas porter avant la tranche `zero_shot`.**
+3. **Dettes à corriger AU portage (pas après)** : annulation `control` non câblée (D-A) + deadline asymétrique (D-B) à trancher ; **3 implémentations de retry à unifier** + bug jitter>plafond ; **bugs latents** `Corpus(source=)`/Gallica masqués par les mocks ; `artifact_store` doit utiliser `_atomic_io`+`fsync` et **valider les chemins** ; **un seul `JobStore`**.
+4. **Élagage discipliné** : **SUPPRIMER** `_fallback_log` (son seul débouché, le narratif, est supprimé), `atomic_write_bytes`, la surface morte (escriptorium/gallica/hf), `execution_mode` (déjà parti) ; **sortir** les ~220 LOC de données démo en `data/` ; **sortie corpus unique = `Corpus`** (fin des dict-manifestes). Registre/découverte = **couche `app`** (entry-points `cinoc.modules`), **seul point d'extension tiers = les briques de pipeline**.
+5. **Placement & dépendances** : les importeurs de corpus restent **first-party en couche 5** (transport + parsing → `Corpus`), l'**orchestration disque** remonte en service `app` ; le **store SQLite longitudinal/tidy** est **rapatrié** de `evaluation/` vers `adapters/storage` (cf. `MIGRATION_COUCHE_3.md`). Whitelist d'archi `adapters/` à **expliciter** (inclut `evaluation` pour le type `Corpus` chargé).
+
+## DoD vivante (couche 5) — **autorité de détail** ; le `MIGRATION_PLAN.md` indexe
+
+> **T8 (D-066)** : tous les modules du socle renvoient `StepOutput` ; les adapters LLM/VLM remontent `tokens_in/out` (OpenAI/Mistral `usage.prompt/completion_tokens`, Anthropic `usage.input/output_tokens`, Ollama `prompt_eval_count`/`eval_count`) via `LLMCompletion` — un seul point de logique (`_base.run_llm_step`).
+
+> **T12 (D-070)** : tesseract publie l'artefact `CONFIDENCES` (sidecar JSON de `ConfidenceToken`, `image_to_data` conf÷100, best-effort → sidecar vide + warning). Preuves : `tests/adapters/test_tesseract.py`.
+
+> **T14 (D-072)** : `+ ocr/kraken.py` (HTR, extra `[kraken]`, `model` requis, RAW_TEXT+CONFIDENCES) `+ ocr/mistral_ocr.py` (cloud à la page, kind `mistral_ocr`). Preuves : `tests/adapters/test_kraken.py` · `test_mistral_ocr.py`.
+
+> Tri-état : `[x]` fait **+ preuve** · `[ ]` à faire · `[~]` différé/réserve + raison.
+> Maj dans le **même commit** que le code. **Statut : ✅ T3 complet** — `precomputed` + `tesseract` + **`openai`** + **`ollama`** (LLM post-correction) verts, annulation câblée (D-A clos) **+ `mistral`** (post-correction cloud, extra `[mistral]`, secret `MISTRAL_API_KEY`) ; stores/VLM **par tranches**. **+ T5 `layout/`** : `precomputed` (source LAYOUT + recognizer région), `assembler` (`AltoAssembler`), **`crop`** (`crop_region` PIL — découpe réelle des blocs du pipeline hybride seg→OCR ; `PIL` ajouté à la whitelist archi `adapters`). — *preuves : `tests/adapters/layout/test_crop.py`, `…/test_alto_assembler.py`, `tests/pipeline/test_hybrid_real_bnl.py` (live)*. **+ T7 `corpus/`** : 1ᵉʳ importeur **IIIF** — `_http` (transport `httpx` durci anti-SSRF : http(s) seul, rejet userinfo + IP non publiques, redirections re-validées, taille plafonnée, **aucun `install_opener` global** ; **anti-DNS-rebinding fermé** D-051 : résolution unique → IP validées **épinglées** via `network_backend` `httpcore` custom (`_PinnedBackend`), URL/`Host`/SNI/cert TLS inchangés, ré-épinglage par redirection — `httpcore` whitelisté en archi adapters + extras ; **`download` en flux disque** D-052 : `.part` au fil de l'eau + `os.replace` atomique + cap `IMAGE_MAX_BYTES`, aucun fichier partiel ; `download` accepte `headers` — média eScriptorium **même-hôte** seul porte le jeton) + `iiif` (parser manifeste v2/v3 → `IIIFImage`, **images seules**, pur) ; matérialisation disque → **`CorpusSpec`** en `app/corpus_import.py` (R-5 : localiser ≠ matérialiser). Sortie **unique `CorpusSpec`** (fin des dict-manifestes). — *preuves : `tests/adapters/corpus/{test_iiif_parse,test_http_ssrf,test_iiif_local_server}.py` (transport réel loopback), `…/test_iiif_live.py` (distant, opt-in), `tests/app/test_corpus_import.py`*. **+ eScriptorium** (porteur de **GT** → corpus **scorable**) : `escriptorium.py` (auth token, pagination `next`, `extract_gt_text` couche transcription, pur ; `_http.fetch_json` gagne `headers`) + `import_escriptorium_corpus` (image + `.gt.txt` → `GroundTruthRef` RAW_TEXT). **R-7/D-I fermé** : pas de `Corpus(source=)` (la sortie est `CorpusSpec`, `source` ∈ `metadata`) — prouvé **non-mocké** (test loopback : auth header + pagination 2 pages + GT lignes/`content`). — *preuves : `tests/adapters/corpus/{test_escriptorium_parse,test_escriptorium_local_server}.py`, `tests/app/test_corpus_import_escriptorium.py`*. **+ Gallica** : `gallica.py` (`normalize_ark` + `manifest_url` **IIIF `/iiif/`** + `fetch_ocr_text` via **ALTO** `RequestDigitalElement` + `alto_to_text` ; `_http.fetch_bytes` ajouté pour parser l'ALTO en octets) — **images réutilisent `IIIFImporter`**, OCR = **référence étiquetée** : type domaine `REFERENCE_TEXT` (D-053, ≠ GT manuelle) + `gt_source=gallica_ocr` — non scoré par défaut, vue référence dédiée (opt-in). **2 bugs prod corrigés (D-058, révélés par la capture réelle)** : URL manifeste `/iiif/` manquant (→ 403, masqué par les mocks) ; `texteBrut` ALTCHA-gated → bascule ALTO (rupture nette, `texteBrut`/`_looks_like_html` supprimés). **R-7 clos** : mapping vue *i* ↔ `f{i}` lu dans l'URL d'image (`/f{n}/`), **sans indirection**, prouvé non-mocké sur **vraies pages Gallica** (`tests/fixtures/gallica_alto/`, *Pourceaugnac*). — *preuves : `tests/adapters/corpus/{test_gallica_parse,test_gallica_alto,test_gallica_local_server}.py`, `tests/app/test_corpus_import_gallica.py`*. **+ HTR-United & HuggingFace** (**découverte**, pas matérialisation) : `htr_united.py` (`fetch_catalogue` YAML via `_http.fetch_text` + `parse_catalogue` pur + recherche + **repli démo `is_demo`** ; `yaml` ajouté à la whitelist adapters) ; `huggingface.py` (`search_reference` socle intégré + `HuggingFaceCatalogue.search` API publique **best-effort** via `_http.fetch_json`, `source` ∈ {reference, api}). **+ import HF matérialisant** (D-054, Lot D) : `stream_pages` (convention Cinoc `image`+`ground_truth`, lib `datasets` en extra `[huggingface]`, `streaming=True`, `Image(decode=False)` → octets sans PIL, `loader` injectable) → `app.import_hf_corpus` (GT `RAW_TEXT` réelle) + endpoint `/api/corpus/import/huggingface` (CSRF, gate public 403, non-conforme 422, extra absent 409). **Importeurs cœur complets.** — *preuves : `tests/adapters/corpus/{test_htr_united,test_htr_united_local_server,test_huggingface,test_huggingface_local_server}.py`*. **+ T7 `storage/history_store.py`** : `HistoryStore` SQLite **longitudinal** — `add(HistoryRecord…)` (idempotent, PK `(run_id,pipeline,view,metric)`), `history(pipeline,view,metric)` (chronologique), `regressions(view,metric, threshold, higher_is_better)` (2 derniers runs, direction-aware). Persistance **pure de lignes primitives** (n'importe pas `RunResult`) ; 1 connexion/opération (thread-safe). — *preuves : `tests/adapters/storage/test_history_store.py` (vrai SQLite : round-trip, idempotence, persistance inter-instances, régression/seuil/sens)*
+
+**Enveloppe :**
+- [x] `precomputed` implémente le `Module` Protocol (couche 4) **directement**, avec `name`/`version`. — *preuve : `tests/adapters/test_precomputed.py` (`isinstance(.., Module)` ; lecture `<stem>.<label>.txt` → `RAW_TEXT` + `content_hash` ; UTF-8 strict ; annulation)*
+- [x] **1ᵉʳ vrai moteur : `tesseract`** (implémente `Module` directement ; `lang` anti-injection, timeout borné par la deadline, écrit dans le **workspace** ; pytesseract = **extra**, invocation **mockable** → CI sans binaire). — *preuve : `test_tesseract` (mock + validations + workspace + annulation) ; `test_live` opt-in*
+- [x] **2ᵉ famille de module : LLM post-correction** (`openai`, mode `text_only`) — `RAW_TEXT → CORRECTED_TEXT` ; SDK extra, invocation **mockable** (CI sans clé) ; **pipeline multi-étapes OCR→LLM** prouvé (`CORRECTED_TEXT` **non vide**, bug historique). — *preuve : `test_openai` + `test_llm_pipeline`*
+- [x] **2ᵉ LLM (généralisation prouvée) : `ollama`** — *même* contrat que `openai`, sortie `CORRECTED_TEXT`, **aucun cas particulier** ; transport `httpx` = **extra**, `_invoke_ollama` **mockable** (CI sans serveur). **Référence d'annulation câblée** : `_invoke_ollama` enregistre `client.close` via `RunControl.register_cancel_handle` → `trigger_cancel` ferme la connexion en vol ; « annulation vs panne » tranchée en sondant `is_cancelled` (`_fail_or_cancel`, **fiable** — remplace l'heuristique de message fragile, **D-A clos**). — *preuve : `test_ollama` (conformité Module + mock + workspace + annulation + `_fail_or_cancel` cancel/panne) ; mécanisme `register_cancel_handle` : `test_run_control` (fire-on-cancel · immédiat-si-déjà-annulé · once · ordre)*
+- [~] VLM/`zero_shot` (0 conso) · `Base*Adapter` mixins · confidences/ALTO · `unregister`/déduplication des handles (accumulation bénigne, runs bornés) : **différés**.
+
+**Garde-fous :**
+- [x] `layer_dependencies` (whitelist `adapters` explicitée : domain+pipeline+formats) · `no_side_effect_imports` · `no_broad_except` · `file_budgets`. — *preuve : `test_adapters_imports_are_allowed` + suite archi verte.* `[~]` `install_opener` global (D-E) : tué à la tranche HTTP.
+
+**Validation par tranche :** `MIGRATION_PLAN.md` §3 — starter pack via `Module` (T1-T3) · **1 seul `JobStore` avec SSE/`job_events` réabsorbés** (T4, cf. §0/D-γ) · bugs latents `Corpus(source=)`/`selected_indices+1` corrigés + test `live` (T7).
+
+- [~] **Différé** : kraken/calamari/pero/cloud OCR, anthropic/mistral, **VLM (0 conso → pas avant `zero_shot`)**, importeurs (1/tranche, sortie unique `Corpus`), stores. **Supprimer** `_fallback_log` + données démo en dur (→`data/`).
+
+---
+
+*Tous les verdicts de la Partie 1 sont marqués **PROVISOIRE — à confirmer au build** : le contact du code corrige souvent l'analyse.*

cinoc/adapters/__init__.py

@@ -0,0 +1,9 @@
+"""Couche 5 — ``adapters`` : modules concrets (starter pack).
+
+Chaque adapter implémente directement le ``Module`` Protocol (couche 4). Les
+dépendances lourdes (SDK LLM, moteurs OCR) sont des extras optionnels, importés
+dans le module qui les utilise — jamais ici. ``__init__`` mince, sans effet de
+bord.
+"""
+
+from __future__ import annotations

cinoc/adapters/_resilience.py

@@ -0,0 +1,170 @@
+"""Résilience des appels réseau (couche 5, adapters) : cap de concurrence + retry.
+
+Deux mécanismes, **par défaut, sans configuration**, pour qu'un run depuis l'UI
+web (n'importe qui) ne sature pas une API instable :
+
+- **Cap de concurrence par fournisseur** (``network_slot``) : un sémaphore borné
+  *par fournisseur* (Mistral, OpenAI… chacun le sien) → au plus N appels réseau
+  simultanés, quel que soit le nombre de threads du runner. C'est le fix
+  structurel du pool global partagé (Pero local + LLM réseau dans un même run).
+- **Retry borné** (``call_resilient``) : sur 429/5xx, attend ``Retry-After`` si le
+  serveur l'indique, sinon un backoff exponentiel borné + gigue, puis recommence.
+
+Stdlib pure (aucune dépendance). **Déterminisme (invariant §12)** : ces mécanismes
+ne changent que le *timing*, jamais la valeur renvoyée → le ``RunResult`` reste
+byte-identique. ``N`` = ``CINOC_NETWORK_CONCURRENCY`` (défaut 3, plancher 1).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import random
+import threading
+import time
+from collections.abc import Callable
+from contextlib import AbstractContextManager
+from typing import TypeVar
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+
+#: Plafond par défaut d'appels réseau concurrents **par fournisseur** (anti-429).
+_DEFAULT_LIMIT = 3
+_LIMIT_ENV = "CINOC_NETWORK_CONCURRENCY"
+#: Politique de retry : tentatives + backoff exponentiel borné (secondes).
+_DEFAULT_ATTEMPTS = 5
+_BASE_BACKOFF = 1.0
+_MAX_BACKOFF = 30.0
+#: Statuts HTTP retentés : 429 (rate limit) + 5xx transitoires (instabilité).
+_RETRYABLE_STATUS = frozenset({429, 500, 502, 503, 504})
+
+#: Registre process-global des sémaphores, créés paresseusement (aucun effet de
+#: bord à l'import). Protégé par un verrou : ``network_slot`` est thread-safe.
+_SEMAPHORES: dict[str, threading.BoundedSemaphore] = {}
+_REGISTRY_LOCK = threading.Lock()
+
+
+def _network_limit() -> int:
+    """Plafond effectif depuis l'environnement (défaut ``_DEFAULT_LIMIT``)."""
+    raw = os.environ.get(_LIMIT_ENV)
+    if raw is None:
+        return _DEFAULT_LIMIT
+    try:
+        value = int(raw)
+    except ValueError:
+        logger.warning(
+            "[resilience] %s=%r invalide (entier attendu) — défaut %d.",
+            _LIMIT_ENV,
+            raw,
+            _DEFAULT_LIMIT,
+        )
+        return _DEFAULT_LIMIT
+    return max(1, value)
+
+
+def network_slot(provider: str) -> AbstractContextManager[bool]:
+    """Sémaphore borné **du fournisseur** : ``with network_slot("mistral"): …``.
+
+    Au plus ``_network_limit()`` détenteurs simultanés par fournisseur. Chaque
+    fournisseur a son quota propre (un run OpenAI + Mistral ne les fait pas se
+    partager le budget). Le plafond est figé à la première création du fournisseur
+    (lecture d'environnement unique, déterministe pour la durée du process)."""
+    with _REGISTRY_LOCK:
+        sem = _SEMAPHORES.get(provider)
+        if sem is None:
+            sem = threading.BoundedSemaphore(_network_limit())
+            _SEMAPHORES[provider] = sem
+    return sem
+
+
+def _default_jitter() -> float:
+    return random.uniform(0.0, 1.0)
+
+
+def _backoff(attempt: int, jitter: Callable[[], float]) -> float:
+    """Backoff exponentiel borné + gigue (désynchronise les threads concurrents)."""
+    return min(_MAX_BACKOFF, _BASE_BACKOFF * (2.0**attempt)) + jitter()
+
+
+def http_is_retryable(exc: BaseException) -> bool:
+    """Vrai si l'exception SDK porte un statut HTTP transitoire (429/5xx).
+
+    Duck-typing assumé : les SDK httpx (mistralai/openai/anthropic) exposent
+    ``status_code``. Une erreur sans statut (réseau coupé, bug local) n'est **pas**
+    retentée — on ne masque pas un vrai défaut."""
+    return getattr(exc, "status_code", None) in _RETRYABLE_STATUS
+
+
+def http_retry_after(exc: BaseException) -> float | None:
+    """Délai ``Retry-After`` (secondes, borné) si le serveur l'indique, sinon ``None``.
+
+    Sonde l'en-tête sur ``exc.response.headers`` puis ``exc.headers`` ; tolère
+    toute absence/forme invalide (→ ``None`` → l'appelant calcule un backoff)."""
+    for holder in (getattr(exc, "response", None), exc):
+        headers = getattr(holder, "headers", None)
+        if headers is None or not hasattr(headers, "get"):
+            continue
+        raw = headers.get("retry-after")
+        if raw is None:
+            continue
+        try:
+            seconds = float(raw)
+        except (TypeError, ValueError):
+            continue
+        if seconds >= 0:
+            return min(_MAX_BACKOFF, seconds)
+    return None
+
+
+def call_resilient(
+    provider: str,
+    fn: Callable[[], T],
+    *,
+    is_retryable: Callable[[BaseException], bool] = http_is_retryable,
+    retry_after: Callable[[BaseException], float | None] = http_retry_after,
+    attempts: int = _DEFAULT_ATTEMPTS,
+    sleep: Callable[[float], None] = time.sleep,
+    jitter: Callable[[], float] = _default_jitter,
+) -> T:
+    """Exécute ``fn`` sous le quota du fournisseur, avec retry borné sur 429/5xx.
+
+    Acquiert ``network_slot(provider)`` **par tentative** (relâché pendant
+    l'attente → on ne gèle pas un quota en dormant). Sur erreur retentable et tant
+    qu'il reste des tentatives : attend ``Retry-After`` si fourni, sinon un backoff
+    exponentiel borné + gigue, puis recommence. Sinon l'exception remonte
+    (l'appelant la traduit en ``AdapterStepError`` → unité isolée par le runner).
+    ``sleep``/``jitter`` injectables (tests déterministes). **Ne change que le
+    *timing*, jamais la valeur renvoyée.**"""
+    for attempt in range(attempts):
+        delay = 0.0
+        with network_slot(provider):
+            try:
+                return fn()
+            except Exception as exc:
+                if not is_retryable(exc) or attempt == attempts - 1:
+                    raise
+                after = retry_after(exc)
+                delay = after if after is not None else _backoff(attempt, jitter)
+                logger.warning(
+                    "[resilience] %s : tentative %d/%d échouée (%s) — "
+                    "nouvelle tentative dans %.1f s.",
+                    provider,
+                    attempt + 1,
+                    attempts,
+                    type(exc).__name__,
+                    delay,
+                )
+        sleep(delay)  # hors du créneau : on ne retient pas le quota en dormant
+    raise AssertionError(  # pragma: no cover — la boucle retourne ou relance avant
+        "call_resilient : boucle épuisée sans issue"
+    )
+
+
+__all__ = [
+    "call_resilient",
+    "http_is_retryable",
+    "http_retry_after",
+    "network_slot",
+]

cinoc/adapters/_workspace.py

@@ -0,0 +1,31 @@
+"""Chemins de sortie dans le workspace (couche 5, partagé par les écrivains).
+
+Les adapters qui **produisent** un artefact (OCR, post-correction LLM) y déposent
+un fichier. Le ``stem`` dérivé du ``document_id`` est **injectif** et sans
+séparateur de chemin : encodage type URL (``quote``), **réversible** donc
+injectif, qui neutralise ``/`` (→ ``%2F``) et l'octet nul (→ ``%00``). Deux ids
+distincts ne peuvent jamais produire le même nom de fichier (et donc s'écraser) —
+y compris les cas limites ``a/_b`` vs ``a_/b`` qu'un simple échappement maison
+collisionnerait. Les ids courants (alphanumériques) restent lisibles.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from urllib.parse import quote
+
+
+def safe_document_stem(document_id: str) -> str:
+    """``document_id`` → composant de nom de fichier **injectif** et sans ``/``."""
+    return quote(document_id, safe="")
+
+
+def workspace_artifact_path(
+    workspace_uri: str, document_id: str, label: str, suffix: str
+) -> Path:
+    """Chemin ``<workspace>/<stem>.<label>.<suffix>`` (``stem`` injectif)."""
+    stem = safe_document_stem(document_id)
+    return Path(workspace_uri) / f"{stem}.{label}.{suffix}"
+
+
+__all__ = ["safe_document_stem", "workspace_artifact_path"]

cinoc/adapters/corpus/__init__.py

@@ -0,0 +1,39 @@
+"""Importeurs de corpus first-party (couche 5).
+
+Chaque importeur **localise** des ressources (transport + parsing de schéma) et
+retourne un type neutre ; la **matérialisation disque → ``CorpusSpec``** vit en
+couche ``app``. Module mince, aucun effet de bord à l'import.
+"""
+
+from __future__ import annotations
+
+from cinoc.adapters.corpus.escriptorium import (
+    EScriptoriumImporter,
+    EScriptoriumPage,
+)
+from cinoc.adapters.corpus.gallica import GallicaImporter, normalize_ark
+from cinoc.adapters.corpus.htr_united import (
+    HTRUnitedCatalogue,
+    HTRUnitedEntry,
+    fetch_catalogue,
+)
+from cinoc.adapters.corpus.huggingface import (
+    HuggingFaceCatalogue,
+    HuggingFaceDataset,
+)
+from cinoc.adapters.corpus.iiif import IIIFImage, IIIFImporter, parse_manifest
+
+__all__ = [
+    "EScriptoriumImporter",
+    "EScriptoriumPage",
+    "GallicaImporter",
+    "HTRUnitedCatalogue",
+    "HTRUnitedEntry",
+    "HuggingFaceCatalogue",
+    "HuggingFaceDataset",
+    "IIIFImage",
+    "IIIFImporter",
+    "fetch_catalogue",
+    "normalize_ark",
+    "parse_manifest",
+]

cinoc/adapters/corpus/_http.py

@@ -0,0 +1,408 @@
+"""Transport HTTP **durci anti-SSRF** pour les importeurs de corpus (couche 5).
+
+Un importeur va chercher des ressources à une URL **fournie par l'utilisateur** :
+le risque est qu'on serve de proxy vers le réseau interne (SSRF) ou qu'on télécharge
+sans borne (DoS mémoire/disque). Défenses, toutes testées :
+
+- **schéma** ``http``/``https`` seuls (pas de ``file://``, ``gopher://``…) ;
+- **pas de userinfo** dans l'URL ;
+- **résolution DNS validée** : *toutes* les IP résolues doivent être **publiques**
+  (rejet loopback / privé / link-local / réservé / multicast / non-spécifié) ;
+  une IP **littérale** n'est pas résolue du tout, et une adresse qui **encapsule**
+  une IPv4 (IPv4-mapped, NAT64 bien connu) est jugée sur cette IPv4 ;
+- **redirections re-validées** à chaque saut (une 30x ne peut pas pointer vers
+  l'interne) ; nombre de sauts borné ;
+- **taille plafonnée** au fil de l'eau (on ne fait pas confiance à
+  ``Content-Length``).
+
+**DNS-rebinding fermé — épinglage d'IP.** ``assert_public_url`` résout l'hôte
+**une seule fois**, valide **toutes** les IP, et **retourne** ces IP. La
+connexion vise alors directement l'IP **épinglée** (transport ``httpx`` à
+``network_backend`` custom, cf. :class:`_PinnedBackend`) : il n'y a **pas de
+seconde résolution** que pourrait détourner un DNS hostile. Le nom d'hôte de
+l'URL reste inchangé, donc le ``Host`` envoyé, le **SNI** et la vérification du
+certificat TLS portent toujours sur le vrai hôte (aucun override fragile) —
+seule la cible TCP est figée. L'épinglage est ré-appliqué **à chaque saut** de
+redirection. Le **gate « mode public » (403)** côté interface reste la première
+barrière (les imports distants y sont refusés) ; l'épinglage est la défense en
+profondeur, désormais étanche.
+
+Auth & redirections : les en-têtes (jeton) ne suivent **pas** un changement
+d'hôte (cf. ``_stream_validated``). Une seule pile HTTP (``httpx`` + son moteur
+``httpcore``) ; **aucun état global** (pas d'``install_opener``).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import ipaddress
+import json
+import os
+import socket
+import typing
+from collections.abc import Iterator
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import httpcore
+import httpx
+
+from cinoc.domain.errors import CinocError
+
+#: Plafonds (généreux mais bornés — un Space gratuit n'est pas un entrepôt).
+MANIFEST_MAX_BYTES = 16 * 1024 * 1024
+IMAGE_MAX_BYTES = 50 * 1024 * 1024
+DEFAULT_TIMEOUT = 30.0
+_MAX_REDIRECTS = 5
+_ALLOWED_SCHEMES = frozenset({"http", "https"})
+
+
+class CorpusHttpError(CinocError):
+    """Échec de transport d'un importeur de corpus."""
+
+
+class SsrfError(CorpusHttpError):
+    """L'URL cible une ressource interdite (schéma, userinfo ou IP non publique)."""
+
+
+class HttpFetchError(CorpusHttpError):
+    """La requête a échoué (statut, redirection cassée, dépassement de taille)."""
+
+
+#: Préfixe NAT64 « bien connu » (RFC 6052 §2.1) : les **32 derniers bits**
+#: portent l'IPv4 traduite. Sur un réseau IPv6-seul (DNS64 — macOS et beaucoup
+#: de réseaux mobiles), *toute* résolution d'un hôte IPv4 passe par là. Juger
+#: l'enveloppe IPv6 au lieu de l'IPv4 embarquée revient à refuser Gallica, IIIF
+#: et HuggingFace : ``64:ff9b::`` commence par un octet nul, donc tombe dans
+#: ``::/8``, que ``ipaddress`` classe **réservé**.
+_NAT64_WELL_KNOWN = ipaddress.IPv6Network("64:ff9b::/96")
+
+
+def _embedded_ipv4(
+    ip: ipaddress.IPv4Address | ipaddress.IPv6Address,
+) -> ipaddress.IPv4Address | None:
+    """L'IPv4 réellement visée par ``ip``, ou ``None`` si elle n'en encapsule pas.
+
+    Deux encapsulations existent : ``::ffff:a.b.c.d`` (IPv4-mapped) et le NAT64
+    bien connu. Un préfixe NAT64 **propre au site** (RFC 6052 §2.2) est
+    indétectable et reste jugé comme l'IPv6 globale qu'il est.
+    """
+    mapped = getattr(ip, "ipv4_mapped", None)
+    if mapped is not None:
+        return typing.cast(ipaddress.IPv4Address, mapped)
+    if isinstance(ip, ipaddress.IPv6Address) and ip in _NAT64_WELL_KNOWN:
+        return ipaddress.IPv4Address(int(ip) & 0xFFFFFFFF)
+    return None
+
+
+def _is_public(ip: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:
+    """``ip`` vise-t-elle une ressource publique ?
+
+    Une adresse qui **encapsule** une IPv4 est jugée sur cette IPv4 : le filtre
+    ne se laisse donc pas contourner par l'enveloppe (``64:ff9b::7f00:1`` est
+    du loopback, et refusé) ni ne refuse à tort une cible publique traduite.
+    """
+    embedded = _embedded_ipv4(ip)
+    if embedded is not None:
+        ip = embedded
+    return not (
+        ip.is_private
+        or ip.is_loopback
+        or ip.is_link_local
+        or ip.is_reserved
+        or ip.is_multicast
+        or ip.is_unspecified
+    )
+
+
+def assert_public_url(url: str) -> tuple[str, ...]:
+    """Valide ``url`` et **retourne les IP publiques** vers lesquelles épingler.
+
+    Résout l'hôte **une seule fois** et exige que **toutes** les IP retournées
+    soient publiques : un nom qui résout (même partiellement) vers l'interne est
+    rejeté (``SsrfError``). Les IP validées sont retournées pour que l'appelant
+    **épingle** la connexion dessus (anti-DNS-rebinding) — pas de seconde
+    résolution. Pour une IP littérale, retourne cette IP (aucun DNS réel).
+    """
+    parts = urlsplit(url)
+    if parts.scheme not in _ALLOWED_SCHEMES:
+        raise SsrfError(f"schéma non autorisé : {parts.scheme!r} (http/https seuls).")
+    if parts.username or parts.password:
+        raise SsrfError("userinfo interdit dans l'URL.")
+    host = parts.hostname
+    if not host:
+        raise SsrfError("URL sans hôte.")
+    try:
+        literal = ipaddress.ip_address(host)
+    except ValueError:
+        literal = None  # type: ignore[assignment]
+    if literal is not None:
+        # Promesse tenue : une IP littérale ne passe **pas** par le résolveur.
+        # Y passer laissait un DNS64 substituer une adresse NAT64 à l'IP écrite
+        # noir sur blanc dans l'URL — et la rejeter.
+        if not _is_public(literal):
+            raise SsrfError(f"IP non publique : {host}.")
+        return (host,)
+    port = parts.port or (443 if parts.scheme == "https" else 80)
+    try:
+        infos = socket.getaddrinfo(host, port, proto=socket.IPPROTO_TCP)
+    except OSError as exc:
+        raise SsrfError(f"résolution DNS impossible pour {host!r} : {exc}.") from exc
+    pins: list[str] = []
+    for info in infos:
+        addr = str(info[4][0])  # sockaddr[0] = adresse textuelle (IPv4/IPv6)
+        if not _is_public(ipaddress.ip_address(addr)):
+            raise SsrfError(
+                f"hôte {host!r} résout vers une IP non publique ({addr})."
+            )
+        if addr not in pins:
+            pins.append(addr)
+    return tuple(pins)
+
+
+class _PinnedBackend(httpcore.SyncBackend):
+    """Épingle la cible TCP sur des IP **pré-validées** (anti-DNS-rebinding).
+
+    ``httpcore`` appelle ``connect_tcp(host, port)`` avec le **nom d'hôte** de
+    l'origine ; on substitue les IP déjà résolues+validées, sans repasser par le
+    DNS. Le nom d'hôte de l'URL restant inchangé, le SNI et la vérification du
+    certificat TLS (pilotés par ``httpcore`` depuis l'origin) portent toujours
+    sur le **vrai hôte** — donc aucun override fragile. On essaie les IP dans
+    l'ordre (comme ``socket.create_connection`` le ferait), préservant le
+    repli multi-adresses.
+    """
+
+    def __init__(self, ips: tuple[str, ...]) -> None:
+        super().__init__()
+        self._ips = ips
+
+    def connect_tcp(
+        self,
+        host: str,
+        port: int,
+        timeout: float | None = None,
+        local_address: str | None = None,
+        socket_options: typing.Any = None,
+    ) -> httpcore.NetworkStream:
+        last_exc: httpcore.ConnectError | None = None
+        for ip in self._ips:
+            try:
+                return super().connect_tcp(
+                    ip,
+                    port,
+                    timeout=timeout,
+                    local_address=local_address,
+                    socket_options=socket_options,
+                )
+            except httpcore.ConnectError as exc:
+                last_exc = exc
+        assert last_exc is not None  # _ips est non vide (cf. _make_client)
+        raise last_exc
+
+
+def _pinned_transport(ips: tuple[str, ...]) -> httpx.HTTPTransport:
+    """Transport ``httpx`` dont le backend réseau épingle ``ips``.
+
+    ``httpx`` n'expose pas ``network_backend`` ; on le pose sur le pool interne
+    (seul point d'injection). Le ``isinstance`` fait échouer **bruyamment** si
+    une future version de ``httpx`` change la forme du pool, plutôt que de
+    contourner silencieusement l'épinglage.
+    """
+    transport = httpx.HTTPTransport()
+    pool = transport._pool
+    if not isinstance(pool, httpcore.ConnectionPool):  # pragma: no cover
+        transport.close()
+        raise CorpusHttpError("épinglage IP indisponible : transport httpx inattendu.")
+    pool._network_backend = _PinnedBackend(ips)
+    return transport
+
+
+def _make_client(pins: tuple[str, ...] | None, timeout: float) -> httpx.Client:
+    """Client mono-saut. ``pins`` vide/None → résolution httpx normale.
+
+    Le cas ``None`` n'arrive qu'en test (``assert_public_url`` neutralisé en
+    no-op pour viser le loopback) ; en production il est toujours non vide.
+    """
+    if not pins:
+        return httpx.Client(timeout=timeout, follow_redirects=False)
+    return httpx.Client(
+        transport=_pinned_transport(pins), timeout=timeout, follow_redirects=False
+    )
+
+
+@contextlib.contextmanager
+def _stream_validated(
+    url: str, *, timeout: float, headers: dict[str, str] | None = None
+) -> Iterator[httpx.Response]:
+    """GET en streaming, **épinglé à l'IP validée** et re-validé à chaque saut.
+
+    Chaque saut (origine + redirections, bornées) : résout+valide une fois via
+    ``assert_public_url``, épingle la connexion sur l'IP retournée, puis envoie.
+    Les en-têtes fournis (ex. ``Authorization: Token …``) ne sont **jamais**
+    propagés vers un **hôte différent** de l'origine (fuite de credentials sur
+    redirection). Un client ``httpx`` distinct est créé par saut (épinglage
+    propre à l'IP du saut) ; tous sont fermés à la sortie du contexte.
+    """
+    origin_host = urlsplit(url).hostname
+    current = url
+    with contextlib.ExitStack() as stack:
+        for _ in range(_MAX_REDIRECTS + 1):
+            pins = assert_public_url(current)
+            # Auth conservée seulement tant qu'on reste sur l'hôte d'origine.
+            hop_headers = headers if urlsplit(current).hostname == origin_host else None
+            client = stack.enter_context(_make_client(pins, timeout))
+            request = client.build_request("GET", current, headers=hop_headers)
+            response = client.send(request, stream=True)
+            if response.is_redirect:
+                location = response.headers.get("location", "")
+                response.close()
+                if not location:
+                    raise HttpFetchError(
+                        f"redirection sans 'Location' depuis {current!r}."
+                    )
+                current = str(request.url.join(location))
+                continue
+            try:
+                yield response
+            finally:
+                response.close()
+            return
+        raise HttpFetchError(f"trop de redirections (> {_MAX_REDIRECTS}) pour {url!r}.")
+
+
+def _read_capped(response: httpx.Response, max_bytes: int) -> bytes:
+    chunks: list[bytes] = []
+    total = 0
+    for chunk in response.iter_bytes():
+        total += len(chunk)
+        if total > max_bytes:
+            raise HttpFetchError(f"réponse dépasse le plafond de {max_bytes} octets.")
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
+def fetch_json(
+    url: str,
+    *,
+    timeout: float = DEFAULT_TIMEOUT,
+    headers: dict[str, str] | None = None,
+) -> object:
+    """Récupère et parse un JSON ; anti-SSRF + plafond ``MANIFEST_MAX_BYTES``.
+
+    ``headers`` permet l'authentification d'API (ex. ``Authorization: Token …``) ;
+    il n'est jamais journalisé (les messages d'erreur ne portent que l'URL).
+    """
+    try:
+        with _stream_validated(url, timeout=timeout, headers=headers) as response:
+            response.raise_for_status()
+            raw = _read_capped(response, MANIFEST_MAX_BYTES)
+    except httpx.HTTPStatusError as exc:
+        raise HttpFetchError(
+            f"statut HTTP {exc.response.status_code} sur {url!r}."
+        ) from exc
+    except httpx.HTTPError as exc:
+        raise HttpFetchError(f"échec de transport sur {url!r} : {exc}.") from exc
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise HttpFetchError(f"réponse non-JSON depuis {url!r} : {exc}.") from exc
+
+
+def download(
+    url: str,
+    dest: Path,
+    *,
+    timeout: float = DEFAULT_TIMEOUT,
+    headers: dict[str, str] | None = None,
+) -> None:
+    """Télécharge ``url`` vers ``dest`` en **flux disque** ; anti-SSRF + plafond.
+
+    Écrit au fil de l'eau dans un fichier ``.part`` voisin (jamais tout le corps
+    en RAM), plafonne à ``IMAGE_MAX_BYTES``, puis **renomme atomiquement**
+    (``os.replace``) vers ``dest``. À la moindre erreur (statut, dépassement de
+    plafond, I/O, annulation), le ``.part`` est supprimé : **aucun fichier
+    partiel** n'est laissé derrière, et ``dest`` n'apparaît qu'une fois complet.
+
+    ``headers`` (ex. ``Authorization``) n'est transmis qu'à l'hôte d'origine —
+    ``_stream_validated`` le retire sur une redirection cross-hôte (cf. D-050).
+    """
+    part = dest.with_name(dest.name + ".part")
+    try:
+        with _stream_validated(url, timeout=timeout, headers=headers) as response:
+            try:
+                response.raise_for_status()
+            except httpx.HTTPStatusError as exc:
+                raise HttpFetchError(
+                    f"statut HTTP {exc.response.status_code} sur {url!r}."
+                ) from exc
+            total = 0
+            with part.open("wb") as handle:
+                for chunk in response.iter_bytes():
+                    total += len(chunk)
+                    if total > IMAGE_MAX_BYTES:
+                        raise HttpFetchError(
+                            f"réponse dépasse le plafond de {IMAGE_MAX_BYTES} octets."
+                        )
+                    handle.write(chunk)
+        os.replace(part, dest)
+    except BaseException:
+        part.unlink(missing_ok=True)
+        raise
+
+
+def fetch_bytes(
+    url: str,
+    *,
+    timeout: float = DEFAULT_TIMEOUT,
+    headers: dict[str, str] | None = None,
+) -> bytes:
+    """Récupère un corps **binaire** en mémoire ; anti-SSRF + plafond manifeste.
+
+    Pour les ressources qui doivent être parsées depuis des **octets** (ex. ALTO
+    Gallica : lxml refuse un ``str`` portant une déclaration d'encodage XML).
+    """
+    try:
+        with _stream_validated(url, timeout=timeout, headers=headers) as response:
+            response.raise_for_status()
+            return _read_capped(response, MANIFEST_MAX_BYTES)
+    except httpx.HTTPStatusError as exc:
+        raise HttpFetchError(
+            f"statut HTTP {exc.response.status_code} sur {url!r}."
+        ) from exc
+    except httpx.HTTPError as exc:
+        # Échec de transport (connexion/timeout/protocole) : on l'enveloppe en
+        # HttpFetchError pour que les appelants n'aient qu'un type réseau à gérer
+        # (jamais une exception httpx brute qui échapperait au repli).
+        raise HttpFetchError(f"échec de transport sur {url!r} : {exc}.") from exc
+
+
+def fetch_text(
+    url: str,
+    *,
+    timeout: float = DEFAULT_TIMEOUT,
+    headers: dict[str, str] | None = None,
+) -> str:
+    """Récupère un corps **texte** (UTF-8, erreurs remplacées) ; anti-SSRF + plafond.
+
+    Pour les endpoints qui ne servent pas du JSON (ex. catalogue HTR-United).
+    """
+    # Accept #15 : un corps distant peut contenir des octets non-UTF-8 isolés ;
+    # `errors="replace"` insère U+FFFD plutôt que d'échouer sur une donnée mal
+    # encodée (le contenu reste exploitable, pas une GT manuelle).
+    return fetch_bytes(url, timeout=timeout, headers=headers).decode(
+        "utf-8", errors="replace"
+    )
+
+
+__all__ = [
+    "CorpusHttpError",
+    "HttpFetchError",
+    "IMAGE_MAX_BYTES",
+    "MANIFEST_MAX_BYTES",
+    "SsrfError",
+    "assert_public_url",
+    "download",
+    "fetch_bytes",
+    "fetch_json",
+    "fetch_text",
+]

cinoc/adapters/corpus/escriptorium.py

@@ -0,0 +1,185 @@
+"""Importeur de corpus **eScriptorium** (API REST) — couche 5.
+
+Rôle : **localiser** les pages d'un document eScriptorium (auth par token →
+liste paginée des *parts* + leur transcription) et retourner un type neutre. La
+**matérialisation disque** (download image + écriture GT → ``CorpusSpec``) vit en
+couche ``app`` (``app/corpus_import.py``).
+
+Contrairement à IIIF, eScriptorium porte une **vérité-terrain** (la couche de
+transcription choisie) → le corpus importé est **scorable** (CER/WER).
+
+API consommée (lecture seule) :
+
+- ``GET /api/documents/{pk}/parts/``                       → pages (paginé) ;
+- ``GET /api/documents/{pk}/parts/{pk}/transcriptions/``   → transcriptions.
+
+Dette de la source **non reprise** : l'export distant de couche OCR, le listing
+projets/connexion (surface morte ~40 %), et surtout le bug latent
+``Corpus(source=…)`` — ici la sortie est un ``CorpusSpec`` (``source`` va dans
+``metadata``), structurellement à l'abri.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urljoin, urlsplit
+
+from cinoc.adapters.corpus._http import DEFAULT_TIMEOUT, HttpFetchError, fetch_json
+
+logger = logging.getLogger(__name__)
+
+#: Couche de transcription par défaut (libellé eScriptorium usuel pour la GT).
+DEFAULT_LAYER = "manual"
+#: Borne de pagination (un document = au plus quelques milliers de pages).
+_MAX_PAGES = 10_000
+
+
+@dataclass(frozen=True)
+class EScriptoriumPage:
+    """Une page (*part*) : son URL d'image absolue + son texte GT (peut être vide)."""
+
+    pk: int
+    image_url: str
+    gt_text: str
+    title: str
+
+
+def _image_uri(item: dict[str, Any], base_url: str) -> str:
+    """Extrait l'URL d'image d'une *part* (champ ``image`` : str ou objet)."""
+    img = item.get("image")
+    if isinstance(img, dict):
+        img = img.get("uri") or img.get("url") or ""
+    if not isinstance(img, str) or not img:
+        return ""
+    return urljoin(base_url, img)
+
+
+def _layer_name(transcription: dict[str, Any]) -> str:
+    nested = transcription.get("transcription")
+    if isinstance(nested, dict):
+        return str(nested.get("name", ""))
+    return str(transcription.get("name", ""))
+
+
+def extract_gt_text(transcriptions: list[dict[str, Any]], layer: str) -> str:
+    """Texte GT de la couche ``layer`` (lignes jointes, ou ``content``). Pur.
+
+    ``layer`` vide → première transcription rencontrée. Renvoie ``""`` si la
+    couche demandée est absente.
+    """
+    for transcription in transcriptions:
+        if layer and _layer_name(transcription) != layer:
+            continue
+        lines = transcription.get("lines") or []
+        if lines:
+            return "\n".join(
+                str(line.get("content", ""))
+                for line in lines
+                if isinstance(line, dict) and line.get("content")
+            )
+        return str(transcription.get("content", "") or "")
+    return ""
+
+
+class EScriptoriumImporter:
+    """Localise les pages d'un document eScriptorium (auth + API, **sans disque**)."""
+
+    name = "escriptorium"
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        layer: str = DEFAULT_LAYER,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._layer = layer
+        self._timeout = timeout
+
+    def _headers(self) -> dict[str, str]:
+        # Le token n'est jamais journalisé (cf. _http : erreurs sans en-têtes).
+        return {"Authorization": f"Token {self._token}", "Accept": "application/json"}
+
+    def _get(self, url: str) -> dict[str, Any]:
+        data = fetch_json(url, timeout=self._timeout, headers=self._headers())
+        if not isinstance(data, dict):
+            raise HttpFetchError(
+                f"réponse eScriptorium inattendue (objet JSON attendu) : {url!r}."
+            )
+        return data
+
+    def _paginate(self, path: str) -> list[dict[str, Any]]:
+        """Suit les liens ``next`` jusqu'à épuisement, **sans quitter l'hôte**.
+
+        Le ``next`` est contrôlé par le serveur : on **n'envoie jamais le jeton**
+        vers un hôte différent de ``base_url`` (un ``next`` cross-hôte est ignoré).
+        """
+        base_host = urlsplit(self._base_url).hostname
+        results: list[dict[str, Any]] = []
+        url: str | None = f"{self._base_url}/api/{path.lstrip('/')}"
+        for _ in range(_MAX_PAGES):
+            if not url:
+                break
+            data = self._get(url)
+            page = data.get("results")
+            results.extend(page if isinstance(page, list) else [])
+            nxt = data.get("next")
+            if not (isinstance(nxt, str) and nxt):
+                break
+            if urlsplit(nxt).hostname != base_host:
+                logger.warning(
+                    "[escriptorium] lien 'next' hors hôte ignoré (pas de jeton "
+                    "envoyé à un tiers) : %s",
+                    nxt,
+                )
+                break
+            url = nxt
+        return results
+
+    def _transcriptions(self, doc_pk: int, part_pk: int) -> list[dict[str, Any]]:
+        url = f"{self._base_url}/api/documents/{doc_pk}/parts/{part_pk}/transcriptions/"
+        data = fetch_json(url, timeout=self._timeout, headers=self._headers())
+        if isinstance(data, list):
+            return [t for t in data if isinstance(t, dict)]
+        if isinstance(data, dict):
+            page = data.get("results")
+            if isinstance(page, list):
+                return [t for t in page if isinstance(t, dict)]
+        return []
+
+    def fetch_pages(self, doc_pk: int) -> tuple[EScriptoriumPage, ...]:
+        pages: list[EScriptoriumPage] = []
+        for item in self._paginate(f"documents/{doc_pk}/parts/"):
+            pk = item.get("pk")
+            if not isinstance(pk, int):
+                # Accept #14 : une *part* sans pk entier (schéma inattendu) est
+                # ignorée — on ne devine pas un identifiant. Avertir, pas planter.
+                logger.warning(
+                    "[escriptorium] part sans 'pk' entier ignorée (doc %s) : %r",
+                    doc_pk,
+                    item.get("pk"),
+                )
+                continue
+            transcriptions = self._transcriptions(doc_pk, pk)
+            pages.append(
+                EScriptoriumPage(
+                    pk=pk,
+                    image_url=_image_uri(item, self._base_url),
+                    gt_text=extract_gt_text(transcriptions, self._layer),
+                    title=str(item.get("title", "") or f"part {pk}"),
+                )
+            )
+        return tuple(pages)
+
+
+__all__ = [
+    "DEFAULT_LAYER",
+    "EScriptoriumImporter",
+    "EScriptoriumPage",
+    "extract_gt_text",
+]

cinoc/adapters/corpus/gallica.py

@@ -0,0 +1,160 @@
+"""Importeur de corpus **Gallica** (BnF) — couche 5.
+
+Gallica expose ses images via un **manifeste IIIF** (réutilisé tel quel par
+``IIIFImporter``) et son OCR par page via l'endpoint **ALTO** officiel
+``RequestDigitalElement``. Cet adapter ne porte que la logique propre à Gallica :
+normalisation de l'**ARK**, URL du manifeste IIIF, et récupération de l'OCR d'une
+page (ALTO → texte en ordre de lecture).
+
+Choix : **ALTO** plutôt que ``texteBrut``. L'endpoint ``f{n}.texteBrut`` est
+désormais protégé par un challenge anti-bot (ALTCHA) en accès automatisé, donc
+inutilisable en import ; ``RequestDigitalElement?...&E=ALTO`` reste accessible et
+plus riche (on en extrait le texte via le parseur ALTO de la couche 2).
+
+Bug latent de la source **corrigé** : la numérotation page→OCR ne passe plus par
+une indirection ``selected_indices[i]+1`` (source d'un décalage) — c'est la
+**vue Gallica** lue dans l'URL d'image IIIF (``/f{n}/``) qui *est* le ``Deb`` de
+la requête ALTO. Le mapping est fait par le service ``app`` et prouvé par test.
+
+⚠️ L'OCR Gallica **n'est pas une vérité-terrain manuelle** : c'est la transcription
+automatique de la BnF, utilisable comme *référence* (baseline) à condition de
+l'étiqueter (``gt_source=gallica_ocr`` dans les métadonnées du corpus).
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from urllib.parse import urlencode
+
+from cinoc.adapters.corpus._http import DEFAULT_TIMEOUT, HttpFetchError, fetch_bytes
+from cinoc.domain.errors import CinocError, FormatError
+from cinoc.formats.alto import (
+    AltoBlock,
+    AltoComposedBlock,
+    AltoDocument,
+    AltoTextBlock,
+    parse_alto,
+)
+
+logger = logging.getLogger(__name__)
+
+#: Hôte Gallica de production (surchargeable pour les tests transport).
+GALLICA_BASE = "https://gallica.bnf.fr"
+
+#: ARK normalisé : ``naID/identifiant`` (ex. ``12148/btv1b8453561w``).
+_ARK_RE = re.compile(r"^[0-9]+/[A-Za-z0-9_.\-]+$")
+
+#: Numéro de **vue** Gallica dans une URL d'image IIIF (``…/ark:/12148/X/f3/…``).
+_VUE_RE = re.compile(r"/f(\d+)/")
+
+
+class GallicaArkError(CinocError):
+    """ARK Gallica malformé."""
+
+
+def normalize_ark(ark: str) -> str:
+    """Normalise un ARK (``ark:/12148/x`` | ``12148/x`` → ``12148/x``). Pur."""
+    value = ark.strip()
+    if value.startswith("ark:/"):
+        value = value[len("ark:/"):]
+    value = value.strip("/")
+    if not _ARK_RE.match(value):
+        raise GallicaArkError(
+            f"ARK invalide : {ark!r}. Forme attendue 'naID/identifiant' "
+            "(ex. '12148/btv1b8453561w')."
+        )
+    return value
+
+
+def vue_number(image_url: str) -> int | None:
+    """Numéro de vue Gallica extrait d'une URL d'image (``/f{n}/``), sinon ``None``.
+
+    C'est la source **autoritaire** pour apparier une image à son OCR : se fier à
+    la position dans la liste d'images est faux dès qu'un canvas sans image est
+    sauté par le parseur IIIF (décalage de page).
+    """
+    match = _VUE_RE.search(image_url)
+    return int(match.group(1)) if match else None
+
+
+def _block_lines(blocks: tuple[AltoBlock, ...], out: list[str]) -> None:
+    """Aplatit les ``<TextBlock>`` (récursif sur les ``<ComposedBlock>``) en lignes."""
+    for block in blocks:
+        if isinstance(block, AltoTextBlock):
+            for line in block.lines:
+                text = " ".join(s.content for s in line.strings if s.content)
+                if text:
+                    out.append(text)
+        elif isinstance(block, AltoComposedBlock):
+            _block_lines(block.blocks, out)
+
+
+def alto_to_text(document: AltoDocument) -> str:
+    """Texte d'un ALTO en **ordre de lecture** : lignes (``String/@CONTENT``) jointes.
+
+    Pas de dé-césure (le ``texteBrut`` historique n'en faisait pas non plus) : on
+    rend le contenu brut, ligne par ligne.
+    """
+    lines: list[str] = []
+    for page in document.pages:
+        _block_lines(page.blocks, lines)
+    return "\n".join(lines)
+
+
+class GallicaImporter:
+    """Localise un document Gallica : URL de manifeste IIIF + OCR ALTO par page."""
+
+    name = "gallica"
+
+    def __init__(
+        self,
+        ark: str,
+        *,
+        base_url: str = GALLICA_BASE,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        self.ark = normalize_ark(ark)
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+
+    @property
+    def _identifier(self) -> str:
+        """Identifiant de la numérisation (ARK sans le naID) — param ``O`` de l'ALTO."""
+        return self.ark.split("/", 1)[1]
+
+    @property
+    def manifest_url(self) -> str:
+        return f"{self._base_url}/iiif/ark:/{self.ark}/manifest.json"
+
+    def alto_url(self, page: int) -> str:
+        """URL ALTO officielle d'une vue (``RequestDigitalElement``)."""
+        query = urlencode({"O": self._identifier, "E": "ALTO", "Deb": page})
+        return f"{self._base_url}/RequestDigitalElement?{query}"
+
+    def fetch_ocr_text(self, page: int) -> str:
+        """OCR d'une vue (1-based) via ALTO → texte. ``""`` si absent ou illisible."""
+        try:
+            data = fetch_bytes(self.alto_url(page), timeout=self._timeout)
+        except HttpFetchError as exc:
+            logger.warning(
+                "[gallica] ALTO indisponible pour %s f%d : %s", self.ark, page, exc
+            )
+            return ""
+        try:
+            return alto_to_text(parse_alto(data))
+        except FormatError as exc:  # ALTO malformé ou XML invalide
+            logger.warning(
+                "[gallica] ALTO illisible pour %s f%d : %s", self.ark, page, exc
+            )
+            return ""
+
+
+__all__ = [
+    "GALLICA_BASE",
+    "GallicaArkError",
+    "GallicaImporter",
+    "alto_to_text",
+    "normalize_ark",
+    "vue_number",
+]

cinoc/adapters/corpus/htr_united.py

@@ -0,0 +1,176 @@
+"""Catalogue **HTR-United** (découverte de corpus GT) — couche 5.
+
+HTR-United publie un index communautaire de corpus de vérité-terrain HTR/OCR sous
+forme d'un fichier YAML versionné sur GitHub. Cet adapter **découvre** (télécharge
+l'index + recherche), il ne **matérialise pas** un corpus (les entrées pointent
+vers des dépôts ALTO/PAGE — matérialisation = incrémentale, ultérieure).
+
+Repli **hors-ligne** assumé : si l'index distant est injoignable ou illisible, on
+sert un **socle de démonstration** intégré (petit, pas un dump) avec
+``source="demo"`` / ``is_demo=True`` — l'appelant sait que ce n'est pas le
+catalogue à jour (alimente la future UI de sélection de corpus).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+
+import yaml
+
+from cinoc.adapters.corpus._http import DEFAULT_TIMEOUT, CorpusHttpError, fetch_text
+
+logger = logging.getLogger(__name__)
+
+#: Index communautaire (YAML brut sur GitHub).
+CATALOGUE_URL = (
+    "https://raw.githubusercontent.com/HTR-United/htr-united/master/htr-united.yml"
+)
+
+
+@dataclass(frozen=True)
+class HTRUnitedEntry:
+    """Une entrée du catalogue (métadonnées de découverte, pas le corpus)."""
+
+    id: str
+    title: str
+    url: str
+    description: str
+    languages: tuple[str, ...]
+
+
+#: Socle de démonstration minimal (corpus HTR-United réels) — repli hors-ligne.
+_DEMO_ENTRIES: tuple[HTRUnitedEntry, ...] = (
+    HTRUnitedEntry(
+        id="cremma-medieval",
+        title="CREMMA Medieval",
+        url="https://github.com/HTR-United/cremma-medieval",
+        description="Manuscrits médiévaux français et latins.",
+        languages=("fr", "la"),
+    ),
+    HTRUnitedEntry(
+        id="lectaurep-repertoires",
+        title="LECTAUREP Répertoires",
+        url="https://github.com/HTR-United/lectaurep-repertoires",
+        description="Répertoires de notaires manuscrits (XIXe-XXe).",
+        languages=("fr",),
+    ),
+    HTRUnitedEntry(
+        id="caroline-minuscule",
+        title="Caroline Minuscule",
+        url="https://github.com/HTR-United/CemmaCarolineMinuscule",
+        description="Minuscule caroline latine.",
+        languages=("la",),
+    ),
+)
+
+
+def _as_languages(raw: object) -> tuple[str, ...]:
+    """Normalise un champ langue (str, liste de str, ou liste de dicts)."""
+    if isinstance(raw, str):
+        return (raw,)
+    if isinstance(raw, list):
+        out: list[str] = []
+        for item in raw:
+            if isinstance(item, str):
+                out.append(item)
+            elif isinstance(item, dict):
+                value = item.get("iso") or item.get("lang") or item.get("label")
+                if value:
+                    out.append(str(value))
+        return tuple(out)
+    return ()
+
+
+def _entry_from_dict(item: dict[str, object]) -> HTRUnitedEntry | None:
+    url = str(item.get("url", "") or "")
+    title = str(item.get("title", "") or "")
+    if not url and not title:
+        return None
+    entry_id = str(item.get("id") or "") or url.rstrip("/").rsplit("/", 1)[-1] or title
+    return HTRUnitedEntry(
+        id=entry_id,
+        title=title or entry_id,
+        url=url,
+        description=str(item.get("description", "") or ""),
+        languages=_as_languages(item.get("language")),
+    )
+
+
+def parse_catalogue(raw_yaml: str) -> tuple[HTRUnitedEntry, ...]:
+    """Parse l'index YAML HTR-United → entrées. Pur (tolérant au schéma)."""
+    data = yaml.safe_load(raw_yaml)
+    if isinstance(data, dict):
+        for key in ("data", "projects", "catalog", "catalogue"):
+            if isinstance(data.get(key), list):
+                data = data[key]
+                break
+    if not isinstance(data, list):
+        return ()
+    entries = [
+        _entry_from_dict(item) for item in data if isinstance(item, dict)
+    ]
+    return tuple(e for e in entries if e is not None)
+
+
+@dataclass(frozen=True)
+class HTRUnitedCatalogue:
+    """Index HTR-United chargé, avec sa provenance (``remote`` | ``demo``)."""
+
+    entries: tuple[HTRUnitedEntry, ...]
+    source: str
+
+    @property
+    def is_demo(self) -> bool:
+        return self.source == "demo"
+
+    @classmethod
+    def from_demo(cls) -> HTRUnitedCatalogue:
+        return cls(entries=_DEMO_ENTRIES, source="demo")
+
+    def search(
+        self, query: str = "", language: str | None = None
+    ) -> tuple[HTRUnitedEntry, ...]:
+        results = self.entries
+        if query:
+            q = query.lower()
+            results = tuple(
+                e
+                for e in results
+                if q in e.title.lower()
+                or q in e.description.lower()
+                or q in e.id.lower()
+                or any(q in lg.lower() for lg in e.languages)
+            )
+        if language:
+            lang = language.lower()
+            results = tuple(
+                e for e in results if any(lang in lg.lower() for lg in e.languages)
+            )
+        return results
+
+
+def fetch_catalogue(
+    *, catalogue_url: str = CATALOGUE_URL, timeout: float = DEFAULT_TIMEOUT
+) -> HTRUnitedCatalogue:
+    """Télécharge l'index HTR-United ; **repli démo** si indisponible/illisible."""
+    try:
+        raw = fetch_text(catalogue_url, timeout=timeout)
+        entries = parse_catalogue(raw)
+    except (CorpusHttpError, yaml.YAMLError) as exc:
+        logger.warning(
+            "[htr_united] index distant indisponible (%s) — repli démo : %s",
+            catalogue_url,
+            exc,
+        )
+        return HTRUnitedCatalogue.from_demo()
+    return HTRUnitedCatalogue(entries=entries, source="remote")
+
+
+__all__ = [
+    "CATALOGUE_URL",
+    "HTRUnitedCatalogue",
+    "HTRUnitedEntry",
+    "fetch_catalogue",
+    "parse_catalogue",
+]

cinoc/adapters/corpus/huggingface.py

@@ -0,0 +1,487 @@
+"""Découverte de datasets HTR/OCR sur **HuggingFace Hub** — couche 5.
+
+Recherche (découverte), pas matérialisation : on liste des datasets candidats
+(socle de **référence** intégré + API publique du Hub). Le téléchargement effectif
+d'un dataset (lib ``datasets``, dépendance lourde) est un extra **ultérieur**
+(`cinoc[huggingface]`), hors de cette tranche.
+
+L'appel API est **best-effort** : s'il échoue, on renvoie le socle de référence
+(``source="reference"``) en journalisant — l'utilisateur n'est jamais bloqué, et
+sait d'où vient chaque résultat (``source`` : ``reference`` | ``api``).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable, Iterable, Iterator
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from urllib.parse import urlencode
+
+from cinoc.adapters.corpus._http import (
+    DEFAULT_TIMEOUT,
+    IMAGE_MAX_BYTES,
+    CorpusHttpError,
+    fetch_json,
+)
+from cinoc.domain.errors import CinocError
+
+logger = logging.getLogger(__name__)
+
+HF_API_BASE = "https://huggingface.co/api"
+
+#: Tag de convention apposé aux datasets **curés Cinoc** (carte HF) : il rend un
+#: dataset de référence **découvrable** sur un compte sans coller son ``repo_id``.
+#: Émis par ``app.dataset_standardize`` (front-matter), filtré par ``discover_curated``.
+CURATED_DATASET_TAG = "cinoc-corpus"
+
+#: Convention Cinoc (cf. ``docs/corpus_huggingface.md``) : un dataset importable
+#: porte **au minimum** une colonne image et une colonne vérité-terrain. La
+#: segmentation est une extension *future* (non requise ici).
+CINOC_IMAGE_COLUMN = "image"
+CINOC_GT_COLUMN = "ground_truth"
+
+#: Extensions image reconnues (sinon ``.jpg`` par défaut) pour nommer le fichier.
+_IMAGE_EXTS = frozenset({".png", ".jpg", ".jpeg", ".tif", ".tiff", ".jp2", ".webp"})
+
+
+@dataclass(frozen=True)
+class HuggingFaceDataset:
+    """Un dataset candidat (métadonnées de découverte)."""
+
+    dataset_id: str
+    title: str
+    description: str
+    languages: tuple[str, ...]
+    downloads: int
+    source: str  # "reference" | "api"
+
+    @property
+    def hf_url(self) -> str:
+        return f"https://huggingface.co/datasets/{self.dataset_id}"
+
+
+@dataclass(frozen=True)
+class CuratedDatasetRef:
+    """Un dataset **curé Cinoc** découvert sur un compte HF (tag de convention).
+
+    Métadonnées d'affichage **et** d'import en un clic : ``repo_id`` (+ ``revision``
+    si l'API la fournit, pour épingler la repro) alimentent directement
+    ``import_curated_hf_corpus``."""
+
+    repo_id: str
+    title: str
+    revision: str | None
+    last_modified: str
+
+
+def _ref(
+    dataset_id: str, title: str, desc: str, langs: tuple[str, ...], dl: int
+) -> HuggingFaceDataset:
+    return HuggingFaceDataset(
+        dataset_id=dataset_id,
+        title=title,
+        description=desc,
+        languages=langs,
+        downloads=dl,
+        source="reference",
+    )
+
+
+#: Socle de référence minimal (datasets HTR/OCR patrimoniaux connus).
+_REFERENCE_DATASETS: tuple[HuggingFaceDataset, ...] = (
+    _ref(
+        "Teklia/NorHand", "NorHand", "Écriture manuscrite norvégienne.", ("no",), 1200
+    ),
+    _ref(
+        "Teklia/IAM-line",
+        "IAM (lignes)",
+        "Référence anglaise manuscrite.",
+        ("en",),
+        8400,
+    ),
+    _ref(
+        "bnf/gallica-presse-xix",
+        "Gallica Presse XIXe",
+        "Journaux numérisés XIXe (OCR + images).",
+        ("fr",),
+        15200,
+    ),
+)
+
+
+def _matches(ds: HuggingFaceDataset, query: str, language: str | None) -> bool:
+    if query:
+        q = query.lower()
+        if not (
+            q in ds.title.lower()
+            or q in ds.description.lower()
+            or q in ds.dataset_id.lower()
+            or any(q in lg.lower() for lg in ds.languages)
+        ):
+            return False
+    if language and not any(language.lower() in lg.lower() for lg in ds.languages):
+        return False
+    return True
+
+
+def search_reference(
+    query: str = "", language: str | None = None
+) -> tuple[HuggingFaceDataset, ...]:
+    """Filtre le socle de référence intégré. Pur (sans réseau)."""
+    return tuple(ds for ds in _REFERENCE_DATASETS if _matches(ds, query, language))
+
+
+def _parse_api(payload: object) -> tuple[HuggingFaceDataset, ...]:
+    """Mappe la réponse de l'API HF (liste de dicts) → datasets. Pur."""
+    if not isinstance(payload, list):
+        return ()
+    out: list[HuggingFaceDataset] = []
+    for item in payload:
+        if not isinstance(item, dict):
+            continue
+        dataset_id = str(item.get("id", "") or "")
+        if not dataset_id:
+            continue
+        downloads = item.get("downloads", 0)
+        out.append(
+            HuggingFaceDataset(
+                dataset_id=dataset_id,
+                title=dataset_id,
+                description="",
+                languages=(),
+                downloads=int(downloads) if isinstance(downloads, int) else 0,
+                source="api",
+            )
+        )
+    return tuple(out)
+
+
+class HuggingFaceCatalogue:
+    """Recherche de datasets : socle de référence + API publique (best-effort)."""
+
+    name = "huggingface"
+
+    def __init__(
+        self, *, api_base: str = HF_API_BASE, timeout: float = DEFAULT_TIMEOUT
+    ) -> None:
+        self._api_base = api_base.rstrip("/")
+        self._timeout = timeout
+
+    def _fetch_api(
+        self, query: str, language: str | None, limit: int
+    ) -> tuple[HuggingFaceDataset, ...]:
+        params: dict[str, str] = {
+            "task_categories": "image-to-text",
+            "limit": str(min(limit, 50)),
+        }
+        if query:
+            params["search"] = query
+        if language:
+            params["language"] = language
+        url = f"{self._api_base}/datasets?{urlencode(params)}"
+        return _parse_api(fetch_json(url, timeout=self._timeout))
+
+    def search(
+        self,
+        query: str = "",
+        language: str | None = None,
+        *,
+        limit: int = 20,
+        use_reference: bool = True,
+        include_api: bool = True,
+    ) -> tuple[HuggingFaceDataset, ...]:
+        results: list[HuggingFaceDataset] = []
+        if use_reference:
+            results.extend(search_reference(query, language))
+        if include_api:
+            seen = {ds.dataset_id for ds in results}
+            try:
+                for ds in self._fetch_api(query, language, limit):
+                    if ds.dataset_id not in seen:
+                        results.append(ds)
+                        seen.add(ds.dataset_id)
+            except CorpusHttpError as exc:
+                logger.warning(
+                    "[huggingface] recherche API indisponible — socle de référence "
+                    "seul : %s",
+                    exc,
+                )
+        # Accept #9 : socle de référence d'abord, API ensuite, puis troncature
+        # finale à `limit` — la référence (curée) prime sur l'API si l'union
+        # dépasse. Choix de découverte (display), pas de classement par score.
+        return tuple(results[:limit])
+
+
+class HuggingFaceConventionError(CinocError):
+    """Le dataset ne respecte pas la **convention Cinoc** (colonnes attendues)."""
+
+
+class HuggingFaceUnavailableError(CinocError):
+    """La lib ``datasets`` (extra ``[huggingface]``) n'est pas installée."""
+
+
+@dataclass(frozen=True)
+class HFPage:
+    """Une page **streamée** : octets image encodés + extension + texte GT.
+
+    Type neutre à la frontière adapter→app : l'image est livrée en **octets**
+    (jamais un objet PIL) pour que la matérialisation disque (couche 6) n'ait
+    aucune dépendance image.
+    """
+
+    image_bytes: bytes
+    image_ext: str
+    gt_text: str
+
+
+#: Charge un dataset en streaming → itérable de lignes. Injectable (test).
+HFLoader = Callable[[str, str], Iterable[object]]
+
+
+def _default_loader(dataset_id: str, split: str) -> Iterable[object]:
+    """Charge le dataset HF **en streaming** (jamais de snapshot local complet).
+
+    Import **paresseux** de ``datasets`` (extra ``[huggingface]``) : sans l'extra,
+    lève ``HuggingFaceUnavailableError`` (message actionnable). Les images sont
+    castées en ``Image(decode=False)`` → octets bruts (pas de décodage PIL).
+    """
+    try:
+        from datasets import Image, load_dataset  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise HuggingFaceUnavailableError(
+            "import HuggingFace indisponible : installer 'cinoc[huggingface]' "
+            "(lib 'datasets')."
+        ) from exc
+    dataset = load_dataset(dataset_id, split=split, streaming=True)
+    features = getattr(dataset, "features", None) or {}
+    if CINOC_IMAGE_COLUMN in features:
+        dataset = dataset.cast_column(CINOC_IMAGE_COLUMN, Image(decode=False))
+    return dataset  # type: ignore[no-any-return]
+
+
+def _ext_from_path(path: object) -> str:
+    if isinstance(path, str) and path:
+        suffix = PurePosixPath(path).suffix.lower()
+        if suffix in _IMAGE_EXTS:
+            return suffix
+    return ".jpg"
+
+
+def _extract_image(value: object) -> tuple[bytes, str]:
+    """Octets image + extension depuis une cellule ``image`` (``decode=False``)."""
+    if isinstance(value, dict):
+        raw = value.get("bytes")
+        if isinstance(raw, bytes) and raw:
+            return raw, _ext_from_path(value.get("path"))
+    raise HuggingFaceConventionError(
+        f"colonne {CINOC_IMAGE_COLUMN!r} : octets image absents (le dataset "
+        "doit stocker l'image en octets ; cf. convention Cinoc)."
+    )
+
+
+def _validate_columns(row: dict[str, object]) -> None:
+    missing = [c for c in (CINOC_IMAGE_COLUMN, CINOC_GT_COLUMN) if c not in row]
+    if missing:
+        raise HuggingFaceConventionError(
+            f"dataset non conforme à la convention Cinoc : colonnes manquantes "
+            f"{missing} (attendu : {CINOC_IMAGE_COLUMN!r} + {CINOC_GT_COLUMN!r})."
+        )
+
+
+def stream_pages(
+    dataset_id: str,
+    *,
+    split: str = "train",
+    limit: int | None = None,
+    loader: HFLoader | None = None,
+) -> Iterator[HFPage]:
+    """Streame les pages d'un dataset HF conforme à la **convention Cinoc**.
+
+    Page-par-page (``streaming=True`` côté ``datasets``) : on ne télécharge jamais
+    le snapshot complet ; ``limit`` borne le nombre de pages lues. La conformité
+    (colonnes ``image`` + ``ground_truth``) est validée sur la **1ʳᵉ ligne**. Une
+    image dépassant ``IMAGE_MAX_BYTES`` est **ignorée** (avertie), pas fatale.
+
+    ``loader`` (``(dataset_id, split) → itérable de lignes``) est injectable pour
+    tester sans la lib ``datasets`` ; défaut = streaming réel.
+    """
+    load = loader or _default_loader
+    validated = False
+    count = 0
+    for row in load(dataset_id, split):
+        if not isinstance(row, dict):
+            continue
+        if not validated:
+            _validate_columns(row)
+            validated = True
+        image_bytes, ext = _extract_image(row[CINOC_IMAGE_COLUMN])
+        if len(image_bytes) > IMAGE_MAX_BYTES:
+            logger.warning(
+                "[huggingface] image > %d octets ignorée (dataset %s).",
+                IMAGE_MAX_BYTES,
+                dataset_id,
+            )
+            continue
+        gt_value = row.get(CINOC_GT_COLUMN)
+        gt_text = gt_value if isinstance(gt_value, str) else ""
+        yield HFPage(image_bytes=image_bytes, image_ext=ext, gt_text=gt_text)
+        count += 1
+        if limit is not None and count >= limit:
+            return
+
+
+#: Récupère un JSON depuis une URL. Injectable → ``discover_curated`` se teste
+#: sans réseau (le défaut tape l'API HF via ``fetch_json``).
+CuratedFetcher = Callable[[str], object]
+
+
+def _parse_curated(payload: object, *, tag: str) -> tuple[CuratedDatasetRef, ...]:
+    """Réponse ``/api/datasets`` (liste de dicts) → datasets curés. Pure.
+
+    Re-filtre **défensivement** sur le tag (si la liste porte ``tags``) : on ne
+    présente que de vrais layouts Cinoc, jamais un dataset quelconque du compte."""
+    if not isinstance(payload, list):
+        return ()
+    out: list[CuratedDatasetRef] = []
+    for item in payload:
+        if not isinstance(item, dict):
+            continue
+        repo_id = str(item.get("id", "") or "")
+        if not repo_id:
+            continue
+        tags = item.get("tags")
+        if isinstance(tags, list) and tag not in tags:
+            continue
+        sha = item.get("sha")
+        out.append(
+            CuratedDatasetRef(
+                repo_id=repo_id,
+                title=str(item.get("id", repo_id)),
+                revision=str(sha) if isinstance(sha, str) and sha else None,
+                last_modified=str(item.get("lastModified", "") or ""),
+            )
+        )
+    return tuple(out)
+
+
+def whoami(
+    token: str,
+    *,
+    api_base: str = HF_API_BASE,
+    timeout: float = DEFAULT_TIMEOUT,
+    fetcher: Callable[[str], object] | None = None,
+) -> str | None:
+    """Handle du compte HF derrière un ``token`` (``/api/whoami-v2``). Best-effort.
+
+    Sert à faire **apparaître automatiquement** les datasets curés de l'opérateur
+    sans qu'il colle son identifiant : on résout son handle depuis sa clé. Échec
+    réseau / token invalide → ``None`` (repli sur ``CINOC_HF_AUTHOR`` ou l'import
+    manuel). Le token n'est jamais journalisé (cf. ``_http``)."""
+    if not token:
+        return None
+    get = fetcher or (
+        lambda url: fetch_json(
+            url, timeout=timeout, headers={"Authorization": f"Bearer {token}"}
+        )
+    )
+    try:
+        payload = get(f"{api_base.rstrip('/')}/whoami-v2")
+    except CorpusHttpError as exc:
+        logger.warning("[huggingface] whoami indisponible : %s", exc)
+        return None
+    if isinstance(payload, dict):
+        name = payload.get("name")
+        if isinstance(name, str) and name.strip():
+            return name.strip()
+    return None
+
+
+def discover_curated(
+    author: str,
+    *,
+    tag: str = CURATED_DATASET_TAG,
+    api_base: str = HF_API_BASE,
+    timeout: float = DEFAULT_TIMEOUT,
+    fetcher: CuratedFetcher | None = None,
+) -> tuple[CuratedDatasetRef, ...]:
+    """Liste les datasets **curés Cinoc** d'un compte HF (``author`` + ``tag``).
+
+    Best-effort : API injoignable → ``()`` en journalisant (l'UI retombe sur
+    l'import manuel par ``repo_id``, jamais un blocage). C'est ce qui fait
+    « apparaître » un dataset publié sans coller son identifiant : on filtre le
+    compte par le tag de convention."""
+    if not author:
+        return ()
+    get = fetcher or (lambda url: fetch_json(url, timeout=timeout))
+    params = {"author": author, "filter": tag, "full": "true", "limit": "100"}
+    url = f"{api_base.rstrip('/')}/datasets?{urlencode(params)}"
+    try:
+        payload = get(url)
+    except CorpusHttpError as exc:
+        logger.warning(
+            "[huggingface] découverte curée indisponible (compte %s) : %s",
+            author,
+            exc,
+        )
+        return ()
+    return _parse_curated(payload, tag=tag)
+
+
+def snapshot_curated_layout(
+    repo_id: str, dest: Path, revision: str | None
+) -> Path:  # pragma: no cover -- réseau réel (test 'live')
+    """Snapshot **partiel** d'un dataset curé Cinoc publié sur HF.
+
+    Ne rapatrie que ``corpus.json`` + ``ground_truth/`` (scorables en local) ; les
+    images restent des **références distantes** : le dataset embarque un layout
+    **IIIF statique** (Image API 3 level0, cf. ``app.dataset_standardize``) servi
+    par la racine ``resolve`` HF épinglée à la révision — l'URL est donc un lien
+    ``huggingface.co`` dont le chemin suit la syntaxe IIIF. Le rapport les affiche
+    (saveur « liens », D-094) et l'orchestrateur les **matérialise au run** (fetch
+    durci) pour les moteurs. ``huggingface_hub`` (extra ``[huggingface]``) est
+    importé paresseusement → sans l'extra, ``HuggingFaceUnavailableError``
+    actionnable ; dépôt/révision injoignable → ``CorpusHttpError`` (→ 422 web).
+    """
+    try:
+        from huggingface_hub import snapshot_download  # type: ignore[import-not-found]
+        from huggingface_hub.utils import (  # type: ignore[import-not-found]
+            HfHubHTTPError,
+        )
+    except ImportError as exc:
+        raise HuggingFaceUnavailableError(
+            "import curé HF indisponible : installer 'cinoc[huggingface]' "
+            "(lib 'huggingface_hub')."
+        ) from exc
+    try:
+        local = snapshot_download(
+            repo_id,
+            repo_type="dataset",
+            revision=revision,
+            allow_patterns=["corpus.json", "ground_truth/*"],
+            local_dir=str(dest),
+        )
+    except HfHubHTTPError as exc:
+        raise CorpusHttpError(
+            f"dataset curé HF {repo_id!r} injoignable : {exc}"
+        ) from exc
+    return Path(local)
+
+
+__all__ = [
+    "HF_API_BASE",
+    "CINOC_GT_COLUMN",
+    "CINOC_IMAGE_COLUMN",
+    "CURATED_DATASET_TAG",
+    "CuratedDatasetRef",
+    "HFPage",
+    "HuggingFaceCatalogue",
+    "HuggingFaceConventionError",
+    "HuggingFaceDataset",
+    "HuggingFaceUnavailableError",
+    "discover_curated",
+    "search_reference",
+    "snapshot_curated_layout",
+    "stream_pages",
+    "whoami",
+]

cinoc/adapters/corpus/iiif.py

@@ -0,0 +1,137 @@
+"""Importeur de corpus **IIIF** (Presentation API v2 & v3) — couche 5.
+
+Rôle : **localiser** les pages d'un manifeste (parsing du schéma → URLs d'image).
+La **matérialisation disque** (téléchargement → ``CorpusSpec``) vit en couche
+``app`` (``app/corpus_import.py``) : un adapter parle protocole, pas filesystem.
+
+Périmètre : **images seules**. Un manifeste IIIF porte des pages numérisées, pas
+de transcription ; le corpus importé est donc sans vérité-terrain (OCR exécutable,
+métriques non applicables tant qu'une GT n'est pas appariée). C'est un choix
+assumé de la tranche, pas un manque.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from cinoc.adapters.corpus._http import DEFAULT_TIMEOUT, HttpFetchError, fetch_json
+
+
+@dataclass(frozen=True)
+class IIIFImage:
+    """Une page du manifeste : son URL d'image + un label lisible."""
+
+    image_url: str
+    label: str
+
+
+def _extract_label(raw: object) -> str:
+    """Aplati les formats de label IIIF (str, liste, map de langue v3)."""
+    if isinstance(raw, str):
+        return raw
+    if isinstance(raw, list) and raw:
+        return _extract_label(raw[0])
+    if isinstance(raw, dict):
+        for lang in ("fr", "en", "none", "@value"):
+            val = raw.get(lang)
+            if val:
+                return str(val[0]) if isinstance(val, list) and val else str(val)
+        for val in raw.values():
+            return _extract_label(val)
+    return str(raw) if raw else ""
+
+
+def _service_image_url(service: object) -> str:
+    """Construit ``{service}/full/max/0/default.jpg`` depuis un service Image API."""
+    if isinstance(service, list):
+        service = service[0] if service else {}
+    if not isinstance(service, dict):
+        return ""
+    svc_id = service.get("@id") or service.get("id") or ""
+    if not isinstance(svc_id, str) or not svc_id:
+        return ""
+    return f"{svc_id.rstrip('/')}/full/max/0/default.jpg"
+
+
+def _image_url_v2(canvas: dict[str, Any]) -> str:
+    images = canvas.get("images") or []
+    if not images or not isinstance(images[0], dict):
+        return ""
+    resource = images[0].get("resource", {})
+    if not isinstance(resource, dict):
+        return ""
+    direct = resource.get("@id", "")
+    if isinstance(direct, str) and direct and not direct.endswith("/info.json"):
+        return direct
+    return _service_image_url(resource.get("service", {}))
+
+
+def _image_url_v3(canvas: dict[str, Any]) -> str:
+    for annotation_page in canvas.get("items") or []:
+        for annotation in annotation_page.get("items") or []:
+            body = annotation.get("body", {})
+            if isinstance(body, list):
+                body = body[0] if body else {}
+            if not isinstance(body, dict):
+                continue
+            url = body.get("id") or body.get("@id") or ""
+            if isinstance(url, str) and url and body.get("type") == "Image":
+                return url
+            service_url = _service_image_url(body.get("service", []))
+            if service_url:
+                return service_url
+            if isinstance(url, str) and url:
+                return url
+    return ""
+
+
+def _detect_version(manifest: dict[str, Any]) -> int:
+    context = manifest.get("@context", "")
+    contexts = context if isinstance(context, list) else [context]
+    if any(isinstance(c, str) and "presentation/3" in c for c in contexts):
+        return 3
+    if manifest.get("type") == "Manifest" and "items" in manifest:
+        return 3
+    return 2
+
+
+def parse_manifest(manifest: dict[str, Any]) -> tuple[IIIFImage, ...]:
+    """Parse un manifeste IIIF (v2/v3 auto-détecté) → pages avec image. Pur."""
+    if _detect_version(manifest) == 3:
+        canvases = manifest.get("items") or []
+        extract = _image_url_v3
+    else:
+        sequences = manifest.get("sequences") or []
+        canvases = sequences[0].get("canvases", []) if sequences else []
+        extract = _image_url_v2
+    images: list[IIIFImage] = []
+    for i, canvas in enumerate(canvases, start=1):
+        if not isinstance(canvas, dict):
+            continue
+        url = extract(canvas)
+        if not url:
+            continue
+        label = _extract_label(canvas.get("label", f"canvas_{i}")) or f"canvas_{i}"
+        images.append(IIIFImage(image_url=url, label=label))
+    return tuple(images)
+
+
+class IIIFImporter:
+    """Localise les pages d'un manifeste IIIF (fetch + parse, **sans disque**)."""
+
+    name = "iiif"
+
+    def __init__(self, *, timeout: float = DEFAULT_TIMEOUT) -> None:
+        self._timeout = timeout
+
+    def fetch_images(self, manifest_url: str) -> tuple[IIIFImage, ...]:
+        manifest = fetch_json(manifest_url, timeout=self._timeout)
+        if not isinstance(manifest, dict):
+            raise HttpFetchError(
+                f"manifeste IIIF {manifest_url!r} : objet JSON attendu."
+            )
+        return parse_manifest(manifest)
+
+
+__all__ = ["IIIFImage", "IIIFImporter", "parse_manifest"]

cinoc/adapters/images.py

@@ -0,0 +1,137 @@
+"""Vignettes du rapport : image → dérivé JPEG redimensionné (couche 5, adapter).
+
+Le redimensionnement utilise **Pillow** (interdit en ``reports`` — couche 7) ; il
+vit donc ici. Deux saveurs partagent le **même cœur** ``_render_jpeg`` :
+
+- ``thumbnail_data_uri`` → **data-URI** embarqué dans le HTML (saveur fichier
+  unique) ; les octets ne touchent jamais le ``RunResult``.
+- ``thumbnail_to_file`` → écrit le dérivé dans un dossier d'assets et renvoie un
+  **href relatif** (saveur dossier : HTML léger à liens relatifs).
+
+**Dégradé gracieux** : si Pillow n'est pas installé (extra ``[images]``), si le
+fichier manque ou est illisible → ``None`` (le rapport retombe sur l'aperçu
+synthétique). Aucune exception large.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def thumbnail_bytes(source: str | Path, *, max_px: int = 280) -> bytes | None:
+    """Octets JPEG d'une image locale redimensionnée ; ``None`` si indisponible.
+
+    Cœur partagé des **trois** saveurs — data-URI (fichier unique), fichier
+    (dossier) et **servie** (le web renvoie ces octets tels quels) : redimensionne
+    pour que le
+    plus grand côté ≤ ``max_px`` (jamais agrandi), convertit en RGB, encode JPEG.
+    ``None`` (avec ``logger.warning``) si Pillow absent, fichier introuvable, ou
+    image illisible — le rendu reste fonctionnel (aperçu synthétique)."""
+    path = Path(source)
+    if not path.is_file():
+        return None
+    try:
+        from PIL import Image, UnidentifiedImageError
+    except ImportError as exc:
+        logger.warning(
+            "[images] Pillow indisponible (%s) — vignettes omises, aperçu "
+            "synthétique. Installer l'extra ``[images]``.",
+            exc,
+        )
+        return None
+    try:
+        with Image.open(path) as opened:
+            rgb = opened.convert("RGB")
+            rgb.thumbnail((max_px, max_px))
+            buffer = io.BytesIO()
+            rgb.save(buffer, format="JPEG", quality=82, optimize=True)
+    except (UnidentifiedImageError, OSError) as exc:
+        logger.warning("[images] image illisible %s : %s — vignette omise.", path, exc)
+        return None
+    return buffer.getvalue()
+
+
+def thumbnail_data_uri(source: str | Path, *, max_px: int = 280) -> str | None:
+    """Vignette JPEG **data-URI** d'une image locale ; ``None`` si indisponible.
+
+    Saveur fichier unique : les octets sont inlinés dans le HTML. ``None`` si le
+    dérivé n'a pu être produit (Pillow absent, fichier manquant/illisible)."""
+    raw = thumbnail_bytes(source, max_px=max_px)
+    if raw is None:
+        return None
+    payload = base64.b64encode(raw).decode("ascii")
+    return f"data:image/jpeg;base64,{payload}"
+
+
+def thumbnail_to_file(
+    source: str | Path, dest_dir: str | Path, stem: str, *, max_px: int = 280
+) -> str | None:
+    """Écrit la vignette JPEG dans ``dest_dir/<stem>.jpg`` ; renvoie un href relatif.
+
+    Saveur dossier : le dérivé est **un fichier sur disque** (pas inliné), le HTML
+    n'en porte qu'une **référence relative**. L'href renvoyé est relatif au
+    **parent** de ``dest_dir`` (``f"{dest_dir.name}/{stem}.jpg"``, séparateur ``/``
+    portable) : l'appelant garantit que le HTML est un voisin de ``dest_dir`` (cf.
+    ``app.report_images.write_report_bundle``). ``None`` si le dérivé n'a pu être
+    produit (dégradé gracieux, aucun fichier écrit, aucun dossier créé)."""
+    raw = thumbnail_bytes(source, max_px=max_px)
+    if raw is None:
+        return None
+    folder = Path(dest_dir)
+    folder.mkdir(parents=True, exist_ok=True)
+    (folder / f"{stem}.jpg").write_bytes(raw)
+    return f"{folder.name}/{stem}.jpg"
+
+
+def iiif_derivative(
+    source: str | Path, dest_path: str | Path, *, width: int
+) -> tuple[int, int] | None:
+    """Écrit un dérivé JPEG de **largeur exacte** ``width`` (jamais agrandi) à
+    ``dest_path`` ; renvoie ``(largeur, hauteur)`` réels, ou ``None`` (dégradé).
+
+    Variante **largeur-fixe** de ``_render_jpeg`` (qui borne le plus grand côté) :
+    une taille IIIF Image API ``full/{w},/`` exige une largeur exacte, pas un
+    cadrage. Convertit en RGB, ré-échantillonne (Lanczos), crée les dossiers
+    parents. ``None`` (avec ``logger.warning``) si Pillow absent, fichier
+    introuvable ou image illisible — l'outil appelant décide d'échouer ou non."""
+    path = Path(source)
+    if not path.is_file():
+        logger.warning("[images] image introuvable %s — dérivé IIIF omis.", path)
+        return None
+    try:
+        from PIL import Image, UnidentifiedImageError
+    except ImportError as exc:
+        logger.warning(
+            "[images] Pillow indisponible (%s) — dérivé IIIF omis. Extra ``[images]``.",
+            exc,
+        )
+        return None
+    try:
+        with Image.open(path) as opened:
+            rgb = opened.convert("RGB")
+            orig_w, orig_h = rgb.size
+            target_w = min(width, orig_w)  # jamais agrandi
+            target_h = max(1, round(orig_h * target_w / orig_w))
+            resized = rgb.resize((target_w, target_h), Image.Resampling.LANCZOS)
+            dest = Path(dest_path)
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            resized.save(dest, format="JPEG", quality=82, optimize=True)
+    except (UnidentifiedImageError, OSError) as exc:
+        logger.warning(
+            "[images] image illisible %s : %s — dérivé IIIF omis.", path, exc
+        )
+        return None
+    return (target_w, target_h)
+
+
+__all__ = [
+    "iiif_derivative",
+    "thumbnail_bytes",
+    "thumbnail_data_uri",
+    "thumbnail_to_file",
+]

cinoc/adapters/layout/__init__.py

@@ -0,0 +1,3 @@
+"""Adapters de mise en page (couche 5) — socle ``precomputed``."""
+
+from __future__ import annotations

cinoc/adapters/layout/_base.py

@@ -0,0 +1,114 @@
+"""Contrat **partagé** des segmenteurs de mise en page (couche 5).
+
+Tout segmenteur (PP-DocLayout maison, segmenteur distant HF, futurs) produit la
+même forme : un détecteur rend des **régions brutes** (``LayoutDetection``), qu'on
+convertit en ``CanonicalLayout`` neutre (``to_canonical_layout``) puis qu'on
+sérialise en artefact ``LAYOUT`` (``layout_step_output``, la *queue* d'``execute``).
+
+Ces pièces sont **agnostiques du moteur** : elles vivaient dans ``pp_doclayout``
+(le segmenteur maison), ce qui forçait le segmenteur distant à importer un module
+PaddleX-spécifique pour les réutiliser. Extraites ici, les deux adapters en
+dépendent sans se coupler l'un à l'autre.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from cinoc.adapters._workspace import workspace_artifact_path
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.layout import BBox, CanonicalLayout, Geometry, LayoutPage, Region
+from cinoc.pipeline.types import RunContext, StepOutput
+
+
+@dataclass(frozen=True)
+class DetectedRegion:
+    """Une région détectée : étiquette, boîte (pixels) et score de confiance."""
+
+    label: str
+    x: int
+    y: int
+    width: int
+    height: int
+    score: float
+
+
+@dataclass(frozen=True)
+class LayoutDetection:
+    """Sortie brute d'un détecteur : dimensions de page + régions détectées."""
+
+    page_width: int
+    page_height: int
+    regions: tuple[DetectedRegion, ...]
+
+
+#: Détecteur **injectable** : chemin image → détection. Le défaut (PaddleX, appel
+#: distant…) est résolu paresseusement à l'exécution ; les tests injectent un faux.
+DetectorFn = Callable[[str], LayoutDetection]
+
+
+def to_canonical_layout(
+    detection: LayoutDetection, *, min_score: float
+) -> CanonicalLayout:
+    """Détections → ``CanonicalLayout`` (1 page, régions **sans lignes**).
+
+    Filtre au seuil de score, **trie** par position (haut→bas puis gauche→droite)
+    pour un ordre de lecture **déterministe** indépendant de l'ordre de détection,
+    et numérote les régions ``r1..rN``. Le ``label`` du modèle devient le
+    ``region_type`` neutre (``None`` si vide).
+    """
+    kept = [r for r in detection.regions if r.score >= min_score]
+    ordered = sorted(kept, key=lambda r: (r.y, r.x))
+    regions = tuple(
+        Region(
+            id=f"r{index + 1}",
+            region_type=r.label or None,
+            geometry=Geometry(
+                bbox=BBox(x=r.x, y=r.y, width=r.width, height=r.height)
+            ),
+        )
+        for index, r in enumerate(ordered)
+    )
+    page = LayoutPage(
+        width=detection.page_width or None,
+        height=detection.page_height or None,
+        regions=regions,
+        reading_order=tuple(region.id for region in regions),
+    )
+    return CanonicalLayout(pages=(page,))
+
+
+def layout_step_output(
+    layout: CanonicalLayout, context: RunContext, name: str
+) -> StepOutput:
+    """Sérialise un ``CanonicalLayout`` → artefact ``LAYOUT`` (tail d'``execute``
+    partagé par tous les segmenteurs : PP-DocLayout, segmenteur distant…)."""
+    if context.workspace_uri is None:
+        raise AdapterStepError(f"{name} : workspace requis (RunContext.workspace_uri).")
+    payload = layout.model_dump_json().encode("utf-8")
+    output_path = workspace_artifact_path(
+        context.workspace_uri, context.document_id, name, "layout.json"
+    )
+    output_path.write_bytes(payload)
+    return StepOutput(
+        artifacts={
+            ArtifactType.LAYOUT: Artifact(
+                id=f"{context.document_id}:{name}:layout",
+                document_id=context.document_id,
+                type=ArtifactType.LAYOUT,
+                uri=str(output_path),
+                content_hash=compute_content_hash(payload),
+            )
+        }
+    )
+
+
+__all__ = [
+    "DetectedRegion",
+    "DetectorFn",
+    "LayoutDetection",
+    "layout_step_output",
+    "to_canonical_layout",
+]

cinoc/adapters/layout/_saknussemm_bridge.py

@@ -0,0 +1,187 @@
+"""Pont ``CanonicalLayout`` → ``DocumentManifest`` de ``saknussemm``.
+
+Isolé de l'adapter pour une raison de contrat : c'est **la** traduction entre
+deux modèles de mise en page, et elle a un coût mesurable. Vérifiée sur les deux
+corpus du dépôt (1088 lignes, ``37-GT-BNL`` + ``BnF-bpt6k3265015q``) : rôle de
+césure, texte de ligne, confiance et ``SUBS_CONTENT`` identiques à ce que le
+parser de ``saknussemm`` obtient en lisant l'ALTO lui-même.
+
+Cette parité **dépend** du fait que ``alto_to_layout`` transporte les ``SP``,
+les ``HYP`` et les ``SUBS``. Avant qu'il le fasse, la même conversion perdait
+36 % des rôles de césure et faussait 21 % des textes sur le corpus BnF.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from cinoc.domain.errors import AdapterStepError
+
+if TYPE_CHECKING:  # pragma: no cover
+    from cinoc.domain.layout import CanonicalLayout, Region
+
+
+def _flatten_regions(regions: tuple[Region, ...]) -> list[Region]:
+    """Régions imbriquées aplaties : un bloc ALTO composé porte ses lignes dans
+    ses enfants, et ``saknussemm`` raisonne sur des blocs plats."""
+    out: list[Region] = []
+    for region in regions:
+        if region.lines:
+            out.append(region)
+        out.extend(_flatten_regions(region.regions))
+    return out
+
+
+def layout_to_manifest(layout: CanonicalLayout, *, document_id: str) -> Any:
+    """Traduit une mise en page neutre en manifeste ``saknussemm``.
+
+    Lève si une ligne n'a pas d'identifiant : ``saknussemm`` fait de
+    ``(page_id, line_id)`` **l'identité** d'une ligne, pas son rang. Une ligne
+    anonyme ne peut donc pas traverser la bibliothèque, et le dire ici nomme la
+    vraie cause.
+    """
+    from saknussemm.core.pairing import (  # type: ignore[import-not-found]  # noqa: PLC0415
+        HYPHEN_CHARS,
+        link_hyphen_pairs,
+        trailing_hyphen_char,
+    )
+    from saknussemm.core.schemas import (  # type: ignore[import-not-found]  # noqa: PLC0415
+        BlockManifest,
+        Coords,
+        DocumentManifest,
+        HyphenRole,
+        LineManifest,
+        PageManifest,
+    )
+
+    pages = []
+    for page_index, lpage in enumerate(layout.pages):
+        page_id = f"P_{page_index + 1:04d}"
+        blocks, lines = [], []
+        order = 0
+        for block_index, region in enumerate(_flatten_regions(lpage.regions)):
+            block_id = region.id or f"B_{block_index + 1:04d}"
+            line_ids = []
+            for line_index, line in enumerate(region.lines):
+                if not line.id:
+                    raise AdapterStepError(
+                        "layout_to_manifest : une ligne du bloc "
+                        f"{block_id!r} n'a pas d'identifiant. saknussemm fait "
+                        "de (page, ligne) une identité, pas un rang."
+                    )
+                confidences = [
+                    w.confidence for w in line.words if w.confidence is not None
+                ]
+                first = line.words[0] if line.words else None
+                last = line.words[-1] if line.words else None
+                lm = LineManifest(
+                    line_id=line.id,
+                    page_id=page_id,
+                    block_id=block_id,
+                    line_order_global=order,
+                    line_order_in_block=line_index,
+                    coords=_coords(Coords, line),
+                    ocr_text=line.text,
+                    # ``None`` et non ``len(words)`` : en ALTO la géométrie par
+                    # jeton se redistribue à n'importe quel compte de mots, donc
+                    # le compte n'est pas une contrainte de projection.
+                    word_count=None,
+                    ocr_confidence=(
+                        sum(confidences) / len(confidences) if confidences else None
+                    ),
+                )
+                _set_hyphenation(
+                    lm,
+                    HyphenRole,
+                    trailing_hyphen_char,
+                    HYPHEN_CHARS,
+                    first_subs=_subs(first),
+                    last_subs=_subs(last),
+                )
+                lines.append(lm)
+                line_ids.append(line.id)
+                order += 1
+            blocks.append(
+                BlockManifest(
+                    block_id=block_id,
+                    page_id=page_id,
+                    block_order=block_index,
+                    coords=_coords(Coords, region),
+                    line_ids=line_ids,
+                )
+            )
+        link_hyphen_pairs(lines)
+        pages.append(
+            PageManifest(
+                page_id=page_id,
+                source_file=f"{document_id}#{page_index}",
+                page_index=page_index,
+                page_width=lpage.width or 0,
+                page_height=lpage.height or 0,
+                blocks=blocks,
+                lines=lines,
+            )
+        )
+    return DocumentManifest(
+        document_id=document_id,
+        source_files=[p.source_file for p in pages],
+        pages=pages,
+    )
+
+
+def _subs(word: Any) -> tuple[str | None, str | None]:
+    """``(SUBS_TYPE, SUBS_CONTENT)`` d'un mot, ou ``(None, None)`` sans mot."""
+    if word is None:
+        return None, None
+    return word.subs_type, word.subs_content
+
+
+def _coords(coords_cls: Any, element: Any) -> Any:
+    box = element.geometry.bbox if element.geometry else None
+    return coords_cls(
+        hpos=box.x if box else 0,
+        vpos=box.y if box else 0,
+        width=box.width if box else 0,
+        height=box.height if box else 0,
+    )
+
+
+def _set_hyphenation(
+    lm: Any,
+    hyphen_role: Any,
+    trailing: Any,
+    hyphen_chars: Any,
+    *,
+    first_subs: tuple[str | None, str | None],
+    last_subs: tuple[str | None, str | None],
+) -> None:
+    """Deux sources, comme le parser ALTO de ``saknussemm`` : le ``SUBS_TYPE``
+    (explicite) et une marque de coupure en fin de ligne (heuristique)."""
+    first_type, first_content = first_subs
+    last_type, last_content = last_subs
+    is_part2 = first_type == "HypPart2"
+    is_part1 = last_type == "HypPart1" or (
+        trailing(lm.ocr_text, hyphen_chars) is not None
+    )
+    if is_part1 and is_part2:
+        lm.hyphen_role = hyphen_role.BOTH
+        lm.hyphen_source_explicit = True
+        lm.hyphen_subs_content = first_content
+        lm.hyphen_forward_explicit = last_type == "HypPart1"
+        lm.hyphen_forward_subs_content = last_content
+    elif is_part2:
+        lm.hyphen_role = hyphen_role.PART2
+        lm.hyphen_source_explicit = True
+        lm.hyphen_subs_content = first_content
+    elif is_part1:
+        lm.hyphen_role = hyphen_role.PART1
+        lm.hyphen_source_explicit = last_type == "HypPart1"
+        lm.hyphen_subs_content = last_content
+
+
+def manifest_page_ids(manifest: Any) -> list[str]:
+    """Les ``page_id`` fabriqués ci-dessus, dans l'ordre des pages du layout."""
+    return [page.page_id for page in manifest.pages]
+
+
+__all__ = ["layout_to_manifest", "manifest_page_ids"]

cinoc/adapters/layout/alto_source.py

@@ -0,0 +1,230 @@
+"""``AltoLayoutSource`` — ``IMAGE → LAYOUT`` depuis un ALTO déjà là (couche 5).
+
+Le banc sait produire une mise en page (segmenteurs) et sait en consommer une
+(``to_text``, ``assembler``, métriques de structure). Il ne savait pas **en
+lire une qui existe déjà** : un corpus patrimonial arrive presque toujours
+accompagné de son ALTO, et rien ne permettait de le faire entrer autrement
+qu'aplati en texte.
+
+Convention de ``PrecomputedLayoutSource`` reprise telle quelle — l'ALTO est
+cherché **à côté de l'image**, ``<stem>.xml`` près de ``<stem>.png``. C'est la
+façon dont les corpus de ce dépôt sont rangés, et ça évite d'ajouter un type
+d'entrée initial au planificateur.
+
+Ce que la lecture conserve, et qui n'a de valeur que conservé : l'identifiant
+de ligne (une identité, pas un rang), la géométrie, la confiance du moteur
+d'origine, et la césure (``SUBS_TYPE``/``SUBS_CONTENT`` + la marque portée par
+``<HYP>``). Un post-correcteur qui recolle un mot coupé a besoin des quatre.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from cinoc.adapters._workspace import workspace_artifact_path
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError, CinocError
+from cinoc.domain.layout import CanonicalLayout, Line, Region
+from cinoc.formats.alto.layout_map import alto_to_layout
+from cinoc.formats.alto.parser import parse_alto
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+
+#: Extensions tentées à côté de l'image, dans l'ordre.
+_SUFFIXES = (".xml", ".alto.xml")
+
+
+class AltoLayoutSource:
+    """Lit l'ALTO voisin de l'image et le projette en ``CanonicalLayout``.
+
+    ``ocr_sidecar`` remplace le **texte** des lignes par une lecture d'OCR
+    réelle, en gardant de l'ALTO tout le reste — identité, géométrie, césure.
+    Sans lui, un corpus à vérité terrain fait entrer sa propre référence dans
+    le banc : le correcteur n'a rien à corriger et le CER vaut zéro **par
+    construction**. Un zéro tautologique ressemble à un excellent résultat, ce
+    qui en fait le plus trompeur de tous.
+
+    Format attendu (celui de ``scripts/ocr_corpus.py``) : ``{"ocr": {fichier:
+    {line_id: texte}}}``. Une ligne absente du sidecar **garde son texte
+    d'ALTO** et est comptée ; une ligne présente mais **vide** est une lecture
+    d'OCR à part entière — le moteur n'a rien reconnu — et remplace donc le
+    texte. Confondre les deux crédite le moteur d'une ligne qu'il n'a pas lue.
+    """
+
+    def __init__(self, *, ocr_sidecar: str = "") -> None:
+        self._sidecar = ocr_sidecar
+
+    @property
+    def name(self) -> str:
+        return "alto_source"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.LAYOUT})
+
+    def _locate(self, image_path: Path) -> Path:
+        for suffix in _SUFFIXES:
+            candidate = image_path.with_name(image_path.stem + suffix)
+            if candidate.is_file():
+                return candidate
+        attendus = " ou ".join(repr(image_path.stem + s) for s in _SUFFIXES)
+        raise AdapterStepError(
+            f"{self.name} : aucun ALTO près de {image_path.name!r} "
+            f"({attendus} attendu dans {image_path.parent})."
+        )
+
+    def _read_sidecar(self, alto_name: str) -> dict[str, str]:
+        chemin = Path(self._sidecar)
+        try:
+            data = json.loads(chemin.read_text(encoding="utf-8"))
+        except (OSError, ValueError) as exc:
+            raise AdapterStepError(
+                f"{self.name} : sidecar OCR illisible ({chemin}) — {exc}"
+            ) from exc
+        par_fichier = data.get("ocr") if isinstance(data, dict) else None
+        if not isinstance(par_fichier, dict):
+            raise AdapterStepError(
+                f"{self.name} : {chemin.name!r} n'a pas de section 'ocr'."
+            )
+        lectures = par_fichier.get(alto_name)
+        if not isinstance(lectures, dict):
+            raise AdapterStepError(
+                f"{self.name} : le sidecar ne connaît pas {alto_name!r}."
+            )
+        return {str(k): str(v) for k, v in lectures.items()}
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],  # noqa: ARG002 — contrat Module
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        image = inputs.get(ArtifactType.IMAGE)
+        if image is None or image.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact IMAGE manquant ou sans URI."
+            )
+        alto_path = self._locate(Path(image.uri))
+        try:
+            layout = alto_to_layout(parse_alto(alto_path.read_bytes()))
+        except CinocError as exc:
+            raise AdapterStepError(
+                f"{self.name} : {alto_path.name!r} illisible — {exc}"
+            ) from exc
+        if self._sidecar:
+            layout, remplacees, total = _apply_ocr(
+                layout, self._read_sidecar(alto_path.name)
+            )
+            if remplacees == 0 and total:
+                # Un sidecar qui ne touche AUCUNE ligne est presque toujours un
+                # mauvais appariement de clés, pas un OCR parfait. Le dire ici
+                # évite de publier un CER nul en croyant mesurer une correction.
+                raise AdapterStepError(
+                    f"{self.name} : le sidecar ne couvre aucune des {total} "
+                    f"lignes de {alto_path.name!r} — clés de fichier ou de "
+                    "ligne incompatibles."
+                )
+
+        # Une ligne sans ``id`` n'a pas d'identité stable, et un post-correcteur
+        # qui reçoit un tel layout ne peut pas rendre ses décisions ligne à
+        # ligne. On le dit ici plutôt que de laisser l'étape suivante échouer
+        # sur une cause qui n'est pas la sienne.
+        sans_id = sum(
+            1
+            for page in layout.pages
+            for region in page.regions
+            for line in region.lines
+            if not line.id
+        )
+        if sans_id:
+            raise AdapterStepError(
+                f"{self.name} : {alto_path.name!r} porte {sans_id} ligne(s) "
+                "sans attribut ID. Sans identifiant, une ligne n'a pas "
+                "d'identité stable d'un artefact à l'autre."
+            )
+
+        payload = layout.model_dump_json().encode("utf-8")
+        # Sans espace de travail, on écrit près de la source — même repli que
+        # ``alto_assembler``.
+        out = (
+            workspace_artifact_path(
+                context.workspace_uri, context.document_id, self.name, "layout.json"
+            )
+            if context.workspace_uri
+            else alto_path.with_name(f"{alto_path.stem}.{self.name}.layout.json")
+        )
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_bytes(payload)
+        return StepOutput(
+            artifacts={
+                ArtifactType.LAYOUT: Artifact(
+                    id=f"{context.document_id}:{self.name}:layout",
+                    document_id=context.document_id,
+                    type=ArtifactType.LAYOUT,
+                    uri=str(out),
+                    content_hash=compute_content_hash(payload),
+                )
+            }
+        )
+
+
+def _apply_ocr(
+    layout: CanonicalLayout, lectures: dict[str, str]
+) -> tuple[CanonicalLayout, int, int]:
+    """Remplace le texte des lignes connues du sidecar. Renvoie ``(layout,
+    remplacées, total)`` — les compteurs servent à refuser un appariement vide.
+
+    Les **mots sont abandonnés** sur une ligne remplacée : leur géométrie
+    décrivait les caractères de la vérité terrain, pas ceux que l'OCR a lus.
+    """
+    remplacees = 0
+    total = 0
+
+    def region(reg: Region) -> Region:
+        nonlocal remplacees, total
+        lignes = []
+        for line in reg.lines:
+            total += 1
+            if line.id is not None and line.id in lectures:
+                remplacees += 1
+                lignes.append(
+                    Line(
+                        id=line.id,
+                        text=lectures[line.id],
+                        geometry=line.geometry,
+                        baseline=line.baseline,
+                        words=(),
+                        confidence=line.confidence,
+                    )
+                )
+            else:
+                lignes.append(line)
+        return reg.model_copy(
+            update={
+                "lines": tuple(lignes),
+                "regions": tuple(region(r) for r in reg.regions),
+            }
+        )
+
+    pages = tuple(
+        page.model_copy(update={"regions": tuple(region(r) for r in page.regions)})
+        for page in layout.pages
+    )
+    return layout.model_copy(update={"pages": pages}), remplacees, total
+
+
+__all__ = ["AltoLayoutSource"]

cinoc/adapters/layout/assembler.py

@@ -0,0 +1,89 @@
+"""``AltoAssembler`` — assemblage ``LAYOUT → ALTO_XML`` (couche 5).
+
+Troisième étage du pipeline de segmentation (``CLAUDE.md`` §3 : *assemblage
+LAYOUT → ALTO_XML*). C'est un **constructeur d'ALTO** au sens du même `Module`
+Protocol que les autres briques : il prend un ``CanonicalLayout`` **rempli**
+(sortie du fan-out, sérialisé JSON) et émet de l'ALTO 4 déterministe
+(``layout_to_alto`` + ``write_alto`` octet-stable).
+
+L'assembleur vit en couche 5 (et non `pipeline`) parce qu'il dépend de `formats`
+(`write_alto`) — un import légal pour un adapter, interdit à `pipeline`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.layout import CanonicalLayout
+from cinoc.formats.alto import write_alto
+from cinoc.formats.alto.layout_map import layout_to_alto
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+
+
+class AltoAssembler:
+    """Assemble un ``LAYOUT`` rempli en ``ALTO_XML`` (ALTO 4, déterministe)."""
+
+    @property
+    def name(self) -> str:
+        return "alto_assembler"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.LAYOUT})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.ALTO_XML})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        layout_art = inputs.get(ArtifactType.LAYOUT)
+        if layout_art is None or layout_art.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact LAYOUT manquant ou sans URI."
+            )
+        layout_path = Path(layout_art.uri)
+        try:
+            layout = CanonicalLayout.model_validate_json(layout_path.read_bytes())
+        except (OSError, ValueError) as exc:
+            raise AdapterStepError(
+                f"{self.name} : LAYOUT illisible ({layout_path.name!r}) : {exc}"
+            ) from exc
+        payload = write_alto(layout_to_alto(layout))
+        out_dir = (
+            Path(context.workspace_uri)
+            if context.workspace_uri
+            else layout_path.parent
+        )
+        out_path = out_dir / f"{context.document_id.replace('/', '_')}.alto.xml"
+        out_path.write_bytes(payload)
+        return StepOutput(
+            artifacts={
+                ArtifactType.ALTO_XML: Artifact(
+                    id=f"{context.document_id}:{self.name}:alto_xml",
+                    document_id=context.document_id,
+                    type=ArtifactType.ALTO_XML,
+                    uri=str(out_path),
+                    content_hash=compute_content_hash(payload),
+                )
+            }
+        )
+
+
+__all__ = ["AltoAssembler"]

cinoc/adapters/layout/crop.py

@@ -0,0 +1,72 @@
+"""``crop_region`` — découpe l'image d'un bloc pour l'OCR par région (couche 5).
+
+Brique du pipeline **hybride** « segmentation externe → OCR des blocs » : le
+fan-out (couche 4) fournit une **boîte relative** ``(x0, y0, x1, y1) ∈ [0, 1]``
+(la couche 4 a déjà neutralisé les unités, ALTO ``mm10`` vs pixels) ; ici on
+ouvre l'image, on convertit en pixels et on découpe — le crop réel vit en
+couche 5 car il dépend de ``PIL`` (interdit à ``pipeline``).
+
+``Pillow`` est un extra optionnel, importé **paresseusement** : importer ce
+module n'exige pas la lib, seule l'exécution.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from urllib.parse import quote
+
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.types import RunContext
+
+_RelBox = tuple[float, float, float, float]
+
+
+def crop_region(
+    page_image: Artifact, rel_bbox: _RelBox, region_id: str, context: RunContext
+) -> Artifact:
+    """Découpe ``rel_bbox`` (relatif) de l'image page → artefact ``IMAGE`` du bloc."""
+    if page_image.uri is None:
+        raise AdapterStepError("crop_region : image page sans URI.")
+    if context.workspace_uri is None:
+        raise AdapterStepError("crop_region : workspace requis pour écrire le crop.")
+    try:
+        from PIL import Image  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "crop_region : Pillow non installé (pip install 'cinoc[tesseract]')."
+        ) from exc
+    try:
+        with Image.open(page_image.uri) as image:
+            width, height = image.size
+            box = (
+                max(0, min(width, round(rel_bbox[0] * width))),
+                max(0, min(height, round(rel_bbox[1] * height))),
+                max(0, min(width, round(rel_bbox[2] * width))),
+                max(0, min(height, round(rel_bbox[3] * height))),
+            )
+            if box[2] <= box[0] or box[3] <= box[1]:
+                raise AdapterStepError(
+                    f"crop_region : boîte vide pour la région {region_id!r}."
+                )
+            crop = image.crop(box)
+            stem = quote(region_id, safe="")
+            out_path = Path(context.workspace_uri) / (
+                f"{quote(context.document_id, safe='')}.{stem}.crop.png"
+            )
+            crop.save(out_path)
+    except OSError as exc:
+        raise AdapterStepError(
+            f"crop_region : image illisible ({page_image.uri!r}) : {exc}"
+        ) from exc
+    return Artifact(
+        id=f"{context.document_id}:crop:{region_id}",
+        document_id=context.document_id,
+        type=ArtifactType.IMAGE,
+        uri=str(out_path),
+        content_hash=compute_content_hash(out_path.read_bytes()),
+        region_id=region_id,
+    )
+
+
+__all__ = ["crop_region"]

cinoc/adapters/layout/pp_doclayout.py

@@ -0,0 +1,147 @@
+"""``PPDocLayoutSegmenter`` — segmenteur de mise en page réel (PP-DocLayout).
+
+Détecte les **régions** d'une page (titre, paragraphe, figure, tableau…) et émet
+un ``LAYOUT`` (``CanonicalLayout`` à régions **sans lignes** — la reconnaissance
+les remplit ensuite, cf. fan-out couche 4). Implémente le ``Module`` Protocol
+**directement**, comme les autres adapters.
+
+Module **maison du socle** (≠ plugin tiers découvert) : enregistré par
+``register_default_modules`` → disponible **même en mode public** sur le Space
+(contrairement aux plugins via entry-points, fail-closed). Son SDK (PaddleX,
+Apache-2.0) est un **extra optionnel** (``cinoc[segment]``), importé
+**paresseusement** : importer ce module n'exige ni la lib ni les poids — seule
+l'exécution les requiert.
+
+Le détecteur est **injectable** (``detector=``) : la conversion détections →
+``CanonicalLayout`` se teste sans SDK ni poids (CI), le vrai modèle reste un test
+``live``/``slow`` opt-in. Déterminisme (§12) : à modèle + poids + params figés et
+seuil de score fixe, la sortie est stable ; l'ordre de lecture est **trié**
+(haut→bas puis gauche→droite), indépendant de l'ordre de détection.
+"""
+
+from __future__ import annotations
+
+from cinoc.adapters.layout._base import (
+    DetectedRegion,
+    DetectorFn,
+    LayoutDetection,
+    layout_step_output,
+    to_canonical_layout,
+)
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+_DEFAULT_MIN_SCORE = 0.5
+
+
+#: Modèle PP-DocLayout par défaut. La variante **légère** ``PP-DocLayout-S``
+#: (poids ~10× plus petits) est bakable dans l'image Space pour **tester
+#: l'option** sans peser sur le free-tier ; ``-L`` reste le défaut qualité.
+#: Surchargé par ``CINOC_PPDOCLAYOUT_MODEL`` (lu par le builder) ou ``model=``.
+_DEFAULT_MODEL = "PP-DocLayout-L"
+
+
+def _detect_with_paddle(  # pragma: no cover -- SDK + poids requis (test 'live')
+    image_path: str, model: str = _DEFAULT_MODEL
+) -> LayoutDetection:
+    """Détecte la mise en page via **PaddleX PP-DocLayout**. Isolé → mockable.
+
+    SDK absent → ``AdapterStepError`` explicite (l'extra ``[segment]`` manque) ;
+    le module reste listable, il ne plante pas à l'import. Le corps qui exécute le
+    modèle n'est exercé que par un test ``live`` (SDK + poids installés). ``model``
+    choisit la variante (``-L`` qualité / ``-S`` légère)."""
+    try:
+        from paddlex import create_model  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "pp_doclayout : PaddleX non installé "
+            "(pip install 'cinoc[segment]' + poids PP-DocLayout)."
+        ) from exc
+    results = list(create_model(model).predict(image_path, batch_size=1))
+    if not results:
+        return LayoutDetection(page_width=0, page_height=0, regions=())
+    boxes = results[0].get("boxes", [])
+    regions = tuple(
+        DetectedRegion(
+            label=str(box.get("label", "")),
+            x=int(box["coordinate"][0]),
+            y=int(box["coordinate"][1]),
+            width=int(box["coordinate"][2]) - int(box["coordinate"][0]),
+            height=int(box["coordinate"][3]) - int(box["coordinate"][1]),
+            score=float(box.get("score", 0.0)),
+        )
+        for box in boxes
+    )
+    shape = results[0].get("input_img_shape") or (0, 0)
+    return LayoutDetection(
+        page_width=int(shape[1]), page_height=int(shape[0]), regions=regions
+    )
+
+
+class PPDocLayoutSegmenter:
+    """Segmenteur PP-DocLayout : ``IMAGE → LAYOUT`` (régions sans lignes)."""
+
+    def __init__(
+        self,
+        *,
+        model: str = _DEFAULT_MODEL,
+        min_score: float = _DEFAULT_MIN_SCORE,
+        detector: DetectorFn | None = None,
+    ) -> None:
+        if not 0.0 <= min_score <= 1.0:
+            raise AdapterStepError(
+                f"PPDocLayoutSegmenter : min_score ∈ [0, 1], reçu {min_score}."
+            )
+        self._model = model
+        self._min_score = min_score
+        self._detector = detector
+
+    @property
+    def name(self) -> str:
+        return "pp_doclayout"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.LAYOUT})
+
+    def _detect(self, image_path: str) -> LayoutDetection:
+        if self._detector is not None:
+            return self._detector(image_path)
+        return _detect_with_paddle(image_path, self._model)
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        image = inputs.get(ArtifactType.IMAGE)
+        if image is None or image.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact IMAGE manquant ou sans URI."
+            )
+        if context.workspace_uri is None:
+            raise AdapterStepError(
+                f"{self.name} : workspace requis (RunContext.workspace_uri)."
+            )
+        layout = to_canonical_layout(
+            self._detect(image.uri), min_score=self._min_score
+        )
+        return layout_step_output(layout, context, self.name)
+
+
+__all__ = ["PPDocLayoutSegmenter"]

cinoc/adapters/layout/precomputed.py

@@ -0,0 +1,178 @@
+"""Socle ``precomputed`` de la tranche segmentation (couche 5, 0 dép, 0 réseau).
+
+Deux briques, **même ``Module`` Protocol** que les autres adapters, qui font
+tourner le squelette segmentation **sans segmenteur ni OCR réels** :
+
+- ``PrecomputedLayoutSource`` : ``IMAGE → LAYOUT`` — rejoue une mise en page
+  pré-calculée (régions seules) depuis ``<stem>.layout.json``.
+- ``PrecomputedRegionRecognizer`` : ``IMAGE → RAW_TEXT`` — rejoue le texte d'**une
+  région** (clé = ``Artifact.region_id`` de l'IMAGE d'entrée) depuis
+  ``<stem>.<label>.regions.json`` (``{region_id: texte}``). Appelé **une fois par
+  région** par le fan-out (couche 4) ; aucun découpage d'image réel (la donnée
+  est figée).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.layout import CanonicalLayout
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+
+
+def _require_image(inputs: dict[ArtifactType, Artifact], who: str) -> Path:
+    image = inputs.get(ArtifactType.IMAGE)
+    if image is None or image.uri is None:
+        raise AdapterStepError(f"{who} : artefact IMAGE manquant ou sans URI.")
+    return Path(image.uri)
+
+
+class PrecomputedLayoutSource:
+    """Rejoue une mise en page pré-calculée (``<stem>.layout.json``)."""
+
+    @property
+    def name(self) -> str:
+        return "precomputed_layout"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.LAYOUT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        image_path = _require_image(inputs, self.name)
+        layout_path = image_path.parent / f"{image_path.stem}.layout.json"
+        if not layout_path.is_file():
+            raise AdapterStepError(
+                f"{self.name} : mise en page pré-calculée introuvable — "
+                f"{layout_path.name!r} attendu près de {image_path.name!r}."
+            )
+        data = layout_path.read_bytes()
+        try:
+            CanonicalLayout.model_validate_json(data)
+        except ValueError as exc:
+            raise AdapterStepError(
+                f"{self.name} : {layout_path.name!r} n'est pas un "
+                f"CanonicalLayout valide : {exc}"
+            ) from exc
+        return StepOutput(
+            artifacts={
+                ArtifactType.LAYOUT: Artifact(
+                    id=f"{context.document_id}:{self.name}:layout",
+                    document_id=context.document_id,
+                    type=ArtifactType.LAYOUT,
+                    uri=str(layout_path),
+                    content_hash=compute_content_hash(data),
+                )
+            }
+        )
+
+
+class PrecomputedRegionRecognizer:
+    """Rejoue le texte d'une région (``<stem>.<label>.regions.json``)."""
+
+    def __init__(self, *, source_label: str) -> None:
+        if not source_label or not all(
+            c.isalnum() or c in "_-" for c in source_label
+        ):
+            raise AdapterStepError(
+                f"PrecomputedRegionRecognizer : source_label invalide "
+                f"{source_label!r} (alphanumérique + _ - uniquement)."
+            )
+        self._label = source_label
+
+    @property
+    def name(self) -> str:
+        return f"precomputed_region:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        image = inputs[ArtifactType.IMAGE]
+        if image.region_id is None:
+            raise AdapterStepError(
+                f"{self.name} : IMAGE sans region_id — la reconnaissance par "
+                "région attend une entrée déjà cadrée par le fan-out."
+            )
+        image_path = _require_image(inputs, self.name)
+        regions_path = (
+            image_path.parent / f"{image_path.stem}.{self._label}.regions.json"
+        )
+        if not regions_path.is_file():
+            raise AdapterStepError(
+                f"{self.name} : textes par région introuvables — "
+                f"{regions_path.name!r} attendu près de {image_path.name!r}."
+            )
+        try:
+            mapping = json.loads(regions_path.read_bytes())
+        except ValueError as exc:
+            raise AdapterStepError(
+                f"{self.name} : {regions_path.name!r} JSON invalide : {exc}"
+            ) from exc
+        if not isinstance(mapping, dict) or image.region_id not in mapping:
+            raise AdapterStepError(
+                f"{self.name} : région {image.region_id!r} absente de "
+                f"{regions_path.name!r}."
+            )
+        text = str(mapping[image.region_id])
+        out_dir = (
+            Path(context.workspace_uri)
+            if context.workspace_uri
+            else image_path.parent
+        )
+        out_path = out_dir / f"{image_path.stem}.{self._label}.{image.region_id}.txt"
+        payload = text.encode("utf-8")
+        out_path.write_bytes(payload)
+        return StepOutput(
+            artifacts={
+                ArtifactType.RAW_TEXT: Artifact(
+                    id=f"{context.document_id}:{self.name}:{image.region_id}:raw_text",
+                    document_id=context.document_id,
+                    type=ArtifactType.RAW_TEXT,
+                    uri=str(out_path),
+                    content_hash=compute_content_hash(payload),
+                    region_id=image.region_id,
+                )
+            }
+        )
+
+
+__all__ = ["PrecomputedLayoutSource", "PrecomputedRegionRecognizer"]

cinoc/adapters/layout/remote.py

@@ -0,0 +1,194 @@
+"""``RemoteSegmenter`` — segmenteur de mise en page **par appel distant**.
+
+Au lieu d'embarquer un modèle lourd (poids dans l'image), ce module **délègue** la
+détection de régions à un modèle hébergé ailleurs : un *Inference Endpoint* HF, un
+Space-modèle, ou tout service exposant l'API **object-detection** de Hugging Face.
+Cinoc **orchestre**, le modèle **tourne à distance** — le Space reste léger (pas de
+poids, pas d'inférence CPU locale).
+
+C'est l'incarnation « distante » du point d'extension unique de Cinoc : il
+implémente le **même ``Module`` Protocol** que ``PPDocLayoutSegmenter`` (et que les
+plugins tiers), donc il apparaît comme **segmenteur sélectionnable** avant un run.
+On change de modèle en changeant l'``endpoint`` — sans rien réinstaller.
+
+Schéma de réponse attendu = sortie **object-detection** HF :
+``[{"label": str, "score": float, "box": {"xmin","ymin","xmax","ymax"}}, …]``.
+
+Le détecteur est **injectable** (``detector=``) : la conversion détections →
+``CanonicalLayout`` se teste sans réseau ; le vrai appel HTTP (``httpx`` + garde
+**anti-SSRF** ``assert_public_url``) n'est exercé qu'en test ``live``. ``httpx`` est
+un extra optionnel (``cinoc[serve]``/``[google]``…), importé paresseusement.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cinoc.adapters.corpus._http import SsrfError, assert_public_url
+from cinoc.adapters.layout._base import (
+    DetectedRegion,
+    DetectorFn,
+    LayoutDetection,
+    layout_step_output,
+    to_canonical_layout,
+)
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+_DEFAULT_MIN_SCORE = 0.5
+_DEFAULT_TIMEOUT = 60.0
+
+
+def parse_hf_detections(
+    payload: object, *, page_width: int, page_height: int
+) -> LayoutDetection:
+    """Réponse object-detection HF → ``LayoutDetection`` (tolérante aux entrées
+    mal formées : les boîtes invalides sont ignorées, jamais une exception)."""
+    if not isinstance(payload, list):
+        raise AdapterStepError(
+            "remote_segmenter : réponse inattendue (liste de détections attendue)."
+        )
+    regions: list[DetectedRegion] = []
+    for item in payload:
+        if not isinstance(item, dict):
+            continue
+        box = item.get("box")
+        if not isinstance(box, dict):
+            continue
+        try:
+            x0, y0 = int(box["xmin"]), int(box["ymin"])
+            x1, y1 = int(box["xmax"]), int(box["ymax"])
+        except (KeyError, TypeError, ValueError):
+            continue
+        regions.append(
+            DetectedRegion(
+                label=str(item.get("label", "")),
+                x=x0,
+                y=y0,
+                width=max(0, x1 - x0),
+                height=max(0, y1 - y0),
+                score=float(item.get("score", 0.0)),
+            )
+        )
+    return LayoutDetection(
+        page_width=page_width, page_height=page_height, regions=tuple(regions)
+    )
+
+
+def _image_dims(image_path: str) -> tuple[int, int]:
+    """Dimensions ``(largeur, hauteur)`` de l'image ; ``(0, 0)`` si indisponible
+    (Pillow absent / illisible) — la conversion gère les dimensions nulles."""
+    try:
+        from PIL import Image, UnidentifiedImageError
+    except ImportError:
+        return (0, 0)
+    try:
+        with Image.open(image_path) as opened:
+            return (int(opened.width), int(opened.height))
+    except (UnidentifiedImageError, OSError):
+        return (0, 0)
+
+
+class RemoteSegmenter:
+    """Segmenteur ``IMAGE → LAYOUT`` délégué à un endpoint object-detection."""
+
+    def __init__(
+        self,
+        *,
+        endpoint: str,
+        token: str | None = None,
+        min_score: float = _DEFAULT_MIN_SCORE,
+        timeout: float = _DEFAULT_TIMEOUT,
+        detector: DetectorFn | None = None,
+    ) -> None:
+        if not endpoint:
+            raise AdapterStepError("remote_segmenter : 'endpoint' requis.")
+        if not 0.0 <= min_score <= 1.0:
+            raise AdapterStepError(
+                f"remote_segmenter : min_score ∈ [0, 1], reçu {min_score}."
+            )
+        self._endpoint = endpoint
+        self._token = token
+        self._min_score = min_score
+        self._timeout = timeout
+        self._detector = detector
+
+    @property
+    def name(self) -> str:
+        return "remote_segmenter"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.LAYOUT})
+
+    def _detect(self, image_path: str) -> LayoutDetection:
+        if self._detector is not None:
+            return self._detector(image_path)
+        return self._remote_detect(image_path)
+
+    def _remote_detect(  # pragma: no cover -- réseau réel (test 'live')
+        self, image_path: str
+    ) -> LayoutDetection:
+        try:
+            assert_public_url(self._endpoint)
+        except SsrfError as exc:
+            raise AdapterStepError(
+                f"remote_segmenter : endpoint refusé (anti-SSRF) : {exc}"
+            ) from exc
+        try:
+            import httpx
+        except ImportError as exc:
+            raise AdapterStepError(
+                "remote_segmenter : httpx absent (extra réseau requis)."
+            ) from exc
+        headers = {"Content-Type": "application/octet-stream"}
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        try:
+            with httpx.Client(timeout=self._timeout) as client:
+                response = client.post(
+                    self._endpoint,
+                    content=Path(image_path).read_bytes(),
+                    headers=headers,
+                )
+                response.raise_for_status()
+                payload = response.json()
+        except httpx.HTTPError as exc:
+            raise AdapterStepError(
+                f"remote_segmenter : appel à l'endpoint échoué : {exc}"
+            ) from exc
+        width, height = _image_dims(image_path)
+        return parse_hf_detections(payload, page_width=width, page_height=height)
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        image = inputs.get(ArtifactType.IMAGE)
+        if image is None or image.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact IMAGE manquant ou sans URI."
+            )
+        layout = to_canonical_layout(
+            self._detect(image.uri), min_score=self._min_score
+        )
+        return layout_step_output(layout, context, self.name)
+
+
+__all__ = ["RemoteSegmenter", "parse_hf_detections"]

cinoc/adapters/layout/saknussemm_correct.py

@@ -0,0 +1,324 @@
+"""``SaknussemmCorrector`` — ``LAYOUT → LAYOUT + CORRECTED_TEXT`` (couche 5).
+
+La post-correction du banc était **texte plat → texte plat** : on aplatissait
+avant de corriger, donc l'identité de ligne, la géométrie et la césure étaient
+détruites *avant* que le modèle voie quoi que ce soit. Cette étape corrige
+**dans** la mise en page : chaque ligne garde son identifiant d'un bout à
+l'autre, et l'appariement avant/après est **connu** au lieu d'être deviné.
+
+Deux sorties, et c'est délibéré :
+
+* ``LAYOUT`` — la mise en page corrigée, que ``alto_assembler`` sait rendre en
+  ALTO et que les métriques de structure savent noter ;
+* ``CORRECTED_TEXT`` — le même contenu aplati, **pour que le bilan de correction
+  existant fonctionne sans être modifié**. Il cherche un ``RAW_TEXT`` et un
+  ``CORRECTED_TEXT`` dans les sorties du pipeline ; les lui donner coûte une
+  projection et évite d'inventer un type d'artefact pour ça ;
+* ``DECISIONS`` — ce qui a été changé, ce qui a été **refusé**, et pourquoi.
+  Un texte corrigé ne dit pas si une ligne est intacte parce qu'une garde l'a
+  protégée ou parce que rien n'a été proposé : deux situations que rien ne
+  distingue une fois le texte écrit.
+
+Ce que la bibliothèque décide, l'étape le rapporte sans le retoucher : une ligne
+refusée par une garde ressort **avec son texte d'origine**. C'est le principe de
+`saknussemm` — l'application décide, le modèle informe — et le contredire ici
+reviendrait à réintroduire en aval ce que les gardes ont écarté.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from cinoc.adapters._workspace import workspace_artifact_path
+from cinoc.adapters.layout.to_text import _page_text
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.layout import CanonicalLayout, Line, Region
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+
+#: Producteurs câblés. ``rules`` ne demande rien (déterministe, hors ligne) ;
+#: ``ollama`` parle à un serveur local, sans clé d'API. Les fournisseurs
+#: distants s'ajouteront quand un run les demandera — pas avant.
+_PRODUCERS = ("rules", "ollama")
+
+
+def _require_saknussemm() -> Any:
+    try:
+        import saknussemm  # type: ignore[import-not-found]  # noqa: PLC0415
+    except ImportError as exc:  # pragma: no cover - dépend de l'installation
+        raise AdapterStepError(
+            "saknussemm_correct : la bibliothèque 'saknussemm' n'est pas "
+            "installée — `pip install cinoc[saknussemm]`."
+        ) from exc
+    return saknussemm
+
+
+class SaknussemmCorrector:
+    """Corrige un ``CanonicalLayout`` ligne à ligne, identités préservées."""
+
+    def __init__(
+        self,
+        *,
+        label: str,
+        producer: str = "rules",
+        model: str = "",
+        host: str = "http://localhost:11434",
+    ) -> None:
+        if producer not in _PRODUCERS:
+            raise AdapterStepError(
+                f"SaknussemmCorrector : producteur {producer!r} inconnu "
+                f"(attendu : {', '.join(_PRODUCERS)})."
+            )
+        if producer == "ollama" and not model:
+            raise AdapterStepError(
+                "SaknussemmCorrector : le producteur 'ollama' exige un `model`."
+            )
+        self._label = label
+        self._producer = producer
+        self._model = model
+        self._host = host
+
+    @property
+    def name(self) -> str:
+        return f"saknussemm:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.LAYOUT})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset(
+            {
+                ArtifactType.LAYOUT,
+                ArtifactType.CORRECTED_TEXT,
+                ArtifactType.DECISIONS,
+            }
+        )
+
+    # -- producteur ---------------------------------------------------------
+
+    def _build_producer(self) -> Any:
+        if self._producer == "rules":
+            from saknussemm.producers.rules import (  # type: ignore[import-not-found]  # noqa: PLC0415
+                RulesProducer,
+                default_french_ocr_rules,
+            )
+
+            return RulesProducer(default_french_ocr_rules())
+
+        from saknussemm.producers.llm_edit import (  # type: ignore[import-not-found]  # noqa: PLC0415, E501
+            LLMEditProducer,
+        )
+
+        from cinoc.adapters.llm.ollama_structured import (  # noqa: PLC0415
+            OllamaStructuredClient,
+        )
+
+        return LLMEditProducer(
+            OllamaStructuredClient(host=self._host), api_key="", model=self._model
+        )
+
+    # -- exécution ----------------------------------------------------------
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],  # noqa: ARG002 — contrat Module
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        artifact = inputs.get(ArtifactType.LAYOUT)
+        if artifact is None or artifact.uri is None:
+            raise AdapterStepError(f"{self.name} : artefact LAYOUT sans URI.")
+        try:
+            layout = CanonicalLayout.model_validate_json(
+                Path(artifact.uri).read_bytes()
+            )
+        except (OSError, ValueError) as exc:
+            raise AdapterStepError(
+                f"{self.name} : {artifact.uri!r} n'est pas un CanonicalLayout "
+                f"lisible — {exc}"
+            ) from exc
+        _require_saknussemm()
+
+        from saknussemm.core.pipeline import (  # type: ignore[import-not-found]  # noqa: PLC0415, E501
+            CorrectionPipeline,
+        )
+
+        from cinoc.adapters.layout._saknussemm_bridge import (  # noqa: PLC0415
+            layout_to_manifest,
+            manifest_page_ids,
+        )
+
+        manifest = layout_to_manifest(layout, document_id=context.document_id)
+        control.raise_if_cancelled()
+
+        class _Observer:
+            def on_event(self, event_type: str, payload: dict[str, Any]) -> None:
+                pass
+
+        pipeline = CorrectionPipeline(
+            producer=self._build_producer(), observer=_Observer()
+        )
+        # ``source_files`` vide : on ne réécrit aucun XML. L'artefact de sortie
+        # est la mise en page, et ``alto_assembler`` sait en faire un ALTO — le
+        # moteur n'a donc rien à rendre lui-même.
+        result = pipeline.run_sync(document_manifest=manifest, source_files={})
+
+        decided = {
+            (outcome.page_id, outcome.line_id): outcome.decision.final_text
+            for outcome in result.report.lines
+        }
+        corrected = _apply(layout, decided, manifest_page_ids(manifest))
+        return self._emit(corrected, _decisions(result, context.document_id), context)
+
+    def _emit(
+        self, layout: CanonicalLayout, decisions: bytes, context: RunContext
+    ) -> StepOutput:
+        payload = layout.model_dump_json().encode("utf-8")
+        text = _flatten(layout).encode("utf-8")
+        layout_path = self._out(context, "layout.json")
+        text_path = self._out(context, "corrected.txt")
+        decisions_path = self._out(context, "decisions.json")
+        layout_path.parent.mkdir(parents=True, exist_ok=True)
+        layout_path.write_bytes(payload)
+        text_path.write_bytes(text)
+        decisions_path.write_bytes(decisions)
+        return StepOutput(
+            artifacts={
+                ArtifactType.LAYOUT: Artifact(
+                    id=f"{context.document_id}:{self.name}:layout",
+                    document_id=context.document_id,
+                    type=ArtifactType.LAYOUT,
+                    uri=str(layout_path),
+                    content_hash=compute_content_hash(payload),
+                ),
+                ArtifactType.CORRECTED_TEXT: Artifact(
+                    id=f"{context.document_id}:{self.name}:text",
+                    document_id=context.document_id,
+                    type=ArtifactType.CORRECTED_TEXT,
+                    uri=str(text_path),
+                    content_hash=compute_content_hash(text),
+                ),
+                ArtifactType.DECISIONS: Artifact(
+                    id=f"{context.document_id}:{self.name}:decisions",
+                    document_id=context.document_id,
+                    type=ArtifactType.DECISIONS,
+                    uri=str(decisions_path),
+                    content_hash=compute_content_hash(decisions),
+                ),
+            }
+        )
+
+    def _out(self, context: RunContext, suffix: str) -> Path:
+        if context.workspace_uri:
+            return workspace_artifact_path(
+                context.workspace_uri, context.document_id, self._label, suffix
+            )
+        return Path(f"{context.document_id.replace('/', '_')}.{self._label}.{suffix}")
+
+
+def _decisions(result: object, document_id: str) -> bytes:
+    """Sérialise ce que la bibliothèque a décidé, ligne par ligne.
+
+    Le **statut** distingue trois situations qu'un texte corrigé confond :
+    la ligne a changé, une garde a refusé un changement proposé, ou rien n'a
+    été proposé. Sans cette distinction, un correcteur prudent et un correcteur
+    inerte rendent le même artefact.
+    """
+    lignes = []
+    for outcome in result.report.lines:  # type: ignore[attr-defined]
+        decision = outcome.decision
+        propose = outcome.proposal.output_text if outcome.proposal else None
+        raison = decision.reason
+        lignes.append(
+            {
+                "document_id": document_id,
+                "page_id": outcome.page_id,
+                "line_id": outcome.line_id,
+                "status": decision.status,
+                "source_text": outcome.source_text,
+                "final_text": decision.final_text,
+                "proposed_text": propose,
+                "hyphen_role": outcome.hyphen_role,
+                "reason_code": raison.code if raison else None,
+                "reason_detail": raison.detail if raison else None,
+            }
+        )
+    return json.dumps(
+        {"document_id": document_id, "lines": lignes}, ensure_ascii=False
+    ).encode("utf-8")
+
+
+def _apply(
+    layout: CanonicalLayout,
+    decided: dict[tuple[str, str], str],
+    page_ids: list[str],
+) -> CanonicalLayout:
+    """Repose les textes décidés sur la mise en page, identités à l'appui.
+
+    Les mots sont **abandonnés sur une ligne modifiée** : leur géométrie décrit
+    des caractères qui ne sont plus là. Les garder ferait dire à l'artefact une
+    position que rien ne soutient — le contraire de ce que la structure sert à
+    porter.
+    """
+
+    def region(reg: Region, page_id: str) -> Region:
+        lines = []
+        for line in reg.lines:
+            texte = decided.get((page_id, line.id or ""))
+            if texte is None or texte == line.text:
+                lines.append(line)
+                continue
+            lines.append(
+                Line(
+                    id=line.id,
+                    text=texte,
+                    geometry=line.geometry,
+                    baseline=line.baseline,
+                    words=(),
+                    confidence=line.confidence,
+                )
+            )
+        return reg.model_copy(
+            update={
+                "lines": tuple(lines),
+                "regions": tuple(region(r, page_id) for r in reg.regions),
+            }
+        )
+
+    pages = tuple(
+        page.model_copy(
+            update={"regions": tuple(region(r, page_ids[i]) for r in page.regions)}
+        )
+        for i, page in enumerate(layout.pages)
+    )
+    return layout.model_copy(update={"pages": pages})
+
+
+def _flatten(layout: CanonicalLayout) -> str:
+    """Aplatit **avec la fonction de ``to_text``**, pas avec une copie.
+
+    Le bilan de correction compare le ``RAW_TEXT`` produit par ``to_text`` au
+    ``CORRECTED_TEXT`` produit ici : deux conventions d'aplatissement
+    différentes fausseraient la comparaison sans rien casser de visible. Une
+    première version réécrivait la boucle et ajoutait 41 lignes vides sur le
+    corpus BnF — les régions sans texte — ce qui aurait décalé tout
+    l'appariement de lignes.
+    """
+    return "\n".join(_page_text(page) for page in layout.pages)
+
+
+__all__ = ["SaknussemmCorrector"]

cinoc/adapters/layout/to_text.py

@@ -0,0 +1,106 @@
+"""``LayoutToTextExtractor`` — ``LAYOUT rempli → RAW_TEXT`` (couche 5).
+
+Quatrième étage **optionnel** d'un pipeline hybride : une fois les régions
+reconnues (fan-out → ``CanonicalLayout`` rempli), on aplatit le texte dans
+**l'ordre de lecture** pour le rendre **scorable** comme n'importe quelle sortie
+``RAW_TEXT`` (CER/WER à la page). C'est ce qui permet à un run « segmenteur →
+reconnaissance par bloc » d'être un **concurrent du Banc d'essai** comparé à un
+OCR à plat, et plus seulement un ALTO produit dans son coin.
+
+Déterministe : ordre = ``reading_order`` de la page (repli sur l'ordre déclaré),
+lignes d'une région jointes par ``\\n``, régions par ``\\n``, pages par ``\\n``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.layout import CanonicalLayout, LayoutPage
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+
+
+def _page_text(page: LayoutPage) -> str:
+    """Texte d'une page, régions dans l'ordre de lecture (repli ordre déclaré)."""
+    by_id = {region.id: region for region in page.regions}
+    ordered = [by_id[rid] for rid in page.reading_order if rid in by_id]
+    seen = {region.id for region in ordered}
+    ordered.extend(region for region in page.regions if region.id not in seen)
+    blocks: list[str] = []
+    for region in ordered:
+        lines = "\n".join(line.text for line in region.lines if line.text)
+        if lines:
+            blocks.append(lines)
+    return "\n".join(blocks)
+
+
+class LayoutToTextExtractor:
+    """Aplatit un ``LAYOUT`` rempli en ``RAW_TEXT`` (ordre de lecture, déterministe)."""
+
+    def __init__(self, label: str) -> None:
+        self._label = label
+
+    @property
+    def name(self) -> str:
+        return f"layout_to_text:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.LAYOUT})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        layout_art = inputs.get(ArtifactType.LAYOUT)
+        if layout_art is None or layout_art.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact LAYOUT manquant ou sans URI."
+            )
+        layout_path = Path(layout_art.uri)
+        try:
+            layout = CanonicalLayout.model_validate_json(layout_path.read_bytes())
+        except (OSError, ValueError) as exc:
+            raise AdapterStepError(
+                f"{self.name} : LAYOUT illisible ({layout_path.name!r}) : {exc}"
+            ) from exc
+        text = "\n".join(_page_text(page) for page in layout.pages)
+        payload = text.encode("utf-8")
+        out_dir = (
+            Path(context.workspace_uri)
+            if context.workspace_uri
+            else layout_path.parent
+        )
+        out_path = out_dir / f"{context.document_id.replace('/', '_')}.layout.txt"
+        out_path.write_bytes(payload)
+        return StepOutput(
+            artifacts={
+                ArtifactType.RAW_TEXT: Artifact(
+                    id=f"{context.document_id}:{self.name}:raw_text",
+                    document_id=context.document_id,
+                    type=ArtifactType.RAW_TEXT,
+                    uri=str(out_path),
+                    content_hash=compute_content_hash(payload),
+                )
+            }
+        )
+
+
+__all__ = ["LayoutToTextExtractor"]

cinoc/adapters/llm/__init__.py

@@ -0,0 +1,15 @@
+"""Adapters LLM/VLM (couche 5) — post-correction texte/image + transcription VLM.
+
+Modes par adapter (``PipelineMode``) : ``text_only`` (tous), ``text_and_image``
+et ``zero_shot`` (openai, mistral, anthropic — vision). ``ollama`` reste
+``text_only`` (socle local minimal).
+"""
+
+from __future__ import annotations
+
+from cinoc.adapters.llm.anthropic import AnthropicAdapter
+from cinoc.adapters.llm.mistral import MistralAdapter
+from cinoc.adapters.llm.ollama import OllamaAdapter
+from cinoc.adapters.llm.openai import OpenAIAdapter
+
+__all__ = ["AnthropicAdapter", "MistralAdapter", "OllamaAdapter", "OpenAIAdapter"]

cinoc/adapters/llm/_base.py

@@ -0,0 +1,285 @@
+"""Helpers partagés des adapters LLM/VLM (post-correction + transcription).
+
+Les adapters concrets (openai, anthropic, mistral, ollama) implémentent le
+``Module`` Protocol et ne fournissent que leurs **appels réseau** (isolés,
+mockables). Toute la logique commune — choix des entrées/sorties selon le
+**mode**, chargement du texte OCR et/ou de l'image, écriture de l'artefact —
+vit **ici**, dans ``run_llm_step`` : un seul endroit, aucun mode dupliqué par
+fournisseur (anti « 8+8+8 », cf. CLAUDE.md §8.8).
+
+Modes (``PipelineMode``, source de vérité unique en ``domain``) :
+
+- ``text_only``      — ``RAW_TEXT`` → ``CORRECTED_TEXT`` (le LLM ne voit pas l'image).
+- ``text_and_image`` — ``{RAW_TEXT, IMAGE}`` → ``CORRECTED_TEXT`` (le VLM voit l'image).
+- ``zero_shot``      — ``IMAGE`` → ``RAW_TEXT`` (transcription directe, sans OCR amont).
+"""
+
+from __future__ import annotations
+
+from base64 import b64encode
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, NamedTuple, cast
+
+from cinoc.adapters._workspace import workspace_artifact_path
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.pipeline import PipelineMode
+from cinoc.domain.usage import ResourceUsage
+from cinoc.formats.text import read_plaintext
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+#: Prompt de post-correction (modes ``text_only`` / ``text_and_image``) ;
+#: ``{ocr_text}`` est substitué par le texte OCR amont.
+DEFAULT_CORRECTION_PROMPT = (
+    "Tu es un correcteur de transcriptions OCR de documents patrimoniaux. "
+    "Corrige uniquement les erreurs manifestes de reconnaissance, sans "
+    "reformuler ni moderniser l'orthographe historique. Réponds par le seul "
+    "texte corrigé.\n\n{ocr_text}"
+)
+
+#: Prompt de transcription directe (mode ``zero_shot`` : le VLM lit l'image).
+DEFAULT_TRANSCRIPTION_PROMPT = (
+    "Transcris fidèlement le texte de cette image de document patrimonial. "
+    "Conserve l'orthographe historique et la ponctuation d'origine. N'ajoute "
+    "aucun commentaire : réponds par le seul texte transcrit."
+)
+
+#: Extension de fichier → media type (sous-ensemble image courant).
+_MEDIA_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".tif": "image/tiff",
+    ".tiff": "image/tiff",
+}
+
+class LLMCompletion(NamedTuple):
+    """Réponse d'un fournisseur : texte + jetons consommés (si exposés)."""
+
+    text: str
+    tokens_in: int | None = None
+    tokens_out: int | None = None
+
+
+#: Appel d'un LLM texte : ``prompt → réponse`` (fournisseur + modèle capturés).
+TextInvoke = Callable[[str], LLMCompletion]
+#: Appel d'un VLM : ``prompt, media_type, image_b64 → réponse``.
+VisionInvoke = Callable[[str, str, str], LLMCompletion]
+
+
+def usage_tokens(value: Any) -> int | None:
+    """Coercition prudente d'un compteur de jetons SDK (``None`` si absent)."""
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        return None
+    return value
+
+
+def normalize_llm_content(raw: Any) -> str:
+    """Aplati une réponse LLM (``str`` ou liste de blocs) en chaîne."""
+    if raw is None:
+        return ""
+    if isinstance(raw, str):
+        return raw
+    if isinstance(raw, list):
+        parts: list[str] = []
+        for chunk in raw:
+            if isinstance(chunk, str):
+                parts.append(chunk)
+            elif isinstance(chunk, dict) and isinstance(chunk.get("text"), str):
+                parts.append(chunk["text"])
+            else:
+                text = getattr(chunk, "text", None)
+                if isinstance(text, str):
+                    parts.append(text)
+        return "".join(parts)
+    return str(raw)
+
+
+def validate_llm_label(label: str, adapter: str) -> str:
+    """Valide un label d'adapter LLM (alphanum + ``_ -``) et le renvoie.
+
+    Le label compose le ``name`` du module (``<kind>:<label>``) ; le restreindre
+    garde les noms de modules sûrs et stables (provenance ``RunManifest``).
+    """
+    if not label or not all(c.isalnum() or c in "_-" for c in label):
+        raise AdapterStepError(
+            f"{adapter} : label invalide {label!r} (alphanum + _ -)."
+        )
+    return label
+
+
+def validate_role(role: str, adapter: str, supported: frozenset[str]) -> PipelineMode:
+    """Valide un mode d'adapter contre ceux que le fournisseur supporte."""
+    if role not in supported:
+        raise AdapterStepError(
+            f"{adapter} : mode {role!r} non supporté "
+            f"(modes : {', '.join(sorted(supported))})."
+        )
+    return cast(PipelineMode, role)
+
+
+def llm_input_types(role: PipelineMode) -> frozenset[ArtifactType]:
+    """Types d'entrée requis par le ``role`` (mode du pipeline)."""
+    if role == "text_only":
+        return frozenset({ArtifactType.RAW_TEXT})
+    if role == "text_and_image":
+        return frozenset({ArtifactType.RAW_TEXT, ArtifactType.IMAGE})
+    return frozenset({ArtifactType.IMAGE})  # zero_shot
+
+
+def llm_output_type(role: PipelineMode) -> ArtifactType:
+    """Type produit : ``RAW_TEXT`` en transcription, sinon ``CORRECTED_TEXT``."""
+    return (
+        ArtifactType.RAW_TEXT
+        if role == "zero_shot"
+        else ArtifactType.CORRECTED_TEXT
+    )
+
+
+def default_prompt_for_role(role: PipelineMode) -> str:
+    """Prompt par défaut adapté au mode (transcription vs correction)."""
+    return (
+        DEFAULT_TRANSCRIPTION_PROMPT
+        if role == "zero_shot"
+        else DEFAULT_CORRECTION_PROMPT
+    )
+
+
+def build_prompt(template: str, ocr_text: str) -> str:
+    return template.replace("{ocr_text}", ocr_text)
+
+
+def load_ocr_text(inputs: dict[ArtifactType, Artifact], adapter_name: str) -> str:
+    artifact = inputs.get(ArtifactType.RAW_TEXT)
+    if artifact is None or artifact.uri is None:
+        raise AdapterStepError(
+            f"{adapter_name} : input RAW_TEXT manquant ou sans URI."
+        )
+    return read_plaintext(Path(artifact.uri).read_bytes())
+
+
+def load_image_b64(
+    inputs: dict[ArtifactType, Artifact], adapter_name: str
+) -> tuple[str, str]:
+    """Charge l'``IMAGE`` d'entrée → ``(media_type, base64)`` pour un VLM."""
+    artifact = inputs.get(ArtifactType.IMAGE)
+    if artifact is None or artifact.uri is None:
+        raise AdapterStepError(
+            f"{adapter_name} : input IMAGE manquant ou sans URI."
+        )
+    path = Path(artifact.uri)
+    media_type = _MEDIA_TYPES.get(path.suffix.lower(), "image/png")
+    return media_type, b64encode(path.read_bytes()).decode("ascii")
+
+
+def write_text_artifact(
+    workspace_uri: str,
+    document_id: str,
+    label: str,
+    adapter_name: str,
+    text: str,
+    *,
+    output_type: ArtifactType,
+) -> dict[ArtifactType, Artifact]:
+    """Écrit ``text`` dans le workspace → artefact du type produit par le mode."""
+    is_corrected = output_type == ArtifactType.CORRECTED_TEXT
+    suffix = "corrected.txt" if is_corrected else "raw.txt"
+    output_path = workspace_artifact_path(
+        workspace_uri, document_id, label, suffix
+    )
+    output_path.write_text(text, encoding="utf-8")
+    return {
+        output_type: Artifact(
+            id=f"{document_id}:{adapter_name}:{output_type.value}",
+            document_id=document_id,
+            type=output_type,
+            uri=str(output_path),
+            content_hash=compute_content_hash(text.encode("utf-8")),
+        )
+    }
+
+
+def run_llm_step(
+    *,
+    role: PipelineMode,
+    label: str,
+    name: str,
+    prompt: str,
+    inputs: dict[ArtifactType, Artifact],
+    context: RunContext,
+    control: RunControl,
+    text_invoke: TextInvoke,
+    vision_invoke: VisionInvoke | None,
+) -> StepOutput:
+    """Exécute une étape LLM/VLM selon le ``role`` — logique de mode unique.
+
+    Aiguille sur le mode : charge les bonnes entrées (texte et/ou image), appelle
+    l'invocation fournisseur idoine, écrit l'artefact du bon type. ``zero_shot``
+    et ``text_and_image`` exigent ``vision_invoke`` (un fournisseur texte-seul,
+    ex. ollama, passe ``None`` → ces modes sont refusés proprement). Les jetons
+    exposés par le fournisseur remontent dans ``StepOutput.usage``.
+    """
+    control.raise_if_cancelled()
+    if context.workspace_uri is None:
+        raise AdapterStepError(
+            f"{name} : workspace requis (RunContext.workspace_uri)."
+        )
+    if role == "zero_shot":
+        if vision_invoke is None:
+            raise AdapterStepError(f"{name} : mode zero_shot requiert un VLM (vision).")
+        media_type, image_b64 = load_image_b64(inputs, name)
+        completion = vision_invoke(prompt, media_type, image_b64)
+    elif role == "text_and_image":
+        if vision_invoke is None:
+            raise AdapterStepError(
+                f"{name} : mode text_and_image requiert un VLM (vision)."
+            )
+        ocr_text = load_ocr_text(inputs, name)
+        media_type, image_b64 = load_image_b64(inputs, name)
+        completion = vision_invoke(
+            build_prompt(prompt, ocr_text), media_type, image_b64
+        )
+    else:  # text_only
+        ocr_text = load_ocr_text(inputs, name)
+        completion = text_invoke(build_prompt(prompt, ocr_text))
+    artifacts = write_text_artifact(
+        context.workspace_uri,
+        context.document_id,
+        label,
+        name,
+        completion.text,
+        output_type=llm_output_type(role),
+    )
+    usage = (
+        ResourceUsage(
+            tokens_in=completion.tokens_in, tokens_out=completion.tokens_out
+        )
+        if completion.tokens_in is not None or completion.tokens_out is not None
+        else None
+    )
+    return StepOutput(artifacts=artifacts, usage=usage)
+
+
+__all__ = [
+    "DEFAULT_CORRECTION_PROMPT",
+    "DEFAULT_TRANSCRIPTION_PROMPT",
+    "LLMCompletion",
+    "TextInvoke",
+    "VisionInvoke",
+    "build_prompt",
+    "default_prompt_for_role",
+    "llm_input_types",
+    "llm_output_type",
+    "load_image_b64",
+    "load_ocr_text",
+    "normalize_llm_content",
+    "run_llm_step",
+    "usage_tokens",
+    "validate_llm_label",
+    "validate_role",
+    "write_text_artifact",
+]

cinoc/adapters/llm/anthropic.py

@@ -0,0 +1,202 @@
+"""``AnthropicAdapter`` — post-correction LLM **et** transcription VLM (Claude).
+
+Implémente le ``Module`` Protocol, trois modes (``PipelineMode``) selon le rôle :
+``text_only`` (texte → corrigé), ``text_and_image`` (Claude vision : image +
+texte → corrigé), ``zero_shot`` (Claude vision : image → texte). Clé
+``ANTHROPIC_API_KEY`` ; SDK ``anthropic`` = **extra** importé paresseusement dans
+``_invoke_anthropic`` / ``_invoke_anthropic_vision`` (isolés → **mockables**, CI
+sans clé ni réseau). La ``Deadline`` borne l'appel.
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from cinoc.adapters._resilience import call_resilient
+from cinoc.adapters.llm._base import (
+    LLMCompletion,
+    default_prompt_for_role,
+    llm_input_types,
+    llm_output_type,
+    normalize_llm_content,
+    run_llm_step,
+    usage_tokens,
+    validate_llm_label,
+    validate_role,
+)
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.deadline import Deadline
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.pipeline import PipelineMode
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+_DEFAULT_MODEL = "claude-haiku-4-5-20251001"
+_MAX_TOKENS = 4096
+_SUPPORTED: frozenset[str] = frozenset({"text_only", "text_and_image", "zero_shot"})
+
+
+def _completion_from_message(response: Any) -> LLMCompletion:
+    """Réponse SDK ``messages.create`` → ``LLMCompletion`` (texte + jetons).
+
+    **Pur** (aucun réseau, aucun SDK) → la cartographie usage→jetons
+    (``input_tokens``/``output_tokens``, **noms propres à Claude**) est **testable
+    sur cassette** (étape 2d) ; le client live (``# pragma: no cover``) ne le
+    permettrait pas. Jetons → économie (coût cloud réel).
+    """
+    usage = getattr(response, "usage", None)
+    return LLMCompletion(
+        normalize_llm_content(getattr(response, "content", None)),
+        usage_tokens(getattr(usage, "input_tokens", None)),
+        usage_tokens(getattr(usage, "output_tokens", None)),
+    )
+
+
+def _anthropic_client(  # pragma: no cover -- réseau + clé API (cf. 'live')
+    model: str, content: object, deadline: Deadline
+) -> LLMCompletion:
+    """Appel ``messages.create`` partagé (texte ou multimodal)."""
+    import os
+
+    api_key = os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        raise AdapterStepError("anthropic : ANTHROPIC_API_KEY manquante.")
+    try:
+        from anthropic import (  # type: ignore[import-not-found]
+            Anthropic,
+            AnthropicError,
+        )
+    except ImportError as exc:
+        raise AdapterStepError(
+            "anthropic : SDK non installé (pip install 'cinoc[anthropic]')."
+        ) from exc
+    client_kwargs: dict[str, object] = {"api_key": api_key}
+    timeout = deadline.as_sdk_timeout()
+    if timeout is not None:
+        client_kwargs["timeout"] = timeout
+    try:
+        # SDK anthropic typé strictement ; dicts valides à l'exécution (tests live).
+        client = Anthropic(**client_kwargs)  # type: ignore[arg-type]
+
+        def _create() -> Any:
+            return client.messages.create(
+                model=model,
+                max_tokens=_MAX_TOKENS,
+                messages=[{"role": "user", "content": content}],  # type: ignore[typeddict-item]
+            )
+
+        # Cap de concurrence (≤ N appels Anthropic simultanés) + retry borné sur
+        # 429/5xx (Retry-After respecté) — par défaut, sans configuration UI.
+        response = call_resilient("anthropic", _create)
+    except AnthropicError as exc:
+        raise AdapterStepError(
+            f"anthropic a échoué ({model}) : {type(exc).__name__}: {exc}"
+        ) from exc
+    return _completion_from_message(response)
+
+
+def _invoke_anthropic(  # pragma: no cover -- réseau + clé API (cf. marqueur 'live')
+    *, model: str, prompt: str, deadline: Deadline
+) -> LLMCompletion:
+    return _anthropic_client(model, prompt, deadline)
+
+
+def _invoke_anthropic_vision(  # pragma: no cover -- réseau + clé API (cf. 'live')
+    *, model: str, prompt: str, media_type: str, image_b64: str, deadline: Deadline
+) -> LLMCompletion:
+    content = [
+        {"type": "text", "text": prompt},
+        {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": media_type,
+                "data": image_b64,
+            },
+        },
+    ]
+    return _anthropic_client(model, content, deadline)
+
+
+class AnthropicAdapter:
+    """Adapter Anthropic multi-mode (post-correction texte/image, transcription)."""
+
+    #: Modes que cet adapter implémente **réellement**. Déclaré ici, à côté du
+    #: code qui les rend possibles : la capacité vision est une closure passée à
+    #: ``run_llm_step``, invérifiable de l'extérieur. Une liste tenue ailleurs
+    #: dérive — c'est arrivé (D-233).
+    SUPPORTED_MODES: ClassVar[frozenset[PipelineMode]] = frozenset(
+        {"text_only", "text_and_image", "zero_shot"}
+    )
+
+
+    def __init__(
+        self,
+        *,
+        label: str,
+        model: str = _DEFAULT_MODEL,
+        role: str = "text_only",
+        prompt: str | None = None,
+    ) -> None:
+        self._label = validate_llm_label(label, "AnthropicAdapter")
+        self._model = model
+        self._role: PipelineMode = validate_role(role, "AnthropicAdapter", _SUPPORTED)
+        self._prompt = (
+            prompt if prompt is not None else default_prompt_for_role(self._role)
+        )
+
+    @property
+    def name(self) -> str:
+        return f"anthropic:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return llm_input_types(self._role)
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({llm_output_type(self._role)})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        def text_invoke(prompt: str) -> LLMCompletion:
+            return _invoke_anthropic(
+                model=self._model, prompt=prompt, deadline=context.deadline
+            )
+
+        def vision_invoke(
+            prompt: str, media_type: str, image_b64: str
+        ) -> LLMCompletion:
+            return _invoke_anthropic_vision(
+                model=self._model,
+                prompt=prompt,
+                media_type=media_type,
+                image_b64=image_b64,
+                deadline=context.deadline,
+            )
+
+        return run_llm_step(
+            role=self._role,
+            label=self._label,
+            name=self.name,
+            prompt=self._prompt,
+            inputs=inputs,
+            context=context,
+            control=control,
+            text_invoke=text_invoke,
+            vision_invoke=vision_invoke,
+        )
+
+
+__all__ = ["AnthropicAdapter"]

cinoc/adapters/llm/mistral.py

@@ -0,0 +1,230 @@
+"""``MistralAdapter`` — post-correction LLM **et** transcription VLM (API Mistral).
+
+Implémente le ``Module`` Protocol, trois modes (``PipelineMode``) selon le rôle :
+``text_only`` (texte → corrigé), ``text_and_image`` (Pixtral : image + texte →
+corrigé), ``zero_shot`` (Pixtral : image → texte). Clé ``MISTRAL_API_KEY`` ; SDK
+``mistralai`` = **extra** importé paresseusement dans ``_invoke_mistral`` /
+``_invoke_mistral_vision`` (isolés → **mockables**, CI sans clé ni réseau).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, ClassVar
+
+from cinoc.adapters._resilience import call_resilient
+from cinoc.adapters.llm._base import (
+    LLMCompletion,
+    default_prompt_for_role,
+    llm_input_types,
+    llm_output_type,
+    normalize_llm_content,
+    run_llm_step,
+    usage_tokens,
+    validate_llm_label,
+    validate_role,
+)
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.deadline import Deadline
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.pipeline import PipelineMode
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+logger = logging.getLogger(__name__)
+
+_VERSION = "1.0"
+_DEFAULT_MODEL = "mistral-small-latest"
+_SUPPORTED: frozenset[str] = frozenset({"text_only", "text_and_image", "zero_shot"})
+
+
+def _completion_from_chat(response: Any) -> LLMCompletion:
+    """Réponse SDK ``chat.complete`` → ``LLMCompletion`` (texte + jetons).
+
+    **Pur** (aucun réseau, aucun SDK) → la cartographie usage→jetons
+    (``prompt_tokens``/``completion_tokens``) est **testable sur cassette** (étape
+    2d) ; le client live (``# pragma: no cover``) ne le permettrait pas. Jetons →
+    économie (coût cloud réel).
+    """
+    usage = getattr(response, "usage", None)
+    tokens_in = usage_tokens(getattr(usage, "prompt_tokens", None))
+    tokens_out = usage_tokens(getattr(usage, "completion_tokens", None))
+    choices = getattr(response, "choices", None)
+    if not choices:
+        return LLMCompletion("", tokens_in, tokens_out)
+    return LLMCompletion(
+        normalize_llm_content(choices[0].message.content), tokens_in, tokens_out
+    )
+
+
+def _mistral_client(  # pragma: no cover -- réseau + clé API (cf. marqueur 'live')
+    model: str, content: object, deadline: Deadline
+) -> LLMCompletion:
+    """Appel ``chat.complete`` partagé (texte ou multimodal)."""
+    import os
+
+    api_key = os.environ.get("MISTRAL_API_KEY")
+    if not api_key:
+        raise AdapterStepError("mistral : MISTRAL_API_KEY manquante.")
+    try:
+        from mistralai import Mistral  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "mistral : SDK non installé (pip install 'cinoc[mistral]')."
+        ) from exc
+    client_kwargs: dict[str, object] = {"api_key": api_key}
+    timeout = deadline.as_sdk_timeout()
+    if timeout is not None:
+        client_kwargs["timeout_ms"] = int(timeout * 1000)
+    try:
+        # Le SDK mistralai 1.x type strictement ses kwargs/messages ; on lui
+        # passe des dicts valides à l'exécution (cf. tests live). ``ignore`` ciblé.
+        client = Mistral(**client_kwargs)  # type: ignore[arg-type]
+
+        def _complete() -> Any:
+            return client.chat.complete(
+                model=model,
+                messages=[{"role": "user", "content": content}],  # type: ignore[arg-type]
+                temperature=0.0,
+            )
+
+        # Cap de concurrence (≤ N appels Mistral simultanés) + retry borné sur
+        # 429/5xx (Retry-After respecté) — par défaut, sans configuration UI.
+        response = call_resilient("mistral", _complete)
+    except Exception as exc:  # le SDK lève des erreurs HTTP/SDK variées
+        raise AdapterStepError(
+            f"mistral a échoué ({model}) : {type(exc).__name__}: {exc}"
+        ) from exc
+    return _completion_from_chat(response)
+
+
+def _invoke_mistral(  # pragma: no cover -- réseau + clé API (cf. marqueur 'live')
+    *, model: str, prompt: str, deadline: Deadline
+) -> LLMCompletion:
+    return _mistral_client(model, prompt, deadline)
+
+
+def _invoke_mistral_vision(  # pragma: no cover -- réseau + clé API (cf. 'live')
+    *, model: str, prompt: str, media_type: str, image_b64: str, deadline: Deadline
+) -> LLMCompletion:
+    content = [
+        {"type": "text", "text": prompt},
+        {"type": "image_url", "image_url": f"data:{media_type};base64,{image_b64}"},
+    ]
+    return _mistral_client(model, content, deadline)
+
+
+class MistralAdapter:
+    """Adapter Mistral multi-mode (post-correction texte/image, transcription VLM)."""
+
+    #: Modes que cet adapter implémente **réellement**. Déclaré ici, à côté du
+    #: code qui les rend possibles : la capacité vision est une closure passée à
+    #: ``run_llm_step``, invérifiable de l'extérieur. Une liste tenue ailleurs
+    #: dérive — c'est arrivé (D-233).
+    SUPPORTED_MODES: ClassVar[frozenset[PipelineMode]] = frozenset(
+        {"text_only", "text_and_image", "zero_shot"}
+    )
+
+
+    def __init__(
+        self,
+        *,
+        label: str,
+        model: str = _DEFAULT_MODEL,
+        role: str = "text_only",
+        prompt: str | None = None,
+    ) -> None:
+        self._label = validate_llm_label(label, "MistralAdapter")
+        self._model = model
+        self._role: PipelineMode = validate_role(role, "MistralAdapter", _SUPPORTED)
+        self._prompt = (
+            prompt if prompt is not None else default_prompt_for_role(self._role)
+        )
+
+    @property
+    def name(self) -> str:
+        return f"mistral:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return llm_input_types(self._role)
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({llm_output_type(self._role)})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        def text_invoke(prompt: str) -> LLMCompletion:
+            return _invoke_mistral(
+                model=self._model, prompt=prompt, deadline=context.deadline
+            )
+
+        def vision_invoke(
+            prompt: str, media_type: str, image_b64: str
+        ) -> LLMCompletion:
+            return _invoke_mistral_vision(
+                model=self._model,
+                prompt=prompt,
+                media_type=media_type,
+                image_b64=image_b64,
+                deadline=context.deadline,
+            )
+
+        return run_llm_step(
+            role=self._role,
+            label=self._label,
+            name=self.name,
+            prompt=self._prompt,
+            inputs=inputs,
+            context=context,
+            control=control,
+            text_invoke=text_invoke,
+            vision_invoke=vision_invoke,
+        )
+
+
+def list_mistral_models(*, timeout: float = 5.0) -> tuple[str, ...]:
+    """IDs des modèles disponibles pour la clé Mistral courante (``models.list``).
+
+    **Best-effort, commodité d'UI** : ``MISTRAL_API_KEY`` absente, SDK absent ou
+    erreur réseau → ``()`` (l'interface retombe sur la saisie libre). Rien de
+    hardcodé : la liste vient **directement de l'API Mistral**.
+    """
+    import os
+
+    api_key = os.environ.get("MISTRAL_API_KEY")
+    if not api_key:
+        return ()
+    try:
+        from mistralai import Mistral  # type: ignore[import-not-found]
+    except ImportError:
+        return ()
+    try:
+        client = Mistral(api_key=api_key, timeout_ms=int(timeout * 1000))
+        response = client.models.list()
+    except Exception as exc:  # noqa: BLE001 — voir rationale ci-dessous
+        # Catch-all **assumé** : commodité d'UI qui ne doit jamais casser la
+        # page du composeur. Le SDK mistralai **enveloppe** ses erreurs HTTP
+        # (auth/429/5xx) dans ses propres types + propage des erreurs httpx pour
+        # le transport ; narrower au seul ``httpx.HTTPError`` (comme ollama, qui
+        # appelle httpx en direct) laisserait fuir une erreur SDK et casserait la
+        # page. On trace (§7) et on retombe sur la saisie libre.
+        logger.warning("[mistral] liste des modèles indisponible : %s", exc)
+        return ()
+    data = getattr(response, "data", None) or ()
+    ids = [m.id for m in data if isinstance(getattr(m, "id", None), str)]
+    return tuple(sorted(set(ids)))
+
+
+__all__ = ["MistralAdapter", "list_mistral_models"]

cinoc/adapters/llm/ollama.py

@@ -0,0 +1,240 @@
+"""``OllamaAdapter`` — post-correction LLM via un serveur ollama local.
+
+Deuxième famille LLM : prouve que le ``Module`` Protocol **généralise au-delà
+d'openai** — même contrat ``RAW_TEXT`` → ``CORRECTED_TEXT``, sortie identique,
+aucun cas particulier. Transport ``httpx`` (extra), importé paresseusement et
+**isolé** dans ``_invoke_ollama`` (→ mockable, CI sans serveur).
+
+C'est l'**implémentation de référence de l'annulation câblée** : ``_invoke_ollama``
+enregistre ``client.close`` via ``RunControl.register_cancel_handle`` ; un
+``trigger_cancel`` ferme la connexion et **interrompt la requête en vol**. La
+distinction « annulation vs vraie panne réseau » se fait en sondant
+``is_cancelled`` (``_fail_or_cancel``) — pas par une heuristique de message
+fragile (dette de l'implémentation source, corrigée au portage).
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar, NoReturn
+
+from cinoc.adapters.llm._base import (
+    LLMCompletion,
+    default_prompt_for_role,
+    llm_input_types,
+    llm_output_type,
+    normalize_llm_content,
+    run_llm_step,
+    usage_tokens,
+    validate_llm_label,
+    validate_role,
+)
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.deadline import Deadline
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.pipeline import PipelineMode
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+_DEFAULT_MODEL = "llama3"
+#: Les trois modes, comme les fournisseurs distants. ``zero_shot`` a un sens
+#: particulier ici : un modèle d'OCR local (churro, par exemple) transcrit
+#: l'image sans OCR amont.
+_SUPPORTED: frozenset[str] = frozenset({"text_only", "text_and_image", "zero_shot"})
+
+_DEFAULT_HOST = "http://localhost:11434"
+
+
+def _fail_or_cancel(control: RunControl, model: str, exc: Exception) -> NoReturn:
+    """Traduit un échec d'appel ollama.
+
+    Si l'annulation a été déclenchée, le ``client.close`` enregistré a fait
+    échouer la requête en vol : on lève alors ``RunCancelledError`` (via
+    ``raise_if_cancelled``). Sinon c'est une vraie panne → ``AdapterStepError``.
+    Sonder ``is_cancelled`` est **fiable**, là où l'implémentation source
+    devinait par le message d'exception (heuristique fragile, D-A).
+    """
+    control.raise_if_cancelled()
+    raise AdapterStepError(f"ollama a échoué ({model}) : {exc}") from exc
+
+
+def _invoke_ollama(  # pragma: no cover -- réseau (serveur ollama ; cf. marqueur 'live')
+    *,
+    model: str,
+    prompt: str,
+    host: str,
+    deadline: Deadline,
+    control: RunControl,
+    image_b64: str | None = None,
+) -> LLMCompletion:
+    try:
+        import httpx  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "ollama : httpx non installé (pip install 'cinoc[ollama]')."
+        ) from exc
+    # L'image voyage dans un tableau ``images`` **du message**, en base64 nu —
+    # pas d'URI ``data:``, pas de type de média : ollama ne suit pas la
+    # convention d'OpenAI ici, et un ``data:`` passé tel quel est ignoré en
+    # silence (le modèle répond alors sans avoir rien vu).
+    demande: dict[str, object] = {"role": "user", "content": prompt}
+    if image_b64 is not None:
+        demande["images"] = [image_b64]
+    payload = {"model": model, "messages": [demande], "stream": False}
+    client = httpx.Client(timeout=deadline.as_sdk_timeout())
+    # Annulation câblée : fermer le client interrompt la requête en vol.
+    control.register_cancel_handle(client.close)
+    try:
+        # **/api/chat** (et non /api/generate) : applique le gabarit de chat du
+        # modèle. Indispensable pour les modèles *instruct* (ex. churro), qui
+        # échouent sur /api/generate (complétion brute). C'est l'endpoint
+        # qu'utilise ``ollama run``.
+        response = client.post(f"{host}/api/chat", json=payload)
+        response.raise_for_status()
+        data = response.json()
+    except httpx.HTTPError as exc:
+        _fail_or_cancel(control, model, exc)
+    finally:
+        client.close()
+    # Ollama peut renvoyer une **erreur en HTTP 200** (modèle introuvable sous ce
+    # nom, mémoire insuffisante…) : ``raise_for_status`` ne la voit pas. On la
+    # remonte explicitement, sinon la « correction » serait un texte vide silencieux.
+    if isinstance(data, dict) and data.get("error"):
+        raise AdapterStepError(f"ollama a échoué ({model}) : {data['error']}")
+    message = data.get("message") if isinstance(data, dict) else None
+    content = message.get("content") if isinstance(message, dict) else None
+    # /api/chat expose la consommation : prompt_eval_count / eval_count.
+    counts = data if isinstance(data, dict) else {}
+    return LLMCompletion(
+        normalize_llm_content(content),
+        usage_tokens(counts.get("prompt_eval_count")),
+        usage_tokens(counts.get("eval_count")),
+    )
+
+
+def list_installed_models(
+    host: str = _DEFAULT_HOST, *, timeout: float = 3.0
+) -> tuple[str, ...]:
+    """Noms des modèles installés sur le serveur ollama (``GET /api/tags``).
+
+    **Best-effort, commodité d'UI** : serveur injoignable, ``httpx`` absent ou
+    réponse inattendue → ``()`` (l'interface retombe alors sur la saisie libre).
+    Aucune exception propagée. Le ``name`` renvoyé est le **tag exact** servable à
+    ``/api/generate`` (ex. ``gemma3:1b`` ou ``hf.co/…/churro-3B-GGUF:Q4_K_M``).
+    """
+    try:
+        import httpx  # type: ignore[import-not-found]
+    except ImportError:
+        return ()
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            response = client.get(f"{host}/api/tags")
+            response.raise_for_status()
+            data = response.json()
+    except (httpx.HTTPError, ValueError):
+        return ()
+    models = data.get("models") if isinstance(data, dict) else None
+    if not isinstance(models, list):
+        return ()
+    return tuple(
+        m["name"]
+        for m in models
+        if isinstance(m, dict) and isinstance(m.get("name"), str)
+    )
+
+
+class OllamaAdapter:
+    """LLM/VLM local (ollama), trois modes comme les fournisseurs distants.
+
+    L'adapter était ``text_only`` : un modèle vision installé en local ne
+    pouvait pas concourir au banc, alors que des poids figés sont **plus**
+    reproductibles qu'un instantané d'API susceptible d'être déprécié.
+    """
+
+    #: Modes que cet adapter implémente **réellement**. Déclaré ici, à côté du
+    #: code qui les rend possibles : la capacité vision est une closure passée à
+    #: ``run_llm_step``, invérifiable de l'extérieur. Une liste tenue ailleurs
+    #: dérive — c'est arrivé (D-233).
+    SUPPORTED_MODES: ClassVar[frozenset[PipelineMode]] = frozenset(
+        {"text_only", "text_and_image", "zero_shot"}
+    )
+
+
+    def __init__(
+        self,
+        *,
+        label: str,
+        model: str = _DEFAULT_MODEL,
+        host: str = _DEFAULT_HOST,
+        role: str = "text_only",
+        prompt: str | None = None,
+    ) -> None:
+        self._label = validate_llm_label(label, "OllamaAdapter")
+        self._model = model
+        self._host = host
+        self._role: PipelineMode = validate_role(role, "OllamaAdapter", _SUPPORTED)
+        self._prompt = (
+            prompt if prompt is not None else default_prompt_for_role(self._role)
+        )
+
+    @property
+    def name(self) -> str:
+        return f"ollama:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return llm_input_types(self._role)
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({llm_output_type(self._role)})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        def text_invoke(prompt: str) -> LLMCompletion:
+            return _invoke_ollama(
+                model=self._model,
+                prompt=prompt,
+                host=self._host,
+                deadline=context.deadline,
+                control=control,
+            )
+
+        def vision_invoke(
+            prompt: str, media_type: str, image_b64: str
+        ) -> LLMCompletion:
+            # ``media_type`` est ignoré : ollama devine le format des octets.
+            del media_type
+            return _invoke_ollama(
+                model=self._model,
+                prompt=prompt,
+                host=self._host,
+                deadline=context.deadline,
+                control=control,
+                image_b64=image_b64,
+            )
+
+        return run_llm_step(
+            role=self._role,
+            label=self._label,
+            name=self.name,
+            prompt=self._prompt,
+            inputs=inputs,
+            context=context,
+            control=control,
+            text_invoke=text_invoke,
+            vision_invoke=vision_invoke,
+        )
+
+
+__all__ = ["OllamaAdapter"]

cinoc/adapters/llm/ollama_structured.py

@@ -0,0 +1,120 @@
+"""``OllamaStructuredClient`` — sortie JSON contrainte, serveur local.
+
+``saknussemm`` ne consomme qu'une seule capacité d'un modèle
+(``StructuredCompletionClient``) : rendre le JSON décrit par un schéma. Ce
+client la fournit depuis un ``ollama`` local — aucune clé d'API, poids figés,
+donc plus reproductible qu'un instantané d'API qui peut être déprécié.
+
+Deux détails qui ne sont pas des détails :
+
+* ``num_ctx`` est **explicite**. Le défaut d'``ollama`` est 2048 jetons et la
+  troncature est **silencieuse** : le JSON revient coupé au milieu d'une chaîne,
+  et l'erreur ressemble à une hallucination du modèle alors que c'est le serveur
+  qui a coupé.
+* les échecs de transport sont traduits en ``ProviderTransientError`` /
+  ``ProviderPermanentError``. La recouvrabilité de ``saknussemm`` est une liste
+  blanche : une exception brute est traitée comme un bug et **fait échouer** le
+  run au lieu d'être réessayée en boucle.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+_DEFAULT_HOST = "http://localhost:11434"
+#: Le défaut d'ollama (2048) tronque en silence une page de journal.
+_DEFAULT_NUM_CTX = 8192
+
+
+class OllamaStructuredClient:
+    """``complete_structured`` sur ``/api/chat``, schéma JSON contraint."""
+
+    def __init__(
+        self,
+        *,
+        host: str = _DEFAULT_HOST,
+        num_ctx: int = _DEFAULT_NUM_CTX,
+        timeout: float = 300.0,
+    ) -> None:
+        self._host = host.rstrip("/")
+        self._num_ctx = num_ctx
+        self._timeout = timeout
+
+    async def complete_structured(
+        self,
+        api_key: str,  # noqa: ARG002 — un serveur local n'en a pas
+        model: str,
+        system_prompt: str,
+        user_payload: dict[str, Any],
+        json_schema: dict[str, Any],
+        temperature: float = 0.0,
+    ) -> tuple[dict[str, Any], Any]:
+        import httpx  # noqa: PLC0415
+
+        # Les classes concrètes vivent en ``core.protocols``, à côté du contrat
+        # qui les lève — ``errors`` n'ancre que leur base ``ProviderError``.
+        from saknussemm.core.protocols import (  # type: ignore[import-not-found]  # noqa: PLC0415
+            ProviderPermanentError,
+            ProviderTransientError,
+        )
+
+        body = {
+            "model": model,
+            "messages": [
+                {"role": "system", "content": system_prompt},
+                {
+                    "role": "user",
+                    "content": json.dumps(user_payload, ensure_ascii=False),
+                },
+            ],
+            "stream": False,
+            "format": _bare_schema(json_schema),
+            "options": {"temperature": temperature, "num_ctx": self._num_ctx},
+        }
+        try:
+            async with httpx.AsyncClient(timeout=self._timeout) as client:
+                response = await client.post(f"{self._host}/api/chat", json=body)
+                response.raise_for_status()
+                data = response.json()
+        except httpx.HTTPStatusError as exc:
+            status = exc.response.status_code
+            message = f"ollama a répondu {status} ({model})"
+            # 4xx = la requête est fautive, la réessayer la referait échouer.
+            if 400 <= status < 500:
+                raise ProviderPermanentError(message) from exc
+            raise ProviderTransientError(message) from exc
+        except (httpx.TimeoutException, httpx.TransportError) as exc:
+            raise ProviderTransientError(
+                f"ollama injoignable ({model}) : {exc}"
+            ) from exc
+
+        content = (data.get("message") or {}).get("content") or ""
+        try:
+            parsed = json.loads(content)
+        except json.JSONDecodeError as exc:
+            raise ProviderTransientError(
+                f"ollama ({model}) n'a pas rendu du JSON — réponse tronquée ou "
+                f"hors schéma : {content[:200]!r}"
+            ) from exc
+        if not isinstance(parsed, dict):
+            raise ProviderTransientError(
+                f"ollama ({model}) a rendu {type(parsed).__name__}, pas un objet."
+            )
+        return parsed, None
+
+
+def _bare_schema(json_schema: dict[str, Any]) -> dict[str, Any]:
+    """``format`` d'ollama attend le schéma **nu**, pas l'enveloppe OpenAI."""
+    direct = json_schema.get("schema")
+    if isinstance(direct, dict):
+        return direct
+    inner = json_schema.get("json_schema")
+    if isinstance(inner, dict):
+        nested = inner.get("schema")
+        if isinstance(nested, dict):
+            return nested
+    return json_schema
+
+
+__all__ = ["OllamaStructuredClient"]

cinoc/adapters/llm/openai.py

@@ -0,0 +1,197 @@
+"""``OpenAIAdapter`` — post-correction LLM **et** transcription VLM (API OpenAI).
+
+Implémente le ``Module`` Protocol. Trois modes (``PipelineMode``) selon le rôle
+passé à la construction : ``text_only`` (``RAW_TEXT`` → ``CORRECTED_TEXT``),
+``text_and_image`` (image + texte → corrigé), ``zero_shot`` (image → texte). La
+clé vient de ``OPENAI_API_KEY`` ; le SDK ``openai`` est un **extra** importé
+paresseusement dans ``_invoke_openai`` / ``_invoke_openai_vision`` (isolés →
+**mockables**, CI sans clé ni réseau). La ``Deadline`` borne l'appel.
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from cinoc.adapters._resilience import call_resilient
+from cinoc.adapters.llm._base import (
+    LLMCompletion,
+    default_prompt_for_role,
+    llm_input_types,
+    llm_output_type,
+    normalize_llm_content,
+    run_llm_step,
+    usage_tokens,
+    validate_llm_label,
+    validate_role,
+)
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.deadline import Deadline
+from cinoc.domain.errors import AdapterStepError
+from cinoc.domain.pipeline import PipelineMode
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+_DEFAULT_MODEL = "gpt-4o-mini"
+_SUPPORTED: frozenset[str] = frozenset({"text_only", "text_and_image", "zero_shot"})
+
+
+def _completion_from_chat(response: Any) -> LLMCompletion:
+    """Réponse SDK ``chat.completions`` → ``LLMCompletion`` (texte + jetons).
+
+    **Pur** (aucun réseau, aucun import SDK) → la cartographie usage→jetons
+    (``prompt_tokens``/``completion_tokens``) est **testable sur une réponse de
+    cassette**, ce que le client live (``# pragma: no cover``) ne permet pas. Les
+    jetons alimentent l'économie (coût réel par modèle).
+    """
+    usage = getattr(response, "usage", None)
+    tokens_in = usage_tokens(getattr(usage, "prompt_tokens", None))
+    tokens_out = usage_tokens(getattr(usage, "completion_tokens", None))
+    choices = getattr(response, "choices", None)
+    if not choices:
+        return LLMCompletion("", tokens_in, tokens_out)
+    return LLMCompletion(
+        normalize_llm_content(choices[0].message.content), tokens_in, tokens_out
+    )
+
+
+def _openai_client(  # pragma: no cover -- réseau + clé API (cf. marqueur 'live')
+    model: str, messages: list[dict[str, object]], deadline: Deadline
+) -> LLMCompletion:
+    """Appel ``chat.completions`` partagé (texte ou multimodal)."""
+    import os
+
+    api_key = os.environ.get("OPENAI_API_KEY")
+    if not api_key:
+        raise AdapterStepError("openai : OPENAI_API_KEY manquante.")
+    try:
+        from openai import OpenAI, OpenAIError  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "openai : SDK non installé (pip install 'cinoc[openai]')."
+        ) from exc
+    kwargs: dict[str, object] = {
+        "model": model,
+        "messages": messages,
+        "temperature": 0.0,
+    }
+    timeout = deadline.as_sdk_timeout()
+    if timeout is not None:
+        kwargs["timeout"] = timeout
+    try:
+        # SDK openai typé strictement ; kwargs valides à l'exécution (tests live).
+        client = OpenAI(api_key=api_key)
+
+        def _create() -> Any:
+            return client.chat.completions.create(**kwargs)  # type: ignore[call-overload]
+
+        # Cap de concurrence (≤ N appels OpenAI simultanés) + retry borné sur
+        # 429/5xx (Retry-After respecté) — par défaut, sans configuration UI.
+        response = call_resilient("openai", _create)
+    except OpenAIError as exc:
+        raise AdapterStepError(
+            f"openai a échoué ({model}) : {type(exc).__name__}: {exc}"
+        ) from exc
+    return _completion_from_chat(response)
+
+
+def _invoke_openai(  # pragma: no cover -- réseau + clé API (cf. marqueur 'live')
+    *, model: str, prompt: str, deadline: Deadline
+) -> LLMCompletion:
+    return _openai_client(model, [{"role": "user", "content": prompt}], deadline)
+
+
+def _invoke_openai_vision(  # pragma: no cover -- réseau + clé API (cf. marqueur 'live')
+    *, model: str, prompt: str, media_type: str, image_b64: str, deadline: Deadline
+) -> LLMCompletion:
+    content = [
+        {"type": "text", "text": prompt},
+        {
+            "type": "image_url",
+            "image_url": {"url": f"data:{media_type};base64,{image_b64}"},
+        },
+    ]
+    return _openai_client(model, [{"role": "user", "content": content}], deadline)
+
+
+class OpenAIAdapter:
+    """Adapter OpenAI multi-mode (post-correction texte/image, transcription VLM)."""
+
+    #: Modes que cet adapter implémente **réellement**. Déclaré ici, à côté du
+    #: code qui les rend possibles : la capacité vision est une closure passée à
+    #: ``run_llm_step``, invérifiable de l'extérieur. Une liste tenue ailleurs
+    #: dérive — c'est arrivé (D-233).
+    SUPPORTED_MODES: ClassVar[frozenset[PipelineMode]] = frozenset(
+        {"text_only", "text_and_image", "zero_shot"}
+    )
+
+
+    def __init__(
+        self,
+        *,
+        label: str,
+        model: str = _DEFAULT_MODEL,
+        role: str = "text_only",
+        prompt: str | None = None,
+    ) -> None:
+        self._label = validate_llm_label(label, "OpenAIAdapter")
+        self._model = model
+        self._role: PipelineMode = validate_role(role, "OpenAIAdapter", _SUPPORTED)
+        self._prompt = (
+            prompt if prompt is not None else default_prompt_for_role(self._role)
+        )
+
+    @property
+    def name(self) -> str:
+        return f"openai:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return llm_input_types(self._role)
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({llm_output_type(self._role)})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        def text_invoke(prompt: str) -> LLMCompletion:
+            return _invoke_openai(
+                model=self._model, prompt=prompt, deadline=context.deadline
+            )
+
+        def vision_invoke(
+            prompt: str, media_type: str, image_b64: str
+        ) -> LLMCompletion:
+            return _invoke_openai_vision(
+                model=self._model,
+                prompt=prompt,
+                media_type=media_type,
+                image_b64=image_b64,
+                deadline=context.deadline,
+            )
+
+        return run_llm_step(
+            role=self._role,
+            label=self._label,
+            name=self.name,
+            prompt=self._prompt,
+            inputs=inputs,
+            context=context,
+            control=control,
+            text_invoke=text_invoke,
+            vision_invoke=vision_invoke,
+        )
+
+
+__all__ = ["OpenAIAdapter"]

cinoc/adapters/ner/__init__.py

@@ -0,0 +1 @@
+"""Adapters NER : extraction d'entités nommées (couche 5)."""

cinoc/adapters/ner/spacy_extractor.py

@@ -0,0 +1,204 @@
+"""``SpacyNerExtractor`` — extraction d'entités nommées via spaCy (couche 5).
+
+Brique de pipeline ``RAW_TEXT|CORRECTED_TEXT → ENTITIES`` (la NER est une étape
+explicite, CLAUDE.md §3). Implémente le ``Module`` Protocol **directement**. Le
+SDK ``spacy`` + le **modèle** sont un extra optionnel (``cinoc[ner]`` + ``python
+-m spacy download <modèle>``), importés paresseusement.
+
+**Anti-silence (réparation R14 amont, bug du modèle source).** Si spaCy ou le
+modèle manque, l'adapter **lève** ``AdapterStepError`` avec le message
+d'installation — il ne renvoie **jamais** ``[]`` (le défaut de la source : un
+benchmark qui « réussit » avec un rappel 0 sans message). L'orchestrateur isole
+alors ce (concurrent × document) ; le document reste simplement non scoré.
+
+L'artefact ``ENTITIES`` embarque **le texte d'entrée** (``{"text", "entities"}``)
+— c'est lui qui rend la reprojection R14 auto-suffisante côté évaluation.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from cinoc.adapters._workspace import workspace_artifact_path
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+logger = logging.getLogger(__name__)
+
+_VERSION = "1.0"
+
+#: Normalisation des labels spaCy vers les conventions courtes HIPE/CoNLL.
+_DEFAULT_LABEL_MAPPING: dict[str, str] = {
+    "PERSON": "PER",
+    "PER": "PER",
+    "LOC": "LOC",
+    "GPE": "LOC",
+    "ORG": "ORG",
+    "DATE": "DATE",
+    "TIME": "DATE",
+    "MISC": "MISC",
+}
+
+#: Texte d'entrée accepté : sortie OCR brute **ou** corrigée par un LLM.
+_INPUT_TYPES = frozenset({ArtifactType.RAW_TEXT, ArtifactType.CORRECTED_TEXT})
+
+
+class SpacyNerExtractor:
+    """NER spaCy : ``RAW_TEXT|CORRECTED_TEXT`` → ``ENTITIES`` (fail-closed)."""
+
+    def __init__(
+        self,
+        *,
+        label: str,
+        model: str = "fr_core_news_sm",
+        loader: Any | None = None,
+    ) -> None:
+        if not label or not all(c.isalnum() or c in "_-" for c in label):
+            raise AdapterStepError(f"ner : label invalide {label!r}.")
+        self._label = label
+        self._model = model
+        #: Injectable en test : ``(model_name) -> nlp`` ; défaut = ``spacy.load``.
+        self._loader = loader
+        self._nlp: Any | None = None
+        self._model_version: str | None = None
+
+    @property
+    def name(self) -> str:
+        return f"ner:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return _INPUT_TYPES
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.ENTITIES})
+
+    def system_binaries(self) -> dict[str, str]:
+        """Versions spaCy + modèle **si déjà chargés** (reproductibilité).
+
+        Best-effort sans effet de bord : ne déclenche aucun chargement — renvoie
+        ``{}`` tant que le modèle n'a pas tourné. Fusionné au ``RunManifest`` par
+        l'orchestrateur (duck-typing, comme le binaire tesseract).
+        """
+        if self._nlp is None:
+            return {}
+        out: dict[str, str] = {}
+        if self._model_version is not None:
+            out[f"spacy_model:{self._model}"] = self._model_version
+        try:
+            import spacy  # type: ignore[import-not-found]
+
+            out["spacy"] = str(spacy.__version__)
+        except ImportError:
+            pass
+        return out
+
+    def _load(self) -> Any:
+        """Charge le modèle (idempotent). Fail-closed : lève si SDK/modèle absent."""
+        if self._nlp is not None:
+            return self._nlp
+        if self._loader is not None:
+            self._nlp = self._loader(self._model)
+            self._model_version = self._probe_model_version(self._nlp)
+            return self._nlp
+        try:
+            import spacy  # type: ignore[import-not-found]
+        except ImportError as exc:
+            raise AdapterStepError(
+                "ner : spaCy non installé — `pip install 'cinoc[ner]'`."
+            ) from exc
+        try:
+            self._nlp = spacy.load(self._model)
+        except OSError as exc:
+            raise AdapterStepError(
+                f"ner : modèle spaCy {self._model!r} introuvable — "
+                f"`python -m spacy download {self._model}`."
+            ) from exc
+        self._model_version = self._probe_model_version(self._nlp)
+        return self._nlp
+
+    @staticmethod
+    def _probe_model_version(nlp: Any) -> str | None:
+        meta = getattr(nlp, "meta", None)
+        if isinstance(meta, dict):
+            version = meta.get("version")
+            return str(version) if version is not None else None
+        return None
+
+    def _extract(self, text: str) -> list[dict[str, object]]:
+        nlp = self._load()
+        doc = nlp(text)
+        entities: list[dict[str, object]] = []
+        for ent in doc.ents:
+            label = _DEFAULT_LABEL_MAPPING.get(ent.label_, ent.label_)
+            entities.append(
+                {
+                    "label": label,
+                    "start": int(ent.start_char),
+                    "end": int(ent.end_char),
+                    "text": ent.text,
+                }
+            )
+        return entities
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        source = inputs.get(ArtifactType.CORRECTED_TEXT) or inputs.get(
+            ArtifactType.RAW_TEXT
+        )
+        if source is None or source.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact texte (RAW_TEXT/CORRECTED_TEXT) manquant."
+            )
+        if context.workspace_uri is None:
+            raise AdapterStepError(f"{self.name} : workspace requis.")
+        text = _read_text(source.uri, self.name)
+        entities = self._extract(text)
+        payload = json.dumps(
+            {"text": text, "entities": entities}, ensure_ascii=False
+        ).encode("utf-8")
+        out_path = workspace_artifact_path(
+            context.workspace_uri, context.document_id, self._label, "entities.json"
+        )
+        out_path.write_bytes(payload)
+        return StepOutput(
+            artifacts={
+                ArtifactType.ENTITIES: Artifact(
+                    id=f"{context.document_id}:{self.name}:entities",
+                    document_id=context.document_id,
+                    type=ArtifactType.ENTITIES,
+                    uri=str(out_path),
+                    content_hash=compute_content_hash(payload),
+                )
+            }
+        )
+
+
+def _read_text(uri: str, name: str) -> str:
+    from pathlib import Path
+
+    try:
+        return Path(uri).read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        raise AdapterStepError(
+            f"{name} : texte d'entrée illisible {uri!r} : {exc}"
+        ) from exc
+
+
+__all__ = ["SpacyNerExtractor"]

cinoc/adapters/ocr/__init__.py

@@ -0,0 +1,8 @@
+"""Modules OCR/HTR (couche 5)."""
+
+from __future__ import annotations
+
+from cinoc.adapters.ocr.precomputed import PrecomputedTextAdapter
+from cinoc.adapters.ocr.tesseract import TesseractAdapter
+
+__all__ = ["PrecomputedTextAdapter", "TesseractAdapter"]

cinoc/adapters/ocr/_base.py

@@ -0,0 +1,64 @@
+"""Squelette commun des adapters OCR « image → un seul RAW_TEXT » (couche 5).
+
+Le même ``execute()`` était recopié dans chaque adapter OCR mono-sortie : sonde
+d'annulation, garde IMAGE, garde workspace, écriture du ``.txt`` dans le workspace,
+construction de l'artefact ``RAW_TEXT`` (id ``{doc}:{name}:raw_text`` + hash du
+texte). On le mutualise ici (miroir de ``llm/_base``) ; le **détail moteur** (params,
+clé API, deadline) reste dans chaque adapter, porté par la closure ``recognize``.
+
+N'est PAS pour les adapters multi-sorties (``tesseract`` : RAW_TEXT + CONFIDENCES
++ ALTO optionnel) — eux gardent leur ``execute()`` propre. Contrat de l'artefact
+``RAW_TEXT`` figé par ``tests/adapters/test_ocr_artifact_contract_anchor``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+
+from cinoc.adapters._workspace import workspace_artifact_path
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+
+def run_image_to_text(
+    *,
+    name: str,
+    label: str,
+    inputs: Mapping[ArtifactType, Artifact],
+    context: RunContext,
+    control: RunControl,
+    recognize: Callable[[str], str],
+) -> StepOutput:
+    """Exécute un OCR image → ``RAW_TEXT`` unique, gardes + persistance mutualisées.
+
+    ``recognize(image_uri) -> texte`` porte la reconnaissance réelle (et ses gardes
+    propres : clé API, modèle…). Ordre identique à l'ancien code par adapter :
+    annulation → IMAGE → workspace → ``recognize`` → écriture ``.txt`` → artefact.
+    """
+    control.raise_if_cancelled()
+    image = inputs.get(ArtifactType.IMAGE)
+    if image is None or image.uri is None:
+        raise AdapterStepError(f"{name} : artefact IMAGE manquant ou sans URI.")
+    if context.workspace_uri is None:
+        raise AdapterStepError(f"{name} : workspace requis.")
+    text = recognize(image.uri)
+    output_path = workspace_artifact_path(
+        context.workspace_uri, context.document_id, label, "txt"
+    )
+    output_path.write_text(text, encoding="utf-8")
+    return StepOutput(
+        artifacts={
+            ArtifactType.RAW_TEXT: Artifact(
+                id=f"{context.document_id}:{name}:raw_text",
+                document_id=context.document_id,
+                type=ArtifactType.RAW_TEXT,
+                uri=str(output_path),
+                content_hash=compute_content_hash(text.encode("utf-8")),
+            )
+        }
+    )
+
+
+__all__ = ["run_image_to_text"]

cinoc/adapters/ocr/azure_di.py

@@ -0,0 +1,223 @@
+"""``AzureDocIntelAdapter`` — OCR cloud (Azure AI Document Intelligence, modèle Read).
+
+Moteur cloud **first-party**. API **REST** (``httpx``) plutôt que le SDK
+``azure-ai-documentintelligence`` (lourd, auth credential) : transport léger,
+**testable par cassette HTTP**. Auth par **clé d'abonnement**
+(``AZURE_DOC_INTEL_KEY``) + endpoint de la ressource (``AZURE_DOC_INTEL_ENDPOINT``).
+Implémente le ``Module`` Protocol **directement** ; ``httpx`` est l'extra
+``cinoc[azure]``, importé **paresseusement** (mockable, CI sans clé ni réseau).
+
+Flux **asynchrone** propre à Azure DI (fidèlement modélisé) : ``POST …:analyze``
+renvoie ``202`` + un en-tête ``Operation-Location`` ; on **sonde** cette URL
+(GET) jusqu'à ``status == "succeeded"`` (ou ``failed``/délai). Sortie :
+``analyzeResult.content`` du modèle ``prebuilt-read`` — le texte complet d'une page.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from base64 import b64encode
+from collections.abc import Callable
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from cinoc.adapters.ocr._base import run_image_to_text
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.deadline import Deadline
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+if TYPE_CHECKING:  # annotations seules — pas d'import httpx au chargement du module
+    import httpx
+
+_VERSION = "1.0"
+_MODEL = "prebuilt-read"
+_API_VERSION = "2024-11-30"
+_ANALYZE_PATH = f"/documentintelligence/documentModels/{_MODEL}:analyze"
+_KEY_HEADER = "Ocp-Apim-Subscription-Key"
+_ENDPOINT_ENV = "AZURE_DOC_INTEL_ENDPOINT"
+_KEY_ENV = "AZURE_DOC_INTEL_KEY"
+#: Borne dure du *polling* (en plus de la ``Deadline``) — évite la boucle infinie
+#: si le service reste indéfiniment ``running`` sous une deadline infinie.
+_MAX_POLLS = 60
+
+
+def _extract_text(data: object) -> str:
+    """Texte complet de ``analyzeResult.content`` ; page vide → ``""``."""
+    if not isinstance(data, dict):
+        raise AdapterStepError("azure_di : réponse JSON inattendue (objet).")
+    result = data.get("analyzeResult")
+    if not isinstance(result, dict):
+        raise AdapterStepError("azure_di : 'analyzeResult' absent de la réponse.")
+    content = result.get("content")
+    return str(content).strip() if content else ""
+
+
+def _invoke_azure_di(
+    *,
+    endpoint: str,
+    image_path: str,
+    deadline: Deadline,
+    key: str,
+    transport: httpx.BaseTransport | None = None,
+    poll_interval: float = 1.0,
+    sleep: Callable[[float], None] = time.sleep,
+) -> str:
+    """Analyse l'image (POST → sonde l'``Operation-Location``) et renvoie le texte.
+
+    ``endpoint`` vient de la **configuration opérateur** (env), pas de
+    l'utilisateur → endpoint de confiance, pas de durcissement anti-SSRF (≠
+    importeurs de corpus). La clé est en **en-tête** (jamais journalisée : les
+    messages d'erreur ne portent que le statut). ``transport``/``sleep`` injectés
+    → cassette **et** sonde déterministes en test (aucune attente réelle).
+    """
+    try:
+        import httpx
+    except ImportError as exc:
+        raise AdapterStepError(
+            "azure_di : httpx non installé (pip install 'cinoc[azure]')."
+        ) from exc
+    content = b64encode(Path(image_path).read_bytes()).decode("ascii")
+    analyze_url = endpoint.rstrip("/") + _ANALYZE_PATH
+    with httpx.Client(
+        timeout=deadline.as_sdk_timeout(), transport=transport
+    ) as client:
+        operation_url = _submit_analysis(
+            client, analyze_url=analyze_url, key=key, content=content
+        )
+        return _poll_result(
+            client,
+            operation_url=operation_url,
+            key=key,
+            deadline=deadline,
+            poll_interval=poll_interval,
+            sleep=sleep,
+        )
+
+
+def _submit_analysis(
+    client: httpx.Client, *, analyze_url: str, key: str, content: str
+) -> str:
+    """POST l'analyse ; renvoie l'URL ``Operation-Location`` à sonder."""
+    import httpx
+
+    headers = {_KEY_HEADER: key, "Content-Type": "application/json"}
+    try:
+        response = client.post(
+            analyze_url,
+            params={"api-version": _API_VERSION},
+            headers=headers,
+            json={"base64Source": content},
+        )
+        response.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        raise AdapterStepError(
+            f"azure_di : statut HTTP {exc.response.status_code} (soumission)."
+        ) from exc
+    except httpx.HTTPError as exc:
+        raise AdapterStepError(
+            f"azure_di : échec de transport (soumission) : {type(exc).__name__}."
+        ) from exc
+    operation_url = response.headers.get("operation-location")
+    if not operation_url:
+        raise AdapterStepError("azure_di : réponse sans en-tête Operation-Location.")
+    return str(operation_url)
+
+
+def _poll_result(
+    client: httpx.Client,
+    *,
+    operation_url: str,
+    key: str,
+    deadline: Deadline,
+    poll_interval: float,
+    sleep: Callable[[float], None],
+) -> str:
+    """Sonde l'``Operation-Location`` jusqu'à un état terminal (ou délai)."""
+    import httpx
+
+    for _ in range(_MAX_POLLS):
+        try:
+            response = client.get(operation_url, headers={_KEY_HEADER: key})
+            response.raise_for_status()
+            data = response.json()
+        except httpx.HTTPStatusError as exc:
+            raise AdapterStepError(
+                f"azure_di : statut HTTP {exc.response.status_code} (sonde)."
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise AdapterStepError(
+                f"azure_di : échec de transport (sonde) : {type(exc).__name__}."
+            ) from exc
+        status = (
+            str(data.get("status", "")).lower() if isinstance(data, dict) else ""
+        )
+        if status == "succeeded":
+            return _extract_text(data)
+        if status == "failed":
+            raise AdapterStepError("azure_di : analyse échouée (status 'failed').")
+        if deadline.is_expired():
+            break
+        sleep(poll_interval)
+    raise AdapterStepError("azure_di : analyse non terminée (délai de sonde dépassé).")
+
+
+class AzureDocIntelAdapter:
+    """OCR cloud Azure DI : ``IMAGE`` → ``RAW_TEXT`` (texte ``prebuilt-read``)."""
+
+    def __init__(self, *, label: str) -> None:
+        if not label or not all(c.isalnum() or c in "_-" for c in label):
+            raise AdapterStepError(f"azure_di : label invalide {label!r}.")
+        self._label = label
+
+    @property
+    def name(self) -> str:
+        return f"azure_di:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        def recognize(image_uri: str) -> str:
+            endpoint = os.environ.get(_ENDPOINT_ENV)
+            key = os.environ.get(_KEY_ENV)
+            if not endpoint:
+                raise AdapterStepError(f"{self.name} : {_ENDPOINT_ENV} manquant.")
+            if not key:
+                raise AdapterStepError(f"{self.name} : {_KEY_ENV} manquante.")
+            return _invoke_azure_di(
+                endpoint=endpoint,
+                image_path=image_uri,
+                deadline=context.deadline,
+                key=key,
+            )
+
+        return run_image_to_text(
+            name=self.name,
+            label=self._label,
+            inputs=inputs,
+            context=context,
+            control=control,
+            recognize=recognize,
+        )
+
+
+__all__ = ["AzureDocIntelAdapter"]

cinoc/adapters/ocr/calamari.py

@@ -0,0 +1,106 @@
+"""``CalamariAdapter`` — moteur OCR réel (calamari-ocr, reconnaissance de lignes).
+
+Local et sans clé. Implémente le ``Module`` Protocol **directement** — même
+contrat que le socle, livré in-tree (pas de discrimination socle/plugin). La lib
+``calamari_ocr`` est un **extra optionnel** (``cinoc[calamari]``), importée
+**paresseusement** dans ``_invoke_calamari`` : importer ce module ne requiert rien ;
+seule l'exécution exige la lib + un **modèle** (``model`` = checkpoint, obligatoire).
+
+Calamari reconnaît une **ligne** par image : utilisé seul sur une page, il traite
+l'image comme une ligne unique ; son usage naturel est en **recognizer par
+région** dans le pipeline de segmentation (fan-out par bloc). Sortie : ``RAW_TEXT``.
+
+**Non déployé au Space** (dép lourde TensorFlow, free-tier) : listé « indisponible »
+sans l'extra, comme Kraken/PERO.
+"""
+
+from __future__ import annotations
+
+from cinoc.adapters.ocr._base import run_image_to_text
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+
+
+def _invoke_calamari(  # pragma: no cover -- lib + modèle requis (cf. 'live')
+    *, image_path: str, model_path: str
+) -> str:
+    """Reconnaissance Calamari de l'image (ligne) → texte prédit."""
+    try:
+        import numpy as np  # type: ignore[import-not-found]
+        from calamari_ocr.ocr.predict.predictor import (  # type: ignore[import-not-found]
+            Predictor,
+            PredictorParams,
+        )
+        from PIL import Image  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "calamari : lib non installée (pip install 'cinoc[calamari]')."
+        ) from exc
+    try:
+        predictor = Predictor.from_checkpoint(
+            params=PredictorParams(), checkpoint=model_path
+        )
+    except (OSError, ValueError, RuntimeError) as exc:  # loader calamari
+        raise AdapterStepError(
+            f"calamari : modèle illisible {model_path!r} : {exc}"
+        ) from exc
+    image = np.array(Image.open(image_path).convert("L"))
+    predictions = predictor.predict_raw([image])
+    texts = [str(prediction.sentence) for prediction in predictions]
+    return " ".join(texts).strip()
+
+
+class CalamariAdapter:
+    """OCR Calamari : ``IMAGE`` → ``RAW_TEXT`` (texte de la ligne reconnue)."""
+
+    def __init__(self, *, label: str, model: str) -> None:
+        if not label or not all(c.isalnum() or c in "_-" for c in label):
+            raise AdapterStepError(f"calamari : label invalide {label!r}.")
+        if not model:
+            raise AdapterStepError(
+                "calamari : paramètre 'model' (checkpoint) requis."
+            )
+        self._label = label
+        self._model = model
+
+    @property
+    def name(self) -> str:
+        return f"calamari:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        return run_image_to_text(
+            name=self.name,
+            label=self._label,
+            inputs=inputs,
+            context=context,
+            control=control,
+            recognize=lambda image_uri: _invoke_calamari(
+                image_path=image_uri, model_path=self._model
+            ),
+        )
+
+
+__all__ = ["CalamariAdapter"]

cinoc/adapters/ocr/google_vision.py

@@ -0,0 +1,157 @@
+"""``GoogleVisionAdapter`` — OCR cloud (Google Cloud Vision REST), facturé à l'image.
+
+Moteur cloud **first-party**. On vise l'**API REST** (``httpx``) plutôt que le SDK
+``google-cloud-vision`` (gRPC + auth ADC service-account, lourd et difficile à
+rejouer) : transport léger, **testable par cassette HTTP**, auth par **clé d'API**
+(``GOOGLE_VISION_API_KEY``). Implémente le ``Module`` Protocol **directement** ;
+``httpx`` est l'extra ``cinoc[google]``, importé **paresseusement** dans
+``_invoke_google_vision`` (mockable, CI sans clé ni réseau).
+
+Sortie : ``fullTextAnnotation.text`` de ``DOCUMENT_TEXT_DETECTION`` — le texte
+dense d'une page (le bon mode pour des documents, ≠ ``TEXT_DETECTION`` épars).
+"""
+
+from __future__ import annotations
+
+import os
+from base64 import b64encode
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from cinoc.adapters.ocr._base import run_image_to_text
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.deadline import Deadline
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+if TYPE_CHECKING:  # annotations seules — pas d'import httpx au chargement du module
+    import httpx
+
+_VERSION = "1.0"
+_ENDPOINT = "https://vision.googleapis.com/v1/images:annotate"
+_API_KEY_ENV = "GOOGLE_VISION_API_KEY"
+_FEATURE = "DOCUMENT_TEXT_DETECTION"
+
+
+def _extract_text(payload: object) -> str:
+    """Texte de la 1ʳᵉ réponse Vision ; erreur par image → ``AdapterStepError``.
+
+    Forme : ``{"responses": [{"fullTextAnnotation": {"text": …}}]}`` (ou
+    ``{"error": {"message": …}}`` pour un échec par image). Aucun texte détecté
+    (page blanche) → ``""`` — un résultat valide, pas une erreur.
+    """
+    if not isinstance(payload, dict):
+        raise AdapterStepError("google_vision : réponse JSON inattendue (objet).")
+    responses = payload.get("responses")
+    if not isinstance(responses, list) or not responses:
+        raise AdapterStepError("google_vision : réponse sans 'responses'.")
+    first = responses[0]
+    if not isinstance(first, dict):
+        raise AdapterStepError("google_vision : 'responses[0]' inattendu.")
+    error = first.get("error")
+    if isinstance(error, dict) and error:
+        message = error.get("message", "erreur sans message")
+        raise AdapterStepError(f"google_vision : erreur API : {message}")
+    annotation = first.get("fullTextAnnotation")
+    if isinstance(annotation, dict):
+        text = annotation.get("text")
+        return str(text).strip() if text else ""
+    return ""
+
+
+def _invoke_google_vision(
+    *,
+    image_path: str,
+    deadline: Deadline,
+    api_key: str,
+    transport: httpx.BaseTransport | None = None,
+) -> str:
+    """POST l'image à Vision et renvoie le texte. ``transport`` injecté → cassette.
+
+    Endpoint **fixe et de confiance** (Google) : pas de durcissement anti-SSRF (≠
+    importeurs de corpus, dont l'URL vient de l'utilisateur). La clé d'API est en
+    *query string* (jamais journalisée : les messages d'erreur ne portent que le
+    statut). ``httpx`` paresseux : importer ce module n'exige pas l'extra.
+    """
+    try:
+        import httpx
+    except ImportError as exc:
+        raise AdapterStepError(
+            "google_vision : httpx non installé (pip install 'cinoc[google]')."
+        ) from exc
+    content = b64encode(Path(image_path).read_bytes()).decode("ascii")
+    body = {
+        "requests": [
+            {"image": {"content": content}, "features": [{"type": _FEATURE}]}
+        ]
+    }
+    try:
+        with httpx.Client(
+            timeout=deadline.as_sdk_timeout(), transport=transport
+        ) as client:
+            response = client.post(_ENDPOINT, params={"key": api_key}, json=body)
+            response.raise_for_status()
+            data = response.json()
+    except httpx.HTTPStatusError as exc:
+        raise AdapterStepError(
+            f"google_vision : statut HTTP {exc.response.status_code}."
+        ) from exc
+    except httpx.HTTPError as exc:
+        raise AdapterStepError(
+            f"google_vision : échec de transport : {type(exc).__name__}."
+        ) from exc
+    return _extract_text(data)
+
+
+class GoogleVisionAdapter:
+    """OCR cloud Google Vision : ``IMAGE`` → ``RAW_TEXT`` (texte dense de la page)."""
+
+    def __init__(self, *, label: str) -> None:
+        if not label or not all(c.isalnum() or c in "_-" for c in label):
+            raise AdapterStepError(f"google_vision : label invalide {label!r}.")
+        self._label = label
+
+    @property
+    def name(self) -> str:
+        return f"google_vision:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        def recognize(image_uri: str) -> str:
+            api_key = os.environ.get(_API_KEY_ENV)
+            if not api_key:
+                raise AdapterStepError(f"{self.name} : {_API_KEY_ENV} manquante.")
+            return _invoke_google_vision(
+                image_path=image_uri, deadline=context.deadline, api_key=api_key
+            )
+
+        return run_image_to_text(
+            name=self.name,
+            label=self._label,
+            inputs=inputs,
+            context=context,
+            control=control,
+            recognize=recognize,
+        )
+
+
+__all__ = ["GoogleVisionAdapter"]

cinoc/adapters/ocr/kraken.py

@@ -0,0 +1,166 @@
+"""``KrakenAdapter`` — moteur HTR réel (kraken, le moteur d'eScriptorium).
+
+Implémente le ``Module`` Protocol directement. Couvre le **manuscrit** (HTR),
+là où tesseract couvre l'imprimé. Le SDK ``kraken`` est un **extra optionnel**
+(``cinoc[kraken]``), importé paresseusement dans ``_invoke_kraken`` — importer
+ce module ne requiert rien ; seule l'exécution exige SDK + **modèle** (.mlmodel,
+paramètre ``model`` obligatoire : pas de modèle par défaut embarqué).
+
+Sorties : ``RAW_TEXT`` (lignes reconnues, ordre de lecture kraken) +
+``CONFIDENCES`` (un jeton par mot, confiance = moyenne des confiances de
+caractères du mot — best-effort, sidecar vide en dégradé).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+
+from cinoc.adapters._workspace import workspace_artifact_path
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.confidence import ConfidenceToken
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+logger = logging.getLogger(__name__)
+
+_VERSION = "1.0"
+
+
+def tokens_from_lines(
+    lines: list[tuple[str, list[float]]],
+) -> list[ConfidenceToken]:
+    """Jetons mot+confiance depuis (texte de ligne, confiances par caractère).
+
+    La confiance d'un mot = moyenne des confiances de ses caractères (bornée
+    [0,1]) ; un mot sans couverture de confiance est ignoré.
+    """
+    tokens: list[ConfidenceToken] = []
+    for text, confidences in lines:
+        cursor = 0
+        for word in text.split():
+            start = text.find(word, cursor)
+            if start < 0:
+                continue
+            cursor = start + len(word)
+            window = confidences[start : start + len(word)]
+            if not window:
+                continue
+            value = max(0.0, min(sum(window) / len(window), 1.0))
+            tokens.append(ConfidenceToken(text=word, confidence=value))
+    return tokens
+
+
+def _invoke_kraken(  # pragma: no cover -- SDK + modèle requis (cf. 'live')
+    *, image_path: str, model_path: str
+) -> list[tuple[str, list[float]]]:
+    """Segmentation + reconnaissance kraken → (texte, confiances/char) par ligne."""
+    try:
+        from kraken import (  # type: ignore[import-not-found]
+            binarization,
+            pageseg,
+            rpred,
+        )
+        from kraken.lib import models  # type: ignore[import-not-found]
+        from PIL import Image  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "kraken : SDK non installé (pip install 'cinoc[kraken]')."
+        ) from exc
+    try:
+        model = models.load_any(model_path)
+    except (OSError, ValueError, RuntimeError) as exc:  # loader kraken
+        raise AdapterStepError(
+            f"kraken : modèle illisible {model_path!r} : {exc}"
+        ) from exc
+    image = Image.open(image_path)
+    binarized = binarization.nlbin(image)
+    segmentation = pageseg.segment(binarized)
+    out: list[tuple[str, list[float]]] = []
+    for record in rpred.rpred(model, binarized, segmentation):
+        out.append((str(record), [float(c) for c in record.confidences]))
+    return out
+
+
+class KrakenAdapter:
+    """HTR kraken : ``IMAGE`` → ``RAW_TEXT`` + ``CONFIDENCES``."""
+
+    def __init__(self, *, label: str, model: str) -> None:
+        if not label or not all(c.isalnum() or c in "_-" for c in label):
+            raise AdapterStepError(f"kraken : label invalide {label!r}.")
+        if not model:
+            raise AdapterStepError(
+                "kraken : paramètre 'model' (chemin .mlmodel) requis."
+            )
+        self._label = label
+        self._model = model
+
+    @property
+    def name(self) -> str:
+        return f"kraken:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT, ArtifactType.CONFIDENCES})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        image = inputs.get(ArtifactType.IMAGE)
+        if image is None or image.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact IMAGE manquant ou sans URI."
+            )
+        if context.workspace_uri is None:
+            raise AdapterStepError(f"{self.name} : workspace requis.")
+        lines = _invoke_kraken(image_path=image.uri, model_path=self._model)
+        text = "\n".join(line for line, _ in lines)
+        tokens = tokens_from_lines(lines)
+        text_path = workspace_artifact_path(
+            context.workspace_uri, context.document_id, self._label, "txt"
+        )
+        text_path.write_text(text, encoding="utf-8")
+        sidecar = json.dumps(
+            [token.model_dump() for token in tokens], ensure_ascii=False
+        ).encode("utf-8")
+        sidecar_path = workspace_artifact_path(
+            context.workspace_uri, context.document_id, self._label,
+            "confidences.json",
+        )
+        sidecar_path.write_bytes(sidecar)
+        return StepOutput(
+            artifacts={
+                ArtifactType.RAW_TEXT: Artifact(
+                    id=f"{context.document_id}:{self.name}:raw_text",
+                    document_id=context.document_id,
+                    type=ArtifactType.RAW_TEXT,
+                    uri=str(text_path),
+                    content_hash=compute_content_hash(text.encode("utf-8")),
+                ),
+                ArtifactType.CONFIDENCES: Artifact(
+                    id=f"{context.document_id}:{self.name}:confidences",
+                    document_id=context.document_id,
+                    type=ArtifactType.CONFIDENCES,
+                    uri=str(sidecar_path),
+                    content_hash=compute_content_hash(sidecar),
+                ),
+            }
+        )
+
+
+__all__ = ["KrakenAdapter", "tokens_from_lines"]

cinoc/adapters/ocr/mistral_ocr.py

@@ -0,0 +1,113 @@
+"""``MistralOCRAdapter`` — OCR cloud (API Mistral OCR), facturé à la page.
+
+Premier moteur **payant à la page** du socle : donne un sens réel à l'axe
+coût du Pareto (économie T10, tarif ``cloud_page_kinds``). Implémente le
+``Module`` Protocol ; SDK ``mistralai`` = extra (``cinoc[mistral]``), importé
+paresseusement dans ``_invoke_mistral_ocr`` (mockable, CI sans clé ni réseau).
+Clé ``MISTRAL_API_KEY``. Sortie : le texte (markdown) des pages, concaténé.
+"""
+
+from __future__ import annotations
+
+from base64 import b64encode
+from pathlib import Path
+
+from cinoc.adapters.ocr._base import run_image_to_text
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.deadline import Deadline
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+_DEFAULT_MODEL = "mistral-ocr-latest"
+_MEDIA = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+          ".webp": "image/webp", ".tif": "image/tiff", ".tiff": "image/tiff"}
+
+
+def _invoke_mistral_ocr(  # pragma: no cover -- réseau + clé API (cf. 'live')
+    *, model: str, image_path: str, deadline: Deadline
+) -> str:
+    import os
+
+    api_key = os.environ.get("MISTRAL_API_KEY")
+    if not api_key:
+        raise AdapterStepError("mistral_ocr : MISTRAL_API_KEY manquante.")
+    try:
+        from mistralai import Mistral  # type: ignore[import-not-found]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "mistral_ocr : SDK non installé (pip install 'cinoc[mistral]')."
+        ) from exc
+    path = Path(image_path)
+    media = _MEDIA.get(path.suffix.lower(), "image/png")
+    image_b64 = b64encode(path.read_bytes()).decode("ascii")
+    client_kwargs: dict[str, object] = {"api_key": api_key}
+    timeout = deadline.as_sdk_timeout()
+    if timeout is not None:
+        client_kwargs["timeout_ms"] = int(timeout * 1000)
+    try:
+        client = Mistral(**client_kwargs)  # type: ignore[arg-type]
+        response = client.ocr.process(
+            model=model,
+            document={
+                "type": "image_url",
+                "image_url": f"data:{media};base64,{image_b64}",
+            },
+        )
+    except Exception as exc:  # le SDK lève des erreurs HTTP/SDK variées
+        raise AdapterStepError(
+            f"mistral_ocr a échoué ({model}) : {type(exc).__name__}: {exc}"
+        ) from exc
+    pages = getattr(response, "pages", None) or []
+    return "\n\n".join(
+        str(getattr(page, "markdown", "") or "") for page in pages
+    ).strip()
+
+
+class MistralOCRAdapter:
+    """OCR cloud Mistral : ``IMAGE`` → ``RAW_TEXT`` (markdown des pages)."""
+
+    def __init__(self, *, label: str, model: str = _DEFAULT_MODEL) -> None:
+        if not label or not all(c.isalnum() or c in "_-" for c in label):
+            raise AdapterStepError(f"mistral_ocr : label invalide {label!r}.")
+        self._label = label
+        self._model = model
+
+    @property
+    def name(self) -> str:
+        return f"mistral_ocr:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        return run_image_to_text(
+            name=self.name,
+            label=self._label,
+            inputs=inputs,
+            context=context,
+            control=control,
+            recognize=lambda image_uri: _invoke_mistral_ocr(
+                model=self._model, image_path=image_uri, deadline=context.deadline
+            ),
+        )
+
+
+__all__ = ["MistralOCRAdapter"]

cinoc/adapters/ocr/pero.py

@@ -0,0 +1,114 @@
+"""``PeroAdapter`` — moteur OCR/HTR réel (pero-ocr).
+
+Local et sans clé : couvre l'imprimé ancien et le manuscrit via les modèles PERO,
+là où tesseract couvre l'imprimé moderne. Implémente le ``Module`` Protocol
+**directement** — même contrat que le socle, livré in-tree (décision : pas de
+discrimination socle/plugin ; seule la livraison diffère). La lib ``pero_ocr`` est
+un **extra optionnel** (``cinoc[pero]``), importée **paresseusement** dans
+``_invoke_pero`` : importer ce module ne requiert rien ; seule l'exécution exige la
+lib + un **modèle** (``model`` = chemin du fichier de config PERO, obligatoire —
+pas de modèle embarqué). Sortie : ``RAW_TEXT`` (lignes reconnues, ordre PERO).
+
+**Non déployé au Space** (dép lourde, free-tier) : listé « indisponible » sans
+l'extra, comme Kraken — pas d'exécution cloud, pas de clé.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cinoc.adapters.ocr._base import run_image_to_text
+from cinoc.domain.artifacts import Artifact, ArtifactType
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+
+
+def _invoke_pero(  # pragma: no cover -- lib + modèle requis (cf. 'live')
+    *, image_path: str, config_path: str
+) -> str:
+    """Mise en page + reconnaissance PERO → texte (lignes jointes, ordre PERO)."""
+    try:
+        import configparser
+
+        import cv2  # type: ignore[import-not-found]
+        from pero_ocr.document_ocr.layout import (  # type: ignore[import-not-found]
+            PageLayout,
+        )
+        from pero_ocr.document_ocr.page_parser import (  # type: ignore[import-not-found]
+            PageParser,
+        )
+    except ImportError as exc:
+        raise AdapterStepError(
+            "pero : lib non installée (pip install 'cinoc[pero]')."
+        ) from exc
+    config = configparser.ConfigParser()
+    if not config.read(config_path):
+        raise AdapterStepError(f"pero : config illisible {config_path!r}.")
+    image = cv2.imread(image_path)
+    if image is None:
+        raise AdapterStepError(f"pero : image illisible {image_path!r}.")
+    parser = PageParser(config, config_path=str(Path(config_path).parent))
+    layout = PageLayout(id="page", page_size=(image.shape[0], image.shape[1]))
+    layout = parser.process_page(image, layout)
+    lines = [
+        str(line.transcription)
+        for region in layout.regions
+        for line in region.lines
+        if line.transcription
+    ]
+    return "\n".join(lines).strip()
+
+
+class PeroAdapter:
+    """OCR/HTR PERO : ``IMAGE`` → ``RAW_TEXT`` (lignes reconnues)."""
+
+    def __init__(self, *, label: str, model: str) -> None:
+        if not label or not all(c.isalnum() or c in "_-" for c in label):
+            raise AdapterStepError(f"pero : label invalide {label!r}.")
+        if not model:
+            raise AdapterStepError(
+                "pero : paramètre 'model' (chemin de config PERO) requis."
+            )
+        self._label = label
+        self._model = model
+
+    @property
+    def name(self) -> str:
+        return f"pero:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        return run_image_to_text(
+            name=self.name,
+            label=self._label,
+            inputs=inputs,
+            context=context,
+            control=control,
+            recognize=lambda image_uri: _invoke_pero(
+                image_path=image_uri, config_path=self._model
+            ),
+        )
+
+
+__all__ = ["PeroAdapter"]

cinoc/adapters/ocr/precomputed.py

@@ -0,0 +1,91 @@
+"""``PrecomputedTextAdapter`` — rejoue un texte OCR pré-calculé depuis le disque.
+
+Module à **zéro dépendance et zéro réseau** : il lit ``<stem>.<source_label>.txt``
+à côté de l'image et renvoie un ``RAW_TEXT``. Brique du *starter pack* — il fait
+tourner le squelette ambulant (``cinoc demo``) et les tests déterministes sans
+moteur réel. Implémente le ``Module`` Protocol (couche 4) **directement**.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+_VERSION = "1.0"
+
+
+class PrecomputedTextAdapter:
+    """Lit un texte OCR pré-calculé (``<stem>.<label>.txt`` près de l'image)."""
+
+    def __init__(self, *, source_label: str) -> None:
+        if not source_label or not all(
+            c.isalnum() or c in "_-" for c in source_label
+        ):
+            raise AdapterStepError(
+                f"PrecomputedTextAdapter : source_label invalide "
+                f"{source_label!r} (alphanumérique + _ - uniquement)."
+            )
+        self._label = source_label
+
+    @property
+    def name(self) -> str:
+        return f"precomputed:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.RAW_TEXT})
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        image = inputs.get(ArtifactType.IMAGE)
+        if image is None or image.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact IMAGE manquant ou sans URI."
+            )
+        image_path = Path(image.uri)
+        text_path = image_path.parent / f"{image_path.stem}.{self._label}.txt"
+        if not text_path.is_file():
+            raise AdapterStepError(
+                f"{self.name} : texte pré-calculé introuvable — "
+                f"{text_path.name!r} attendu près de {image_path.name!r}."
+            )
+        data = text_path.read_bytes()
+        try:
+            data.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise AdapterStepError(
+                f"{self.name} : {text_path.name!r} n'est pas en UTF-8 : {exc}"
+            ) from exc
+        return StepOutput(
+            artifacts={
+                ArtifactType.RAW_TEXT: Artifact(
+                    id=f"{context.document_id}:{self.name}:raw_text",
+                    document_id=context.document_id,
+                    type=ArtifactType.RAW_TEXT,
+                    uri=str(text_path),
+                    content_hash=compute_content_hash(data),
+                )
+            }
+        )
+
+
+__all__ = ["PrecomputedTextAdapter"]

cinoc/adapters/ocr/tesseract.py

@@ -0,0 +1,332 @@
+"""``TesseractAdapter`` — moteur OCR réel (Tesseract 5 via ``pytesseract``).
+
+Implémente le ``Module`` Protocol (couche 4) **directement**. L'OCR a lieu dans
+le binaire C ``tesseract`` lancé en sous-processus (le thread relâche le GIL).
+``pytesseract`` est un **extra optionnel** (``cinoc[tesseract]``), importé
+**paresseusement** dans ``_invoke_tesseract`` : importer ce module ne requiert ni
+la lib ni le binaire — seule l'exécution les exige.
+
+Sécurité : ``lang`` est validé (anti-injection ligne de commande) ; ``timeout``
+est borné par la ``Deadline`` (un sous-processus figé ne doit pas geler le run).
+Les **confidences** par mot (TSV natif, 0-100 → [0,1]) sont écrites en
+sidecar JSON (``ConfidenceToken``) et publiées comme artefact ``CONFIDENCES``
+— best-effort : un échec d'extraction dégrade en sidecar vide, jamais en
+panne de l'OCR.
+
+**ALTO natif** (``alto=True``) : Tesseract émet en plus un artefact
+``ALTO_XML`` (géométrie + texte par mot, ``image_to_alto_xml``) — la forme
+ré-importable dans un outil de relecture (eScriptorium, Transkribus). Contrairement
+aux confidences, l'ALTO est ici le **livrable demandé** : un échec d'émission lève
+(``AdapterStepError``), il ne dégrade pas en silence.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import subprocess
+from collections.abc import Callable
+
+from cinoc.adapters._workspace import workspace_artifact_path
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.confidence import ConfidenceToken
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+logger = logging.getLogger(__name__)
+
+_VERSION = "1.0"
+_DEFAULT_TIMEOUT = 120.0
+
+#: Codes langue Tesseract : ISO 639-3 (≥3 lettres ASCII), combinables par ``+``
+#: (``fra+lat``). ``lang`` finit sur la ligne de commande tesseract → on refuse
+#: tout caractère interprétable comme flag/séparateur (anti-injection).
+_LANG_RE = re.compile(r"^[a-zA-Z]{3,}(?:\+[a-zA-Z]{3,})*$")
+
+#: Lanceur de sous-processus, injectable → version sondable en test sans binaire.
+BinaryRunner = Callable[..., "subprocess.CompletedProcess[str]"]
+
+
+def tesseract_binary_version(*, run: BinaryRunner = subprocess.run) -> str | None:
+    """Version du binaire ``tesseract`` (1ʳᵉ ligne de ``tesseract --version``).
+
+    **Best-effort, jamais bloquant** : binaire absent, timeout, ou sortie illisible
+    → ``None`` (jamais une panne). Sert la **reproductibilité** (``RunManifest`` §12) :
+    deux runs ne sont comparables qu'à version de binaire égale — la version
+    d'*adapter* (``_VERSION``) ne dit rien du Tesseract réellement installé.
+    ``run`` est injecté → la sonde est déterministe en test, sans le binaire.
+
+    Tesseract émet sa bannière tantôt sur ``stdout`` tantôt sur ``stderr`` selon le
+    build → on lit les deux et garde la 1ʳᵉ ligne non vide (ex. ``tesseract 5.3.0``).
+    """
+    try:
+        completed = run(
+            ["tesseract", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    lines = ((completed.stdout or "") + "\n" + (completed.stderr or "")).splitlines()
+    for line in lines:
+        if line.strip():
+            return line.strip()
+    return None
+
+
+def _invoke_tesseract(  # pragma: no cover -- binaire requis (cf. marqueur 'live')
+    *, image_path: str, lang: str, psm: int, oem: int, timeout: float
+) -> str:
+    """Lance tesseract et renvoie le texte. **Isolé → mockable** (CI sans binaire)."""
+    try:
+        import pytesseract  # type: ignore[import-not-found, import-untyped]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "tesseract : pytesseract non installé "
+            "(pip install 'cinoc[tesseract]' + binaire tesseract)."
+        ) from exc
+    config = f"--oem {oem} --psm {psm}"
+    try:
+        text = pytesseract.image_to_string(
+            image_path, lang=lang, config=config, timeout=timeout
+        )
+    except (
+        pytesseract.TesseractNotFoundError,
+        pytesseract.TesseractError,
+        RuntimeError,
+    ) as exc:
+        raise AdapterStepError(
+            f"tesseract a échoué sur {image_path!r} : {type(exc).__name__}: {exc}"
+        ) from exc
+    return str(text).strip()
+
+
+def _invoke_tesseract_alto(  # pragma: no cover -- binaire requis ('live')
+    *, image_path: str, lang: str, psm: int, oem: int, timeout: float
+) -> bytes:
+    """ALTO XML natif via ``image_to_alto_xml`` (géométrie + texte par mot).
+
+    Renvoie les octets XML bruts (déjà conformes ALTO) — destinés à la
+    ré-importation dans un outil de relecture. Une panne du binaire lève
+    ``AdapterStepError`` : l'ALTO est le livrable demandé, pas un extra dégradable.
+    """
+    try:
+        import pytesseract  # type: ignore[import-not-found, import-untyped]
+    except ImportError as exc:
+        raise AdapterStepError(
+            "tesseract : pytesseract non installé "
+            "(pip install 'cinoc[tesseract]' + binaire tesseract)."
+        ) from exc
+    try:
+        xml = pytesseract.image_to_alto_xml(
+            image_path, lang=lang, config=f"--oem {oem} --psm {psm}", timeout=timeout
+        )
+    except (
+        pytesseract.TesseractNotFoundError,
+        pytesseract.TesseractError,
+        RuntimeError,
+    ) as exc:
+        raise AdapterStepError(
+            f"tesseract ALTO a échoué sur {image_path!r} : "
+            f"{type(exc).__name__}: {exc}"
+        ) from exc
+    return bytes(xml)
+
+
+def _invoke_tesseract_confidences(  # pragma: no cover -- binaire requis ('live')
+    *, image_path: str, lang: str, psm: int, oem: int, timeout: float
+) -> list[ConfidenceToken]:
+    """Confidences par mot via ``image_to_data`` (TSV natif, conf 0-100)."""
+    import pytesseract  # type: ignore[import-not-found]
+
+    data = pytesseract.image_to_data(
+        image_path,
+        lang=lang,
+        config=f"--psm {psm} --oem {oem}",
+        timeout=timeout,
+        output_type=pytesseract.Output.DICT,
+    )
+    tokens: list[ConfidenceToken] = []
+    for word, conf in zip(data["text"], data["conf"], strict=False):
+        if not isinstance(word, str) or not word.strip():
+            continue
+        value = float(conf)
+        if value < 0:  # -1 : entrée non textuelle du TSV
+            continue
+        tokens.append(
+            ConfidenceToken(text=word.strip(), confidence=min(value / 100.0, 1.0))
+        )
+    return tokens
+
+
+class TesseractAdapter:
+    """OCR Tesseract 5 ; écrit le texte dans le workspace, renvoie un ``RAW_TEXT``."""
+
+    def __init__(
+        self,
+        *,
+        label: str,
+        lang: str = "fra",
+        psm: int = 6,
+        oem: int = 3,
+        alto: bool = False,
+    ) -> None:
+        if not label or not all(c.isalnum() or c in "_-" for c in label):
+            raise AdapterStepError(
+                f"TesseractAdapter : label invalide {label!r} "
+                "(alphanumérique + _ - uniquement)."
+            )
+        if not _LANG_RE.fullmatch(lang):
+            raise AdapterStepError(
+                f"TesseractAdapter : lang invalide {lang!r} "
+                "(ISO 639-3, combinable par '+' : ex. 'fra+lat')."
+            )
+        if not 0 <= psm <= 13:
+            raise AdapterStepError(f"TesseractAdapter : psm ∈ [0, 13], reçu {psm}.")
+        if not 0 <= oem <= 3:
+            raise AdapterStepError(f"TesseractAdapter : oem ∈ [0, 3], reçu {oem}.")
+        self._label = label
+        self._lang = lang
+        self._psm = psm
+        self._oem = oem
+        #: Émet en plus un artefact ``ALTO_XML`` (ré-import eScriptorium/Transkribus).
+        self._alto = alto
+
+    @property
+    def name(self) -> str:
+        return f"tesseract:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    def system_binaries(self) -> dict[str, str]:
+        """Version du **binaire externe** pour le ``RunManifest`` (reproductibilité).
+
+        Hook de **provenance optionnel** (hors ``Module`` Protocol, qui reste le
+        contrat d'exécution unique) : l'orchestrateur l'appelle par *duck-typing*
+        sur les modules qui l'exposent et fusionne le résultat dans
+        ``system_binaries_lock``. Best-effort : binaire absent → ``{}``.
+        """
+        version = tesseract_binary_version()
+        return {"tesseract": version} if version is not None else {}
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        types = {ArtifactType.RAW_TEXT, ArtifactType.CONFIDENCES}
+        if self._alto:
+            types.add(ArtifactType.ALTO_XML)
+        return frozenset(types)
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        image = inputs.get(ArtifactType.IMAGE)
+        if image is None or image.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact IMAGE manquant ou sans URI."
+            )
+        if context.workspace_uri is None:
+            raise AdapterStepError(
+                f"{self.name} : workspace requis (RunContext.workspace_uri)."
+            )
+        timeout = max(0.001, context.deadline.clamp_to_remaining(_DEFAULT_TIMEOUT))
+        text = _invoke_tesseract(
+            image_path=image.uri,
+            lang=self._lang,
+            psm=self._psm,
+            oem=self._oem,
+            timeout=timeout,
+        )
+        output_path = workspace_artifact_path(
+            context.workspace_uri, context.document_id, self._label, "txt"
+        )
+        output_path.write_text(text, encoding="utf-8")
+        # Confidences best-effort : un échec d'extraction ne doit pas faire
+        # échouer un OCR réussi — sidecar vide + avertissement.
+        try:
+            tokens = _invoke_tesseract_confidences(
+                image_path=image.uri,
+                lang=self._lang,
+                psm=self._psm,
+                oem=self._oem,
+                timeout=timeout,
+            )
+        except (
+            AdapterStepError,
+            ImportError,
+            RuntimeError,
+            ValueError,
+            OSError,
+        ) as exc:
+            logger.warning(
+                "[tesseract] confidences dégradées (sidecar vide) : %s", exc
+            )
+            tokens = []
+        sidecar = json.dumps(
+            [token.model_dump() for token in tokens], ensure_ascii=False
+        ).encode("utf-8")
+        sidecar_path = workspace_artifact_path(
+            context.workspace_uri,
+            context.document_id,
+            self._label,
+            "confidences.json",
+        )
+        sidecar_path.write_bytes(sidecar)
+        artifacts: dict[ArtifactType, Artifact] = {
+            ArtifactType.RAW_TEXT: Artifact(
+                id=f"{context.document_id}:{self.name}:raw_text",
+                document_id=context.document_id,
+                type=ArtifactType.RAW_TEXT,
+                uri=str(output_path),
+                content_hash=compute_content_hash(text.encode("utf-8")),
+            ),
+            ArtifactType.CONFIDENCES: Artifact(
+                id=f"{context.document_id}:{self.name}:confidences",
+                document_id=context.document_id,
+                type=ArtifactType.CONFIDENCES,
+                uri=str(sidecar_path),
+                content_hash=compute_content_hash(sidecar),
+            ),
+        }
+        if self._alto:
+            # ALTO demandé → livrable : un échec lève (≠ confidences best-effort).
+            alto_bytes = _invoke_tesseract_alto(
+                image_path=image.uri,
+                lang=self._lang,
+                psm=self._psm,
+                oem=self._oem,
+                timeout=timeout,
+            )
+            alto_path = workspace_artifact_path(
+                context.workspace_uri,
+                context.document_id,
+                self._label,
+                "alto.xml",
+            )
+            alto_path.write_bytes(alto_bytes)
+            artifacts[ArtifactType.ALTO_XML] = Artifact(
+                id=f"{context.document_id}:{self.name}:alto_xml",
+                document_id=context.document_id,
+                type=ArtifactType.ALTO_XML,
+                uri=str(alto_path),
+                content_hash=compute_content_hash(alto_bytes),
+            )
+        return StepOutput(artifacts=artifacts)
+
+
+__all__ = ["TesseractAdapter", "tesseract_binary_version"]

cinoc/adapters/preprocess/__init__.py

@@ -0,0 +1,5 @@
+"""Prétraitement d'image (couche 5) : ``IMAGE → IMAGE``."""
+
+from cinoc.adapters.preprocess.image_prep import ImagePreprocessor
+
+__all__ = ["ImagePreprocessor"]

cinoc/adapters/preprocess/_ops.py

@@ -0,0 +1,115 @@
+"""Opérations de prétraitement — **numpy pur**, sans décodage d'image.
+
+Séparées de l'adapter pour qu'elles se testent sur des matrices construites à la
+main, sans Pillow et sans fichier. C'est la même discipline que les métriques :
+les maths d'un côté, l'entrée/sortie de l'autre.
+
+**Aucun seuil arbitraire.** C'est une contrainte de conception, pas un hasard :
+une mesure de qualité d'image a été retirée de ce dépôt précisément parce que son
+score composite reposait sur des constantes non validées (D-190). Ici, le seuil
+de binarisation est **calculé sur l'image** (Otsu maximise la variance
+inter-classes), et l'angle de redressement est **cherché**, pas postulé. Les deux
+seules constantes sont des **bornes de recherche** — l'amplitude et le pas —, qui
+ne décident de rien : elles disent seulement où l'on cherche.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def to_grayscale(image: np.ndarray) -> np.ndarray:
+    """RVB → niveaux de gris (luminance ITU-R BT.601), en ``uint8``.
+
+    Déjà en gris (2 dimensions) → renvoyé tel quel : l'opération est idempotente,
+    ce qui permet de la chaîner sans y penser.
+    """
+    if image.ndim == 2:
+        return image.astype(np.uint8, copy=False)
+    poids = np.array([0.299, 0.587, 0.114], dtype=np.float64)
+    gris = image[..., :3].astype(np.float64) @ poids
+    return np.clip(np.rint(gris), 0, 255).astype(np.uint8)
+
+
+def otsu_threshold(gray: np.ndarray) -> int:
+    """Seuil d'Otsu : celui qui **maximise la variance inter-classes**.
+
+    Calculé sur l'histogramme de l'image, donc propre à elle : deux pages
+    différemment exposées reçoivent deux seuils différents, ce qu'une constante
+    ne saurait pas faire. Image uniforme → renvoie sa valeur (aucune séparation
+    n'a de sens, et un seuil médian inventerait du contraste).
+    """
+    histogramme = np.bincount(gray.reshape(-1), minlength=256).astype(np.float64)
+    total = histogramme.sum()
+    if total == 0:
+        return 0
+    niveaux = np.arange(256, dtype=np.float64)
+    poids_bas = np.cumsum(histogramme)
+    poids_haut = total - poids_bas
+    somme_totale = float(niveaux @ histogramme)
+    somme_bas = np.cumsum(niveaux * histogramme)
+    # Classes vides → variance nulle : on les écarte au lieu de diviser par zéro.
+    valide = (poids_bas > 0) & (poids_haut > 0)
+    if not valide.any():
+        return int(gray.reshape(-1)[0])
+    moy_bas = np.divide(somme_bas, poids_bas, out=np.zeros(256), where=valide)
+    moy_haut = np.divide(
+        somme_totale - somme_bas, poids_haut, out=np.zeros(256), where=valide
+    )
+    inter = poids_bas * poids_haut * (moy_bas - moy_haut) ** 2
+    inter[~valide] = -1.0
+    return int(np.argmax(inter))
+
+
+def binarize(gray: np.ndarray, threshold: int) -> np.ndarray:
+    """Gris → noir et blanc (0 / 255) au seuil donné. Encre = sombre = 0."""
+    return np.where(gray > threshold, np.uint8(255), np.uint8(0))
+
+
+def estimate_skew(
+    gray: np.ndarray, *, amplitude_deg: float = 5.0, pas_deg: float = 0.5
+) -> float:
+    """Angle d'inclinaison, en degrés, par profil de projection.
+
+    Une page droite a des lignes de texte horizontales : la somme de l'encre par
+    rangée y est donc très **contrastée** — des pics sur le texte, des creux
+    entre les lignes. Incliner la page lisse ce profil. On cherche l'angle qui
+    maximise la variance du profil : c'est celui qui remet les lignes à plat.
+
+    **L'accumulateur a une hauteur fixe**, dimensionnée pour l'angle maximal, et
+    rien n'y est écrêté. C'est la seule façon de comparer des angles entre eux :
+    une première version rabattait les rangées hors cadre sur la première et la
+    dernière, ce qui y empilait de l'encre et gonflait la variance d'autant plus
+    que l'angle était grand. Le maximum tombait alors **toujours** sur la borne
+    de recherche — y compris pour une page parfaitement droite.
+
+    ``amplitude_deg`` et ``pas_deg`` bornent la recherche, ils ne la décident
+    pas. Amplitude volontairement modeste : au-delà, ce n'est plus une
+    inclinaison de numérisation mais une page tournée, qui relève d'une autre
+    opération. Image trop petite → ``0.0`` : rien à mesurer, et on ne devine pas.
+    """
+    if gray.ndim != 2 or min(gray.shape) < 16:
+        return 0.0
+    encre = 255.0 - gray.astype(np.float64)
+    hauteur, largeur = encre.shape
+    pas = max(pas_deg, 0.01)
+    marge = int(np.ceil(np.tan(np.radians(amplitude_deg)) * largeur)) + 1
+    etendue = hauteur + 2 * marge
+    lignes = np.arange(hauteur, dtype=np.float64)[:, None]
+    colonnes = np.arange(largeur, dtype=np.float64)[None, :]
+    meilleur_angle, meilleure_variance = 0.0, -1.0
+    for k in range(-int(amplitude_deg / pas), int(amplitude_deg / pas) + 1):
+        angle = k * pas
+        # Cisaillement vertical : approxime la rotation pour de petits angles,
+        # sans ré-échantillonner l'image — donc sans en inventer les pixels.
+        decal = np.tan(np.radians(angle)) * colonnes
+        rangs = np.rint(lignes + decal).astype(np.int64) + marge
+        profil = np.zeros(etendue, dtype=np.float64)
+        np.add.at(profil, rangs.ravel(), encre.ravel())
+        variance = float(profil.var())
+        if variance > meilleure_variance:
+            meilleure_variance, meilleur_angle = variance, angle
+    return meilleur_angle
+
+
+__all__ = ["binarize", "estimate_skew", "otsu_threshold", "to_grayscale"]

cinoc/adapters/preprocess/image_prep.py

@@ -0,0 +1,214 @@
+"""``ImagePreprocessor`` — ``IMAGE → IMAGE`` (couche 5).
+
+Le banc savait lire une image, la segmenter, la transcrire, la corriger. Il ne
+savait pas la **préparer** — alors que tous les systèmes de référence ont cet
+étage : OCR-D en fait une famille entière (binarisation, rognage, débruitage,
+redressement, dé-gondolage), PP-Structure ouvre par un module d'orientation et
+de rectification, et NDNP le pratique avant Tesseract.
+
+Sans ce rôle, une question restait sans réponse mesurable : **restaurer avant de
+lire, est-ce que ça paie ?** Un banc ne doit pas y répondre par un score de
+qualité arbitraire — c'est ce qui a fait retirer la mesure de qualité d'image de
+ce dépôt (D-190) — mais en comparant deux pipelines sur le seul critère qui
+tranche, le taux d'erreur.
+
+Le pool d'artefacts étant indexé par type, l'``IMAGE`` produite **remplace**
+l'originale pour les étapes suivantes : c'est le comportement voulu. Une étape
+qui tiendrait à l'image d'origine la nomme explicitement dans son ``inputs_from``.
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from cinoc.adapters._workspace import workspace_artifact_path
+from cinoc.adapters.preprocess._ops import (
+    binarize,
+    estimate_skew,
+    otsu_threshold,
+    to_grayscale,
+)
+from cinoc.domain.artifacts import Artifact, ArtifactType, compute_content_hash
+from cinoc.domain.errors import AdapterStepError
+from cinoc.pipeline.protocols import ParamValue
+from cinoc.pipeline.run_control import RunControl
+from cinoc.pipeline.types import RunContext, StepOutput
+
+logger = logging.getLogger(__name__)
+
+_VERSION = "1.0"
+
+#: Opérations disponibles, dans l'ordre où elles ont un sens : on redresse avant
+#: de binariser (une binarisation fige les pixels, une rotation les ré-interpole).
+OPERATIONS: tuple[str, ...] = ("grayscale", "deskew", "binarize")
+
+
+class ImagePreprocessor:
+    """Prépare une image avant lecture. Déterministe, local, sans modèle.
+
+    ``operations`` est une liste **séparée par des virgules** — les paramètres
+    d'adapter sont plats par contrat, et une liste imbriquée n'y entrerait pas.
+    L'ordre déclaré est respecté tel quel : c'est un choix de l'utilisateur, et
+    deux ordres différents sont deux pipelines différents à comparer.
+    """
+
+    def __init__(
+        self,
+        *,
+        label: str,
+        operations: str = "deskew,binarize",
+        skew_amplitude_deg: float = 5.0,
+    ) -> None:
+        self._label = label
+        self._skew = skew_amplitude_deg
+        demandees = [o.strip() for o in operations.split(",") if o.strip()]
+        inconnues = [o for o in demandees if o not in OPERATIONS]
+        if inconnues:
+            raise AdapterStepError(
+                f"preprocess : opération(s) inconnue(s) {inconnues} "
+                f"(attendu parmi {list(OPERATIONS)})."
+            )
+        if not demandees:
+            raise AdapterStepError(
+                "preprocess : aucune opération demandée — une étape qui ne fait "
+                "rien fausserait la comparaison en se faisant passer pour un "
+                "traitement."
+            )
+        self._operations = tuple(demandees)
+
+    @property
+    def name(self) -> str:
+        return f"preprocess:{self._label}"
+
+    @property
+    def version(self) -> str:
+        return _VERSION
+
+    @property
+    def input_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def output_types(self) -> frozenset[ArtifactType]:
+        return frozenset({ArtifactType.IMAGE})
+
+    @property
+    def operations(self) -> tuple[str, ...]:
+        return self._operations
+
+    def execute(
+        self,
+        inputs: dict[ArtifactType, Artifact],
+        params: dict[str, ParamValue],  # noqa: ARG002 — contrat Module
+        context: RunContext,
+        control: RunControl,
+    ) -> StepOutput:
+        control.raise_if_cancelled()
+        image = inputs.get(ArtifactType.IMAGE)
+        if image is None or image.uri is None:
+            raise AdapterStepError(
+                f"{self.name} : artefact IMAGE manquant ou sans URI."
+            )
+        source = Path(image.uri)
+        if not source.is_file():
+            raise AdapterStepError(f"{self.name} : image introuvable ({source}).")
+
+        try:
+            import PIL  # noqa: PLC0415
+            from PIL import Image, UnidentifiedImageError  # noqa: PLC0415
+        except ImportError as exc:  # pragma: no cover — dépend de l'installation
+            raise AdapterStepError(
+                f"{self.name} : Pillow requis pour lire l'image (extra [images])."
+            ) from exc
+
+        try:
+            with Image.open(source) as ouverte:
+                tableau = _en_tableau(ouverte)
+        except (UnidentifiedImageError, OSError) as exc:
+            raise AdapterStepError(
+                f"{self.name} : image illisible ({source.name}) — {exc}"
+            ) from exc
+
+        for operation in self._operations:
+            control.raise_if_cancelled()
+            tableau, note = self._appliquer(operation, tableau, PIL)
+            # Journalisé plutôt que silencieux : l'angle réellement mesuré et le
+            # seuil réellement calculé sont ce qui distingue deux exécutions sur
+            # deux pages. Les taire rendrait le traitement inexplicable.
+            logger.info("[preprocess] %s · %s", context.document_id, note)
+
+        # PNG : la sortie d'une binarisation ne survit pas à une compression avec
+        # perte, et un banc ne peut pas mesurer un traitement que l'encodage a
+        # déjà modifié.
+        tampon = io.BytesIO()
+        Image.fromarray(tableau).save(tampon, format="PNG", optimize=True)
+        octets = tampon.getvalue()
+
+        cible = (
+            workspace_artifact_path(
+                context.workspace_uri, context.document_id, self._label, "png"
+            )
+            if context.workspace_uri
+            else source.with_name(f"{source.stem}.{self._label}.png")
+        )
+        cible.parent.mkdir(parents=True, exist_ok=True)
+        cible.write_bytes(octets)
+        return StepOutput(
+            artifacts={
+                ArtifactType.IMAGE: Artifact(
+                    id=f"{context.document_id}:{self._label}:image",
+                    document_id=context.document_id,
+                    type=ArtifactType.IMAGE,
+                    uri=str(cible),
+                    content_hash=compute_content_hash(octets),
+                    produced_by_step=self._label,
+                )
+            }
+        )
+
+    def _appliquer(
+        self, operation: str, matrice: np.ndarray, pil: Any
+    ) -> tuple[np.ndarray, str]:
+        """Applique une opération, et rend la note qui dit ce qu'elle a fait."""
+        if operation == "grayscale":
+            return to_grayscale(matrice), "grayscale"
+        if operation == "deskew":
+            angle = estimate_skew(to_grayscale(matrice), amplitude_deg=self._skew)
+            if angle == 0.0:
+                # Le dire : « aucune rotation appliquée » et « inclinaison
+                # mesurée nulle » se ressemblent dans un rapport, et ne veulent
+                # pas dire la même chose.
+                return matrice, "deskew : 0,00° (aucune inclinaison mesurée)"
+            tournee = pil.Image.fromarray(matrice).rotate(
+                -angle,
+                resample=pil.Image.Resampling.BICUBIC,
+                expand=False,
+                fillcolor=_fond(matrice),
+            )
+            return np.asarray(tournee), f"deskew : {angle:+.2f}°"
+        gris = to_grayscale(matrice)
+        seuil = otsu_threshold(gris)
+        return binarize(gris, seuil), f"binarize : seuil d'Otsu {seuil}"
+
+
+def _en_tableau(ouverte: Any) -> np.ndarray:
+    """Image PIL → tableau numpy, en RVB ou en gris (jamais en palette)."""
+    converti = ouverte if ouverte.mode in {"L", "RGB"} else ouverte.convert("RGB")
+    return np.asarray(converti)
+
+
+def _fond(matrice: np.ndarray) -> int | tuple[int, int, int]:
+    """Remplissage d'une rotation : le blanc du support, jamais du noir.
+
+    Combler avec du noir créerait de fausses zones d'encre dans les coins, que
+    la binarisation prendrait ensuite pour du texte.
+    """
+    return 255 if matrice.ndim == 2 else (255, 255, 255)
+
+
+__all__ = ["OPERATIONS", "ImagePreprocessor"]

cinoc/adapters/storage/__init__.py

@@ -0,0 +1,24 @@
+"""Stockage (couche 5) : état des jobs de run lancés via le web/CLI long.
+
+En mémoire par choix : suffit au lanceur mono-worker du Space. Le journal
+d'événements du ``JobStore`` porte la reprise SSE ``Last-Event-ID`` (réserve
+R-10 d'ANALYSE_COUCHE_5, levée).
+"""
+
+from __future__ import annotations
+
+from cinoc.adapters.storage.history_store import (
+    HistoryRecord,
+    HistoryStore,
+    Regression,
+)
+from cinoc.adapters.storage.job_store import Job, JobState, JobStore
+
+__all__ = [
+    "HistoryRecord",
+    "HistoryStore",
+    "Job",
+    "JobState",
+    "JobStore",
+    "Regression",
+]