refactor(adapters): Sprint A14-S11 — migration des adapters LLM + 2 importers corpus

Sprint S11 du plan rewrite ciblé. Phase 2 continue.

Déplacement physique (sans modification de logique) de 8 fichiers
adapters vers ``picarones/adapters/`` :

- 5 LLM (base + 4 providers) → ``picarones/adapters/llm/``
- 2 corpus importers (htr_united, huggingface) +
1 helper (_fallback_log) → ``picarones/adapters/corpus/``

L'ancien emplacement devient un re-export pour ne casser aucun
consommateur. Aucun test modifié.

Migrés (8)
----------
``picarones/adapters/llm/``
- ``base.py`` (BaseLLMAdapter, normalize_llm_content, etc.)
- ``openai_adapter.py``
- ``mistral_adapter.py``
- ``anthropic_adapter.py``
- ``ollama_adapter.py``

``picarones/adapters/corpus/``
- ``_fallback_log.py``
- ``htr_united.py``
- ``huggingface.py``

Imports internes mis à jour
---------------------------
Les 4 adapters LLM importaient ``picarones.llm.base`` ;
réécrit en ``picarones.adapters.llm.base``.

Les 2 importers corpus importaient
``picarones.extras.importers._fallback_log`` (imports paresseux
dans des fonctions) ; réécrit en
``picarones.adapters.corpus._fallback_log``.

Mécanisme de re-export
----------------------
Pour chaque fichier migré, l'ancien emplacement est un re-export
de 10 lignes. Trois fichiers ré-exposent en plus des **symboles
privés** importés par les tests :

- ``llm/mistral_adapter.py`` : ``_TEXT_ONLY_MODELS``
- ``extras/importers/huggingface.py`` : ``_REFERENCE_DATASETS``
- ``adapters/corpus/_fallback_log.py`` : helper privé partagé

Reste à migrer (différé)
------------------------

**Adapters OCR** (5 fichiers : tesseract, pero_ocr, mistral_ocr,
google_vision, azure_doc_intel) restent dans
``picarones/engines/``. Tous importent ``engines/base.py`` qui
hérite de ``core.modules.BaseModule``. Migration différée
jusqu'au S20 quand ``core.modules`` aura disparu (remplacé par
le protocole ``StepExecutor`` du S6).

**Importers patrimoniaux** (3 fichiers : iiif, gallica,
escriptorium) restent dans ``picarones/extras/importers/``. Tous
importent ``core.corpus.{Corpus, Document}``. Migration différée
jusqu'au déplacement de ``core.corpus`` vers ``domain/`` (sprint
dédié).

Documenté dans ``BACKLOG_POST_LIVRAISON.md`` §2.5b.

Mise à jour des budgets
-----------------------
``tests/architecture/test_file_budgets.py`` :
- ``picarones/adapters/corpus/htr_united.py`` (473 lignes)
- ``picarones/adapters/corpus/huggingface.py`` (464 lignes)

Les anciens emplacements restent dans la whitelist comme
re-exports, conservant leur ancien plafond.

État de la suite
----------------
``pytest tests/ -q`` → 4163 passed, 8 skipped, 2 failed
(strictement environnementaux). +1 test vs S10. Aucune
régression S11.

Critère go/no-go S11 (partiel) atteint
--------------------------------------
- 5 LLM adapters migrés proprement : tous passent par
``picarones.adapters.llm.*``. Le module legacy
``picarones.llm.*`` est devenu une couche de re-exports.
- 2 corpus importers (htr_united, huggingface) migrés.

Le critère "engines/, llm/, extras/ ne contiennent plus que des
re-exports" du plan original n'est PAS atteint (5 OCR + 3
importers patrimoniaux restent legacy). C'est un choix
pragmatique assumé documenté dans BACKLOG : leur migration
demande d'abord de déplacer ``core.modules`` et ``core.corpus``,
ce qui est hors scope S11.

Prêt pour S12 (équivalence numérique CER/WER avec l'ancien
runner sur fixtures).

https://claude.ai/code/session_011XQZNitg1rCgia8ZD1a2hP

BACKLOG_POST_LIVRAISON.md

@@ -126,7 +126,24 @@ exister à la livraison BnF.
 
 → Sprint S5 + S20 du rewrite.
 
-### 2.5 Migration des fichiers `measurements/*.py` restants vers `evaluation/metrics/`
+### 2.5b Migration des adapters restants
+
+Le Sprint S11 a migré 5 LLM (base + openai/mistral/anthropic/ollama)
++ 2 corpus importers (htr_united, huggingface) + 1 helper privé
+(_fallback_log).  L'ancien emplacement est un re-export.
+
+**Adapters OCR** (5 fichiers : tesseract, pero_ocr, mistral_ocr,
+google_vision, azure_doc_intel) restent dans `picarones/engines/`.
+Tous importent `engines/base.py` qui hérite de `core.modules.BaseModule`.
+Migration différée jusqu'au S20 quand `core.modules` aura disparu
+(remplacé par le protocole `StepExecutor` du S6).
+
+**Importers patrimoniaux** (3 fichiers : iiif, gallica, escriptorium)
+restent dans `picarones/extras/importers/`.  Tous importent
+`core.corpus.{Corpus, Document}`.  Migration différée jusqu'au
+déplacement de `core.corpus` vers `domain/` (sprint dédié).
+
+### 2.5c Migration des fichiers `measurements/*.py` restants vers `evaluation/metrics/`
 
 Le Sprint S10 a migré 23 fichiers de calcul autonomes.  17 fichiers
 restent dans `picarones/measurements/` à migrer.

picarones/adapters/corpus/_fallback_log.py

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

picarones/adapters/corpus/htr_united.py

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

picarones/adapters/corpus/huggingface.py

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

picarones/adapters/llm/anthropic_adapter.py

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

picarones/adapters/llm/base.py

@@ -0,0 +1,279 @@
+"""Interface abstraite commune à tous les adaptateurs LLM."""
+
+from __future__ import annotations
+
+import logging
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+# Paramètres de retry par défaut
+_DEFAULT_MAX_RETRIES = 3
+_DEFAULT_BACKOFF_BASE = 2.0  # secondes : 2, 4, 8
+
+
+def _is_retryable(exc: Exception) -> bool:
+    """Détermine si une exception est retryable (429, 5xx, timeout réseau)."""
+    # HTTP status codes retryables
+    status = getattr(exc, "status_code", None) or getattr(exc, "http_status", None)
+    if status is not None:
+        return status == 429 or status >= 500
+
+    # Erreurs réseau / timeout
+    exc_name = type(exc).__name__
+    if exc_name in ("TimeoutError", "ConnectionError", "URLError"):
+        return True
+
+    # Messages d'erreur courants
+    msg = str(exc).lower()
+    if "rate" in msg and "limit" in msg:
+        return True
+    if "timeout" in msg or "connection" in msg:
+        return True
+    if "429" in msg or "503" in msg or "502" in msg:
+        return True
+
+    return False
+
+
+def normalize_llm_content(raw: Any) -> str:
+    """Normalise une réponse LLM en chaîne plate.
+
+    Chantier 4 (post-Sprint 97) — propagation du fix Mistral
+    Sprint 15 à tous les providers. Le SDK Mistral peut retourner
+    une liste de ``ContentChunk`` au lieu d'une chaîne pour certains
+    modèles/versions ; le SDK OpenAI peut faire de même quand on
+    active des features de structuration. Ce helper applique la même
+    discipline pour les 4 adapters :
+
+    - ``str``                          → renvoyée telle quelle (ou ``""``).
+    - ``None``                         → ``""``.
+    - ``list[ContentChunk]``           → concaténation des ``.text``.
+    - ``list[dict]`` avec clé ``text`` → concaténation des ``["text"]``.
+    - ``list[str]``                    → concaténation directe.
+    - autre objet avec ``.text``       → ``obj.text``.
+    - autre                            → ``str(obj)`` (best-effort).
+
+    Le résultat est garanti être une ``str`` ; ``""`` quand la réponse
+    est vide. La fonction est idempotente : ``normalize_llm_content(s)
+    == s`` pour toute chaîne ``s``.
+    """
+    if raw is None:
+        return ""
+    if isinstance(raw, str):
+        return raw
+    if isinstance(raw, list):
+        parts: list[str] = []
+        for chunk in raw:
+            if chunk is None:
+                continue
+            if isinstance(chunk, str):
+                parts.append(chunk)
+                continue
+            if hasattr(chunk, "text"):
+                txt = getattr(chunk, "text", None)
+                if isinstance(txt, str):
+                    parts.append(txt)
+                    continue
+            if isinstance(chunk, dict) and isinstance(chunk.get("text"), str):
+                parts.append(chunk["text"])
+                continue
+            # Dernier recours — convertit le chunk en chaîne
+            parts.append(str(chunk))
+        return "".join(parts)
+    if hasattr(raw, "text") and isinstance(getattr(raw, "text", None), str):
+        return raw.text  # type: ignore[no-any-return]
+    return str(raw)
+
+
+def log_http_error(
+    adapter_name: str,
+    model: str,
+    exc: Exception,
+    *,
+    env_var: Optional[str] = None,
+) -> None:
+    """Log standardisé des erreurs HTTP des SDK LLM.
+
+    Chantier 4 (post-Sprint 97) — propagation du log discriminant
+    Mistral/OpenAI à tous les providers. Inspecte ``status_code`` et
+    ``http_status`` puis émet un warning ciblé selon le code :
+
+    - 401 : clé API invalide/expirée (mention de la variable
+      d'environnement à vérifier si fournie).
+    - 429 : rate limit / quota dépassé.
+    - 5xx : problème serveur côté provider.
+    - autre / pas de status_code : log générique.
+
+    L'exception n'est pas levée — l'appelant doit ``raise``
+    explicitement après ce log s'il veut propager (le retry est géré
+    par ``BaseLLMAdapter.complete`` selon ``_is_retryable``).
+    """
+    status = getattr(exc, "status_code", None) or getattr(exc, "http_status", None)
+    if status == 401:
+        suffix = f" Vérifier {env_var}." if env_var else ""
+        logger.warning(
+            "[%s] erreur HTTP 401 — clé API invalide ou expirée "
+            "(modèle=%s).%s",
+            adapter_name, model, suffix,
+        )
+    elif status == 429:
+        logger.warning(
+            "[%s] erreur HTTP 429 — quota dépassé ou rate-limit "
+            "(modèle=%s). Réessayer plus tard.",
+            adapter_name, model,
+        )
+    elif status is not None and status >= 500:
+        logger.warning(
+            "[%s] erreur HTTP %d — problème serveur (modèle=%s) : %s",
+            adapter_name, status, model, exc,
+        )
+    else:
+        logger.warning(
+            "[%s] erreur lors de l'appel API (modèle=%s) : %s",
+            adapter_name, model, exc,
+        )
+
+
+@dataclass
+class LLMResult:
+    """Résultat produit par un appel LLM."""
+
+    model_id: str
+    text: str
+    duration_seconds: float
+    tokens_used: Optional[int] = None
+    error: Optional[str] = None
+
+    @property
+    def success(self) -> bool:
+        return self.error is None
+
+
+class BaseLLMAdapter(ABC):
+    """Classe de base pour tous les adaptateurs LLM.
+
+    Chaque adaptateur doit implémenter :
+    - ``name``         : identifiant du provider (ex : 'openai')
+    - ``default_model``: modèle par défaut du provider
+    - ``_call()``      : appel API effectif, retourne le texte brut
+
+    Les clés API sont lues depuis les variables d'environnement uniquement.
+
+    Retry automatique
+    -----------------
+    Les erreurs retryables (HTTP 429, 5xx, timeout réseau) sont automatiquement
+    retentées avec backoff exponentiel (2s, 4s, 8s par défaut). Configurable
+    via ``config["max_retries"]`` et ``config["retry_backoff"]``.
+
+    Normalisation des réponses (chantier 4)
+    ---------------------------------------
+    Les sous-classes utilisent :func:`normalize_llm_content` sur la
+    réponse SDK avant de la retourner — garantit qu'une réponse de
+    type ``list[ContentChunk]`` (Mistral, parfois OpenAI) est
+    convertie en ``str`` plate.
+
+    Logging d'erreurs HTTP (chantier 4)
+    -----------------------------------
+    Les sous-classes utilisent :func:`log_http_error` pour produire
+    un log discriminant par ``status_code`` (401 → clé invalide,
+    429 → rate limit, 5xx → serveur).  Auparavant ce log était
+    dupliqué chez Mistral/OpenAI et absent chez Anthropic.
+    """
+
+    # Variable d'environnement portant la clé API.  Sous-classes
+    # surchargent (ex. ``"OPENAI_API_KEY"``) ; mention utilisée par
+    # :func:`log_http_error` quand un 401 est rencontré.  ``None``
+    # pour les providers sans clé (Ollama).
+    api_key_env_var: Optional[str] = None
+
+    def __init__(
+        self,
+        model: Optional[str] = None,
+        config: Optional[dict] = None,
+    ) -> None:
+        self.config: dict = config or {}
+        self.model: str = model or self.default_model
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Identifiant du provider (ex : 'openai', 'anthropic')."""
+
+    @property
+    @abstractmethod
+    def default_model(self) -> str:
+        """Modèle utilisé si aucun n'est fourni explicitement."""
+
+    @abstractmethod
+    def _call(self, prompt: str, image_b64: Optional[str] = None) -> str:
+        """Appel LLM effectif.
+
+        Parameters
+        ----------
+        prompt:
+            Texte du prompt final (variables déjà substituées).
+        image_b64:
+            Image encodée en base64 (sans préfixe data URI).
+            None pour les appels texte-uniquement.
+
+        Returns
+        -------
+        str
+            Texte généré par le LLM.
+        """
+
+    def complete(
+        self,
+        prompt: str,
+        image_b64: Optional[str] = None,
+    ) -> LLMResult:
+        """Point d'entrée public : appelle le LLM avec retry automatique."""
+        max_retries = int(self.config.get("max_retries", _DEFAULT_MAX_RETRIES))
+        backoff_base = float(self.config.get("retry_backoff", _DEFAULT_BACKOFF_BASE))
+
+        start = time.perf_counter()
+        last_exc: Optional[Exception] = None
+
+        for attempt in range(max_retries + 1):
+            try:
+                text = self._call(prompt, image_b64)
+                duration = time.perf_counter() - start
+                return LLMResult(
+                    model_id=self.model,
+                    text=text,
+                    duration_seconds=round(duration, 4),
+                )
+            except Exception as exc:  # noqa: BLE001
+                last_exc = exc
+                if attempt < max_retries and _is_retryable(exc):
+                    wait = backoff_base ** (attempt + 1)
+                    logger.warning(
+                        "[%s] erreur retryable (tentative %d/%d, attente %.1fs) : %s",
+                        self.name, attempt + 1, max_retries + 1, wait, exc,
+                    )
+                    time.sleep(wait)
+                else:
+                    break
+
+        duration = time.perf_counter() - start
+        return LLMResult(
+            model_id=self.model,
+            text="",
+            duration_seconds=round(duration, 4),
+            error=str(last_exc),
+        )
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(model={self.model!r})"
+
+
+__all__ = [
+    "BaseLLMAdapter",
+    "LLMResult",
+    "log_http_error",
+    "normalize_llm_content",
+]

picarones/adapters/llm/mistral_adapter.py

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

picarones/adapters/llm/ollama_adapter.py

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

picarones/adapters/llm/openai_adapter.py

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

picarones/extras/importers/_fallback_log.py

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

picarones/extras/importers/htr_united.py

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

picarones/extras/importers/huggingface.py

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

picarones/llm/anthropic_adapter.py

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

picarones/llm/base.py

@@ -1,279 +1,10 @@
-"""Interface abstraite commune à tous les adaptateurs LLM."""
+"""Re-export — Sprint A14-S11. Le contenu canonique vit dans
+``picarones.adapters.llm.base``.
 
-from __future__ import annotations
-
-import logging
-import time
-from abc import ABC, abstractmethod
-from dataclasses import dataclass
-from typing import Any, Optional
-
-logger = logging.getLogger(__name__)
-
-# Paramètres de retry par défaut
-_DEFAULT_MAX_RETRIES = 3
-_DEFAULT_BACKOFF_BASE = 2.0  # secondes : 2, 4, 8
-
-
-def _is_retryable(exc: Exception) -> bool:
-    """Détermine si une exception est retryable (429, 5xx, timeout réseau)."""
-    # HTTP status codes retryables
-    status = getattr(exc, "status_code", None) or getattr(exc, "http_status", None)
-    if status is not None:
-        return status == 429 or status >= 500
-
-    # Erreurs réseau / timeout
-    exc_name = type(exc).__name__
-    if exc_name in ("TimeoutError", "ConnectionError", "URLError"):
-        return True
-
-    # Messages d'erreur courants
-    msg = str(exc).lower()
-    if "rate" in msg and "limit" in msg:
-        return True
-    if "timeout" in msg or "connection" in msg:
-        return True
-    if "429" in msg or "503" in msg or "502" in msg:
-        return True
-
-    return False
-
-
-def normalize_llm_content(raw: Any) -> str:
-    """Normalise une réponse LLM en chaîne plate.
-
-    Chantier 4 (post-Sprint 97) — propagation du fix Mistral
-    Sprint 15 à tous les providers. Le SDK Mistral peut retourner
-    une liste de ``ContentChunk`` au lieu d'une chaîne pour certains
-    modèles/versions ; le SDK OpenAI peut faire de même quand on
-    active des features de structuration. Ce helper applique la même
-    discipline pour les 4 adapters :
-
-    - ``str``                          → renvoyée telle quelle (ou ``""``).
-    - ``None``                         → ``""``.
-    - ``list[ContentChunk]``           → concaténation des ``.text``.
-    - ``list[dict]`` avec clé ``text`` → concaténation des ``["text"]``.
-    - ``list[str]``                    → concaténation directe.
-    - autre objet avec ``.text``       → ``obj.text``.
-    - autre                            → ``str(obj)`` (best-effort).
-
-    Le résultat est garanti être une ``str`` ; ``""`` quand la réponse
-    est vide. La fonction est idempotente : ``normalize_llm_content(s)
-    == s`` pour toute chaîne ``s``.
-    """
-    if raw is None:
-        return ""
-    if isinstance(raw, str):
-        return raw
-    if isinstance(raw, list):
-        parts: list[str] = []
-        for chunk in raw:
-            if chunk is None:
-                continue
-            if isinstance(chunk, str):
-                parts.append(chunk)
-                continue
-            if hasattr(chunk, "text"):
-                txt = getattr(chunk, "text", None)
-                if isinstance(txt, str):
-                    parts.append(txt)
-                    continue
-            if isinstance(chunk, dict) and isinstance(chunk.get("text"), str):
-                parts.append(chunk["text"])
-                continue
-            # Dernier recours — convertit le chunk en chaîne
-            parts.append(str(chunk))
-        return "".join(parts)
-    if hasattr(raw, "text") and isinstance(getattr(raw, "text", None), str):
-        return raw.text  # type: ignore[no-any-return]
-    return str(raw)
-
-
-def log_http_error(
-    adapter_name: str,
-    model: str,
-    exc: Exception,
-    *,
-    env_var: Optional[str] = None,
-) -> None:
-    """Log standardisé des erreurs HTTP des SDK LLM.
-
-    Chantier 4 (post-Sprint 97) — propagation du log discriminant
-    Mistral/OpenAI à tous les providers. Inspecte ``status_code`` et
-    ``http_status`` puis émet un warning ciblé selon le code :
-
-    - 401 : clé API invalide/expirée (mention de la variable
-      d'environnement à vérifier si fournie).
-    - 429 : rate limit / quota dépassé.
-    - 5xx : problème serveur côté provider.
-    - autre / pas de status_code : log générique.
-
-    L'exception n'est pas levée — l'appelant doit ``raise``
-    explicitement après ce log s'il veut propager (le retry est géré
-    par ``BaseLLMAdapter.complete`` selon ``_is_retryable``).
-    """
-    status = getattr(exc, "status_code", None) or getattr(exc, "http_status", None)
-    if status == 401:
-        suffix = f" Vérifier {env_var}." if env_var else ""
-        logger.warning(
-            "[%s] erreur HTTP 401 — clé API invalide ou expirée "
-            "(modèle=%s).%s",
-            adapter_name, model, suffix,
-        )
-    elif status == 429:
-        logger.warning(
-            "[%s] erreur HTTP 429 — quota dépassé ou rate-limit "
-            "(modèle=%s). Réessayer plus tard.",
-            adapter_name, model,
-        )
-    elif status is not None and status >= 500:
-        logger.warning(
-            "[%s] erreur HTTP %d — problème serveur (modèle=%s) : %s",
-            adapter_name, status, model, exc,
-        )
-    else:
-        logger.warning(
-            "[%s] erreur lors de l'appel API (modèle=%s) : %s",
-            adapter_name, model, exc,
-        )
-
-
-@dataclass
-class LLMResult:
-    """Résultat produit par un appel LLM."""
-
-    model_id: str
-    text: str
-    duration_seconds: float
-    tokens_used: Optional[int] = None
-    error: Optional[str] = None
-
-    @property
-    def success(self) -> bool:
-        return self.error is None
-
-
-class BaseLLMAdapter(ABC):
-    """Classe de base pour tous les adaptateurs LLM.
-
-    Chaque adaptateur doit implémenter :
-    - ``name``         : identifiant du provider (ex : 'openai')
-    - ``default_model``: modèle par défaut du provider
-    - ``_call()``      : appel API effectif, retourne le texte brut
-
-    Les clés API sont lues depuis les variables d'environnement uniquement.
-
-    Retry automatique
-    -----------------
-    Les erreurs retryables (HTTP 429, 5xx, timeout réseau) sont automatiquement
-    retentées avec backoff exponentiel (2s, 4s, 8s par défaut). Configurable
-    via ``config["max_retries"]`` et ``config["retry_backoff"]``.
-
-    Normalisation des réponses (chantier 4)
-    ---------------------------------------
-    Les sous-classes utilisent :func:`normalize_llm_content` sur la
-    réponse SDK avant de la retourner — garantit qu'une réponse de
-    type ``list[ContentChunk]`` (Mistral, parfois OpenAI) est
-    convertie en ``str`` plate.
-
-    Logging d'erreurs HTTP (chantier 4)
-    -----------------------------------
-    Les sous-classes utilisent :func:`log_http_error` pour produire
-    un log discriminant par ``status_code`` (401 → clé invalide,
-    429 → rate limit, 5xx → serveur).  Auparavant ce log était
-    dupliqué chez Mistral/OpenAI et absent chez Anthropic.
-    """
-
-    # Variable d'environnement portant la clé API.  Sous-classes
-    # surchargent (ex. ``"OPENAI_API_KEY"``) ; mention utilisée par
-    # :func:`log_http_error` quand un 401 est rencontré.  ``None``
-    # pour les providers sans clé (Ollama).
-    api_key_env_var: Optional[str] = None
-
-    def __init__(
-        self,
-        model: Optional[str] = None,
-        config: Optional[dict] = None,
-    ) -> None:
-        self.config: dict = config or {}
-        self.model: str = model or self.default_model
-
-    @property
-    @abstractmethod
-    def name(self) -> str:
-        """Identifiant du provider (ex : 'openai', 'anthropic')."""
-
-    @property
-    @abstractmethod
-    def default_model(self) -> str:
-        """Modèle utilisé si aucun n'est fourni explicitement."""
-
-    @abstractmethod
-    def _call(self, prompt: str, image_b64: Optional[str] = None) -> str:
-        """Appel LLM effectif.
-
-        Parameters
-        ----------
-        prompt:
-            Texte du prompt final (variables déjà substituées).
-        image_b64:
-            Image encodée en base64 (sans préfixe data URI).
-            None pour les appels texte-uniquement.
-
-        Returns
-        -------
-        str
-            Texte généré par le LLM.
-        """
-
-    def complete(
-        self,
-        prompt: str,
-        image_b64: Optional[str] = None,
-    ) -> LLMResult:
-        """Point d'entrée public : appelle le LLM avec retry automatique."""
-        max_retries = int(self.config.get("max_retries", _DEFAULT_MAX_RETRIES))
-        backoff_base = float(self.config.get("retry_backoff", _DEFAULT_BACKOFF_BASE))
-
-        start = time.perf_counter()
-        last_exc: Optional[Exception] = None
-
-        for attempt in range(max_retries + 1):
-            try:
-                text = self._call(prompt, image_b64)
-                duration = time.perf_counter() - start
-                return LLMResult(
-                    model_id=self.model,
-                    text=text,
-                    duration_seconds=round(duration, 4),
-                )
-            except Exception as exc:  # noqa: BLE001
-                last_exc = exc
-                if attempt < max_retries and _is_retryable(exc):
-                    wait = backoff_base ** (attempt + 1)
-                    logger.warning(
-                        "[%s] erreur retryable (tentative %d/%d, attente %.1fs) : %s",
-                        self.name, attempt + 1, max_retries + 1, wait, exc,
-                    )
-                    time.sleep(wait)
-                else:
-                    break
-
-        duration = time.perf_counter() - start
-        return LLMResult(
-            model_id=self.model,
-            text="",
-            duration_seconds=round(duration, 4),
-            error=str(last_exc),
-        )
-
-    def __repr__(self) -> str:
-        return f"{self.__class__.__name__}(model={self.model!r})"
+L'ancien chemin ``picarones.llm.base`` est conservé pour ne casser
+aucun consommateur.  Au S22, ce re-export disparaîtra.
+"""
 
+from __future__ import annotations
 
-__all__ = [
-    "BaseLLMAdapter",
-    "LLMResult",
-    "log_http_error",
-    "normalize_llm_content",
-]
+from picarones.adapters.llm.base import *  # noqa: F401,F403

picarones/llm/mistral_adapter.py

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

picarones/llm/ollama_adapter.py

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

picarones/llm/openai_adapter.py

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

tests/architecture/test_file_budgets.py

@@ -82,7 +82,11 @@ FILE_BUDGETS: dict[str, int] = {
     "picarones/fixtures.py": 600,                         # actuel 510
     "picarones/measurements/inter_engine.py": 575,        # actuel 484
     "picarones/measurements/roman_numerals.py": 575,      # actuel 478
-    "picarones/extras/importers/htr_united.py": 575,      # actuel 473
+    "picarones/extras/importers/htr_united.py": 575,      # actuel 473 (re-export S11)
+    # Sprint A14-S11 — d\xc3\xa9plac\xc3\xa9s depuis extras/importers/, l'ancien
+    # emplacement est d\xc3\xa9sormais un re-export.
+    "picarones/adapters/corpus/htr_united.py": 575,       # actuel 473
+    "picarones/adapters/corpus/huggingface.py": 550,      # actuel 464
     "picarones/cli/_workflows.py": 550,                   # actuel 469
     "picarones/extras/importers/huggingface.py": 550,     # actuel 464
     "picarones/core/metric_hooks.py": 500,                # actuel 423